python-terminusgps 31.0.1__py3-none-any.whl → 31.2.0__py3-none-any.whl

{python_terminusgps-31.0.1.dist-info → python_terminusgps-31.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 31.0.1
+Version: 31.2.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
@@ -22,3 +22,18 @@ Requires-Dist: pandas>=2.2.3
 Requires-Dist: python-wialon>=1.2.4
 Requires-Dist: pyzbar>=0.1.9
 Requires-Dist: twilio>=9.4.5
+Description-Content-Type: text/markdown
+
+# python-terminusgps
+
+*python-terminusgps* is a collection of Python libraries intended for use by Terminus GPS developers. 
+
+[Documentation](https://docs.terminusgps.com/)
+
+Currently, the following services are streamlined for web development:
+
+  * [AWS/boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
+  * [Authorizenet API](https://developer.authorize.net/api/reference/index.html)
+  * [Twilio API](https://www.twilio.com/docs)
+  * [Wialon Remote API](https://sdk.wialon.com/wiki/en/sidebar/remoteapi/apiref/apiref)
+

{python_terminusgps-31.0.1.dist-info → python_terminusgps-31.2.0.dist-info}/RECORD

@@ -13,28 +13,28 @@ terminusgps/aws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/aws/connect.py,sha256=TWf2bVz6LqSNQfVD7FKRn3K71VuLOwBj05Gs-9BsROg,693
 terminusgps/aws/secrets.py,sha256=MxQEmmBLpMUQ2tYAsHdCYf-7RZ84LiogdKcTsACX5dw,361
 terminusgps/django/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-terminusgps/django/mixins.py,sha256=jzs_dH_YDmohH86I3uPnN-66C9OPVXaDPVdRHXA6vdk,940
-terminusgps/django/settings.py,sha256=vY5yNjyMu-7Ya0bIPWUvrrSLERtxHGdkfeoY4Ul6cP0,613
+terminusgps/django/mixins.py,sha256=Q9ZJuzpk3d9lDnlVA8ZTVvnZWxB13p08EQ8yVJcztn4,1034
+terminusgps/django/settings.py,sha256=cKUpFXH-uYWStvT6vzclczJAKwCGNx_2wY9-fqsbmIs,624
 terminusgps/django/utils.py,sha256=SYDQyHA5tTuVwdpZGsCtf0LpTTD0ilRKoxa8StfSTpQ,156
 terminusgps/twilio/__init__.py,sha256=dYo41F2jft_eHDWSUtSpKGSRG1bewq_qClqilUJZkYM,33
 terminusgps/twilio/caller.py,sha256=Q0wcJ5aaNDGvKfht7ARwPTFdqpFoB81DmZ_K2oZixyA,5077
-terminusgps/twilio/validators.py,sha256=nn7CCBTktNjcln6M4MR0ACxEsClgioSu89LRLgIiBZk,1112
+terminusgps/twilio/validators.py,sha256=HWCpzgDXTedofty4Zhrm2OenbgtkzrDUC08B1l15gqc,1112
 terminusgps/wialon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/wialon/constants.py,sha256=-fRrvtQuSAJ6hpBJzp_Xa4GDI4LuQbqZ1z1L_QFzZiE,5609
 terminusgps/wialon/flags.py,sha256=M50EdhxQ8IMnJnU0mrHK7-h8Asc6tvNiTOOfd1dBW6A,12815
 terminusgps/wialon/logger.py,sha256=nUBsaLMaffSaAHGHAM6mFXDzix9hbNecVtA3INVtii8,968
-terminusgps/wialon/session.py,sha256=emB0XHJjFObtb6WbttsXZXTeRaPztcbjAV212B_Ssek,9781
-terminusgps/wialon/utils.py,sha256=iRZi4uLk-qqNUXdEIbL-4ibfXh9xvEjXWmdoML9CubQ,10051
-terminusgps/wialon/validators.py,sha256=NNqMhoXn1M_f4Edm6oD8I7lzzXKZSqyZ6n7fR3obWj8,4241
+terminusgps/wialon/session.py,sha256=21ZRBUnsuK5zhkUHeccQW1lR39A4kQ_0qkLlRT1hsS8,10044
+terminusgps/wialon/utils.py,sha256=JWHZ7VEeo8VNBH67gjOAQk5ITKuPllWDlJ4dVSQ5blA,11002
+terminusgps/wialon/validators.py,sha256=CVEpFsxqplEcpv4U2ipA6v9y5cSrMKFUXLvze-3vs4U,4223
 terminusgps/wialon/items/__init__.py,sha256=3BVthghekMvhMQSzQgBMlD_phxmKSmp3Zvmo-z0O8Bs,211
-terminusgps/wialon/items/base.py,sha256=4TAsmSQ-pw4mqiuL4_clN_Kvplcze4lZwL9oO1p7gkk,8001
-terminusgps/wialon/items/resource.py,sha256=wfUxACO4OdzT2IdCF9oBmU_7nYiH3Xvs6BripPD5IMI,14622
+terminusgps/wialon/items/base.py,sha256=y0z3eW_Gz7dlusKHj3T3TH3_nPsx5yGUKuImEJSK10M,10215
+terminusgps/wialon/items/resource.py,sha256=FmuY0thel8aIThSWKJXur72Sptful3MuwBfIn9bdeaY,14616
 terminusgps/wialon/items/retranslator.py,sha256=sVEWrp8q1I-tO_rMTCH7TeQDDbZryIq8d9KVnhYyhH0,3795
 terminusgps/wialon/items/route.py,sha256=amNPKZqgl8pEzKA_XJudnvBPzEsfHTmrC7uF15sZVI4,1216
-terminusgps/wialon/items/unit.py,sha256=ChONjm3wlFSlbNz-yEXziNbbs4LJ70F9-MI2c-p905k,10638
+terminusgps/wialon/items/unit.py,sha256=jq4S8EV_yukRTTE8rr2oXpu_9AdXDFYA6-GCjkR6shw,12282
 terminusgps/wialon/items/unit_group.py,sha256=QV2ZZgICaN3n6W1pFIyMLyNKB6KYBsLyKG64i-qXoOg,4113
 terminusgps/wialon/items/user.py,sha256=N30wdejdG7LXrgafdKZH74YArGkX3xpZfTucn3m3aqM,7155
-python_terminusgps-31.0.1.dist-info/METADATA,sha256=nrk9c775z_OXX5PVMLZgRkd4x_Butw1pspqwR_XyF48,1061
-python_terminusgps-31.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_terminusgps-31.0.1.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_terminusgps-31.0.1.dist-info/RECORD,,
+python_terminusgps-31.2.0.dist-info/METADATA,sha256=EwPAAmEbYoZnSd8MUlqJErruNb1nS8UZ-iyKBrmE2x8,1648
+python_terminusgps-31.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_terminusgps-31.2.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_terminusgps-31.2.0.dist-info/RECORD,,

terminusgps/django/mixins.py

@@ -24,6 +24,7 @@ class HtmxTemplateResponseMixin(TemplateResponseMixin):
     def render_to_response(
         self, context: dict[str, typing.Any], **response_kwargs: typing.Any
     ) -> HttpResponse:
+        """Sets :py:attr:`template_name` to :py:attr:`partial_template_name` if necessary."""
         htmx_request = self.request.headers.get("HX-Request", False)
         boosted = self.request.headers.get("HX-Boosted", False)
 

terminusgps/django/settings.py

@@ -1,15 +1,17 @@
 import os
 import pathlib
 
-DEBUG = True
 BASE_DIR = pathlib.Path(__file__).resolve().parent
+DEBUG = True
+SECRET_KEY = "xem*6no%8d9%^qzt2f3x3ar-uq4_+7h9myc$t0!+4%bj5us6f)"
+
+# Secrets
+CONNECT_SECRET = os.getenv("CONNECT_SECRET")
 MERCHANT_AUTH_LOGIN_ID = os.getenv("MERCHANT_AUTH_LOGIN_ID")
 MERCHANT_AUTH_TRANSACTION_KEY = os.getenv("MERCHANT_AUTH_TRANSACTION_KEY")
-SECRET_KEY = "xem*6no%8d9%^qzt2f3x3ar-uq4_+7h9myc$t0!+4%bj5us6f)"
 TWILIO_FROM_NUMBER = os.getenv("TWILIO_FROM_NUMBER")
 TWILIO_MESSAGING_SID = os.getenv("TWILIO_MESSAGING_SID")
 TWILIO_SID = os.getenv("TWILIO_SID")
 TWILIO_TOKEN = os.getenv("TWILIO_TOKEN")
 WIALON_ADMIN_ID = os.getenv("WIALON_ADMIN_ID")
 WIALON_TOKEN = os.getenv("WIALON_TOKEN")
-CONNECT_SECRET = os.getenv("CONNECT_SECRET")

terminusgps/twilio/validators.py

@@ -27,5 +27,5 @@ def validate_phone_number(value: str) -> None:
         raise ValidationError(
             _("Phone number cannot be greater than %(max)s characters, got %(len)s."),
             code="invalid",
-            params={"max": min_length, "len": len(value)},
+            params={"max": max_length, "len": len(value)},
         )

terminusgps/wialon/items/base.py

@@ -9,6 +9,20 @@ class WialonBase:
     def __init__(
         self, id: str | int | None, session: WialonSession, *args, **kwargs
     ) -> None:
+        """
+        Sets the Wialon session and id for the Wialon object.
+
+        If no id was provided, :py:meth:`create` is executed to get one.
+
+        :param id: An optional Wialon object id.
+        :type id: :py:obj:`str` | :py:obj:`int` | :py:obj:`None`
+        :param session: A valid Wialon API session.
+        :type session: :py:obj:`~terminusgps.wialon.session.WialonSession`
+        :raises ValueError: If ``id`` was a string that contained non-digit values.
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
         if isinstance(id, str) and not id.isdigit():
             raise ValueError(f"'id' must be a digit. Got '{id}'.")
 
@@ -19,13 +33,23 @@ class WialonBase:
         self._access_lvl = None
 
     def __str__(self) -> str:
+        """Returns the Wialon object id as a string."""
         return str(self.id)
 
     def __repr__(self) -> str:
+        """Returns the Wialon object type and parameters used to initialize it."""
         return f"{type(self).__name__}(id={self.id}, session={self.session.id})"
 
     def populate(self) -> None:
-        """Retrieves and saves the latest data for the item from Wialon."""
+        """
+        Retrieves and saves the latest data for the item from Wialon.
+
+        :raises AssertionError: If :py:attr:`id` wasn't set.
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        assert self.id, "No Wialon object id set."
         response = self.session.wialon_api.core_search_item(
             **{"id": str(self.id), "flags": flags.DataFlag.UNIT_BASE}
         )
@@ -111,6 +135,50 @@ class WialonBase:
         )
         self._name = new_name
 
+    def get_cfield_id(self, key: str) -> int | None:
+        """
+        Returns a custom field id by its key, if it exists.
+
+        :param key: A custom field key.
+        :type key: :py:obj:`str`
+        :returns: A custom field id, if any.
+        :rtype: :py:obj:`int` | :py:obj:`None`
+
+        """
+        cfields = (
+            self.session.wialon_api.core_search_item(
+                **{"id": str(self.id), "flags": flags.DataFlag.UNIT_CUSTOM_FIELDS}
+            )
+            .get("item", {})
+            .get("flds", {})
+            .values()
+        )
+        for field in cfields:
+            if field["n"] == key:
+                return int(field["id"])
+
+    def get_afield_id(self, key: str) -> int | None:
+        """
+        Returns an admin field id by its key, if it exists.
+
+        :param key: An admin field key.
+        :type key: :py:obj:`str`
+        :returns: An admin field id, if any.
+        :rtype: :py:obj:`int` | :py:obj:`None`
+
+        """
+        afields = (
+            self.session.wialon_api.core_search_item(
+                **{"id": str(self.id), "flags": flags.DataFlag.UNIT_ADMIN_FIELDS}
+            )
+            .get("item", {})
+            .get("aflds", {})
+            .values()
+        )
+        for field in afields:
+            if field["n"] == key:
+                return int(field["id"])
+
     def add_afield(self, key: str, value: str) -> None:
         """
         Adds an admin field to the Wialon object.

terminusgps/wialon/items/resource.py

@@ -30,7 +30,7 @@ class WialonResource(WialonBase):
             **{
                 "creatorId": creator_id,
                 "name": name,
-                "dataFlags": flags.DataFlag.UNIT_BASE.value,
+                "dataFlags": flags.DataFlag.UNIT_BASE,
                 "skipCreatorCheck": int(skip_creator_check),
             }
         )

terminusgps/wialon/items/unit.py

@@ -70,7 +70,7 @@ class WialonUnit(WialonBase):
 
     def get_position(self) -> dict | None:
         return self.session.wialon_api.core_search_item(
-            **{"id": self.id, "flags": flags.DataFlag.UNIT_POSITION.value}
+            **{"id": self.id, "flags": flags.DataFlag.UNIT_POSITION}
         )
 
     @property
@@ -152,10 +152,62 @@ class WialonUnit(WialonBase):
 
     @property
     def image_url(self) -> str | None:
+        """Returns an absolute url to the unit's icon in Wialon."""
         if hasattr(settings, "WIALON_HOST"):
             return urljoin(settings.WIALON_HOST, self._image_uri)
         return urljoin("https://hst-api.wialon.com", self._image_uri)
 
+    def assign_to_number(self, value: str) -> None:
+        """
+        Sets ``value`` to the unit's ``to_number`` custom field.
+
+        :param value: A new value for the unit's ``to_number`` custom field.
+        :type value: :py:obj:`str`
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        cfield_key: str = "to_number"
+        cfield_val: str = value
+        cfield_id: int | None = self.get_cfield_id(cfield_key)
+
+        if cfield_id:
+            self.update_cfield(cfield_id, cfield_key, cfield_val)
+
+    def assign_iccid(self, value: str) -> None:
+        """
+        Sets ``value`` to the unit's ``iccid`` admin field.
+
+        :param value: A new value for the unit's ``iccid`` custom field.
+        :type value: :py:obj:`str`
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        afield_key: str = "iccid"
+        afield_val: str = value
+        afield_id: int | None = self.get_afield_id(afield_key)
+
+        if afield_id:
+            self.update_afield(afield_id, afield_key, afield_val)
+
+    def assign_carrier(self, value: str) -> None:
+        """
+        Sets ``value`` to the unit's ``carrier`` admin field.
+
+        :param value: A new value for the unit's ``carrier`` custom field.
+        :type value: :py:obj:`str`
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        afield_key: str = "carrier"
+        afield_val: str = value
+        afield_id: int | None = self.get_afield_id(afield_key)
+
+        if afield_id:
+            self.update_afield(afield_id, afield_key, afield_val)
+
     def execute_command(
         self,
         name: str,

terminusgps/wialon/session.py

@@ -105,13 +105,26 @@ class WialonSession:
         return f"{self.__class__}(sid={self.id})"
 
     def __enter__(self) -> "WialonSession":
-        """Logs into the Wialon API using a token set in :py:meth:`__init__`."""
+        """
+        Logs into the Wialon API using :py:meth:`login`.
+
+        :raises AssertionError: If the Wialon API token was not set.
+        :returns: A valid Wialon API session.
+        :rtype: :py:obj:`~terminusgps.wialon.session.WialonSession`
+
+        """
         assert self.token, "Wialon API token was not set"
         self.login(self.token)
         return self
 
     def __exit__(self, exc_type, exc_value, exc_traceback) -> None:
-        """Logs out of the session by calling :py:meth:`logout`."""
+        """
+        Logs out of the session by calling :py:meth:`logout`.
+
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
         self.logout()
 
     @property

terminusgps/wialon/utils.py

@@ -2,10 +2,39 @@ import secrets
 import string
 import typing
 
-from terminusgps.wialon import constants, flags
-from terminusgps.wialon.items import WialonUnit
-from terminusgps.wialon.items.resource import WialonResource
-from terminusgps.wialon.session import WialonSession
+from . import constants, flags
+from .items import WialonResource, WialonUnit
+from .session import WialonSession
+
+
+def get_user_by_name(name: str, session: WialonSession) -> WialonUnit | None:
+    """
+    Returns a Wialon user by name, if it exists.
+
+    :param name: A Wialon user name.
+    :type name: :py:obj:`str`
+    :param session: A valid Wialon API session.
+    :type session: :py:obj:`~terminusgps.wialon.session.WialonSession`
+    :returns: A Wialon unit, if any.
+    :rtype: :py:obj:`~terminusgps.wialon.items.unit.WialonUnit` | :py:obj:`None`
+
+    """
+    results: dict = session.wialon_api.core_search_items(
+        **{
+            "spec": {
+                "itemsType": constants.WialonItemsType.USER,
+                "propName": constants.WialonItemProperty.NAME,
+                "propValueMask": name,
+                "sortType": constants.WialonItemProperty.NAME,
+            },
+            "force": 0,
+            "flags": flags.DataFlag.USER_BASE,
+            "from": 0,
+            "to": 0,
+        }
+    )
+    if results and results.get("items", [{}]):
+        return WialonUnit(id=results.get("items", [{}])[0].get("id"), session=session)
 
 
 def get_carrier_names(session: WialonSession) -> list[str]:

terminusgps/wialon/validators.py

@@ -4,7 +4,7 @@ from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured, ValidationError
 from django.utils.translation import gettext_lazy as _
 
-from terminusgps.wialon.session import WialonSession
+from .session import WialonSession
 
 if not hasattr(settings, "WIALON_TOKEN"):
     raise ImproperlyConfigured("'WIALON_TOKEN' setting is required.")