bruce-models 0.0.1__tar.gz

bruce_models-0.0.1/MANIFEST.in

@@ -0,0 +1,10 @@
+# Include README and LICENSE files.
+include README.md
+include LICENSE
+
+# Include all files in a specific folder.
+recursive-include bruce_models
+
+# Exclude unwanted files.
+exclude *.pyc
+exclude public

bruce_models-0.0.1/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.1
+Name: bruce-models
+Version: 0.0.1
+Summary: This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.
+Author: Matvey Lavrinovich
+Author-email: matveylavrinovich@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0
+
+# bruce-models
+
+This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.
+
+### Local build
+
+- `pip install .`
+
+- `python ./public/main.py` (to test it loads after build)
+
+### Test a release build
+
+- `python -m build`

bruce_models-0.0.1/README.md

@@ -0,0 +1,13 @@
+# bruce-models
+
+This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.
+
+### Local build
+
+- `pip install .`
+
+- `python ./public/main.py` (to test it loads after build)
+
+### Test a release build
+
+- `python -m build`

bruce_models-0.0.1/bruce_models/__init__.py

@@ -0,0 +1,15 @@
+from .api.api import Api
+from .api.bruce_api import BruceApi
+from .api.guardian_api import GuardianApi
+from .scenario.scenario import Scenario
+from .entity.entity import Entity
+from .entity.entity_type import EntityType
+
+__all__ = [
+    "Api"
+    "BruceApi",
+    "GuardianApi",
+    "Scenario",
+    "Entity",
+    "EntityType"
+]

bruce_models-0.0.1/bruce_models/api/__init__.py

@@ -0,0 +1,3 @@
+from .api import Api
+from .bruce_api import BruceApi
+from .guardian_api import GuardianApi

bruce_models-0.0.1/bruce_models/api/api.py

@@ -0,0 +1,18 @@
+import requests
+from typing import Dict
+
+class Api:
+    @staticmethod
+    def parse_result(result: requests.Response) -> Dict:
+        """
+        Parses the result of an API request to a Nextspace endpoint.
+        """
+        if result.status_code >= 400 or result.status_code < 200:
+            error = result.json()
+            raise Exception(error)
+        
+        # Technically, our API can return other types such as a raw CSV file.
+        # However, it is very rare.
+        # If we need to update this method, we can check for the type and wrap non-json (CSV) in a dict.
+
+        return result.json()

bruce_models-0.0.1/bruce_models/api/bruce_api.py

