tagmapper-sdk

Python SDK for retrieving timeseries and constant value mappings for data models from the SDP tag mapping library.

Overview

tagmapper-sdk provides a simple, typed interface to fetch and work with data model mappings. It supports:

• SDP-defined models for Separators and Wells
• Generic models with optional schema validation
• Azure authentication with bearer token management
• Structured data access with intelligent mapping and reporting

Note: Requires access to Equinor internal network (office network or VPN Location_All)

Installation

Install from PyPI:

pip install tagmapper

Quick Start

Working with Pre-defined Models

The following SDP-defined models are available out-of-the-box:

• Well – Well data and timeseries mappings
• Separator – Separator equipment mappings
• Pipe – Pipe (flowline) mappings

from tagmapper import Well

# Create a well object
w = Well("NO 30/6-E-2")

# Print the default report
w.print_report()

# Print a formatted report
w.print_formatted_report()

See well demo for more examples.

Working with Generic Models

from tagmapper import Model

# List available models
available_models = Model.get_model_names()
model_owner = available_models[0]["model_owner"]
model_name = available_models[0]["model_name"]

# Get object names for a model
object_names = Model.get_object_names(
    model_owner=model_owner, 
    model_name=model_name
)

# Fetch a model from API
mod = Model.get_model(
    model_owner=model_owner,
    model_name=model_name,
    object_name=object_names[0]
)

mod.print_report()

See model demo for additional examples.

Looking Up a Facility

Resolve a STID installation code or an existing government facility name:

from tagmapper import resolve_facility_name

facility_name = resolve_facility_name(facility_code="ASGA")

The lookup uses the SPD production /facility-master endpoint and restores the API client's previous environment selection after the request. If the endpoint returns HTTP 404/410 or a server error (5xx), or the request fails with a connection error or timeout, it falls back to CommonLib's governmental facility-name resolver. Authentication and authorization errors are not masked by the fallback. A successful SPD response requires exactly one distinct, non-empty gov_fcty_name matching either the ims_facility code or the government name itself. If the code query returns no rows, the lookup retries using the gov_fcty_name filter. Missing or ambiguous matches raise ValueError.

Development

Prerequisites

• Python 3.10+
• uv for dependency management

Setup

Clone the repository and install dependencies:

git clone https://github.com/equinor/tagmapper-sdk.git
cd tagmapper-sdk
uv sync

Testing

Run tests with coverage reporting:

uv run pytest --cov=. --cov-report=xml:coverage.xml

Compare coverage against the main branch:

diff-cover coverage.xml --compare-branch=origin/main

Contributing

Contributions are welcome! Please ensure:

• All tests pass: uv run pytest
• Code coverage remains above the current baseline
• Changes are well-documented with clear commit messages