Metadata-Version: 2.3
Name: commonlib-reader
Version: 1.3.0
Summary: Reader for Equinor commonlib api.
Author: Åsmund Våge Fannemel
Author-email: Åsmund Våge Fannemel <asmf@equinor.com>
License: MIT
Requires-Dist: pandas>=2.1.4
Requires-Dist: eq-api-connector>=1.1.0,<2.0.0
Requires-Python: >=3.10, <4.0.0
Project-URL: Repository, https://github.com/equinor/commonlib-reader.git
Description-Content-Type: text/markdown

# commonlib-reader
Connector package for Equinor [Commonlib](https://commonlib.equinor.com/) [api](https://commonlibapi.equinor.com/swagger/index.html). 

Current features:
- Reading any code table with the `Code` class
- Reading library definitions and attribute definitions with the `Library` and `AttributeDefinition` classes
- Getting facility data using the [Facility](commonlib_reader/facility.py) class
- [IMS source ](commonlib_reader/ims.py) lookup tables for facilities
- Getting Tag category, Tag type, Tag format, and Tag format element data. See [tag.py](commonlib_reader/tag.py)
- Getting [units of measure](commonlib_reader/ims.py) definitions.


## Use
Try it out by running the [demo](examples/demo.py).

### Libraries and codes

A `Library` defines a code table and its attribute schema; a `Code` is one entry
in that table. Use package-provided specialized readers when available, such as
`Facility`, `Discipline`, `Unit`, `TagType`, `TagCategory`, and `TagFormat`;
otherwise use the generic `Code` reader.

### Libraries

Use `Library` to discover available code tables and inspect their definitions.

```python
from commonlib_reader import Library

library_names = Library.get_names()
discipline_library = Library.get("Discipline")
attribute_definitions = discipline_library.attribute_definitions
is_scoped = discipline_library.is_scope_specific
scope_type = discipline_library.scope_type
```

`Library.get_all()` supports name and scope filters. Each `AttributeDefinition`
provides its name, description, required status, identity participation, validation
regular expression, and referenced library name.

Check `is_scope_specific` and `scope_type` before retrieving codes. For example,
when `scope_type` is `"Facility"` and `is_scope_specific` is `True`, pass the
facility installation code, such as `"TROC"`, as `scope`.

### Code tables

Use `Code.get_codes()` to retrieve entries from any CommonLib code table. Filter by
installation scope or code name when needed.

```python
from commonlib_reader import Code

disciplines = Code.get_codes("Discipline", scope="TROC")
administration = Code.get_codes("Discipline", scope="TROC", name="A")
```

Each entry provides `name`, `description`, `identity`, `is_valid`, `attributes`, and
other CommonLib metadata. Use `Code.get_names()` or `Code.get_name_and_desc()` when
only dropdown-friendly names or name/description data is required.

## Installing

Install package from pypi using `pip install commonlib_reader`


## Developing / testing

uv is preferred for developers. Clone and install with required packages for testing and coverage:
`uv sync`

For testing with coverage run:
`uv run pytest --cov --cov-report=html`
