python-terminusgps 31.0.0__py3-none-any.whl → 31.1.0__py3-none-any.whl

{python_terminusgps-31.0.0.dist-info → python_terminusgps-31.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 31.0.0
+Version: 31.1.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,15 @@ 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](https://docs.terminusgps.com/) is a collection of Python libraries intended for use by Terminus GPS developers. 
+
+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.0.dist-info → python_terminusgps-31.1.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/mixins.py,sha256=Q9ZJuzpk3d9lDnlVA8ZTVvnZWxB13p08EQ8yVJcztn4,1034
 terminusgps/django/settings.py,sha256=vY5yNjyMu-7Ya0bIPWUvrrSLERtxHGdkfeoY4Ul6cP0,613
 terminusgps/django/utils.py,sha256=SYDQyHA5tTuVwdpZGsCtf0LpTTD0ilRKoxa8StfSTpQ,156
 terminusgps/twilio/__init__.py,sha256=dYo41F2jft_eHDWSUtSpKGSRG1bewq_qClqilUJZkYM,33
-terminusgps/twilio/caller.py,sha256=TiQ4f0TDDC35he1M1iSsBM2vutdGriwtV4pc17T--6I,3552
-terminusgps/twilio/validators.py,sha256=nn7CCBTktNjcln6M4MR0ACxEsClgioSu89LRLgIiBZk,1112
+terminusgps/twilio/caller.py,sha256=Q0wcJ5aaNDGvKfht7ARwPTFdqpFoB81DmZ_K2oZixyA,5077
+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/utils.py,sha256=eRo-NHWEi8zq8mMWFnCs8__iDbkpPvSkCqcsdr13ltI,9953
+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.0.dist-info/METADATA,sha256=y4fXM6pCMkZ0znIWvVqoAOzitHrjZDbrhSDPIy06qcE,1061
-python_terminusgps-31.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_terminusgps-31.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_terminusgps-31.0.0.dist-info/RECORD,,
+python_terminusgps-31.1.0.dist-info/METADATA,sha256=MIfipx-9aKDFbozGWwy-i6MXtywcZMOk8O968CjS2TQ,1630
+python_terminusgps-31.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_terminusgps-31.1.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_terminusgps-31.1.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/twilio/caller.py

@@ -17,30 +17,53 @@ if not hasattr(settings, "TWILIO_MESSAGING_SID"):
 
 
 class TwilioCaller:
-    def __init__(self) -> None:
-        """Sets Twilio messaging session variables."""
-        self.client_sid = settings.TWILIO_SID
-        self.client_token = settings.TWILIO_TOKEN
-        self.from_number = settings.TWILIO_FROM_NUMBER
-        self.messaging_sid = settings.TWILIO_MESSAGING_SID
+    def __init__(
+        self,
+        client_sid: str | None = None,
+        client_token: str | None = None,
+        from_number: str | None = None,
+        messaging_sid: str | None = None,
+    ) -> None:
+        """
+        Sets Twilio client session variables.
+
+        All parameters are optional, default values are pulled from a Django settings module.
+
+        :param client_sid: A Twilio client session id.
+        :type client_sid: :py:obj:`str` | :py:obj:`None`
+        :param client_token: A Twilio client API token.
+        :type client_token: :py:obj:`str` | :py:obj:`None`
+        :param from_number: Phone number used to send notifications.
+        :type from_number: :py:obj:`str` | :py:obj:`None`
+        :param messaging_sid: A Twilio client messaging service session id.
+        :type messaging_sid: :py:obj:`str` | :py:obj:`None`
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        self._client_sid = client_sid or settings.TWILIO_SID
+        self._client_token = client_token or settings.TWILIO_TOKEN
+        self._from_number = from_number or settings.TWILIO_FROM_NUMBER
+        self._messaging_sid = messaging_sid or settings.TWILIO_MESSAGING_SID
 
     def __enter__(self) -> "TwilioCaller":
-        """Creates an asyncronous Twilio client."""
+        """Opens a context manager and creates an asyncronous Twilio client."""
         self.client = twilio.rest.Client(
-            self.client_sid, self.client_token, http_client=AsyncTwilioHttpClient()
+            self.client_sid, self._client_token, http_client=AsyncTwilioHttpClient()
         )
         return self
 
     def __exit__(self, exc_type, exc_value, exc_tb) -> None:
+        """Closes the context manager."""
         return None
 
-    async def create_notification(
+    def create_notification(
         self, to_number: str, message: str, method: str = "sms"
     ) -> asyncio.Task[Any]:
         """
         Returns an awaitable notification task.
 
-        Available methods are ``"sms"``, ``"call"`` and ``"phone"``.
+        Valid methods are ``"sms"``, ``"call"`` and ``"phone"``.
 
         :param to_number: A phone number to notify.
         :type to_number: :py:obj:`str`
@@ -48,6 +71,7 @@ class TwilioCaller:
         :type message: :py:obj:`str`
         :param method: A notification method. Default is ``"sms"``.
         :type method: :py:obj:`str`
+        :raises ValueError: If ``method`` is invalid.
         :returns: An awaitable task.
         :rtype: :py:obj:`~asyncio.Task`
 
@@ -100,3 +124,33 @@ class TwilioCaller:
             body=message,
             messaging_service_sid=self.messaging_sid,
         )
+
+    @property
+    def client_sid(self) -> str:
+        """
+        Client session id.
+
+        :type: :py:obj:`str`
+
+        """
+        return self._client_sid
+
+    @property
+    def from_number(self) -> str:
+        """
+        Origin phone number.
+
+        :type: :py:obj:`str`
+
+        """
+        return self._from_number
+
+    @property
+    def messaging_sid(self) -> str:
+        """
+        Messaging service session id.
+
+        :type: :py:obj:`str`
+
+        """
+        return self._messaging_sid

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/utils.py

@@ -2,10 +2,9 @@ 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_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.")