python-terminusgps 1.15.1__tar.gz → 1.16.0__tar.gz

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 1.15.1
+Version: 1.16.0
 Summary: Provides abstractions/utilities for working with Wialon API, Authorize.NET API, AWS API, and more.
 Project-URL: Documentation, https://app.terminusgps.com/docs/apps/python-terminusgps/index.html
 Project-URL: Repository, https://github.com/terminusgps/python-terminusgps

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-terminusgps"
-version = "1.15.1"
+version = "1.16.0"
 description = "Provides abstractions/utilities for working with Wialon API, Authorize.NET API, AWS API, and more."
 readme = "README.md"
 authors = [ {name = "Blake Nall", email = "blake@terminusgps.com" } ]

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/terminusgps/wialon/items/base.py

@@ -1,4 +1,5 @@
 from abc import abstractmethod
+from typing import Type
 
 from terminusgps.wialon import flags
 from terminusgps.wialon.session import WialonSession
@@ -24,6 +25,7 @@ class WialonBase:
         return str(self.id)
 
     def populate(self) -> None:
+        """Retrieves and saves the latest data for the item from Wialon."""
         response = self.session.wialon_api.core_search_item(
             **{"id": str(self.id), "flags": 0x1}
         ).get("item", {})
@@ -53,7 +55,7 @@ class WialonBase:
 
         return int(self._id) if self._id else None
 
-    def has_access(self, other: "WialonBase") -> bool:
+    def has_access(self, other: Type["WialonBase"]) -> bool:
         """
         Checks if this Wialon object has access to ``other``.
 
@@ -74,7 +76,7 @@ class WialonBase:
         """
         Renames the Wialon object to the new name.
 
-        :param new_name: A new name for this object.
+        :param new_name: A new name.
         :type new_name: :py:obj:`str`
         :returns: Nothing.
         :rtype: :py:obj:`None`
@@ -215,24 +217,27 @@ class WialonBase:
 
         self.session.wialon_api.item_delete_item(**{"itemId": self.id})
 
-    def _get_cfields(self) -> dict:
-        response = self.session.wialon_api.core_search_item(
-            **{"id": self.id, "flags": flags.DATAFLAG_UNIT_CUSTOM_FIELDS}
-        )
-        return response["item"]["flds"]
-
-    def _get_afields(self) -> dict:
-        response = self.session.wialon_api.core_search_item(
-            **{"id": self.id, "flags": flags.DATAFLAG_UNIT_ADMIN_FIELDS}
-        )
-        return response["item"]["aflds"]
-
     @property
     def cfields(self) -> dict:
-        fields = self._get_cfields()
-        return {field["n"]: field["v"] for _, field in fields.items()}
+        """Custom fields associated with the Wialon object."""
+        fields = (
+            self.session.wialon_api.core_search_item(
+                **{"id": self.id, "flags": flags.DATAFLAG_UNIT_CUSTOM_FIELDS}
+            )
+            .get("item", {})
+            .get("cfields")
+        )
+
+        return {field["n"]: field["v"] for _, field in fields.items()} if fields else {}
 
     @property
     def afields(self) -> dict:
-        fields = self._get_afields()
-        return {field["n"]: field["v"] for _, field in fields.items()}
+        """Admin fields associated with the Wialon object."""
+        fields = (
+            self.session.wialon_api.core_search_item(
+                **{"id": self.id, "flags": flags.DATAFLAG_UNIT_ADMIN_FIELDS}
+            )
+            .get("item", {})
+            .get("afields")
+        )
+        return {field["n"]: field["v"] for _, field in fields.items()} if fields else {}

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/terminusgps/wialon/items/resource.py

@@ -21,10 +21,34 @@ class WialonResource(WialonBase):
         return response.get("item", {}).get("id")
 
     def delete(self) -> None:
