commonlib-reader 1.2.0__tar.gz → 1.3.0__tar.gz

commonlib_reader-1.3.0/PKG-INFO

@@ -0,0 +1,85 @@
+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`

commonlib_reader-1.3.0/README.md

@@ -0,0 +1,72 @@
+# 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`

commonlib_reader-1.3.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "commonlib-reader"
+version = "1.3.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.0/pyproject.toml → commonlib_reader-1.3.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "commonlib-reader"
-version = "1.2.0"
+version = "1.3.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.0 → commonlib_reader-1.3.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.3.0/src/commonlib_reader/code.py

@@ -0,0 +1,170 @@
+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 to read entries from libraries without
+    a dedicated domain class implemented in this package, such as Facility,
+    Discipline, Unit, TagType, TagCategory, or TagFormat.
+
+    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.0 → commonlib_reader-1.3.0}/src/commonlib_reader/connector.py

@@ -14,7 +14,7 @@ def get_connector() -> APIConnector:
         clientID = "728cfddd-b8e9-4ed7-b9a3-8f2fd5b8e79a"
         scopes = ["37d598fc-da0f-46bd-949f-7107918d47a5/user_impersonation"]
         connector = APIConnector(client_id=clientID, scope=scopes)
-        connector.set_url_prod("https://commonlibapi.equinor.com/")
+        connector.url_prod = "https://commonlibapi.equinor.com/"
         _connector = connector
 
     return _connector

{commonlib_reader-1.2.0 → commonlib_reader-1.3.0}/src/commonlib_reader/discipline.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from commonlib_reader.utils import get_code
+from commonlib_reader.code import Code
 
 
 class Discipline:
@@ -45,7 +45,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

{commonlib_reader-1.2.0 → commonlib_reader-1.3.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,14 +39,25 @@ 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
 
+    def __eq__(self, other):
+        if isinstance(other, Facility):
+            return self.identity == other.identity and self._data == other._data
+        return False
+
+    def __str__(self):
+        return f"Facility(identity={self.identity}, name={self.description})"
+
     @property
     def identity(self) -> str:
         return self._data.get("identity", "")
@@ -96,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.
 
@@ -109,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.
@@ -226,7 +247,7 @@ class Facility:
     @classmethod
     def get_sap_facilities(cls) -> List["Facility"]:
         fac = cls.get_all_facilities()
-        return [f for f in fac if len(f.sap) > 0]
+        return [f for f in fac if len(f.sap) > 0 and f.sap.isdigit()]
 
     @classmethod
     def get_ioc_facilities(cls) -> List["Facility"]:
@@ -259,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.0 → commonlib_reader-1.3.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:
@@ -60,9 +66,10 @@ class IMS:
     @staticmethod
     def from_facility(facility: Union[Facility, str, int]) -> "IMS":
         """Get IMS instance from STID code.
+        If no IMS instance is found for the input facility, will try to find IMS instance for parent facility recursively.
 
         Args:
-            facility (str): Facility inst code (STID) or SAP code.
+            facility (Facility, str, int): Facility object, inst code (STID) or SAP code.
 
         Raises:
             ValueError: Not able to instantiate IMS object from input facility code.
@@ -70,18 +77,15 @@ class IMS:
         Returns:
             IMS: IMS instance
         """
-        if isinstance(facility, int):
+        if not isinstance(facility, Facility):
             facility = Facility(facility)
 
-        if isinstance(facility, Facility):
-            facility = facility.identity
-
-        if not isinstance(facility, str) or len(facility) == 0:
-            raise ValueError("Not able to detect facility from input {facility}.")
-
         ims = IMS.get_ims_list(facility=facility)
         if len(ims) == 1:
             return ims[0]
+        if len(ims) == 0:
+            if facility.parent_facility:
+                return IMS.from_facility(facility.parent_facility)
 
         raise ValueError(f"Not able to get IMS object for facility {facility}")
 
@@ -90,15 +94,15 @@ 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]
 
     @staticmethod
-    def get_ims_list(facility: str = "") -> List["IMS"]:
+    def get_ims_list(facility: Union[str, Facility] = "") -> List["IMS"]:
         """Get list of IMS objects.
 
         Args:
@@ -107,6 +111,10 @@ class IMS:
         Returns:
             List[IMS]: list of IMS objects
         """
