stidapi 1.0.1__tar.gz

stidapi-1.0.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: stidapi
+Version: 1.0.1
+Summary: Python client for connecting to Equinor STIDapi
+License: Proprietary
+Author: Åsmund Våge Fannemel
+Author-email: asmf@equinor.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: certifi (>=2023.11.17,<2024.0.0)
+Requires-Dist: msal-bearer (>=0.2.1,<1.1.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: repository, https://github.com/equinor/STIDapi-python
+Description-Content-Type: text/markdown
+
+# STIDapi-python
+
+A simple wrapper package to interface Equinor [STIDapi](https://stidapi.equinor.com/).  
+Used to get plant, systen and tag and (future) doc data from STID rest api.
+
+
+## Use
+
+Try it out by running the [demo](examples/demo.py).
+
+## Installing
+
+To **install** call the following from your project environment:  
+`pip install git+https://github.com/equinor/STIDapi-python.git`
+
+To **upgrade** call the following from your project environment:  
+`pip install --upgrade git+https://github.com/equinor/STIDapi-python.git`
+
+To include in your project, add the following to your requirements file:  
+`git+https://github.com/equinor/STIDapi-python.git`
+
+or in requirements setup.py:  
+`'stidapi @ git+https://github.com/equinor/STIDapi-python'` 
+
+or in pyproject.toml:  
+`stidapi = { git = "https://github.com/Equinor/stidapi-python" }` 
+
+
+## Developing / testing
+
+Poetry is preferred for developers. Install with required packages for testing and coverage:  
+`poetry install`
+
+Call `poetry run pytest` to run tests.
+
+To generate coverage report in html run `poetry run pytest --cov=stidapi tests/ --cov-report html`
+
+

stidapi-1.0.1/README.md

@@ -0,0 +1,37 @@
+# STIDapi-python
+
+A simple wrapper package to interface Equinor [STIDapi](https://stidapi.equinor.com/).  
+Used to get plant, systen and tag and (future) doc data from STID rest api.
+
+
+## Use
+
+Try it out by running the [demo](examples/demo.py).
+
+## Installing
+
+To **install** call the following from your project environment:  
+`pip install git+https://github.com/equinor/STIDapi-python.git`
+
+To **upgrade** call the following from your project environment:  
+`pip install --upgrade git+https://github.com/equinor/STIDapi-python.git`
+
+To include in your project, add the following to your requirements file:  
+`git+https://github.com/equinor/STIDapi-python.git`
+
+or in requirements setup.py:  
+`'stidapi @ git+https://github.com/equinor/STIDapi-python'` 
+
+or in pyproject.toml:  
+`stidapi = { git = "https://github.com/Equinor/stidapi-python" }` 
+
+
+## Developing / testing
+
+Poetry is preferred for developers. Install with required packages for testing and coverage:  
+`poetry install`
+
+Call `poetry run pytest` to run tests.
+
+To generate coverage report in html run `poetry run pytest --cov=stidapi tests/ --cov-report html`
+

stidapi-1.0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[tool.poetry]
+name = "stidapi"
+version = "1.0.1"
+description = "Python client for connecting to Equinor STIDapi"
+authors = ["Åsmund Våge Fannemel <asmf@equinor.com>"]
+license = "Proprietary"
+readme = "README.md"
+
+[tool.poetry.urls]
+"repository" = "https://github.com/equinor/STIDapi-python"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+certifi = "^2023.11.17"
+msal-bearer = ">=0.2.1,<1.1.0"
+requests = "^2.31.0"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^7.4.4"
+pytest-cov = "^4.1.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

stidapi-1.0.1/stidapi/Doc.py

@@ -0,0 +1,152 @@
+from typing import List
+from urllib.parse import urljoin
+import stidapi.utils as u
+
+
+class File:
+    """Class for internal use. Copy of File as returned by document endpoint."""
+
+    # "id": 0,
+    # "instCode": "string",
+    # "fileName": "string",
+    # "objectType": "string",
+    # "description": "string",
+    # "fileOrder": 0,
+    # "prodViewCode": "string",
+    # "insertedDate": "2024-04-09T11:46:07.501Z",
+    # "thumbnail": "string",
+    # "fileSize": 0,
+    # "blobId": "string"
+
+    def __init__(self, data: dict):
+        for prop in data.keys():
+            self.__setattr__(prop, data[prop])
+
+    def __str__(self):
+        return f"InstCode: {self.instCode}, FileName: {self.fileName}, Description: {self.description}, ObjectType: {self.objectType}"
+
+
+class Revision:
+    """Class for internal use. Copy of Revision as returned by document endpoint."""
+
+    # "revNo": "string",
+    # "revStatus": "string",
+    # "revStatusDescription": "string",
+    # "revDate": "2024-04-09T11:46:07.501Z",
+    # "isCurrent": true,
+    # "projectCode": "string",
+    # "projectCodeDescription": "string",
+    # "reasonForIssue": "string",
+    # "acceptanceCode": 0,
+    # "acceptanceCodeDescription": "string",
+    # "files": [File objects]
+
+    def __init__(self, data: dict):
+        self._data = data
+        for prop in data.keys():
+            if prop == "files":
+                continue
+            self.__setattr__(prop, data[prop])
+
+    def get_files(self):
+        return [File(x) for x in self._data["files"]]
+
+    def __str__(self):
+        return (
+            f"RevNo: {self.revNo}, RevStatus: {self.revStatus}, RevDate: {self.revDate}"
+        )
+
+
+class Doc:
+    def __init__(self, inst_code: str, doc_no: str):
+        """
+        Object initializer for Doc
+        :param inst_code: STID installation code
+        :param doc_no: Doc number as found in STID
+
+        Initializes object and gets data from STID if available.
+        """
+        self.inst_code = ""
+        self.no = ""
+        self.title = ""
+
+        self.category = ""
+        self.discipline = ""
+        self.type = ""
+
+        self._data = Doc.get(inst_code=inst_code, doc_no=doc_no)
+
+        common_prop = [
+            ("instCode", "inst_code"),
+            ("docNo", "no"),
+            ("docTitle", "title"),
+            ("docCategoryDescription", "category"),
+            ("disciplineCodeDescription", "discipline"),
+            ("docTypeDescription", "type"),
+        ]
+        for prop in common_prop:
+            if prop[0] in self._data:
+                self.__setattr__(prop[1], self._data[prop[0]])
+            else:
+                self.__setattr__(prop[1], "")
+
+        self.docNo = self.no
+        self.description = self.title
+
+        optional_prop = []
+        for prop in optional_prop:
+            if prop[0] in self._data and self._data[prop[0]] is not None:
+                self.__setattr__(prop[1], self._data[prop[0]])
+
+    def get_current_revision(self) -> Revision:
+        return Revision(self._data["currentRevision"])
+
+    def get_files(self) -> List[File]:
+        return self.get_current_revision().get_files()
+
+    def __str__(self):
+        return f"InstCode: {self.inst_code}, No: {self.no}, Title: {self.title}"
+
+    # "instCode": "string", "instCodeDescription": "string",
+    # "docNo": "string", "docTitle": "string",
+    # "docCategory": "string", "docCategoryDescription": "string",
+    # "docType": "string", "docTypeDescription": "string",
+    # "projectCode": "string", "projectCodeDescription": "string",
+    # "contrCode": "string", "contrCodeDescription": "string",
+    # "disciplineCode": "string","disciplineCodeDescription": "string",
+    # "locationCode": "string","locationCodeDescription": "string",
+    # "docClass": "string","docClassName": "string",        "docClassDescription": "string",
+    # "poNo": "string","poNoDescription": "string",
+    # "system": "string","systemDescription": "string",
+    # "remark": "string",
+    # "supplDocNo": "string",
+    # "companyCode": "string",
+    # "source": "string",
+    # "size": "string",
+    # "priority": "string",        "priorityDescription": "string",
+    # "weightBearing": "string",
+    # "productCode": "string",
+    # "insulationClass": "string",        "insulationClassDescription": "string",
+    # "tagRefCount": 0,        "docRefCount": 0,
+    # "currentRevision": { Revision object },
+    # "projectRevisions": [ { Revision object }],
+    # "additionalFields": [{"type": "string","typeDescription": "string","value": "string","description": "string"}],
+    # "projects": [{"instCode": "string","projectCode": "string","description": "string","stidDeliveryCode": "string",
+    #        "insertedDate": "2024-04-09T11:46:07.501Z","isPrimary": true,"isValid": true,}],
+    # "purchaseOrders": [
+    #    {"instCode": "string","poNo": "string","description": "string","insertedDate": "2024-04-09T11:46:07.501Z","isPrimary": true,"isValid": true}],
+    # "apiResponseTime": "string",
+
+    @staticmethod
+    def get(inst_code: str, doc_no: str):
+        """
+        Get tag data from STID for a single doc.
+        :param inst_code: STID installation code
+        :param doc_no: STID doc number
+        :return: Dictionary of data from STID for doc.
+        """
+
+        url = urljoin(
+            u.get_api_url(), str(inst_code) + "/document?docNo=" + str(doc_no)
+        )
+        return u.get_json(url)

stidapi-1.0.1/stidapi/Plant.py

@@ -0,0 +1,113 @@
+from typing import List, Union
+from urllib.parse import urljoin
+
+import stidapi.utils as u
+
+
+class Plant:
+    _plant_list = []
+
+    def __init__(self, code: Union[str, int] = "", data=None):
+        self.inst_code = ""
+        self.sap_id = ""
+        self.description = ""
+        self.business_area = ""
+        self.ims = ""
+
+        if isinstance(code, int):
+            code = str(code)
+
+        if isinstance(code, str) and len(code) > 0:
+            self.inst_code = code
+            if data is None:
+                data = Plant._get_data(code)
+
+        if isinstance(data, dict) and len(data) > 0:
+            self._data = data
+            self.inst_code = data["instCode"]
+            self.sap_id = data["sapPlantId"]
+            self.description = data["description"]
+            self.business_area = data["businessArea"]
+            self.ims = data["imsPlant"]
+        else:
+            self._data = {}
+
+        self.plant_code = self.inst_code
+
+    def __str__(self):
+        if not isinstance(self.inst_code, str) or len(self.inst_code) == 0:
+            return "Empty plant object"
+
+        if len(self._data) > 0:
+            return (
+                "Plant "
+                + str(self.inst_code)
+                + " - "
+                + str(self.description)
+                + " with data"
+            )
+        else:
+            return (
+                "Plant "
+                + str(self.inst_code)
+                + " - "
+                + str(self.description)
+                + " with no data"
+            )
+
+    @classmethod
+    def get_all_inst_code(cls) -> List[str]:
+        return [x["instCode"] for x in Plant.get_all_data()]
+
+    @classmethod
+    def get_all_data(cls):
+        if len(cls._plant_list) == 0:
+            url = urljoin(u.get_api_url(), "plants")
+            parsed_json = u.get_json(url)
+
+            if isinstance(parsed_json, list):
+                cls._plant_list = [x for x in parsed_json if "instCode" in x]
+
+        return cls._plant_list
+
+    @classmethod
+    def _get_data(cls, code: Union[str, int]):
+        if (
+            code is None
+            or (isinstance(code, str) and len(code) == 0)
+            or (isinstance(code, int) and code < 1000)
+        ):
+            return None
+
+        plant_data_list = Plant.get_all_data()
+
+        if len(plant_data_list) == 0:
+            return None
+
+        if isinstance(code, str):
+            plant_data_list = [
+                x
+                for x in plant_data_list
+                if x["instCode"].lower() == code.lower() or x["sapPlantId"] == code
+            ]
+        elif isinstance(code, int):
+            plant_data_list = [x for x in plant_data_list if x["sapPlantId"] == code]
+        else:
+            return ValueError("Input code must be string or int.")
+
+        if len(plant_data_list) > 0:
+            return plant_data_list[0]
+        else:
+            print("Warning: did not get data for Plant " + str(code))
+            return None
+
+    @classmethod
+    def get_plant(cls, inst_code: Union[str, int]) -> "Plant":
+        plant_data = Plant._get_data(inst_code)
+        return Plant(inst_code, plant_data)
+
+    @classmethod
+    def get_plants(cls) -> List["Plant"]:
+        plant_data_list = Plant.get_all_data()
+
+        return [Plant(x["instCode"], x) for x in plant_data_list]

stidapi-1.0.1/stidapi/System.py

@@ -0,0 +1,40 @@
+from urllib.parse import urljoin
+
+import stidapi.utils as u
+
+
+class System:
+    def __init__(self, inst_code: str = "", data=None):
+        if isinstance(inst_code, str) and len(inst_code) > 0:
+            self.inst_code = inst_code
+
+        self._data = {}
+        self.no = ""
+        self.description = ""
+        self.inst_code = ""
+        self.valid = None
+
+        if isinstance(data, dict) and len(data) > 0:
+            self._data = data
+            self.inst_code = data["instCode"]
+            self.no = data["system"]
+            self.description = data["description"]
+            self.valid = data["validFlg"]
+
+    @staticmethod
+    def get_all_data(inst_code, is_valid: bool = False):
+        """
+
+        :param get_statistics:
+        :return:
+        """
+
+        url = urljoin(u.get_api_url(), f"{inst_code}/system?isValid={is_valid}")
+        parsed_json = u.get_json(url)
+
+        return parsed_json
+
+    @staticmethod
+    def get_system(inst_code: str, get_statistics: bool = False):
+        plant_data = System.get_all_data(inst_code, get_statistics)
+        return [System(inst_code, x) for x in plant_data]

stidapi-1.0.1/stidapi/Tag.py

@@ -0,0 +1,262 @@
+from typing import List, Union
+from urllib.parse import urljoin
+
+from stidapi.Doc import Doc
+from stidapi.Plant import Plant
+import stidapi.utils as u
+
+
+class Tag:
+    def __init__(self, inst_code: str, tag_no: str):
+        """
+        Object initializer for Tag
+        :param inst_code: STID installation code
+        :param tag_no: Tag number as found in STID
+
+        Initializes object and gets data from STID if available.
+        """
+
+        self.inst_code = ""
+        self.no = ""
+        self.description = ""
+        self.category = ""
+        self.discipline = ""
+        self.is_function = False
+        self.is_signal = False
+
+        self._data = Tag.get(inst_code=inst_code, tag_no=tag_no)
+
+        common_prop = [
+            ("instCode", "inst_code"),
+            ("tagNo", "no"),
+            ("description", "description"),
+            ("tagCategoryDescription", "category"),
+            ("disciplineCodeDescription", "discipline"),
+        ]
+        for prop in common_prop:
+            if prop[0] in self._data:
+                self.__setattr__(prop[1], self._data[prop[0]])
+            else:
+                self.__setattr__(prop[1], "")
+
+        self.tag_no = self.no
+
+        if "isFunction" in self._data and self._data["isFunction"]:
+            self.is_function = True
+            function_prop = [("functionBlock", "FB")]
+            for prop in function_prop:
+                if prop[0] in self._data:
+                    self.__setattr__(prop[1], self._data[prop[0]])
+
+        if "isSignal" in self._data and self._data["isSignal"]:
+            self.is_signal = True
+            signal_prop = [("signalType", "signalType")]
+            for prop in signal_prop:
+                if prop[0] in self._data:
+                    self.__setattr__(prop[1], self._data[prop[0]])
+
+        optional_prop = [
+            ("setpointL", "L"),
+            ("setpointLl", "LL"),
+            ("setpointH", "H"),
+            ("setpointHh", "HH"),
+        ]
+        for prop in optional_prop:
+            if prop[0] in self._data and self._data[prop[0]] is not None:
+                self.__setattr__(prop[1], self._data[prop[0]])
+
+    def get_addition_field(self, field: str = "") -> List[dict]:
+        """Get list of additional fields. Optionally filter by type.
+
+        Args:
+            field (str, optional): Filter by field type. Defaults to "" which returns all.
+
+        Returns:
+            List[dict]: List of additional fields.
+        """
+        if field is None or len(field) == 0:
+            return self._data["additionalFields"]
+
+        return [x for x in self._data["additionalFields"] if x["type"] == field]
+
+    def get_doc(self) -> List[Doc]:
+        """Get list of documents that tag refers to.
+
+        Returns:
+            List[Doc]: List of referred Documents
+        """
+
+        return [Doc(x["instCode"], x["docNo"]) for x in self.get_doc_references()]
+
+    def get_doc_references(self) -> List[dict]:
+        """Get doc references of tag from stidapi as dicts.
+
+        Returns:
+            List[dict]: List of dicts describing document references.
+        """
+        url = urljoin(
+            u.get_api_url(),
+            f"{str(self.inst_code)}/tag/document-refs?tagNo={str(self.tag_no)}&noContentAs200=true",
+        )
+        json = u.get_json(url)
+        return json
+
+    def get_functional_location(self) -> str:
+        """Get functional location of Tagged item or empty string if it does not have a functional location.
+
+        Returns:
+            str: Functional location or empty string if tagged item does not have a functional location.
+        """
+
+        url = urljoin(
+            u.get_api_url(),
+            f"portal/{self.inst_code}/tag/sap-tag?tagNo={self.tag_no}",
+        )
+        json = u.get_json(url)
+
+        if isinstance(json, dict) and "functionalLocation" in json.keys():
+            return json["functionalLocation"]
+        else:
+            return ""
+
+    def __str__(self):
+        """
+        Overload string representation of object.
+        :return: Pretty-print string describing Tag object
+        """
+        if isinstance(self._data, dict) and len(self._data) > 0:
+            return str(self.tag_no) + "@" + str(self.inst_code) + " with data"
+        else:
+            return str(self.tag_no) + "@" + str(self.inst_code) + " with no data"
+
+    def prune_empty_data(self):
+        """
+        Remove all empty, i.e., containing None, entries in data dictionary.
+        """
+        if isinstance(self._data, dict) and len(self._data) > 0:
+            self._data = {k: v for k, v in self._data.items() if v is not None}
+        else:
+            print("Tag has no data to prune")
+
+    @staticmethod
+    def get(inst_code: str, tag_no: str):
+        """
+        Get tag data from STID for a single tag.
+        :param inst_code: STID installation code
+        :param tag_no: STID tag number
+        :return: Dictionary of data from STID for tag.
+        """
+
+        url = urljoin(u.get_api_url(), str(inst_code) + "/tag?tagNo=" + str(tag_no))
+        return u.get_json(url)
+
+    @staticmethod
+    def search(
+        inst_code: str,
+        tag_no: str = "",
+        description: str = "",
+        tag_status: str = "",
+        tag_category: int = -1,
+        tag_type: str = "",
+        system: str = "",
+        discipline_code: str = "",
+        skip: int = 0,
+        take: int = 50,
+    ):
+        # string subSystem, string mainSystem, string projectCode, string poNo,
+        # string contrCode, string locationCode, string plantId,
+        if len(tag_no) > 0:
+            tag_no = "tagNo=" + tag_no + "&"
+
+        if len(description) > 0:
+            description = "description=" + description + "&"
+
+        if len(tag_status) > 0:
+            tag_status = "tagStatus=" + tag_status + "&"
+
+        if tag_category > 0:
+            tag_category_string = "tagCategory=" + str(tag_category) + "&"
+        else:
+            tag_category_string = ""
+
+        if len(tag_type) > 0:
+            tag_type = "tagType=" + tag_type + "&"
+
+        if len(system) > 0:
+            system = "system=" + system + "&"
+
+        if len(discipline_code) > 0:
+            discipline_code = "disciplineCode=" + discipline_code + "&"
+
+        skip_string = "skip=" + str(skip) + "&"
+
+        # take shall be last, thus no trailing &
+        take_string = "take=" + str(take)
+
+        url = urljoin(
+            u.get_api_url(),
+            f"/{inst_code}/tags"
+            + "?"
+            + str(tag_no)
+            + str(description)
+            + str(tag_status)
+            + str(tag_category_string)
+            + str(tag_type)
+            + str(system)
+            + str(skip_string)
+            + str(take_string),
+        )
+
+        return u.get_json(url)
+
+    @staticmethod
+    def search_additional_field(
+        inst_code: str, field_name: str, value: str
+    ) -> List[dict]:
+        url = urljoin(
+            u.get_api_url(),
+            f"/{inst_code}/tag-additional-field/{field_name}?searchValue={value}&noContentAs200=true",
+        )
+        return u.get_json(url)
+
+    @staticmethod
+    def get_from_additional_field(
+        field_name: str,
+        value: str,
+        inst_code: Union[str, List[str]] = None,
+        stop_first=True,
+    ) -> List["Tag"]:
+        """Get List of Tag objects by searching for additional fields
+        field_name: Name of additional field
+        value: Value of additional field
+        inst_code: STID plant code, or list of codes, to limit search to.
+                Defaults to empty which will search all.
+        stop_first: Set to False to get matches from all provided inst_code,
+                else will stop at first match. Defaults to False.
+
+        Returns:
+            (List["Tag"]): List of Tag objects for matches.
+        """
+
+        if inst_code is None or (isinstance(inst_code, str) and len(inst_code) == 0):
+            inst_code = Plant.get_all_inst_code()
+
+        if isinstance(inst_code, str):
+            inst_code = [inst_code]
+
+        res = []
+
+        for code in inst_code:
+            data = [
+                Tag(inst_code=x["instCode"], tag_no=x["tagNo"])
+                for x in Tag.search_additional_field(
+                    inst_code=code, field_name=field_name, value=value
+                )
+            ]
+            if len(data) > 0:
+                res.extend(data)
+
+                if stop_first:
+                    break
+
+        return res

stidapi-1.0.1/stidapi/utils.py

@@ -0,0 +1,48 @@
+import json
+from types import SimpleNamespace
+
+import requests
+
+
+def get_api_url():
+    return "https://stidapi.equinor.com/"
+
+
+def get_auth():
+    from msal_bearer.BearerAuth import BearerAuth, get_login_name
+
+    tenantID = "3aa4a235-b6e2-48d5-9195-7fcf05b459b0"
+    clientID = "1a35a8df-b48d-40df-987b-267968b1b198"  # stidapi-python
+    scopes = ["1734406c-3449-4192-a50d-7c3a63d3f57d/user_impersonation"]
+    auth = BearerAuth.get_auth(
+        tenantID=tenantID,
+        clientID=clientID,
+        scopes=scopes,
+        username=f"{get_login_name()}@equinor.com",
+    )
+
+    return auth
+
+
+def get_object_from_json(text: str):
+    if isinstance(text, list):
+        obj = [json.loads(x, object_hook=lambda d: SimpleNamespace(**d)) for x in text]
+    else:
+        obj = json.loads(text, object_hook=lambda d: SimpleNamespace(**d))
+    return obj
+
+
+def get_json(url: str):
+    response = requests.get(url, auth=get_auth())
+    # response.raise_for_status()
+    if response.status_code == 200:
+        try:
+            return response.json()
+        except json.JSONDecodeError:
+            print(
+                f"Warning: {str(url)} returned successfully, but not with a valid json response"
+            )
+    else:
+        print(f"Warning: {str(url)} returned status code {response.status_code}")
+
+    return []