python-terminusgps 43.2.0__tar.gz → 44.0.0__tar.gz

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 43.2.0
+Version: 44.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-43.2.0 → python_terminusgps-44.0.0}/docs/source/authorizenet/api.rst

@@ -1,5 +1,5 @@
-Authorizenet API Endpoints
-==========================
+Functions
+=========
 
 ================
 Address Profiles

python_terminusgps-44.0.0/docs/source/authorizenet/auth.rst

@@ -0,0 +1,22 @@
+Authentication
+==============
+
+Authentication for each Authorizenet API call is handled by values defined in a Django ``settings.py`` module.
+
+Required settings:
+
+   +-----------------------------------+---------------+
+   | setting                           | type          |
+   +===================================+===============+
+   | ``MERCHANT_AUTH_ENVIRONMENT``     | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_LOGIN_ID``        | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_TRANSACTION_KEY`` | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_VALIDATION_MODE`` | :py:obj:`str` |
+   +-----------------------------------+---------------+
+
+.. automodule:: terminusgps.authorizenet.auth
+    :synopsis: Provides functions for authenticating Authorizenet API calls.
+    :members:

python_terminusgps-44.0.0/docs/source/authorizenet/constants.rst

@@ -0,0 +1,20 @@
+Constants
+=========
+
+These constants inherit from :py:obj:`~django.db.models.TextChoices`, not the built-in Python :py:obj:`~enum.StrEnum` type.
+
+Django :py:obj:`~django.db.models.TextChoices` provides attributes such as :py:attr:`~django.db.models.TextChoices.choices`, :py:attr:`~django.db.models.TextChoices.values`, :py:attr:`~django.db.models.TextChoices.labels` and more.
+
+.. py:currentmodule:: terminusgps.authorizenet.constants
+
+.. autoclass:: Environment
+    :members:
+
+.. autoclass:: SubscriptionStatus
+    :members:
+
+.. autoclass:: SubscriptionIntervalUnit
+    :members:
+
+.. autoclass:: ValidationMode
+    :members:

python_terminusgps-43.2.0/docs/source/authorizenet/controllers.rst → python_terminusgps-44.0.0/docs/source/authorizenet/exceptions.rst

@@ -1,4 +1,4 @@
-API Controllers
-===============
+Exceptions
+==========
 
 .. autoexception:: terminusgps.authorizenet.controllers.AuthorizenetControllerExecutionError

python_terminusgps-44.0.0/docs/source/authorizenet/index.rst

@@ -0,0 +1,33 @@
+Authorizenet
+============
+
+The :py:mod:`terminusgps.authorizenet` package provides convenient functions for interacting with the Authorizenet API in a Pythonic interface.
+
+Most `Authorizenet API endpoints <https://developer.authorize.net/api/reference/index.html>`_ are represented as plain Python functions.
+
+.. attention:: These functions require the following settings to be present in your Django project's ``settings.py`` module.
+
+   Using this package without setting these settings will raise :py:exc:`~django.core.exceptions.ImproperlyConfigured`.
+
+   +-----------------------------------+---------------+
+   | setting                           | type          |
+   +===================================+===============+
+   | ``MERCHANT_AUTH_ENVIRONMENT``     | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_LOGIN_ID``        | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_TRANSACTION_KEY`` | :py:obj:`str` |
+   +-----------------------------------+---------------+
+   | ``MERCHANT_AUTH_VALIDATION_MODE`` | :py:obj:`str` |
+   +-----------------------------------+---------------+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    api.rst
+    auth.rst
+    constants.rst
+    exceptions.rst
+    usage.rst
+    validators.rst

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/docs/source/conf.py

@@ -12,7 +12,7 @@ sys.path.insert(0, os.path.abspath("../../"))
 project = "python-terminusgps"
 copyright = "2025, Terminus GPS, LLC"
 author = "Terminus GPS, LLC"
-release = "43.2.0"
+release = "44.0.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -28,8 +28,8 @@ extensions = [
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "django": (
-        "http://docs.djangoproject.com/en/stable/",
-        "http://docs.djangoproject.com/en/stable/_objects/",
+        "https://docs.djangoproject.com/en/5.2/",
+        "https://docs.djangoproject.com/en/5.2/objects.inv",
     ),
 }
 
@@ -40,7 +40,9 @@ exclude_patterns = []
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+autodoc_member_order = "groupwise"
 html_theme = "sphinxawesome_theme"
 pygments_style = "sas"
 pygments_style_dark = "lightbulb"
 html_static_path = ["_static"]
+graphviz_dot = "/usr/bin/dot"

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/docs/source/index.rst