+
+        if isinstance(facility, Facility):
+            facility = facility.identity
+
         i = IMS._get_ims_codes()
         if len(facility) > 0:
             return [x for x in i if x.facility == facility]

commonlib_reader-1.3.0/src/commonlib_reader/library.py

@@ -0,0 +1,174 @@
+from typing import List, Optional
+
+from commonlib_reader.connector import get_connector
+
+
+class AttributeDefinition:
+    """Definition of an attribute belonging to a CommonLib library.
+
+    Attributes:
+        name (str): Name of the attribute.
+        description (str): Description of the attribute.
+        required (bool): Whether the attribute is required.
+        include_in_identity (bool): Whether the attribute is part of the code identity.
+        regex (str): Validation pattern for the attribute value, if any.
+        reference_library_name (str): Library referenced by this attribute, if any.
+    """
+
+    def __init__(self, data: dict):
+        if not isinstance(data, dict):
+            raise ValueError("Input data must be a dict from api")
+        self._data = data
+
+    def __eq__(self, other):
+        if isinstance(other, AttributeDefinition):
+            return self._data == other._data
+        return False
+
+    def __str__(self):
+        return self.name
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str:
+        return self._data.get("description", "") or ""
+
+    @property
+    def required(self) -> bool:
+        return self._data.get("required", False)
+
+    @property
+    def include_in_identity(self) -> bool:
+        return self._data.get("includeInIdentity", False)
+
+    @property
+    def regex(self) -> str:
+        return self._data.get("regex", "") or ""
+
+    @property
+    def reference_library_name(self) -> str:
+        return self._data.get("referenceLibraryName", "") or ""
+
+
+class Library:
+    """A CommonLib library (a code-table definition and attribute schema).
+
+    A Library defines a code table and the attributes available on its Code
+    entries. It is not a container of Code instances; retrieve entries with
+    Code.get_codes() using this library's name.
+
+    Attributes:
+        name (str): Name of the library.
+        description (str): Description of the library.
+        is_valid (bool): Whether the library can still be used with new data.
+        scope_type (str): The scope type of the library.
+        is_global (bool): Whether the library is global.
+        is_scope_specific (bool): Whether the library is scope specific.
+        attribute_definitions (List[AttributeDefinition]): Attribute definitions of the library.
+    """
+
+    def __init__(self, data: dict):
+        if not isinstance(data, dict):
+            raise ValueError("Input data must be a dict from api")
+        self._data = data
+
+    def __eq__(self, other):
+        if isinstance(other, Library):
+            return self._data == other._data
+        return False
+
+    def __str__(self):
+        return f"{self.name} - {self.description}"
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str:
+        return self._data.get("description", "") or ""
+
+    @property
+    def is_valid(self) -> bool:
+        return self._data.get("isValid", False)
+
+    @property
+    def scope_type(self) -> str:
+        return self._data.get("scopeType", "") or ""
+
+    @property
+    def is_global(self) -> bool:
+        return self._data.get("isGlobal", False)
+
+    @property
+    def is_scope_specific(self) -> bool:
+        return self._data.get("isScopeSpecific", False)
+
+    @property
+    def attribute_definitions(self) -> List[AttributeDefinition]:
+        return [
+            AttributeDefinition(x)
+            for x in self._data.get("attributeDefinitions", []) or []
+        ]
+
+    @classmethod
+    def get(cls, name: str) -> "Library":
+        """Get a single library by name.
+
+        Args:
+            name (str): Name of the library to retrieve.
+
+        Returns:
+            Library: The requested library object.
+
+        Raises:
+            ValueError: If the library is not found.
+        """
+        for lib in cls.get_all(name=name):
+            if lib.name.upper() == name.upper():
+                return lib
+        raise ValueError(f"Library {name} not found")
+
+    @classmethod
+    def get_all(
+        cls, name: Optional[str] = None, scope: Optional[str] = None
+    ) -> List["Library"]:
+        """Get libraries as a list of Library objects.
+
+        Args:
+            name (str, optional): Criterion for library name (use % for wildcards).
+            scope (str, optional): Return libraries for this scope only.
+
+        Returns:
+            List[Library]: List of Library objects.
+        """
+        params = {}
+        if name is not None:
+            params["name"] = name
+        if scope is not None:
+            params["scope"] = scope
+
+        data = get_connector().get_json("/api/Library", params=params)
+        if not isinstance(data, list):
+            raise ValueError("Invalid library data from api")
+
+        return [cls(x) for x in data]
+
+    @staticmethod
+    def get_names() -> List[str]:
+        """Get library names as a list of strings. For dropdowns etc.
+
+        Returns:
+            List[str]: Sorted list of library name strings.
+        """
+        library_names = get_connector().get_json(url="/api/Library/NameList")
+        if isinstance(library_names, list) and all(
+            isinstance(name, str) for name in library_names
+        ):
+            library_names.sort()
+            return library_names
+
+        raise ValueError("Wrong data from API when getting library names.")