-        if self.is_account:
-            self.delete_account()
-            return
-        super().delete()
+        """
+        Deletes all micro-objects assigned to the resource.
+
+        If the resource is an account, instead deletes all macro-objects and micro-objects assigned to the account.
+
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        self.delete_account() if self.is_account else super().delete()
+
+    @property
+    def is_dealer(self) -> bool:
+        """
+        Whether or not the resource/account has dealer rights.
+
+        If the resource is **not** an account, this always returns :py:obj:`False`.
+
+        :type: :py:obj:`bool`
+
+        """
+        if not self.is_account:
+            return False  # Resources cannot have dealer rights
+        return bool(
+            self.session.wialon_api.get_account_data(
+                **{"itemId": self.id, "type": 1}
+            ).get("dealerRights")
+        )
 
     @property
     def is_account(self) -> bool:
@@ -60,6 +84,8 @@ class WialonResource(WialonBase):
         """
         Sets dealer rights on the account.
 
+        You **probably don't** need to use this method.
+
         :param enabled: :py:obj:`True` to enable dealer rights, :py:obj:`False` to disable dealer rights. Default is :py:obj:`False`.
         :type enabled: :py:obj:`bool`
         :raises AssertionError: If the resource is not an account.
@@ -123,6 +149,7 @@ class WialonResource(WialonBase):
         self.session.wialon_api.account_create_account(
             **{"itemId": self.id, "plan": billing_plan}
         )
+        self.set_settings_flags()
 
     def delete_account(self) -> None:
         """

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/terminusgps/wialon/items/unit_group.py

@@ -1,4 +1,5 @@
-from terminusgps.wialon import constants, flags
+from typing import Type
+from terminusgps.wialon import flags
 from terminusgps.wialon.items.base import WialonBase
 
 
@@ -31,7 +32,7 @@ class WialonUnitGroup(WialonBase):
         )
         return response.get("item", {}).get("id")
 
-    def _update_items(self, new_items: list[str]) -> None:
+    def set_items(self, new_items: list[str]) -> None:
         """
         Sets this group's members to a list of Wialon unit ids.
 
@@ -47,7 +48,7 @@ class WialonUnitGroup(WialonBase):
             **{"itemId": self.id, "units": new_items}
         )
 
-    def is_member(self, item: WialonBase) -> bool:
+    def is_member(self, item: Type[WialonBase]) -> bool:
         """
         Determines whether or not ``item`` is a member of the group.
 
@@ -60,43 +61,9 @@ class WialonUnitGroup(WialonBase):
         """
         return True if str(item.id) in self.items else False
 
-    def grant_access(
-        self, item: WialonBase, access_mask: int = constants.ACCESSMASK_UNIT_BASIC
-    ) -> None:
+    def add_item(self, item: Type[WialonBase]) -> None:
         """
-        Grants ``item`` access to the group, if it didn't already have access.
-
-        :param item: A Wialon object.
-        :type item: :py:obj:`~terminusgps.wialon.items.base.WialonBase`
-        :param access_mask: A Wialon access mask.
-        :type access_mask: :py:obj:`int`
-        :raises WialonError: If something goes wrong with Wialon.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        self.session.wialon_api.user_update_item_access(
-            **{"userId": item.id, "itemId": self.id, "accessMask": access_mask}
-        )
-
-    def revoke_access(self, item: WialonBase) -> None:
-        """
-        Revokes ``item``'s access from the group, if it had access.
-
-        :param item: A Wialon object.
-        :type item: :py:obj:`~terminusgps.wialon.items.base.WialonBase`
-        :raises WialonError: If something goes wrong with Wialon.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        self.session.wialon_api.user_update_item_access(
-            **{"userId": item.id, "itemId": self.id, "accessMask": 0}
-        )
-
-    def add_item(self, item: WialonBase) -> None:
-        """
-        Adds a Wialon unit to the group.
+        Adds a Wialon item to the group.
 
         :param item: A Wialon object.
         :type item: :py:obj:`~terminusgps.wialon.items.base.WialonBase`
@@ -106,9 +73,9 @@ class WialonUnitGroup(WialonBase):
 
         """
         new_items: list[str] = self.items.copy() + [str(item.id)]
-        self._update_items(new_items)
+        self.set_items(new_items)
 
