commonlib-reader 1.2.1__tar.gz → 1.4.0__tar.gz

commonlib_reader-1.4.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: commonlib-reader
+Version: 1.4.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). 
+
+See the [changelog](CHANGELOG.md) for release history.
+
+Current features:
+- Reading any code table with the `Code` class
+- Reading library definitions and attribute definitions with the `Library` and `AttributeDefinition` classes
+- Reading projects with the `Project` class
+- 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.
+
+### Projects
+
+Use `Project.get_all()` to retrieve projects and optionally filter by name or
+abbreviation.
+
+```python
+from commonlib_reader import Project
+
+projects = Project.get_all(name="M.IGLED.6I.X.0010")
+matching_projects = Project.get_all(abbreviation="IGLED")
+```
+
+## 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`

commonlib_reader-1.4.0/README.md

@@ -0,0 +1,87 @@
+# commonlib-reader
+Connector package for Equinor [Commonlib](https://commonlib.equinor.com/) [api](https://commonlibapi.equinor.com/swagger/index.html). 
+
+See the [changelog](CHANGELOG.md) for release history.
+
+Current features:
+- Reading any code table with the `Code` class
+- Reading library definitions and attribute definitions with the `Library` and `AttributeDefinition` classes
+- Reading projects with the `Project` class
+- 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.
+
+### Projects
+
+Use `Project.get_all()` to retrieve projects and optionally filter by name or
+abbreviation.
+
+```python
+from commonlib_reader import Project
+
+projects = Project.get_all(name="M.IGLED.6I.X.0010")
+matching_projects = Project.get_all(abbreviation="IGLED")
+```
+
+## 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`

commonlib_reader-1.4.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "commonlib-reader"
+version = "1.4.0"
+description = "Reader for Equinor commonlib api."
+readme = "README.md"
+requires-python = ">=3.10,<4.0.0"
+dependencies = [
+    "pandas>=2.1.4",
+    "eq-api-connector (>=1.1.0,<2.0.0)",
+]
+
+[[project.authors]]
+name = "Åsmund Våge Fannemel"
+email = "asmf@equinor.com"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Repository = "https://github.com/equinor/commonlib-reader.git"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.4.4,<10.0.0",
+    "pytest-cov>=7.0.0,<8.0.0",
+    "black>=24.1.1,<27.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.13"]
+build-backend = "uv_build"

