Metadata-Version: 2.3
Name: tagmapper
Version: 0.9.7
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.4,<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.

### Deleting All Mappings for a Model and UOI

Create a model with the exact owner, model name, and unique object identifier
(UOI, represented by `object_name`), then call `delete_mappings()`:

```python
from tagmapper import Model

mod = Model({
    "owner": "your_owner",
    "name": "your_model",
    "object_name": "your_uoi",
})
mod.delete_mappings()
```

This deletes all attribute mappings across all modes for that model and UOI
in the API client's selected environment. No mappings need to be loaded first.
It also clears any mappings held by this instance after the request succeeds,
while retaining attribute definitions. Request failures propagate and leave local
mappings unchanged.

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