@@ -8,7 +8,7 @@ python-terminusgps documentation
 
 `python-terminusgps <https://pypi.org/project/python-terminusgps>`_ is a package [#f1]_ of subpackages that streamlines the use of web APIs for Terminus GPS developers.
 
-`Terminus GPS <https://terminusgps.com/>`_ is an IoT hardware/software GPS monitoring company.
+`Terminus GPS <https://terminusgps.com/>`_ is an IoT software/hardware GPS monitoring company.
 
 .. [#f1] In other programming languages, the term "library" is used to describe what Python calls a "package". Put simply, a "package" is a Python "library".
 
@@ -16,23 +16,17 @@ python-terminusgps documentation
 Installation
 ============
 
-
 Use pip to install from `PyPI <https://pypi.org/project/python-terminusgps/>`_.
 
 .. code:: bash
 
-   pip install python-terminusgps
-
-All subpackages are nested within :py:mod:`terminusgps`:
-
-.. code:: python
-
-    from terminusgps.wialon.session import WialonSession # Creates Wialon API sessions
+    pip install python-terminusgps
 
 .. toctree::
     :maxdepth: 2
     :caption: Contents:
 
     authorizenet/index.rst
-    django/index.rst
+    mixins.rst
+    validators.rst
     wialon/index.rst

python_terminusgps-44.0.0/docs/source/mixins.rst

@@ -0,0 +1,5 @@
+Mixins
+======
+
+.. autoclass:: terminusgps.mixins.HtmxTemplateResponseMixin
+    :members:

python_terminusgps-44.0.0/docs/source/validators.rst

@@ -0,0 +1,5 @@
+Validators
+==========
+
+.. automodule:: terminusgps.validators
+    :members:

python_terminusgps-44.0.0/docs/source/wialon/exceptions.rst

@@ -0,0 +1,5 @@
+Exceptions
+==========
+
+.. autoexception:: terminusgps.wialon.session.WialonAPIError
+    :members:

python_terminusgps-44.0.0/docs/source/wialon/index.rst

@@ -0,0 +1,14 @@
+Wialon
+======
+The :py:mod:`terminusgps.wialon` package provides a Pythonic interface for interacting with the Wialon API.
+
+Most Wialon objects are modeled as plain Python objects which have attributes and methods that make `Wialon API calls <https://help.wialon.com/en/api/user-guide/api-reference>`_.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    items.rst
+    exceptions.rst
+    session.rst
+    usage.rst

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/docs/source/wialon/items.rst

@@ -9,38 +9,43 @@ Base
     :autoclasstoc:
     :members:
 
-=======
-Factory
-=======
+=========
+Factories
+=========
 
 .. autoclass:: terminusgps.wialon.items.factory.WialonObjectFactory
     :autoclasstoc:
-    :members:
+
 
 ==============
 Wialon objects
 ==============
 
 .. autoclass:: terminusgps.wialon.items.account.WialonAccount
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.resource.WialonResource
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.retranslator.WialonRetranslator
-    :members:
-
-.. autoclass:: terminusgps.wialon.items.retranslator.WialonRetranslatorConfiguration
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.route.WialonRoute
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.unit.WialonUnit
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.unit_group.WialonUnitGroup
+    :autoclasstoc:
     :members:
 
 .. autoclass:: terminusgps.wialon.items.user.WialonUser
+    :autoclasstoc:
     :members:
+

python_terminusgps-44.0.0/docs/source/wialon/session.rst

@@ -0,0 +1,6 @@
+Sessions
+========
+
+.. autoclass:: terminusgps.wialon.session.WialonSession
+   :members:
+   :class-doc-from: init

python_terminusgps-44.0.0/docs/source/wialon/usage.rst

@@ -0,0 +1,70 @@
+Usage
+=====
+
+To perform Wialon API operations, open a :py:obj:`~terminusgps.wialon.session.WialonSession` in a context manager, passing in your desired Wialon API token to use during the session's lifetime.
+
+If :py:data:`token` isn't provided, the environment variable ``"WIALON_TOKEN"`` is passed instead.
+
+.. code:: python
+
+    from terminusgps.wialon.session import WialonSession
+
+    # Context manager handles logging in and out of the Wialon API session
+    with WialonSession(token="my_wialon_api_token") as session:
+        # Perform Wialon API calls within this block
+        # Session is logged out when the interpreter exits this block
+        session.wialon_api.core_search_item(**{"id": 123, "flags": 0x1})
+
+    # Will raise WialonAPIError because the session is now invalid (logged out)
+    session.wialon_api.core_search_item(**{"id": 123, "flags": 0x1})
+
+Instead of remembering every `Wialon API endpoint <https://help.wialon.com/en/api/user-guide/api-reference>`_, initialize a :py:obj:`~terminusgps.wialon.items.factory.WialonObjectFactory` in a :py:obj:`~terminusgps.wialon.session.WialonSession` to retrieve objects with convenient methods for calling the Wialon API:
+
+.. code:: python
+
+    from terminusgps.wialon.items import WialonObjectFactory
+    from terminusgps.wialon.session import WialonSession
+
+    with WialonSession(token="my_wialon_api_token") as session:
+        # A valid Wialon API session is the only argument passed to the factory
+        factory = WialonObjectFactory(session)
+        # Call get() or create() on the factory to retrieve a WialonObject instance
+        # The 'items_type' argument mirrors Wialon's definition of Wialon objects, e.g. 'avl_unit' for WialonUnit, 'avl_resource' for WialonResource, etc.
+        unit = factory.get("avl_unit", 123)
+        # Refer to your IDE or this documentation for available attributes and methods of each Wialon object type.
+
+========
+Examples
+========
+
+Creating a new Wialon user
+--------------------------
+
+.. code:: python
+
+    from terminusgps.wialon.items import WialonObjectFactory
+    from terminusgps.wialon.session import WialonSession
+
+    with WialonSession() as session:
+        factory = WialonObjectFactory(session)
+        user = factory.create(
+            "user",
+            creator_id=12345678,
+            name="New User",
+            password="my_secure_password!1",
+        )
+
+.. seealso:: :py:meth:`~terminusgps.wialon.items.user.WialonUser.create` for details on creating a Wialon user.
+
+Update an existing Wialon user's name
+-------------------------------------
+
+.. code:: python
+
+    from terminusgps.wialon.items import WialonObjectFactory
+    from terminusgps.wialon.session import WialonSession
+
+    with WialonSession() as session:
+        factory = WialonObjectFactory(session)
+        user = factory.get("user", id=12345678)
+        user.set_name("New User")

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-terminusgps"
-version = "43.2.0"
+version = "44.0.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-44.0.0/terminusgps/authorizenet/auth.py

@@ -0,0 +1,56 @@
+from authorizenet.apicontractsv1 import merchantAuthenticationType
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+
+def get_merchant_auth() -> merchantAuthenticationType:
+    """
+    Returns the merchant authentication information for Authorizenet API controller execution.
+
+    :raises ~django.core.exceptions.ImproperlyConfigured: If the :py:data:`MERCHANT_AUTH_LOGIN_ID` or the :py:data:`MERCHANT_AUTH_TRANSACTION_KEY` settings weren't set.
+    :returns: A merchant authentication object.
+    :rtype: ~authorizenet.apicontractsv1.merchantAuthenticationType
+
+    """
+    if not all(
+        [
+            hasattr(settings, "MERCHANT_AUTH_LOGIN_ID"),
+            hasattr(settings, "MERCHANT_AUTH_TRANSACTION_KEY"),
+        ]
+    ):
+        error_msg: str = "'MERCHANT_AUTH_LOGIN_ID' and 'MERCHANT_AUTH_TRANSACTION_KEY' settings are required."
+        raise ImproperlyConfigured(error_msg)
+    return merchantAuthenticationType(
+        name=str(settings.MERCHANT_AUTH_LOGIN_ID),
+        transactionKey=str(settings.MERCHANT_AUTH_TRANSACTION_KEY),
+    )
+
+
+def get_environment() -> str:
+    """
+    Returns the environment for Authorizenet API controller execution.
+
+    :raises ~django.core.exceptions.ImproperlyConfigured: If the :py:data:`MERCHANT_AUTH_ENVIRONMENT` setting wasn't set.
+    :returns: An Authorizenet API environment string.
+    :rtype: str
+
+    """
+    if not hasattr(settings, "MERCHANT_AUTH_ENVIRONMENT"):
+        error_msg: str = "'MERCHANT_AUTH_ENVIRONMENT' setting is required."
+        raise ImproperlyConfigured(error_msg)
+    return settings.MERCHANT_AUTH_ENVIRONMENT
+
+
+def get_validation_mode() -> str:
+    """
+    Returns the validation mode for Authorizenet API controller execution.
+
+    :raises ~django.core.exceptions.ImproperlyConfigured: If the :py:data:`MERCHANT_AUTH_VALIDATION_MODE` setting wasn't set.
+    :returns: An Authorizenet API validation string.
+    :rtype: str
+
+    """
+    if not hasattr(settings, "MERCHANT_AUTH_VALIDATION_MODE"):
+        error_msg: str = "'MERCHANT_AUTH_VALIDATION_MODE' setting is required."
+        raise ImproperlyConfigured(error_msg)
+    return settings.MERCHANT_AUTH_VALIDATION_MODE

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/terminusgps/authorizenet/constants.py

@@ -1,12 +1,10 @@
 from authorizenet import apicontractsv1
+from authorizenet.constants import constants as anet_constants
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-ANET_XMLNS = "{AnetApi/xml/v1/schema/AnetApiSchema.xsd}"
-"""Authorizenet XML namespace."""
 
-
-class AuthorizenetSubscriptionStatus(models.TextChoices):
+class SubscriptionStatus(models.TextChoices):
     """An Authorizenet subscription status."""
 
     ACTIVE = "active", _("Active")
@@ -21,10 +19,28 @@ class AuthorizenetSubscriptionStatus(models.TextChoices):
     """Terminated subscription."""
 
 
-class AuthorizenetSubscriptionIntervalUnit(models.TextChoices):
+class SubscriptionIntervalUnit(models.TextChoices):
     """An Authorizenet subscription interval unit."""
 
     DAYS = apicontractsv1.ARBSubscriptionUnitEnum.days, _("Days")
     """Days interval unit."""
     MONTHS = apicontractsv1.ARBSubscriptionUnitEnum.months, _("Months")
     """Months interval unit."""
+
+
+class Environment(models.TextChoices):
+    """An Authorizenet execution environment."""
+
+    SANDBOX = anet_constants.SANDBOX, _("Sandbox Environment")
+    """Sandbox environment."""
+    PRODUCTION = anet_constants.PRODUCTION, _("Production Environment")
+    """Production environment."""
+
+
+class ValidationMode(models.TextChoices):
+    """An Authorizenet validation mode."""
+
+    TEST = "testMode", _("Test Mode")
+    """Test mode."""
+    LIVE = "liveMode", _("Live Mode")
+    """Live mode."""

{python_terminusgps-43.2.0 → python_terminusgps-44.0.0}/terminusgps/authorizenet/controllers.py

@@ -11,10 +11,10 @@ def execute_controller(
     Executes an Authorizenet API controller and returns its response.
 
     :param controller: An Authorizenet API controller.
-    :type controller: :py:obj:`~authorizenet.apicontrollersbase.APIOperationBase`
+    :type controller: ~authorizenet.apicontrollersbase.APIOperationBase
     :raises AuthorizenetControllerExecutionError: If the API call fails.
     :returns: An Authorizenet API response, if any.
-    :rtype: :py:obj:`~lxml.objectify.ObjectifiedElement` | :py:obj:`None`
+    :rtype: ~lxml.objectify.ObjectifiedElement | None
 
     """
     controller.setenvironment(get_environment())
@@ -33,17 +33,6 @@ class AuthorizenetControllerExecutionError(Exception):
     """Raised when an Authorizenet API controller fails to execute."""
 
     def __init__(self, message: str, code: str, *args, **kwargs) -> None:
-        """
-        Sets :py:attr:`message` and :py:attr`code` for the exception.
-
-        :param message: An Authorizenet API error message.
-        :type message: :py:obj:`str`
-        :param code: An Authorizenet API error code.
-        :type code: :py:obj:`str`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
         super().__init__(message, *args, **kwargs)
         self._message = message
         self._code = code

python_terminusgps-43.2.0/terminusgps/django/settings.py → python_terminusgps-44.0.0/terminusgps/default_settings.py

@@ -1,18 +1,18 @@
 import os
 import pathlib
 
-from authorizenet.constants import constants
+from terminusgps.authorizenet.constants import Environment, ValidationMode
 
 BASE_DIR = pathlib.Path(__file__).resolve().parent
+
 DEBUG = True
 SECRET_KEY = "xem*6no%8d9%^qzt2f3x3ar-uq4_+7h9myc$t0!+4%bj5us6f)"
 USE_TZ = False
-DEFAULT_FIELD_CLASS = "p-2 w-full bg-white dark:bg-gray-700 dark:text-white rounded border dark:border-terminus-gray-300"
-DEFAULT_TAX_RATE = "0.0825"
+
+MERCHANT_AUTH_ENVIRONMENT = Environment.SANDBOX
+MERCHANT_AUTH_VALIDATION_MODE = ValidationMode.TEST
 
 # Secrets
 MERCHANT_AUTH_LOGIN_ID = os.getenv("MERCHANT_AUTH_LOGIN_ID")
 MERCHANT_AUTH_TRANSACTION_KEY = os.getenv("MERCHANT_AUTH_TRANSACTION_KEY")
-MERCHANT_AUTH_ENVIRONMENT = constants.SANDBOX
-MERCHANT_AUTH_VALIDATION_MODE = "testMode"
 WIALON_TOKEN = os.getenv("WIALON_TOKEN")