Metadata-Version: 2.3
Name: tagmapper
Version: 0.9.6
Summary: Python wrapper for Equinor SPD tag mapping database
Author: Åsmund Våge Fannemel
Author-email: Åsmund Våge Fannemel <asmf@equinor.com>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pandas>=2.2.2,<4
Requires-Dist: certifi>=2026.10.23
Requires-Dist: pyyaml>=6.0.2,<7
Requires-Dist: eq-api-connector>=1.2.1,<2
Requires-Dist: commonlib-reader>=1.4.0,<2
Requires-Python: >=3.10.0, <4.0
Description-Content-Type: text/markdown

# 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:

```bash
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

```python
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](examples/demo_spd_classes.py) for more examples.

### Working with Generic Models

```python
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](examples/demo_get_models.py) for additional examples.

### Looking Up a Facility

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

```python
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](https://docs.astral.sh/uv/) for dependency management

### Setup

Clone the repository and install dependencies:

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

## Testing

Run tests with coverage reporting:

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

Compare coverage against the main branch:

```bash
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