commonlib_reader-1.3.0/src/commonlib_reader/project.py

@@ -0,0 +1,74 @@
+from typing import List, Optional
+
+from commonlib_reader.connector import get_connector
+
+
+class Project:
+    """A project.
+
+    Attributes:
+        name (str): Name of the project.
+        description (str): Description of the project.
+        abbreviation (str): Project abbreviation / alias.
+        is_valid (bool): Whether the project can still be used with new data.
+    """
+
+    def __init__(self, data: dict):
+        if not isinstance(data, dict):
+            raise ValueError("Input data must be a dict from api")
+        self._data = data
+
+    def __eq__(self, other):
+        if isinstance(other, Project):
+            return self._data == other._data
+        return False
+
+    def __str__(self):
+        return f"{self.name} - {self.description}"
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str:
+        return self._data.get("description", "") or ""
+
+    @property
+    def is_valid(self) -> bool:
+        return self._data.get("isValid", False)
+
+    @property
+    def abbreviation(self) -> str:
+        return self._data.get("aliasName", "") or ""
+
+    @classmethod
+    def get_all(
+        cls,
+        name: Optional[str] = None,
+        abbreviation: Optional[str] = None,
+        only_valid: bool = True,
+    ) -> List["Project"]:
+        """Get projects as a list of Project objects.
+
+        Args:
+            name (str, optional): Criterion for project name (use % for wildcards).
+            abbreviation (str, optional): Criterion for project abbreviation (use % for wildcards).
+            only_valid (bool): If True, only return projects usable with new data. Defaults to True.
+
+        Returns:
+            List[Project]: List of Project objects.
+        """
+        params = {}
+        if name is not None:
+            params["name"] = name
+        if abbreviation is not None:
+            params["abbreviation"] = abbreviation
+        if not only_valid:
+            params["isValid"] = "null"
+
+        data = get_connector().get_json("/api/Project", params=params)
+        if not isinstance(data, list):
+            raise ValueError("Invalid project data from api")
+
+        return [cls(x) for x in data]

{commonlib_reader-1.2.0 → commonlib_reader-1.3.0}/src/commonlib_reader/tag.py

@@ -1,8 +1,7 @@
 from typing import List, Optional, Union
+from commonlib_reader.code import Code
 from commonlib_reader.utils import (
     attributes_list_to_dict,
-    get_code,
-    get_code_param,
     query_sql,
 )
 import re
@@ -19,11 +18,11 @@ class TagFormatElement:
     """A class representing the elements constructing a tag number.
 
     Attributes:
-        description (str)
-        name (str)
-        IsValid (bool)
-        IsRequired (bool)
-        IsSelected (bool)
+        description (str): Description of the tag format element.
+        name (str): Name of the tag format element.
+        is_valid (bool): Whether the tag format element is valid.
+        is_required (bool): Whether the tag format element is required.
+        is_selected (bool): Whether the tag format element is selected.
 
     """
 
