python-terminusgps 46.0.0__py3-none-any.whl → 47.0.0__py3-none-any.whl

{python_terminusgps-46.0.0.dist-info → python_terminusgps-47.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 46.0.0
+Version: 47.0.0
 Summary: Provides abstractions/utilities for working with Wialon API, Authorize.NET API, AWS API, and more.
 Project-URL: Documentation, https://terminusgps.github.io/python-terminusgps
 Project-URL: Repository, https://github.com/terminusgps/python-terminusgps

{python_terminusgps-46.0.0.dist-info → python_terminusgps-47.0.0.dist-info}/RECORD

@@ -3,7 +3,7 @@ terminusgps/default_settings.py,sha256=7GLW3RlkuTbpj82KSWjcbgf-unEmrPvKCyLci14LG
 terminusgps/mixins.py,sha256=Q9ZJuzpk3d9lDnlVA8ZTVvnZWxB13p08EQ8yVJcztn4,1034
 terminusgps/validators.py,sha256=Mf0c7ku_wTQ7uv4hcLRyz0r2eRjvznIL77LLTE5uJ6E,9152
 terminusgps/authorizenet/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-terminusgps/authorizenet/constants.py,sha256=Bat87PXB-g5_FM0pkAwX2dTHLJ05UAf_xLery4eKmr0,2723
+terminusgps/authorizenet/constants.py,sha256=nz3XX2jp9icsJhbSTKi9X-TQDr6jrs35opSWpYuwePc,2757
 terminusgps/authorizenet/service.py,sha256=jjYo1vLgTZSXVNeBY6uKSma94AgEj3Q5xOAT5wUB6ko,4260
 terminusgps/authorizenet/api/__init__.py,sha256=VXR4Yco1yz5R-R7vgaH2zTP9VFqzfvvGy_XJVjyb3i0,154
 terminusgps/authorizenet/api/address_profiles.py,sha256=VouUN6dIxlnuE3qEiacFqqDBi_VtwvSbsELqTqFZ0BE,4746
@@ -14,7 +14,7 @@ terminusgps/authorizenet/api/transactions.py,sha256=zwbUXGxI1wkTXSPG4L4O5Y2fdNgx
 terminusgps/wialon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/wialon/constants.py,sha256=p2BhopeE6lXzjzdzb4ZKOz0rhJQIMUbXLrBy1Yzf57s,13730
 terminusgps/wialon/flags.py,sha256=M50EdhxQ8IMnJnU0mrHK7-h8Asc6tvNiTOOfd1dBW6A,12815
-terminusgps/wialon/session.py,sha256=GdgPvhNbUrvx_-vPRWsjY5TeuI3HgjlHcy315LBpZ7o,5646
+terminusgps/wialon/session.py,sha256=lvxQ2uh0XSrK7DiSlkeMTfplR56111pVPK5tPCd_13U,6761
 terminusgps/wialon/utils.py,sha256=E7J9s4p7P-OePtttxcBogxu3WiXqf4xxr_Tksbisl60,9957
 terminusgps/wialon/validators.py,sha256=o5__H9HHnGYth8QAKErJG5rEub7FnT8ue0S3IQ8b67o,4232
 terminusgps/wialon/items/__init__.py,sha256=RTiY9ziXqKCB8VWGoExOIErDlUMBBfzzsA7nlOlCZ2w,41
@@ -27,7 +27,7 @@ terminusgps/wialon/items/route.py,sha256=9hmRBEFRJF3lKukv_y3blZxqxv75YgFCcRALrU6
 terminusgps/wialon/items/unit.py,sha256=B5iuGEghu89SL8KzYLUytYNRa8cogsVtf-bJ_RybPTA,5522
 terminusgps/wialon/items/unit_group.py,sha256=MIR0x5IlTjcnwx8Y9wXLNTql-wwVVj7NCe7dL2vOw4c,2131
 terminusgps/wialon/items/user.py,sha256=CRSICiJ-qzybEO_gXuKyzW5oa2RQeIp0SzX9ARcdME4,5151
-python_terminusgps-46.0.0.dist-info/METADATA,sha256=FEQ3DDBwtUI1T9NTyNl0Az-9M2ecIW8ihK4v8Ynftns,938
-python_terminusgps-46.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_terminusgps-46.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_terminusgps-46.0.0.dist-info/RECORD,,
+python_terminusgps-47.0.0.dist-info/METADATA,sha256=x73rSYGD1RfEUhMbYqZbpxUI7pv2j4dd_y-7pmutVUY,938
+python_terminusgps-47.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_terminusgps-47.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_terminusgps-47.0.0.dist-info/RECORD,,

terminusgps/authorizenet/constants.py

@@ -46,15 +46,17 @@ class SubscriptionStatus(models.TextChoices):
     """An Authorizenet subscription status."""
 
     ACTIVE = "active", _("Active")
-    """Active subscription."""
+    """Active status."""
     EXPIRED = "expired", _("Expired")
-    """Expired subscription."""
+    """Expired status."""
     SUSPENDED = "suspended", _("Suspended")
-    """Suspended subscription."""
+    """Suspended status."""
     CANCELED = "canceled", _("Canceled")
-    """Canceled subscription."""
+    """Canceled status."""
     TERMINATED = "terminated", _("Terminated")
-    """Terminated subscription."""
+    """Terminated status."""
+    UNKNOWN = "unknown", _("Unknown")
+    """Unknown status."""
 
 
 class SubscriptionIntervalUnit(models.TextChoices):

terminusgps/wialon/session.py

@@ -1,8 +1,11 @@
+import logging
 import os
 import typing
 
 import wialon.api
 
+logger = logging.getLogger(__name__)
+
 
 class WialonAPIError(Exception):
     """Raised when a Wialon API call fails."""
@@ -19,46 +22,56 @@ class WialonAPIError(Exception):
 
 
 class Wialon(wialon.api.Wialon):
-    def call(self, *argc, **kwargs) -> dict[str, typing.Any]:
+    def call(self, action_name, *argc, **kwargs) -> dict[str, typing.Any]:
         try:
-            return super().call(*argc, **kwargs)
+            return super().call(action_name, *argc, **kwargs)
         except wialon.api.WialonError as e:
+            logger.warning(f"Failed to execute '{action_name}': '{e}'")
             raise WialonAPIError(e)
 
 
 class WialonSession:
     def __init__(
         self,
-        token: str | None = None,
-        sid: str | None = None,
         scheme: str = "https",
         host: str = "hst-api.wialon.com",
         port: int = 443,
+        sid: str | None = None,
+        token: str | None = None,
+        auth_hash: str | None = None,
+        username: str | None = None,
+        check_service: str | None = None,
     ) -> None:
         """
         Starts or continues a Wialon API session.
 
-        :param token: A Wialon API token. If not provided, the environment variable ``"WIALON_TOKEN"`` is used.
-        :type token: str | None
-        :param sid: An optional Wialon API session id. If provided, the session is continued.
-        :type sid: str | None
         :param scheme: HTTP request scheme to use. Default is ``"https"``.
         :type scheme: str
         :param host: Wialon API host url. Default is ``"hst-api.wialon.com"``.
         :type host: str
         :param port: Wialon API port. Default is ``443``.
         :type port: int
+        :param sid: A Wialon API session id. Default is :py:obj:`None`.
+        :type sid: str | None
+        :param token: A Wialon API token. Default is :py:obj:`None`.
+        :type token: str | None
+        :param auth_hash: A Wialon API authentication hash. Default is environment variable ``"WIALON_TOKEN"``.
+        :type auth_hash: str | None
+        :param username: A Wialon user id to operate as during the session. Default is :py:obj:`None`.
+        :type username: str | None
+        :param check_service: A Wialon service name to check before calling the Wialon API. Default is :py:obj:`None`.
+        :type check_service: str | None
         :returns: Nothing.
         :rtype: None
 
         """
+        self._uid = None
+        self._wialon_api = Wialon(scheme=scheme, host=host, port=port, sid=sid)
 
         self._token = token if token else os.getenv("WIALON_TOKEN")
-        self._username = None
-        self._uid = None
-        self._wialon_api = Wialon(
-            scheme=scheme, host=host, port=port, sid=sid, token=self.token
-        )
+        self._username = username
+        self._auth_hash = auth_hash
+        self._check_service = check_service
 
     def __str__(self) -> str:
         return f"Session #{self.id}"
@@ -67,27 +80,89 @@ class WialonSession:
         return f"{self.__class__}(sid={self.id})"
 
     def __enter__(self) -> "WialonSession":
+        """Logs into the Wialon API session if it wasn't already active before returning it."""
+        if self.id is None:
+            if self._token:
+                self.token_login(token=self._token, username=self._username)
+            elif self._auth_hash and self._username:
+                self.auth_hash_login(
+                    auth_hash=self._auth_hash,
+                    username=self._username,
+                    check_service=self._check_service,
+                )
+            else:
+                raise WialonAPIError(
+                    message="Failed to login to the Wialon API", code=9001
+                )
+        return self
+
+    def __exit__(self, *args, **kwargs) -> None:
+        """Logs out of the Wialon API session if :py:attr:`id` was set."""
+        if self.id is not None:
+            self.logout()
+
+    def token_login(self, token: str, username: str | None = None) -> None:
         """
-        Logs into the Wialon API using :py:meth:`login`.
+        Logs in to a Wialon API session using a token.
 
-        :raises AssertionError: If the session's Wialon API :py:attr:`token` wasn't set.
-        :returns: A valid Wialon API session.
-        :rtype: ~terminusgps.wialon.session.WialonSession
+        :param token: A Wialon API token.
+        :type token: str
+        :param username: Wialon user to operate as during the Wialon API session. Default is :py:obj:`None`.
+        :type username: str
+        :returns: Nothing.
+        :rtype: None
 
         """
-        assert self.token, "Wialon API token wasn't set."
-        self.login(self.token)
-        return self
+        params = {"token": token, "flags": 0x3 if username else 0x1}
+        if username is not None:
+            params.update({"operateAs": username})
+        response = self.wialon_api.token_login(**params)
+        self.wialon_api.sid = response.get("eid")
+        self._username = response.get("au")
+        self._uid = response.get("user", {}).get("id")
+
+    def auth_hash_login(
+        self, auth_hash: str, username: str, check_service: str | None = None
+    ) -> None:
+        """
+        Logs in to a Wialon API session using an auth hash.
+
+        :param auth_hash: An authorization hash.
+        :type auth_hash: str
+        :param username: Wialon user to operate as during the Wialon API session.
+        :type username: str
+        :param check_service: Name of a Wialon service to check if the user has access to. Default is :py:obj:`None` (no service check).
+        :type check_service: str | None
+        :returns: Nothing.
+        :rtype: None
 
-    def __exit__(self, exc_type, exc_value, exc_traceback) -> None:
         """
-        Logs out of the session by calling :py:meth:`logout`.
+        params = {"authHash": auth_hash, "operateAs": username}
+        if check_service is not None:
+            params.update({"checkService": check_service})
+        response = self.wialon_api.core_use_auth_hash(**params)
+        self.wialon_api.sid = response.get("eid")
+        self._username = response.get("au")
+        self._uid = response.get("user", {}).get("id")
 
+    def logout(self) -> None:
+        """
+        Logs out of the Wialon API session.
+
+        :raises WialonAPIError: If the Wialon API session logout failed.
         :returns: Nothing.
         :rtype: None
 
         """
-        self.logout()
+        session_id = self.wialon_api.sid
+        if session_id is not None:
+            response = self.wialon_api.core_logout({})
+            if not int(response.get("error")) == 0:
+                raise WialonAPIError(
+                    message=f"Failed to logout of the Wialon API session #{session_id}",
+                    code=int(response.get("error")),
+                )
+            self.wialon_api.sid = None
 
     @property
     def wialon_api(self) -> Wialon:
@@ -128,74 +203,3 @@ class WialonSession:
 
         """
         return self.wialon_api.sid
-
-    @property
-    def token(self) -> str:
-        """
-        Wialon API token set during :py:meth:`WialonSession.__init__`.
-
-        :type: str
-
-        """
-        return str(self._token)
-
-    def login(self, token: str, flags: int | None = None) -> str:
-        """
-        Logs into the Wialon API, starts a new session then returns its id.
-
-        :param token: An active Wialon API token.
-        :type token: str
-        :param flags: A login response flag integer.
-        :type flags: int
-        :raises WialonError: If the login fails.
-        :raises AssertionError: If the login token was not set.
-        :returns: The new session id.
-        :rtype: str
-
-        """
-        try:
-            response = self.wialon_api.token_login(
-                **{"token": token, "fl": flags if flags else 0x2}
-            )
-            self._set_login_response(response)
-            return response.get("eid", "")
-        except (wialon.api.WialonError, ValueError):
-            print("Failed to login to the Wialon API.")
-            raise
-
-    def logout(self) -> None:
-        """
-        Logs out of the Wialon API session.
-
-        :returns: Nothing.
-        :rtype: None
-
-        """
-        sid = self.wialon_api.sid
-        response = self.wialon_api.core_logout({})
-
-        if response.get("error") != 0:
-            print(
-                f"Failed to properly logout of session #{sid}: '{response.get('message')}'"
-            )
-        self.wialon_api.sid = None
-
-    def _set_login_response(self, login_response: dict | None = None) -> None:
-        """
-        Sets the Wialon API session's attributes based on a login response.
-
-        :param login_response: A dictionary returned from :py:meth:`login`.
-        :type login_response: dict
-        :raises ValueError: If ``login_response`` wasn't provided.
-        :returns: Nothing.
-        :rtype: None
-
-        """
-        if login_response is None:
-            raise ValueError(
-                f"Login response is required, got '{login_response}'"
-            )
-
-        self.wialon_api.sid = login_response.get("eid")
-        self._uid = login_response.get("user", {}).get("id")
-        self._username = login_response.get("au")