commonlib_reader-1.2.1/pyproject.toml → commonlib_reader-1.4.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "commonlib-reader"
-version = "1.2.1"
+version = "1.4.0"
 description = "Reader for Equinor commonlib api."
 authors = [
 	{ name = "Åsmund Våge Fannemel", email = "asmf@equinor.com" }
@@ -22,5 +22,5 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.16,<0.12"]
+requires = ["uv_build>=0.11.16,<0.13"]
 build-backend = "uv_build"

{commonlib_reader-1.2.1 → commonlib_reader-1.4.0}/src/commonlib_reader/__init__.py

@@ -1,25 +1,22 @@
-from commonlib_reader.utils import (
-    get_code,
-    get_code_param,
-    get_library_names,
-)
-
-
 from .discipline import Discipline
 from .tag import TagType, TagCategory, TagFormat
 from .ims import IMS
 from .facility import Facility
 from .unit import Unit
+from .code import Code
+from .library import Library, AttributeDefinition
+from .project import Project
 
 __all__ = [
+    "AttributeDefinition",
+    "Code",
     "Discipline",
     "Facility",
     "IMS",
+    "Library",
+    "Project",
     "TagType",
     "TagCategory",
     "TagFormat",
     "Unit",
-    "get_code",
-    "get_code_param",
-    "get_library_names",
 ]

commonlib_reader-1.4.0/src/commonlib_reader/code.py

@@ -0,0 +1,169 @@
+from typing import Dict, List, Optional
+
+from commonlib_reader.connector import get_connector
+from commonlib_reader.utils import attributes_list_to_dict
+
+
+class Code:
+    """A generic representation of one entry in a CommonLib library.
+
+    A Library defines the code table and its attribute schema; a Code stores one
+    value from that table. Use this class directly for generic libraries, or as
+    a base class for dedicated readers that add library-specific behavior.
+
+    Attributes:
+        library (str): Name of the library the code belongs to.
+        name (str): The code name (the code value).
+        description (str): Description of the code.
+        is_valid (bool): Whether the code can still be used with new data.
+        identity (str): Unique identity used to cross reference the code.
+        iri (str): CommonLib IRI of the code.
+        project (str): Project the code belongs to, if any.
+        attachment_key (str): Key used to download an attached file, if any.
+        attributes (Dict[str, str]): Library specific attributes keyed by definition name.
+    """
+
+    def __init__(self, data: dict, library: str = ""):
+        if not isinstance(data, dict):
+            raise ValueError("Input data must be a dict from codetable")
+        self._data = data
+        self._library = library
+        self._attributes = attributes_list_to_dict(self._data.get("attributes", []))
+
+    def __eq__(self, other):
+        if isinstance(other, Code):
+            return self._data == other._data and self._library == other._library
+        return False
+
+    def __str__(self):
+        return f"{self.name} - {self.description}"
+
+    @property
+    def library(self) -> str:
+        return self._library
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str:
+        return self._data.get("description", "")
+
+    @property
+    def is_valid(self) -> bool:
+        return self._data.get("isValid", False)
+
+    @property
+    def identity(self) -> str:
+        return self._data.get("identity", "")
+
+    @property
+    def iri(self) -> str:
+        return self._data.get("iri", "") or ""
+
+    @property
+    def project(self) -> str:
+        return self._data.get("project", "") or ""
+
+    @property
+    def attachment_key(self) -> str:
+        return self._data.get("attachmentKey", "") or ""
+
+    @property
+    def attributes(self) -> Dict[str, str]:
+        return self._attributes
+
+    @staticmethod
+    def _get_code_data_param(code: str, params: Optional[dict] = None):
+        """Retrieve raw code-table data using pre-built request parameters.
+
+        Args:
+            code (str): Name of the code library to read.
+            params (dict, optional): Query parameters to send to the API.
+
+        Returns:
+            list: Raw code entries returned by the API.
+        """
+        return get_connector().get_json(f"/api/Code/{code}", params=params or {})
+
+    @classmethod
+    def _get_code_data(
+        cls,
+        library: str,
+        scope: Optional[str] = None,
+        name: Optional[str] = None,
+    ):
+        """Retrieve raw code-table data with optional scope and name filters.
+
+        Args:
+            library (str): Name of the code library to read.
+            scope (str, optional): Scope (installation code) to filter by.
+            name (str, optional): Criterion for code name (use % for wildcards).
+
+        Returns:
+            list: Raw code entries returned by the API.
+        """
+        params = {}
+        if scope is not None:
+            params["scope"] = scope
+        if name is not None:
+            params["name"] = name
+        return cls._get_code_data_param(library, params=params)
+
+    @classmethod
+    def get_codes(
+        cls,
+        library: str,
+        scope: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> List["Code"]:
+        """Get all codes from a library as Code objects.
+
+        Args:
+            library (str): Name of the library to read.
+            scope (str, optional): Scope (installation code) to filter by.
+            name (str, optional): Criterion for code name (use % for wildcards).
+
+        Returns:
+            List[Code]: List of Code objects from the library.
+        """
+        data = cls._get_code_data(library, scope=scope, name=name)
+        if not isinstance(data, list):
+            raise ValueError(f"Invalid data from api for library {library}")
+
+        return [cls(x, library=library) for x in data]
+
+    @staticmethod
+    def get_names(library: str, scope: Optional[str] = None) -> list:
+        """Get code names of a library as a list of strings. For dropdowns etc.
+
+        Args:
+            library (str): Name of the library to read.
+            scope (str, optional): Scope (installation code) to filter by.
+
+        Returns:
+            list: List of code name strings.
+        """
+        params = {}
+        if scope is not None:
+            params["scope"] = scope
+        return get_connector().get_json(f"/api/Code/NameList/{library}", params=params)
+
+    @staticmethod
+    def get_name_and_desc(library: str, scope: Optional[str] = None) -> list:
+        """Get codes of a library as a list of name and description objects.
+
+        Args:
+            library (str): Name of the library to read.
+            scope (str, optional): Scope (installation code) to filter by.
+
+        Returns:
+            list: List of objects with name, description and isValid.
+        """
+        params = {}
+        if scope is not None:
+            params["scope"] = scope
+        return get_connector().get_json(
+            f"/api/Code/NameAndDesc/{library}", params=params
+        )

{commonlib_reader-1.2.1 → commonlib_reader-1.4.0}/src/commonlib_reader/discipline.py

@@ -1,40 +1,17 @@
 from typing import List
 
-from commonlib_reader.utils import get_code
+from commonlib_reader.code import Code
 
 
-class Discipline:
+class Discipline(Code):
     def __init__(self, data: dict):
         if not isinstance(data, dict):
             raise ValueError("Input data shall be dictionary.")
-
-        self._data = data
-
-    def __eq__(self, other):
-        if isinstance(other, Discipline):
-            return self._data == other._data
-
-        return False
+        super().__init__(data, library="Discipline")
 
     def __str__(self):
         return f"Discipline: {self.name}-{self.description}"
 
-    @property
-    def name(self) -> str:
-        return self._data.get("name", "")
-
-    @property
-    def description(self) -> str:
-        return self._data.get("description", "")
-
-    @property
-    def identity(self) -> str:
-        return self._data.get("identity", "")
-
-    @property
-    def is_valid(self) -> bool:
-        return self._data.get("isValid", False)
-
     @classmethod
     def get_all(cls, scope: str, only_valid: bool = True) -> List["Discipline"]:
         """Get all disciplines for
@@ -45,7 +22,7 @@ class Discipline:
         Returns:
             List["Discipline"]: List of discipline objects
         """
-        dis_data = get_code("Discipline", scope=scope)
+        dis_data = Code._get_code_data("Discipline", scope=scope)
 
         if not isinstance(dis_data, list) or not all(
             isinstance(x, dict) for x in dis_data
@@ -57,7 +34,7 @@ class Discipline:
                 f"No discipline data found for scope {scope}. Verify that scope is correct."
             )
 
-        dis = [Discipline(x) for x in dis_data]  # type: ignore
+        dis = [cls(x) for x in dis_data]
         if only_valid:
             dis = [x for x in dis if x.is_valid]
 

{commonlib_reader-1.2.1 → commonlib_reader-1.4.0}/src/commonlib_reader/facility.py

@@ -1,6 +1,7 @@
 from typing import List, Union
 
-from commonlib_reader.utils import attributes_list_to_dict, get_code
+from commonlib_reader.code import Code
+from commonlib_reader.utils import attributes_list_to_dict
 
 
 class Facility:
@@ -38,11 +39,14 @@ class Facility:
         self._data = Facility._get_facility_data(code=code)
         self._attributes = attributes_list_to_dict(self._data["attributes"])
 
+        # Backward compatibility aliases
         if self.is_stid:
             self.STID = self.identity
         self.instCode = self.identity  # Alias for identity
         try:
-            self.SAP = int(self.sap)  # Alias for SAPPlant as integer
+            self.SAP = int(
+                self.sap
+            )  # Backward compatibility alias for SAPPlant as integer
         except (TypeError, ValueError):
             pass
 
@@ -104,7 +108,7 @@ class Facility:
     def ioc_plant(self) -> str:
         return self._attributes.get("IOCPlant", "")
 
-    def isSTID(self):
+    def _check_is_stid(self) -> bool:
         """
         Checks if the facility is marked for STID.
 
@@ -117,6 +121,15 @@ class Facility:
 
         return False
 
+    def isSTID(self) -> bool:
+        """
+        Backward compatibility method. Use is_stid property instead.
+
+        Returns:
+            bool: True if the facility is marked for STID, False otherwise.
+        """
+        return self._check_is_stid()
+
     def resolve_gov_facility_name(self) -> str:
         """
         Retrieves the governmental facility name.
@@ -267,7 +280,7 @@ class Facility:
             List[dict]: A list of dictionaries, each representing facility data.
         """
         if cls._cache is None:
-            code = get_code("Facility")
+            code = Code._get_code_data("Facility")
             if isinstance(code, list):
                 cls._cache = code
             else:

{commonlib_reader-1.2.1 → commonlib_reader-1.4.0}/src/commonlib_reader/ims.py

@@ -1,20 +1,22 @@
 from typing import List, Union
+from commonlib_reader.code import Code
 from commonlib_reader.facility import Facility
-from commonlib_reader.utils import attributes_list_to_dict, get_code
+from commonlib_reader.utils import attributes_list_to_dict
 
 
 class IMS:
-    _ims_codes = []
-
-    """Class for IMS objects.
-
-    properties:
-    Facility (str) - Name of facility
-    IMSType (str) - Type of IMS
-    Alias (str) - Facility name aliases
-    isValid (bool) - True if IMS is in operation
+    """Class for IMS (Information Management System) objects.
+
+    Properties:
+        facility (str): Name of the facility associated with this IMS.
+        type (str): Type of the IMS system.
+        alias (str): Facility name alias used by the IMS.
+        is_valid (bool): True if the IMS is in operation, False otherwise.
+        seeq_datasource (str): The Seeq datasource identifier for this IMS.
     """
 
+    _ims_codes = None
+
     def __init__(self, data: Union[str, dict]):
         """Instance constructor for IMS object. End-users should use static method IMS.from_facility()
 
@@ -33,7 +35,6 @@ class IMS:
         self._data = data
         self._attributes = attributes_list_to_dict(self._data["attributes"])
 
-        self.isValid = data["isValid"]
         for attr in self._data["attributes"]:
             self.__setattr__(attr["definitionName"], attr["displayValue"])
 
@@ -51,7 +52,12 @@ class IMS:
 
     @property
     def is_valid(self) -> bool:
-        return getattr(self, "isValid", False)
+        return self._data.get("isValid", False)
+
+    @property
+    def isValid(self) -> bool:
+        """Backward compatibility alias for is_valid."""
+        return self.is_valid
 
     @property
     def seeq_datasource(self) -> str:
@@ -88,10 +94,10 @@ class IMS:
         """Get list of IMS instance of entries in code library ApplicationIMS. Caches locally in memory.
 
         Returns:
-            List[IMS]: list of IMS instance from entries in code library ApplicationIMS.
+            List[IMS]: List of IMS instances from entries in code library ApplicationIMS.
         """
-        if cls._ims_codes is None or len(cls._ims_codes) == 0:
-            cls._ims_codes = get_code("ApplicationIMS")
+        if cls._ims_codes is None:
+            cls._ims_codes = Code._get_code_data("ApplicationIMS")
 
         return [IMS(x) for x in cls._ims_codes]