@@ -35,10 +34,9 @@ class TagFormatElement:
             data (dict): Data containing different properties of a tag format element.
         """
         self._data = data
-
-        self.IsValid = bool(data["IsValid"])
-        self.IsRequired = bool(data["Required"])
-        self.IsSelected = bool(data["SelectFlag"])
+        self._is_valid = bool(data["IsValid"])
+        self._is_required = bool(data["Required"])
+        self._is_selected = bool(data["SelectFlag"])
 
     @property
     def name(self) -> str:
@@ -50,15 +48,30 @@ class TagFormatElement:
 
     @property
     def is_valid(self) -> bool:
-        return self.IsValid
+        return self._is_valid
+
+    @property
+    def IsValid(self) -> bool:
+        """Backward compatibility property for is_valid."""
+        return self.is_valid
 
     @property
     def is_required(self) -> bool:
-        return self.IsRequired
+        return self._is_required
+
+    @property
+    def IsRequired(self) -> bool:
+        """Backward compatibility property for is_required."""
+        return self.is_required
 
     @property
     def is_selected(self) -> bool:
-        return self.IsSelected
+        return self._is_selected
+
+    @property
+    def IsSelected(self) -> bool:
+        """Backward compatibility property for is_selected."""
+        return self.is_selected
 
     def get_TagFormat(self) -> "TagFormat":
         tag_format_id = self._data["TagFormat_ID"]
@@ -254,9 +267,9 @@ class TagType:
         inst_code (str): The facility code the tag type is associated with.
         name (str): The name of the tag type.
         description (str): A description of the tag type.
-        is_valid (bool): A flag indicating whether the tag type is valid.
         tag_category (str): The category under which this tag type falls.
-        STID_tag_Count (int): The number of STID tags associated with this tag type.
+        is_valid (bool): A flag indicating whether the tag type is valid.
+        stid_tag_count (int): The number of STID tags associated with this tag type.
     """
 
     def __init__(self, data: dict, inst_code: str):
@@ -270,10 +283,11 @@ class TagType:
         self._data = data
         self._attributes = attributes_list_to_dict(self._data["attributes"])
         self._inst_code = inst_code
+        self._stid_tag_count = 0
 
         for attr in self._data["attributes"]:
             if attr["definitionName"] == "STIDTagCount":
-                self.STID_tag_Count = int(attr["displayValue"])
+                self._stid_tag_count = int(attr["displayValue"])
 
     @property
     def inst_code(self) -> str:
@@ -295,9 +309,19 @@ class TagType:
     def is_valid(self) -> bool:
         return self._data["isValid"]
 
+    @property
+    def isValid(self) -> bool:
+        """Backward compatibility property for is_valid."""
+        return self.is_valid
+
     @property
     def stid_tag_count(self) -> int:
-        return self.STID_tag_Count
+        return self._stid_tag_count
+
+    @property
+    def STID_tag_Count(self) -> int:
+        """Backward compatibility property for stid_tag_count."""
+        return self.stid_tag_count
 
     def __str__(self):
         return f"{self.name} - {self.description}"
@@ -336,13 +360,9 @@ class TagType:
             List[TagType]: A list of TagType objects matching the criteria.
         """
 
-        params = {}
-        params["scope"] = inst_code
-        params["name"] = name
-
         tag_types = [
             TagType(x, inst_code=inst_code)
-            for x in get_code_param("TagType", params=params)
+            for x in Code._get_code_data("TagType", scope=inst_code, name=name)
         ]
 
         if tag_category:
@@ -455,14 +475,14 @@ class TagCategory:
     A class representing a Facility specific category of tag types.
 
     Attributes:
-        inst_code (str): Installation code for the facilitye the TagCategory is associated with.
+        inst_code (str): Installation code for the facility the TagCategory is associated with.
         name (str): Name of the tag category.
         description (str): Description of the tag category.
         is_valid (bool): Flag indicating whether the tag category is considered valid.
-        TagCategoryId (int): Unique identifier of the tag category.
-        TagCategoryDlg (str): Additional dialog information associated with the tag category.
-        IndividFlag (str): A flag indicating individual characteristics for the category.
-        SapFlCategory (str): Corresponding SAP functional location category.
+        tag_category_id (int): Unique identifier of the tag category.
+        tag_category_dlg (str): Additional dialog information associated with the tag category.
+        individ_flag (str): A flag indicating individual characteristics for the category.
+        sap_fl_category (str): Corresponding SAP functional location category.
     """
 
     def __init__(self, data, inst_code):
@@ -476,16 +496,20 @@ class TagCategory:
         self._data = data
         self._inst_code = inst_code
         self._attributes = attributes_list_to_dict(self._data["attributes"])
