python-terminusgps 35.0.0__tar.gz → 35.1.0__tar.gz

{python_terminusgps-35.0.0 → python_terminusgps-35.1.0}/PKG-INFO

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

{python_terminusgps-35.0.0 → python_terminusgps-35.1.0}/docs/source/aws/index.rst

@@ -9,5 +9,4 @@ AWS API
 
     notifications.rst
     secrets.rst
-    speech.rst
     utils.rst

python_terminusgps-35.1.0/docs/source/aws/notifications.rst

@@ -0,0 +1,7 @@
+Notifications
+=============
+
+.. autoclass:: terminusgps.aws.notifications.AsyncNotificationManager
+    :members:
+    :exclude-members: __weakref__
+    :autoclasstoc:

{python_terminusgps-35.0.0 → python_terminusgps-35.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-terminusgps"
-version = "35.0.0"
+version = "35.1.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-35.1.0/terminusgps/aws/notifications.py

@@ -0,0 +1,197 @@
+import os
+from contextlib import AsyncExitStack
+
+from aiobotocore.session import AioSession
+
+
+class AsyncNotificationManager:
+    """Asyncronously delivers notifications using `AWS End User Messaging <https://docs.aws.amazon.com/end-user-messaging/>`_."""
+
+    def __init__(
+        self,
+        origin_pool_arn: str | None = os.getenv("AWS_MESSAGING_ORIGIN_POOL"),
+        configuration_set: str | None = os.getenv("AWS_MESSAGING_CONFIGURATION"),
+        max_sms_price: str = "0.20",
+        max_voice_price: str = "0.20",
+        region_name: str = "us-east-1",
+        debug_enabled: bool = False,
+    ) -> None:
+        """
+        Sets attributes on the notification manager.
+
+        :param origin_pool_arn: A phone pool ARN for notification dispatch. Default is :envvar:`AWS_MESSAGING_ORIGIN_POOL`.
+        :type origin_pool_arn: :py:obj:`str` | :py:obj:`None`
+        :param configuration_set: An end-user messaging configuration set ARN. Default is :envvar:`AWS_MESSAGING_CONFIGURATION`.
+        :type configuration_set: :py:obj:`str` | :py:obj:`None`
+        :param max_sms_price: Max price to spend on a single SMS message.
+        :type max_sms_price: :py:obj:`str`
+        :param max_voice_price: Max price to spend per minute on a single voice message.
+        :type max_voice_price: :py:obj:`str`
+        :param region_name: An AWS region name used to open an AWS client.
+        :type region_name: :py:obj:`str`
+        :param debug_enabled: Whether or not to enable debug mode.
+        :type debug_enabled: :py:obj:`None`
+        :raises ValueError: If ``origin_pool_arn`` wasn't provided and :envvar:`AWS_MESSAGING_ORIGIN_POOL` wasn't set.
+        :raises ValueError: If ``configuration_set`` wasn't provided and :envvar:`AWS_MESSAGING_CONFIGURATION` wasn't set.
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        if origin_pool_arn is None:
+            raise ValueError(f"'origin_pool_arn' is required, got '{origin_pool_arn}'.")
+        if configuration_set is None:
+            raise ValueError(
+                f"'configuration_set' is required, got '{configuration_set}'."
+            )
+
+        self._exit_stack = AsyncExitStack()
+        self._pinpoint_client = None
+        self._region_name = region_name
+        self._origin_pool_arn = origin_pool_arn
+        self._configuration_set = configuration_set
+        self._max_sms_price = max_sms_price
+        self._max_voice_price = max_voice_price
+        self._debug = debug_enabled
+
+    async def __aenter__(self) -> "AsyncNotificationManager":
+        """
+        Creates asyncronous clients.
+
+        :returns: The notification manager.
+        :rtype: :py:obj:`~terminusgps.aws.notifications.AsyncNotificationManager`
+
+        """
+        session = AioSession()
+        self._pinpoint_client = await self._exit_stack.enter_async_context(
+            session.create_client("pinpoint-sms-voice-v2", region_name=self.region_name)
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """
+        Destroys asyncronous clients.
+
+        :param exc_type: Exception type.
+        :param exc_val: Exception value.
+        :param exc_tb: Exception traceback.
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+
+    @property
+    def region_name(self) -> str:
+        """
+        An AWS region name.
+
+        :type: :py:obj:`str`
+
+        """
+        return self._region_name
+
+    @property
+    def configuration_set(self) -> str:
+        return self._configuration_set
+
+    @property
+    def origin_pool(self) -> str:
+        return self._origin_pool_arn
+
+    @property
+    def max_sms_price(self) -> str:
+        return self._max_sms_price
+
+    @property
+    def max_voice_price(self) -> str:
+        return self._max_voice_price
+
+    @property
+    def debug(self) -> bool:
+        return self._debug
+
+    async def send_sms(
+        self,
+        phone: str,
+        message: str,
+        ttl: int = 300,
+        dry_run: bool = False,
+        feedback: bool = False,
+    ) -> dict:
+        """
+        Texts ``message`` to ``phone`` via sms.
+
+        :param phone: A destination phone number.
+        :type phone: :py:obj:`str`
+        :param message: A message body.
+        :type message: :py:obj:`str`
+        :param ttl: Time to live in ms. Default is ``300``.
+        :type ttl: :py:obj:`int`
+        :param dry_run: Whether or not to execute the voice message as a dry run. Default is :py:obj:`False`.
+        :type dry_run: :py:obj:`bool`
+        :param feedback: Whether or not to include message feedback in the response. Default is :py:obj:`False`.
+        :type feedback: :py:obj:`bool`
+        :raises AssertionError: If :py:attr:`_pinpoint_client` wasn't set.
+        :returns: A voice message response.
+        :rtype: :py:obj:`dict`
+
+        """
+        assert self._pinpoint_client, "Asyncronous client wasn't set."
+        return await self._pinpoint_client.send_text_message(
+            **{
+                "DestinationPhoneNumber": phone,
+                "OriginationIdentity": self.origin_pool,
+                "MessageBody": message,
+                "MessageType": "TRANSACTIONAL",
+                "ConfigurationSetName": self.configuration_set,
+                "MaxPrice": self.max_sms_price,
+                "TimeToLive": ttl,
+                "DryRun": dry_run or self.debug,
+                "MessageFeedbackEnabled": feedback,
+            }
+        )
+
+    async def send_voice(
+        self,
+        phone: str,
+        message: str,
+        ttl: int = 300,
+        voice_id: str = "Joanna",
+        dry_run: bool = False,
+        feedback: bool = False,
+    ) -> dict:
+        """
+        Calls ``phone`` and reads ``message`` aloud.
+
+        :param phone: A destination phone number.
+        :type phone: :py:obj:`str`
+        :param message: A message body.
+        :type message: :py:obj:`str`
+        :param ttl: Time to live in ms. Default is ``300``.
+        :type ttl: :py:obj:`int`
+        :param voice_id: A voice id to use for speech synthesis.
+        :type voice_id: :py:obj:`str`
+        :param dry_run: Whether or not to execute the voice message as a dry run. Default is :py:obj:`False`.
+        :type dry_run: :py:obj:`bool`
+        :param feedback: Whether or not to include message feedback in the response. Default is :py:obj:`False`.
+        :type feedback: :py:obj:`bool`
+        :raises AssertionError: If :py:attr:`_pinpoint_client` wasn't set.
+        :returns: A voice message response.
+        :rtype: :py:obj:`dict`
+
+        """
+        assert self._pinpoint_client, "Asyncronous client wasn't set."
+        return await self._pinpoint_client.send_voice_message(
+            **{
+                "DestinationPhoneNumber": phone,
+                "OriginationIdentity": self.origin_pool,
+                "MessageBody": message,
+                "MessageBodyTextType": "TEXT",
+                "VoiceId": voice_id.upper(),
+                "ConfigurationSetName": self.configuration_set,
+                "MaxPricePerMinute": self.max_voice_price,
+                "TimeToLive": ttl,
+                "DryRun": dry_run or self.debug,
+                "MessageFeedbackEnabled": feedback,
+            }
+        )

{python_terminusgps-35.0.0 → python_terminusgps-35.1.0}/uv.lock

@@ -223,14 +223,14 @@ wheels = [
 
 [[package]]
 name = "botocore-stubs"
-version = "1.38.5"
+version = "1.38.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "types-awscrt" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b3/40/00e33666d4644b9aba4a8948ec3d21da5d8efdb2dcacef4844ba670c52c6/botocore_stubs-1.38.5.tar.gz", hash = "sha256:560e193e39f2b153b0d64bc420a7e02f8a188f3f1c667b79a94bbf2ab56addc7", size = 42311 }
+sdist = { url = "https://files.pythonhosted.org/packages/72/a2/02b37b9a239598c6f5b9981408bf49b87e25e9c2f70ea3dbff898c86f4fd/botocore_stubs-1.38.6.tar.gz", hash = "sha256:56ed87b3e0870d21a968a8346129b578e1f6b70ee902d00bbb6b162c291222f4", size = 42276 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/78/6d/5490e8058b8c354d3e7ae82336d85ab1719dcf4ca3c8e9a8df1560b872ff/botocore_stubs-1.38.5-py3-none-any.whl", hash = "sha256:e5c3f6a7d1377b5f183848eab985bea71926df43b00e02ca36fb8a22e827af48", size = 65590 },
+    { url = "https://files.pythonhosted.org/packages/75/40/858b0fddb11c7c387cea3d2a68eeb3212700deccc91aa68dec671f069a49/botocore_stubs-1.38.6-py3-none-any.whl", hash = "sha256:9a17a5cc2d36120f3683ebe78c40a96281497592e07175a8bf6ee6cd01910a50", size = 65590 },
 ]
 
 [[package]]
@@ -964,7 +964,7 @@ wheels = [
 
 [[package]]
 name = "python-terminusgps"
-version = "35.0.0"
+version = "35.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiobotocore" },

python_terminusgps-35.0.0/docs/source/aws/notifications.rst

@@ -1,50 +0,0 @@
-Notifications
-=============
-
-.. autoclass:: terminusgps.aws.notifications.AsyncNotificationManager
-    :members:
-    :exclude-members: __weakref__
-    :autoclasstoc:
-
-=====
-Usage
-=====
-
-Phone numbers must be in `E.164`_ format to be passed to a :py:obj:`~terminusgps.aws.notifications.AsyncNotificationManager` method, i.e. ``"+17135555555"``.
-
-You can use :py:func:`~terminusgps.django.validators.validate_e164_phone_number` to confirm a ``to_number`` is correctly formatted.
-
-.. _E.164: https://en.wikipedia.org/wiki/E.164
-
-.. code:: python
-
-    import asyncio
-    import uuid
-
-    from terminusgps.aws.notifications import AsyncNotificationManager
-
-    async def main() -> None:
-        # Manager requires a group_id
-        group_id: str = str(uuid.uuid4())
-        message: str = "We know where ours are... do you?"
-        async with AsyncNotificationManager(group_id) as manager:
-
-            # Send an sms to one phone number
-            # Phone numbers must be in E.164 format
-            to_number: str = "+17135555555"
-            await manager.send_sms(
-                to_number=to_number, message=message, message_id=message_id
-            )
-
-            # Send an sms to multiple phone numbers
-            to_numbers: list[str] = ["+17135555555", "+12815555555", "+18325555555"]
-            await manager.send_sms_batch(to_numbers=to_numbers, message=message)
-
-            # Send a push notification to an AWS resource
-            target_arn: str = "arn:aws:sns:us-east-1:555555555555:MyAWSResource"
-            await manager.send_push(
-                target_arn=target_arn, message=message, message_id=message_id
-            )
-
-    if __name__ == "__main__":
-        asyncio.run(main())

python_terminusgps-35.0.0/docs/source/aws/speech.rst

@@ -1,25 +0,0 @@
-Speech
-======
-
-.. autoclass:: terminusgps.aws.speech.AsyncSpeechSynthesisManager
-    :members:
-    :exclude-members: __weakref__
-    :autoclasstoc:
-
-=====
-Usage
-=====
-
-.. code:: python
-
-    import asyncio
-
-    from terminusgps.aws.speech import AsyncSpeechSynthesisManager
-
-    async def main() -> None:
-        async with AsyncSpeechSynthesisManager("my-bucket-name") as manager:
-            message: str = "This message should be read aloud and saved as a file in an S3 bucket."
-            await manager.synthesize_speech(message)
-
-    if __name__ == "__main__":
-        asyncio.run(main())

python_terminusgps-35.0.0/terminusgps/aws/notifications.py

@@ -1,311 +0,0 @@
-import asyncio
-import os
-import uuid
-from collections.abc import Sequence
-from contextlib import AsyncExitStack
-
-from aiobotocore.session import AioSession
-
-from terminusgps.django.validators import validate_e164_phone_number
-
-
-class AsyncPollyManager:
-    def __init__(
-        self, bucket_name: str | None = None, region_name: str = "us-east-1"
-    ) -> None:
-        self._exit_stack = AsyncExitStack()
-        self._polly_client = None
-        self._region_name = region_name
-        self._bucket_name = bucket_name or os.getenv("AWS_POLLY_BUCKET_NAME", "")
-
-    @property
-    def region_name(self) -> str:
-        """
-        An AWS region name.
-
-        :type: :py:obj:`str`
-
-        """
-        return self._region_name
-
-    @property
-    def bucket_name(self) -> str:
-        """
-        The AWS bucket that will host audio files.
-
-        :type: :py:obj:`str`
-
-        """
-        return self._bucket_name
-
-    async def __aenter__(self) -> "AsyncPollyManager":
-        """
-        Creates an asyncronous session and client.
-
-        :returns: The polly manager.
-        :rtype: :py:obj:`~terminusgps.aws.notifications.AsyncPollyManager`
-
-        """
-        session = AioSession()
-        self._polly_client = await self._exit_stack.enter_async_context(
-            session.create_client("polly", region_name=self.region_name)
-        )
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
-        """
-        Destroys the asyncronous session.
-
-        :param exc_type: Exception type.
-        :param exc_val: Exception value.
-        :param exc_tb: Exception traceback.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
-
-    async def synthesize_speech(
-        self,
-        message: str,
-        format: str = "ogg_vorbis",
-        sample_rate: int = 22050,
-        language_code: str = "en-US",
-    ) -> None:
-        """
-        Synthesizes the message into an audio file and saves it to the S3 bucket.
-
-        :param message: A message to be read aloud.
-        :type message: :py:obj:`str`
-        :param format: A file format. Default is ``"ogg_vorbis"``.
-        :type format: :py:obj:`str`
-        :param sample_rate: The audio frequency in Hz. Default is ``22050``.
-        :type sample_rate: :py:obj:`int`
-        :param language_code: The language to use in the synthesis. Default is ``"en-US"``.
-        :type language_code: :py:obj:`str`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        await self._polly_client.start_speech_synthesis_task(
-            **{
-                "Engine": "standard",
-                "LanguageCode": language_code,
-                "OutputFormat": format,
-                "OutputS3BucketName": self.bucket_name,
-                "SampleRate": str(sample_rate),
-                "Text": f"<speak>{message}</speak>",
-                "TextType": "ssml",
-                "VoiceId": "Joanna",
-            }
-        )
-
-    async def synthesize_speech_batch(
-        self,
-        messages: Sequence[str],
-        format: str = "ogg_vorbis",
-        sample_rate: int = 22050,
-        language_code: str = "en-US",
-    ) -> None:
-        """
-        Synthesizes a sequence of messages into audio files and saves them to the S3 bucket.
-
-        :param messages: A sequence of messages to be read aloud.
-        :type messages: :py:obj:`Sequence`
-        :param format: A file format. Default is ``"ogg_vorbis"``.
-        :type format: :py:obj:`str`
-        :param sample_rate: The audio frequency in Hz. Default is ``22050``.
-        :type sample_rate: :py:obj:`int`
-        :param language_code: The language to use in the synthesis. Default is ``"en-US"``.
-        :type language_code: :py:obj:`str`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        await asyncio.gather(
-            *[
-                self.synthesize_speech(
-                    message=message,
-                    format=format,
-                    sample_rate=sample_rate,
-                    language_code=language_code,
-                )
-                for message in messages
-            ]
-        )
-
-
-class AsyncNotificationManager:
-    def __init__(
-        self, group_id: str | None = None, region_name: str = "us-east-1"
-    ) -> None:
-        """
-        Sets :py:attr:`group_id` and :py:attr:`region_name`.
-
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        self._exit_stack = AsyncExitStack()
-        self._sns_client = None
-        self._region_name = region_name
-        self.group_id = group_id
-
-    async def __aenter__(self) -> "AsyncNotificationManager":
-        """
-        Creates an asyncronous session and client.
-
-        :returns: The notification manager.
-        :rtype: :py:obj:`~terminusgps.aws.notifications.AsyncNotificationManager`
-
-        """
-        session = AioSession()
-        self._sns_client = await self._exit_stack.enter_async_context(
-            session.create_client("sns", region_name=self.region_name)
-        )
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
-        """
-        Destroys the asyncronous session.
-
-        :param exc_type: Exception type.
-        :param exc_val: Exception value.
-        :param exc_tb: Exception traceback.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
-
-    @property
-    def region_name(self) -> str:
-        """
-        An AWS region name.
-
-        :type: :py:obj:`str`
-
-        """
-        return self._region_name
-
-    @property
-    def group_id(self) -> str:
-        """
-        A message group id.
-
-        :type: :py:obj:`str`
-
-        """
-        return str(self._group_id)
-
-    @group_id.setter
-    def group_id(self, other: str | None) -> None:
-        """
-        Sets :py:attr:`group_id` to ``other``.
-
-        If ``other`` isn't provided, instead set :py:attr:`group_id` to :py:func:`~uuid.uuid4`.
-
-        :param other: A message group id.
-        :type other: :py:obj:`str` | :py:obj:`None`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        if not other:
-            other = str(uuid.uuid4())
-        self._group_id = other
-
-    async def send_sms(
-        self, to_number: str, message: str, message_id: str | None = None
-    ) -> None:
-        """
-        Sends an sms to ``to_number``.
-
-        :param to_number: A destination phone number.
-        :type to_number: :py:obj:`str`
-        :param message: A message body.
-        :type message: :py:obj:`str`
-        :param message_id: A message deduplication id. :py:func:`~uuid.uuid4` is used if ``message_id`` was not provided.
-        :type message_id: :py:obj:`str` | :py:obj:`None`
-        :raises ValidationError: If ``to_number`` wasn't a valid E.164 formatted phone number.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        validate_e164_phone_number(to_number)
-
-        if not message_id:
-            message_id = str(uuid.uuid4())
-
-        await self._sns_client.publish(
-            **{
-                "PhoneNumber": to_number,
-                "Message": message,
-                "MessageDeduplicationId": message_id,
-                "MessageGroupId": self.group_id,
-            }
-        )
-
-    async def send_push(
-        self, target_arn: str, message: str, message_id: str | None = None
-    ) -> None:
-        """
-        Sends a push notification to ``target_arn``.
-
-        :param target_arn: An AWS resource ARN.
-        :type target_arn: :py:obj:`str`
-        :param message: A message body.
-        :type message: :py:obj:`str`
-        :param message_id: A message deduplication id. :py:func:`~uuid.uuid4` is used if ``message_id`` was not provided.
-        :type message_id: :py:obj:`str` | :py:obj:`None`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        if not message_id:
-            message_id = str(uuid.uuid4())
-
-        await self._sns_client.publish(
-            **{
-                "TargetArn": target_arn,
-                "Message": message,
-                "MessageDeduplicationId": message_id,
-                "MessageGroupId": self.group_id,
-            }
-        )
-
-    async def send_sms_batch(self, to_numbers: Sequence[str], message: str) -> None:
-        """
-        Sends an sms message to each phone number in ``to_numbers``.
-
-        :param to_numbers: A sequence of phone numbers.
-        :type to_numbers: :py:obj:`~collections.abc.Sequence`
-        :param message: A message body.
-        :type message: :py:obj:`str`
-        :raises ValidationError: If a ``to_number`` wasn't a valid E.164 formatted phone number.
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        for to_number in to_numbers:
-            validate_e164_phone_number(to_number)
-
-        await asyncio.gather(
-            *[self.send_sms(to_number=num, message=message) for num in to_numbers]
-        )
-
-    async def send_push_batch(self, target_arns: Sequence[str], message: str) -> None:
-        """
-        Sends a push notification to each AWS resource by ARN in ``target_arns``.
-
-        :param target_arns: A sequence of AWS resource ARNs.
-        :type target_arns: :py:obj:`~collections.abc.Sequence`
-        :param message: A message body.
-        :type message: :py:obj:`str`
-        :returns: Nothing.
-        :rtype: :py:obj:`None`
-
-        """
-        await asyncio.gather(
-            *[self.send_push(target_arn=arn, message=message) for arn in target_arns]
-        )