-    def rm_item(self, item: WialonBase) -> None:
+    def rm_item(self, item: Type[WialonBase]) -> None:
         """
         Removes a Wialon unit from the group, if it's a member of the group.
 
@@ -123,7 +90,7 @@ class WialonUnitGroup(WialonBase):
         assert self.is_member(item), f"Cannot remove {item}, it's not in the group"
         new_items: list[str] = self.items.copy()
         new_items.remove(str(item.id))
-        self._update_items(new_items)
+        self.set_items(new_items)
 
     @property
     def items(self) -> list[str]:
@@ -149,4 +116,4 @@ class WialonUnitGroup(WialonBase):
                 "to": 0,
             }
         )
-        return [str(unit_id) for unit_id in response.get("items")[0].get("u", [])]
+        return [unit_id for unit_id in response.get("items")[0].get("u", [])]

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/terminusgps/wialon/session.py

@@ -1,25 +1,24 @@
 import threading
 import logging
-
-from typing import Any
-from dataclasses import dataclass
-from datetime import datetime
+import typing
+import dataclasses
+import datetime
 
 from wialon.api import WialonError
 from wialon.api import Wialon as WialonAPI
 from django.conf import settings
 from django.utils import timezone
 
-from .errors import WialonLogoutError, WialonLoginError
+from terminusgps.wialon.errors import WialonLogoutError, WialonLoginError
 
 
-@dataclass
+@dataclasses.dataclass
 class WialonAPICall:
     action: str
-    timestamp: datetime
+    timestamp: datetime.datetime
     args: tuple
     kwargs: dict
-    result: Any = None
+    result: typing.Any = None
     error: Exception | None = None
 
 
@@ -45,7 +44,7 @@ class Wialon(WialonAPI):
     def failure_rate(self) -> float:
         return len(self.failed_calls) / self.total_calls
 
-    def call(self, action_name: str, *argc, **kwargs) -> Any:
+    def call(self, action_name: str, *argc, **kwargs) -> typing.Any:
         self.logger.info(f"Executing '{action_name}'...")
         self.logger.debug(f"Executing '{action_name}' using: '{kwargs}'")
         call_record = WialonAPICall(

python_terminusgps-1.16.0/terminusgps/wialon/utils.py

@@ -0,0 +1,185 @@
+import secrets
+import string
+import warnings
+import typing
+
+from terminusgps.wialon import items, flags
+from terminusgps.wialon.items.base import WialonBase
+from terminusgps.wialon.session import WialonSession
+
+
+def get_hw_type_id(name: str, session: WialonSession) -> int | None:
+    """
+    Takes a Wialon hardware type name and returns its id, if it exists.
+
+    :param name: The name of a Wialon hardware type.
+    :type name: :py:obj:`str`
+    :param session: A valid Wialon API session.
+    :type session: :py:obj:`~terminusgps.wialon.session.WialonSession`
+    :raises WialonError: If something goes wrong with Wialon.
+    :returns: A Wialon hardware type id, if it was found.
+    :rtype: :py:obj:`int` | :py:obj:`None`
+
+    """
+    response = session.wialon_api.core_get_hw_types(
+        **{
+            "filterType": "id",
+            "filterValue": "name,id",
+            "includeType": "true",
+            "ignoreRename": "true",
+        }
+    )
+    hw_types = {item.get("name"): item.get("id") for item in response}
+    return int(hw_types.get(name)) if name in hw_types.keys() else None
+
+
+def get_id_from_iccid(iccid: str, session: WialonSession) -> str | None:
+    """
+    Takes a Wialon unit's IMEI # and returns its unit id, if it exists.
+
+    :param iccid: A unique id.
+    :type iccid: :py:obj:`str`
+    :param session: A valid Wialon API session.
+    :type session: :py:obj:`~terminusgps.wialon.session.WialonSession`
+    :raises WialonError: If something goes wrong with Wialon.
+    :returns: A Wialon object id, if it was found.
+    :rtype: :py:obj:`str` | :py:obj:`None`
+
+    """
+    response = session.wialon_api.core_search_items(
+        **{
+            "spec": {
+                "itemsType": "avl_unit",
+                "propName": "rel_admin_field_value",
+                "propValueMask": str(iccid),
+                "sortType": "admin_fields",
+                "propType": "adminfield",
+                "or_logic": 0,
+            },
+            "force": 0,
+            "flags": flags.DATAFLAG_UNIT_BASE,
+            "from": 0,
+            "to": 0,
+        }
+    )
+
+    if response.get("totalItemsCount", 0) == 1:
+        return response["items"][0].get("id")
+
+
+def get_wialon_cls(items_type: str) -> typing.Type[WialonBase]:
+    """
+    Returns a Wialon object class based on items_type.
+
+    :param items_type: A Wialon object type.
+    :type items_type: :py:obj:`str`
+    :returns: A subclass of :py:obj:`~terminusgps.wialon.items.base.WialonBase`.
+    :rtype: :py:obj:`~terminusgps.wialon.items.base.WialonBase`
+
+    """
+    match items_type:
+        case "user":
+            wialon_cls = items.WialonUser
+        case "avl_unit":
+            wialon_cls = items.WialonUnit
+        case "avl_unit_group":
+            wialon_cls = items.WialonUnitGroup
+        case "avl_resource":
+            wialon_cls = items.WialonResource
+        case _:
+            raise ValueError(f"Invalid items_type '{items_type}'")
+    return wialon_cls
+
+
+def is_unique(value: str, session: WialonSession, items_type: str = "avl_unit") -> bool:
+    """
+    Determines if the value is unique among Wialon objects of type 'items_type'.
+
+    :param value: A value whose uniqueness is unknown.
+    :type value: :py:obj:`str`
+    :param session: A valid Wialon API session.
+    :type session: :py:obj:`~terminusgps.wialon.session.WialonSession`
+    :param items_type: The type of Wialon objects to validate the value against. Default is ``"avl_unit"``.
+    :type items_type: :py:obj:`str`
+    :returns: Whether or not the value is unique among 'items_type'.
+    :rtype: :py:obj:`bool`
+
+
+    """
+    result = session.wialon_api.core_check_unique(
+        **{"type": items_type, "value": value.strip()}
+    ).get("result")
+    return not bool(result)
+
+
+def generate_wialon_password(length: int = 32) -> str:
+    """
+    Generates a Wialon compliant password of random characters.
+
+    Password length can be between ``8`` and ``64`` characters.
+
+    :param length: Length of the generated password. Default is ``32``.
+    :type length: :py:obj:`int`
+    :raises ValueError: If the provided length is invalid.
+    :returns: A Wialon compliant password.
+    :rtype: :py:obj:`str`
+
+    """
+    min_length, max_length = 8, 64
+    if length > max_length:
+        raise ValueError(
+            f"Password cannot be greater than {max_length} characters in length. Got {length}."
+        )
+    elif length < min_length:
+        raise ValueError(
+            f"Password cannot be less than {min_length} characters in length. Got {length}."
+        )
+
+    s0 = list(string.ascii_uppercase)
+    s1 = list(string.ascii_lowercase)
+    s2 = list(string.digits)
+    s3 = list("!@#$%^*()[]-_+")
+
+    while True:
+        password = "".join([secrets.choice(s0 + s1 + s2 + s3) for _ in range(length)])
+        if (
+            any(c.islower() for c in password)
+            and any(c.isupper() for c in password)
+            and sum(c.isdigit() for c in password) >= 3
+            and any(c in s3 for c in password)
+        ):
+            break
+    return password
+
+
+def gen_wialon_password(length: int = 32) -> str:
+    """
+    DEPRECATED: Use :py:func:`~terminusgps.wialon.utils.generate_wialon_password` instead.
+
+    Generates a Wialon compliant password of random characters.
+
+    Password length can be between ``8`` and ``64`` characters.
+
+    :param length: Length of the generated password. Default is ``32``.
+    :type length: :py:obj:`int`
+    :raises ValueError: If the provided length is invalid.
+    :returns: A Wialon compliant password.
+    :rtype: :py:obj:`str`
+
+    """
+    warnings.warn(
+        "gen_wialon_password is deprecated and will be removed in a future version. Use generate_wialon_password instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return generate_wialon_password(length)
+
+
+__all__ = [
+    "get_hw_type_id",
+    "get_id_from_iccid",
+    "get_wialon_cls",
+    "is_unique",
+    "generate_wialon_password",
+    "gen_wialon_password",
+]

{python_terminusgps-1.15.1 → python_terminusgps-1.16.0}/uv.lock

@@ -504,7 +504,7 @@ wheels = [
 
 [[package]]
 name = "python-terminusgps"
-version = "1.15.1"
+version = "1.16.0"
 source = { editable = "." }
 dependencies = [
     { name = "argparse" },

python_terminusgps-1.15.1/terminusgps/wialon/utils.py

@@ -1,113 +0,0 @@
-import secrets
-import string
-
-from typing import Any
-from .session import WialonSession
-from .flags import DATAFLAG_UNIT_BASE
-
-from terminusgps.wialon.items import (
-    WialonUser,
-    WialonUnit,
-    WialonUnitGroup,
-    WialonResource,
-)
-
-
-def get_hw_type_id(name: str, session: WialonSession) -> int | None:
-    response = session.wialon_api.core_get_hw_types(
-        **{
-            "filterType": "id",
-            "filterValue": "name,id",
-            "includeType": "true",
-            "ignoreRename": "true",
-        }
-    )
-    hw_types = {item.get("name"): item.get("id") for item in response}
-    return int(hw_types.get(name)) if name in hw_types.keys() else None
-
-
-def get_wialon_cls(items_type: str) -> Any:
-    """Returns a Wialon object class based on items_type."""
-    match items_type:
-        case "user":
-            wialon_cls = WialonUser
-        case "avl_unit":
-            wialon_cls = WialonUnit
-        case "avl_unit_group":
-            wialon_cls = WialonUnitGroup
-        case "avl_resource":
-            wialon_cls = WialonResource
-        case _:
-            raise ValueError(f"Invalid items_type '{items_type}'")
-    return wialon_cls
-
-
-def is_unique(value: str, session: WialonSession, items_type: str = "avl_unit") -> bool:
-    """Determines if the value is unique among Wialon objects of type 'items_type'."""
-    result = session.wialon_api.core_check_unique(
-        **{"type": items_type, "value": value.strip()}
-    ).get("result")
-    return not bool(result)
-
-
-def gen_wialon_password(length: int = 32) -> str:
-    """Generates a Wialon compliant password."""
-    min_length, max_length = 4, 64
-    if length > max_length:
-        raise ValueError(
-            f"Password cannot be greater than {max_length} characters in length. Got {length}."
-        )
-    elif length < min_length:
-        raise ValueError(
-            f"Password cannot be less than {min_length} characters in length. Got {length}."
-        )
-
-    s0 = list(string.ascii_uppercase)
-    s1 = list(string.ascii_lowercase)
-    s2 = list(string.digits)
-    s3 = list("!@#$%^*()[]-_+")
-
-    while True:
-        password = "".join([secrets.choice(s0 + s1 + s2 + s3) for _ in range(length)])
-        if (
-            any(c.islower() for c in password)
-            and any(c.isupper() for c in password)
-            and sum(c.isdigit() for c in password) >= 3
-            and any(c in s3 for c in password)
-        ):
-            break
-    return password
-
-
-def get_id_from_iccid(iccid: str, session: WialonSession) -> str | None:
-    """Takes a Wialon unit's IMEI # and returns its unit id, if it exists."""
-    response = session.wialon_api.core_search_items(
-        **{
-            "spec": {
-                "itemsType": "avl_unit",
-                "propName": "rel_admin_field_value",
-                "propValueMask": str(iccid),
-                "sortType": "admin_fields",
-                "propType": "adminfield",
-                "or_logic": 0,
-            },
-            "force": 0,
-            "flags": DATAFLAG_UNIT_BASE,
-            "from": 0,
-            "to": 0,
-        }
-    )
-
-    if response.get("totalItemsCount", 0) == 1:
-        return response["items"][0].get("id")
-
-
-def main() -> None:
-    with WialonSession() as session:
-        wialon_id = get_id_from_iccid("89015809000307608963", session)
-        print(f"{wialon_id = }")
-    return
-
-
-if __name__ == "__main__":
-    main()