@@ -0,0 +1,118 @@
+import requests
+from typing import Optional, Dict, TypedDict
+import threading
+from bruce_models import Api
+from bruce_models import GuardianApi
+
+class BruceApiParams(TypedDict):
+    """
+    Represents the parameters for the Bruce API.
+    """
+    base_url: Optional[str]
+    session_id: Optional[str]
+    account_id: Optional[str]
+    env: Optional[str]
+    guardian: Optional[GuardianApi]
+
+class BruceApi:
+    """
+    A basic API wrapper for making HTTP requests.
+    """
+    def __init__(self, params: BruceApiParams):
+        self._loading = True
+        self._lock = threading.Lock()
+        self._init(params)
+
+    @property
+    def loading(self) -> bool:
+        return self._loading
+
+    def _init(self, params):
+        try:
+            # If no env was supplied, set to PROD.
+            self.env = params.get("env", "PROD")
+            self.base_url = params.get("base_url")
+            self.session_id = params.get("session_id")
+            self.account_id = params.get("account_id")
+
+            # If no base_url was supplied, but an account_id was, we can request for it.
+            if not self.base_url and self.account_id:
+                # Use Guardian instance if was supplied, if not, create one.
+                guardian = params.get("guardian", GuardianApi({ "env": self.env, "session_id": self.session_id }))
+                account = guardian.GET(f"account/{self.account_id}")
+                self.base_url = account.get("URL").get("Base")
+            elif not self.base_url:
+                raise ValueError("A valid base URL or account ID is required.")
+            
+            self._loading = False
+        except Exception as e:
+            self._loading = False
+            raise e
+
+    def set_session_id(self, session_id: str):
+        """
+        Sets the x-sessionid header for all future requests.
+        """
+        self.session_id = session_id
+
+    def get_env(self):
+        """
+        Returns the current environment.
+        """
+        return self.env
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Builds the headers for all requests that are sent.
+        """
+        headers = {
+            "Content-Type": "application/json"
+        }
+        if self.session_id:
+            headers["x-sessionid"] = self.session_id
+        return headers
+
+    def get(self, url: str, params: dict = {}) -> Dict:
+        """
+        Sends a GET request to the API.
+        The URL should be absolute.
+        """
+        self._wait_for_loading()
+        response = requests.get(url, headers=self._build_headers(), params=params)
+        return Api.parse_result(response)
+
+    def GET(self, url: str, params: dict = {}) -> Dict:
+        """
+        Sends a GET request to the API.
+        The URL should be relative to the base URL.
+        """
+        self._wait_for_loading()
+        full = f"{self.base_url}/{url.lstrip('/')}"
+        return self.get(full, params)
+    
+    def post(self, url: str, data: dict = {}, params: dict = {}) -> Dict:
+        """
+        Sends a POST request to the API.
+        The URL should be absolute.
+        """
+        self._wait_for_loading()
+        response = requests.post(url, headers=self._build_headers(), json=data, params=params)
+        return Api.parse_result(response)
+    
+    def POST(self, url: str, data: dict = {}, params: dict = {}) -> Dict:
+        """
+        Sends a POST request to the API.
+        The URL should be relative to the base URL.
+        """
+        self._wait_for_loading()
+        full = f"{self.base_url}/{url.lstrip('/')}"
+        return self.post(full, data, params)
+
+    def _wait_for_loading(self):
+        """
+        Blocks further requests until the loading state is set to False.
+        This method will prevent further requests until initialization is complete.
+        """
+        with self._lock:
+            while self._loading:
+                pass

bruce_models-0.0.1/bruce_models/api/guardian_api.py

@@ -0,0 +1,98 @@
+import requests
+from typing import Optional, Dict, TypedDict
+import threading
+from bruce_models import Api
+
+class GuardianApiParams(TypedDict):
+    """
+    Represents the parameters for the Guardian API.
+    """
+    base_url: Optional[str]
+    session_id: Optional[str]
+    env: Optional[str]
+
+class GuardianApi:
+    """
+    A basic API wrapper for making HTTP requests.
+    """
+    def __init__(self, params: GuardianApiParams):
+        self._loading = True
+        self._lock = threading.Lock()
+        self._init(params)
+
+    @property
+    def loading(self) -> bool:
+        return self._loading
+
+    def _init(self, params):
+        try:
+            # If no env was supplied, set to PROD.
+            self.env = params.get("env", "PROD")
+            self.base_url = params.get("base_url")
+            self.session_id = params.get("session_id")
+
+            # If no base_url was supplied, we'll calculate it based on the env.
+            if not self.base_url:
+                if self.env == "DEV":
+                    self.base_url = "https://guardian.nextspace-dev.net/"
+                elif self.env == "STG":
+                    self.base_url = "https://guardian.nextspace-stg.net/"
+                elif self.env == "UAT":
+                    self.base_url = "https://guardan.nextspace-uat.net/"
+                else:
+                    self.base_url = "https://guardian.nextspace.host/"
+            
+            self._loading = False
+        except Exception as e:
+            self._loading = False
+            raise e
+
+    def set_session_id(self, session_id: str):
+        """
+        Sets the x-sessionid header for all future requests.
+        """
+        self.session_id = session_id
+
+    def get_env(self):
+        """
+        Returns the current environment.
+        """
+        return self.env
+
+    def _build_headers(self) -> Dict[str, str]:
+        """
+        Builds the headers for all requests that are sent.
+        """
+        headers = {
+            "Content-Type": "application/json"
+        }
+        if self.session_id:
+            headers["x-sessionid"] = self.session_id
+        return headers
+
+    def get(self, url: str) -> Dict:
+        """
+        Sends a GET request to the API.
+        The URL should be absolute.
+        """
+        self._wait_for_loading()
+        response = requests.get(url, headers=self._build_headers())
+        return Api.parse_result(response)
+
+    def GET(self, url: str) -> Dict:
+        """
+        Sends a GET request to the API.
+        The URL should be relative to the base URL.
+        """
+        self._wait_for_loading()
+        full = f"{self.base_url}/{url.lstrip('/')}"
+        return self.get(full)
+    
+    def _wait_for_loading(self):
+        """
+        Blocks further requests until the loading state is set to False.
+        This method will prevent further requests until initialization is complete.
+        """
+        with self._lock:
+            while self._loading:
+                pass

bruce_models-0.0.1/bruce_models/entity/__init__.py

@@ -0,0 +1,2 @@
+from .entity import Entity
+from .entity_type import EntityType

bruce_models-0.0.1/bruce_models/entity/entity.py

@@ -0,0 +1,150 @@
+from typing import Optional, TypedDict, List, Any
+from bruce_models import BruceApi
+
+class JEntityInternal(TypedDict):
+    """
+    Represents the Nextspace internal properties defined under the 'Bruce' key of an Entity record.
+    """
+
+    # ID of the entity.
+    # If unset an ID will be generated during the Update request.
+    ID: Optional[str]
+    # Name of the Entity.
+    # This can be set directly, or the Entity Type can be configured to use a specific attribute.
+    # If the attribute is changed, a re-index should be launched to update the name.
+    Name: Optional[str]
+    # Nextspace internal ID.
+    # Readonly and created on Entity creation.
+    InternalID: Optional[int]
+
+    # Entity Type ID.
+    EntityType_ID: str
+
+    # ID of the user who created the entity.
+    # Will be set automatically on creation.
+    CreatedBy_User_ID: Optional[str]
+    # Created date/time of the entity.
+    CreatedTime: Optional[Any]
+    # Array of associated tags (Used to be called layers).
+    # Update to change what tags are associated. Exclude from data to keep it the same.
+    Layer_ID: Optional[List[int]]
+
+    # Scenario this is related to. Typically the Key, but if the record isn't found then it will be the ID.
+    # When present, this indicates this is a variant of the primary record and not the primary record.
+    Scenario: Optional[str | int]
+
+    # If we're retrieving historic records, then these values are populated,
+    # to indicate the historic data key and date-time.
+    HistoricAttrKey: Optional[str]
+    HistoricDateTime: Optional[str]
+    
+    # Marker that indicates the entity is a calculated alternative schema.
+    # This is used to indicate that the entity is read-only and should not be saved.
+    SchemaID: Optional[str]
+
+    # Entity relative position to parent within an assembly.
+    AssemblyPosition: Optional[List[List[float]]]
+
+    # Entity location in degrees/meters.
+    # This is typically relative to the active scene's terrain.
+    # However what its relative to is dictated by the Entity Style during rendering.
+    # This dictates where 3D models are placed, in the absence of VectorGeometry-
+    #this is used to place vector points as well.
+    Location: Optional[Any]
+    # These are applied only to the Entity's LOD and not the VectorGeometry.
+    Transform: Optional[Any]
+    # Entity boundaries in degrees/meters.
+    Boundaries: Optional[Any]
+    # Entity vector geometry. Eg: a point, polyline, or polygon to draw.
+    VectorGeometry: Optional[Any]
+
+class Entity:
+    """
+    Represents an Entity in Nextspace.
+    You will find the JEntity data-model and all related API communication here.
+    """
+
+    class JEntity(TypedDict, total=False):
+        """
+        Represents the JSON structure of an Entity.
+        """
+        Bruce: JEntityInternal
+        __additional__: Optional[dict[str, Any]]
+
+    @staticmethod
+    def get(api: BruceApi, entity_id: str = "") -> JEntity:
+        """
+        Retrieves an Entity by its ID.
+        """
+        if not entity_id:
+            raise ValueError("A valid Entity ID is required.")
+        return api.GET(f"v3/entity/{entity_id}")
+    
+    @staticmethod
+    def get(api: BruceApi, entity_id: str = "", scenario: Optional[str | int] = 0) -> JEntity:
+        """
+        Retrieves an Entity by its ID and Scenario.
+        """
+        if not entity_id:
+            raise ValueError("A valid Entity ID is required.")
+        return api.GET(f"v3/entity/{entity_id}?Scenario={scenario}")
+    
+    @staticmethod
+    def get_list(
+        api: BruceApi, 
+        entity_type_id: str = "", 
+        skip: int = 0, 
+        take: int = 50,
+        scenario: Optional[str | int] = 0
+    ) -> List[JEntity]:
+        """
+        Retrieves a list of Entities.
+        """
+        params = {
+            "Type": entity_type_id,
+            "PageIndex": skip,
+            "PageSize": take,
+            "Scenario": scenario
+        }
+        data = api.GET("v3/entities", params)
+        return data["Items"]
+    
+    @staticmethod
+    def update(
+        api: BruceApi,
+        # Entity to update/create.
+        entity: JEntityInternal, 
+        # (Optional) Scenario to update the Entity under.
+        # It can be specified here, or within the Entity itself.
+        # If specified here, it will override the Entity's Scenario.
+        scenario: Optional[str | int] = 0
+    ) -> JEntity:
+        """
+        Updates or creates an Entity.
+        If an Entity does not have an ID, a new record is made.
+        """
+        params = {
+            "Scenario": scenario
+        }
+        return api.POST("v3/entity", entity, params)
+    
+    @staticmethod
+    def update_list(
+        api: BruceApi,
+        # List of Entities to update/create.
+        entities: List[JEntityInternal], 
+        # (Optional) Scenario to update the Entities under.
+        # It can be specified here, or within the Entity itself.
+        # If specified here, it will override the Entity's Scenario.
+        scenario: Optional[str | int] = 0
+    ) -> List[JEntity]:
+        """
+        Updates or creates a list of Entities.
+        If an Entity does not have an ID, a new record is made.
+        """
+        body = {
+            "Items": entities,
+            "Scenario": scenario
+        }
+        data = api.POST("v3/entities", body)
+        return data["Items"]

bruce_models-0.0.1/bruce_models/entity/entity_type.py

@@ -0,0 +1,52 @@
+from typing import Optional, TypedDict, List, Any
+from bruce_models import BruceApi
+
+class EntityType:
+    """
+    Represents an Entity Type in Nextspace.
+    You will find the JEntityType data-model and all related API communication here.
+    """
+
+    class JEntityType(TypedDict):
+        # ID of the Entity Type.
+        ID: Optional[str]
+        # Human readable name of the Entity Type.
+        Name: str;
+        # Human readable description of the Entity Type.
+        Description: Optional[str]
+        # If Entity Type access (and Entity access) should be restricted.
+        # When an Entity Type is restricted a user must have the "EntityType_<typeId>" permission.
+        IsAccessRestricted: Optional[bool]
+        # The data schema defining expected attributes for entities to have.
+        DataSchema: Optional[Any]
+        # Attribute that defines Entity names in the Entity Type.
+        # If not supplied, then the Entities can have names set directly.
+        # It is a comma separated array of attribute string paths.
+        DisplayNameAttributePath: Optional[str]
+        # If this schema is "strict". If Entities in an Entity Type are different enough between each-other then the schema is not strict.
+        # This will dictate how UI will display the attributes.
+        IsStrictSchema: Optional[bool]
+        # Default Style for the corresponding Entities.
+        DisplaySettings_ID: Optional[int]
+        # Last updated date/time.
+        LastUpdate_Time: Optional[Any]
+        # ID of the parent Entity Type (if any).
+        # This is used for organization. When a parent type is deleted, the child types are also deleted.
+        Parent_EntityType_ID: Optional[str]
+
+    @staticmethod
+    def get(api: BruceApi, id: str) -> JEntityType:
+        """
+        Get an Entity Type by its ID.
+        """
+        if not id:
+            raise ValueError("ID is required to get an Entity Type.")
+        return api.GET("entitytype", id)
+    
+    @staticmethod
+    def get_list(api: BruceApi) -> List[JEntityType]:
+        """
+        Get a list of all Entity Types.
+        """
+        data = api.GET("entitytypes")
+        return data["Items"]

bruce_models-0.0.1/bruce_models/scenario/__init__.py

@@ -0,0 +1 @@
+from .scenario import Scenario

bruce_models-0.0.1/bruce_models/scenario/scenario.py

@@ -0,0 +1,43 @@
+from typing import Optional, TypedDict
+from bruce_models import BruceApi
+
+class Scenario:
+    """
+    Represents a Scenario in Nextspace.
+    You will find the JScenario data-model and all related API communication here.
+    """
+
+    class JScenario(TypedDict):
+        """
+        Represents the JSON structure of a Scenario.
+        """
+
+        # Unique numeric identity of the record.
+        # Generated by the database.
+        ID: Optional[int]
+        # (30) Unique keyword that is used for identification of the record when referred to in URL.
+        Key: str
+        # (120) User friendly name to display in UI.
+        DisplayName: str
+
+    """
+    Represents the Scenario model and provides functions to interact with the API.
+    """
+
+    @staticmethod
+    def get_by_id(api: BruceApi, scenario_id: int = 0) -> JScenario:
+        """
+        Retrieves a Scenario by its ID.
+        """
+        if not scenario_id or scenario_id < 1:
+            raise ValueError("A valid scenario ID is required.")
+        return api.GET(f"scenario/{scenario_id}")
+    
+    @staticmethod
+    def get_by_key(api: BruceApi, scenario_key: str = "") -> JScenario:
+        """
+        Retrieves a Scenario by its Key.
+        """
+        if not scenario_key:
+            raise ValueError("A valid scenario Key is required.")
+        return api.GET(f"scenario/key/{scenario_key}")

bruce_models-0.0.1/bruce_models.egg-info/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.1
+Name: bruce-models
+Version: 0.0.1
+Summary: This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.
+Author: Matvey Lavrinovich
+Author-email: matveylavrinovich@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0
+
+# bruce-models
+
+This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.
+
+### Local build
+
+- `pip install .`
+
+- `python ./public/main.py` (to test it loads after build)
+
+### Test a release build
+
+- `python -m build`

bruce_models-0.0.1/bruce_models.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+bruce_models/__init__.py
+bruce_models.egg-info/PKG-INFO
+bruce_models.egg-info/SOURCES.txt
+bruce_models.egg-info/dependency_links.txt
+bruce_models.egg-info/requires.txt
+bruce_models.egg-info/top_level.txt
+bruce_models/api/__init__.py
+bruce_models/api/api.py
+bruce_models/api/bruce_api.py
+bruce_models/api/guardian_api.py
+bruce_models/entity/__init__.py
+bruce_models/entity/entity.py
+bruce_models/entity/entity_type.py
+bruce_models/scenario/__init__.py
+bruce_models/scenario/scenario.py

bruce_models-0.0.1/bruce_models.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bruce_models-0.0.1/bruce_models.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.0

bruce_models-0.0.1/bruce_models.egg-info/top_level.txt

@@ -0,0 +1 @@
+bruce_models

bruce_models-0.0.1/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

bruce_models-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bruce_models-0.0.1/setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="bruce-models",
+    version="0.0.1",
+    description="This is a library which defines data-models for the Nextspace API and provides functions for communicating with the endpoints.",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="Matvey Lavrinovich",
+    author_email="matveylavrinovich@gmail.com",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.0"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+        "Intended Audience :: Developers"
+    ],
+    python_requires=">=3.6",
+)