+        self._tag_category_id = 0
+        self._tag_category_dlg = ""
+        self._individ_flag = ""
+        self._sap_fl_category = ""
 
         for attr in self._data["attributes"]:
             if attr["definitionName"] == "TagCategoryId":
-                self.TagCategoryId = int(attr["displayValue"])
+                self._tag_category_id = int(attr["displayValue"])
             elif attr["definitionName"] == "TagCategoryDlg":
-                self.TagCategoryDlg = attr["displayValue"]
+                self._tag_category_dlg = attr["displayValue"]
             elif attr["definitionName"] == "IndividFlag":
-                self.IndividFlag = attr["displayValue"]
+                self._individ_flag = attr["displayValue"]
             elif attr["definitionName"] == "SapFlCategory":
-                self.SapFlCategory = attr["displayValue"]
+                self._sap_fl_category = attr["displayValue"]
 
         self._types = []
         self._formats = []
@@ -506,25 +530,49 @@ class TagCategory:
     def is_valid(self) -> bool:
         return self._data["isValid"]
 
+    @property
+    def isValid(self) -> bool:
+        """Backward compatibility property for is_valid."""
+        return self.is_valid
+
     @property
     def tag_category_id(self) -> int:
-        id = self._attributes.get("TagCategoryId")
-        if id is None:
+        id = self._tag_category_id
+        if id == 0:
             raise ValueError("TagCategoryId attribute not found")
-
         return int(id)
 
+    @property
+    def TagCategoryId(self) -> int:
+        """Backward compatibility property for tag_category_id."""
+        return self.tag_category_id
+
     @property
     def tag_category_dlg(self) -> str:
-        return self._attributes.get("TagCategoryDlg", "")
+        return self._tag_category_dlg
+
+    @property
+    def TagCategoryDlg(self) -> str:
+        """Backward compatibility property for tag_category_dlg."""
+        return self.tag_category_dlg
 
     @property
     def individ_flag(self) -> str:
-        return self._attributes.get("IndividFlag", "")
+        return self._individ_flag
+
+    @property
+    def IndividFlag(self) -> str:
+        """Backward compatibility property for individ_flag."""
+        return self.individ_flag
 
     @property
     def sap_fl_category(self) -> str:
-        return self._attributes.get("SapFlCategory", "")
+        return self._sap_fl_category
+
+    @property
+    def SapFlCategory(self) -> str:
+        """Backward compatibility property for sap_fl_category."""
+        return self.sap_fl_category
 
     def get_formats(self) -> List[TagFormat]:
         """Get tag formats for this specific tag category.
@@ -625,7 +673,9 @@ def _get_category_data(inst_code: str) -> List[dict]:
     global _cache
 
     if inst_code not in _cache["TagCategory"].keys():
-        _cache["TagCategory"][inst_code] = get_code("TagCategory", scope=inst_code)
+        _cache["TagCategory"][inst_code] = Code._get_code_data(
+            "TagCategory", scope=inst_code
+        )
 
     return _cache["TagCategory"][inst_code]
 
@@ -642,7 +692,7 @@ def _get_type_data(inst_code: str) -> List[dict]:
     global _cache
 
     if inst_code not in _cache["TagType"].keys():
-        _cache["TagType"][inst_code] = get_code("TagType", scope=inst_code)
+        _cache["TagType"][inst_code] = Code._get_code_data("TagType", scope=inst_code)
 
     return _cache["TagType"][inst_code]
 
@@ -656,7 +706,7 @@ def _get_master_type_data(scope="") -> List[dict]:
     global _cache
 
     if "MasterTagType" not in _cache.keys():
-        _cache["MasterTagType"] = get_code("MasterTagType")
+        _cache["MasterTagType"] = Code._get_code_data("MasterTagType")
 
     return _cache["MasterTagType"]
 
@@ -673,6 +723,8 @@ def _get_format_data(inst_code: str) -> List[dict]:
     global _cache
 
     if inst_code not in _cache["TagFormat"].keys():
-        _cache["TagFormat"][inst_code] = get_code("TagFormat", scope=inst_code)
+        _cache["TagFormat"][inst_code] = Code._get_code_data(
+            "TagFormat", scope=inst_code
+        )
 
     return _cache["TagFormat"][inst_code]

{commonlib_reader-1.2.0 → commonlib_reader-1.3.0}/src/commonlib_reader/unit.py

@@ -1,10 +1,19 @@
-from typing import Union
+from typing import List, Union
 
-from commonlib_reader.utils import get_code
+from commonlib_reader.code import Code
 
 
 class Unit:
-    _units = []
+    """A class representing a unit of measurement.
+
+    Properties:
+        name (str): The name of the unit.
+        description (str): A description of the unit.
+        identity (str): The unique identifier for the unit.
+        quantity (str): The quantity this unit measures.
+    """
+
+    _units = None
 
     def __init__(self, data: Union[dict, str]):
         if isinstance(data, str):
@@ -26,41 +35,48 @@ class Unit:
             raise ValueError("Input data must be a dict from codetable")
 
     @property
-    def name(self):
+    def name(self) -> str:
+        """Get the unit name."""
         return getattr(self, "_name", "")
 
     @name.setter
-    def name(self, value):
+    def name(self, value: str):
+        """Set the unit name."""
         self._name = value
 
     @property
-    def description(self):
+    def description(self) -> str:
+        """Get the unit description."""
         return getattr(self, "_description", "")
 
     @description.setter
-    def description(self, value):
+    def description(self, value: str):
+        """Set the unit description."""
         self._description = value
 
     @property
-    def identity(self):
+    def identity(self) -> str:
+        """Get the unit identity."""
         return getattr(self, "_identity", "")
 
     @identity.setter
-    def identity(self, value):
+    def identity(self, value: str):
+        """Set the unit identity."""
         self._identity = value
 
     @property
-    def quantity(self):
+    def quantity(self) -> str:
+        """Get the quantity measured by this unit."""
         return getattr(self, "Quantity", "")
 
     @classmethod
-    def get_units(cls):
+    def get_units(cls) -> List["Unit"]:
         """Get list of Unit objects of entries in code library. Caches locally in memory.
 
         Returns:
-            List[IMS]: list of Unit objects from entries in code library.
+            List[Unit]: List of Unit objects from entries in code library.
         """
-        if cls._units is None or len(cls._units) == 0:
-            cls._units = get_code("UnitOfMeasure")
+        if cls._units is None:
+            cls._units = Code._get_code_data("UnitOfMeasure")
 
         return [Unit(x) for x in cls._units]

{commonlib_reader-1.2.0 → commonlib_reader-1.3.0}/src/commonlib_reader/utils.py

@@ -1,5 +1,5 @@
 import json
-from typing import Dict, List, Optional
+from typing import Dict, List
 from urllib.parse import urljoin
 
 import requests
@@ -7,43 +7,6 @@ import requests
 from commonlib_reader.connector import get_connector
 
 
-def get_library_names() -> list[str]:
-    library_names = get_connector().get_json(url="/api/Library/NameList")
-    if isinstance(library_names, list) and all(
-        [isinstance(x, str) for x in library_names]
-    ):
-        library_names.sort()  # type: ignore
-        return library_names  # type: ignore
-
-    raise ValueError("Wrong data from API when getting library names.")
-
-
-def get_code(code: str, scope: Optional[str] = None, name: Optional[str] = None):
-    params = {}
-    if scope is not None:
-        params["scope"] = scope
-
-    if name is not None:
-        params["name"] = name
-    return get_code_param(code=code, params=params)
-
-
-def get_code_param(code, params=None):
-    """_summary_
-
-    Args:
-        code (_type_): _description_
-        params (_type_, optional): _description_. Defaults to None.
-
-    Returns:
-        _type_: _description_
-    """
-    if params is None:
-        params = {}
-
-    return get_connector().get_json(f"/api/Code/{code}", params=params)
-
-
 def query_sql(sql: str):
     return post_sql(sql=sql, take=0, skip=0)
 

commonlib_reader-1.2.0/PKG-INFO

@@ -1,39 +0,0 @@
-Metadata-Version: 2.3
-Name: commonlib-reader
-Version: 1.2.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 code tables
-- 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).
-
-## 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.2.0/README.md

@@ -1,26 +0,0 @@
-# commonlib-reader
-Connector package for Equinor [Commonlib](https://commonlib.equinor.com/) [api](https://commonlibapi.equinor.com/swagger/index.html). 
-
-Current features:
-- Reading code tables
-- 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).
-
-## 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`