python-terminusgps 34.0.0__py3-none-any.whl → 35.0.0__py3-none-any.whl

{python_terminusgps-34.0.0.dist-info → python_terminusgps-35.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 34.0.0
+Version: 35.0.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-34.0.0.dist-info → python_terminusgps-35.0.0.dist-info}/RECORD

@@ -15,8 +15,9 @@ terminusgps/authorizenet/tests/test_auth.py,sha256=sdByYrcv8RKjcJckOHbyHH1z_M4qr
 terminusgps/authorizenet/tests/test_profiles.py,sha256=tvLBY0iSAC33RlWiBP_NSnPskUQBjfrf0YHMpR-m22k,7566
 terminusgps/authorizenet/tests/test_utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/aws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-terminusgps/aws/notifications.py,sha256=N5p9EqN4wqBRJAMEFOjyseVatpwsxlB0QrHyqFDK5SI,5698
+terminusgps/aws/notifications.py,sha256=HQDsxvFh_8vpAvoOo0K_3nteV0ArM-kgSeMhNzBx3es,9618
 terminusgps/aws/secrets.py,sha256=MxQEmmBLpMUQ2tYAsHdCYf-7RZ84LiogdKcTsACX5dw,361
+terminusgps/aws/speech.py,sha256=8d4kLzc1obzW7uAhlSBmPWh_hw92d1eydcIiQROTj7A,4563
 terminusgps/aws/utils.py,sha256=68GWcllu4h41qzFiKdUkWOAA4LDsTPqRY446VRMxYsY,116
 terminusgps/aws/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/aws/tests/test_notifications.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -26,7 +27,7 @@ terminusgps/django/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuF
 terminusgps/django/mixins.py,sha256=Q9ZJuzpk3d9lDnlVA8ZTVvnZWxB13p08EQ8yVJcztn4,1034
 terminusgps/django/settings.py,sha256=yJIcBE0xjY60AXF_gonY5hS3ofseqPW2k9uSoELgoho,639
 terminusgps/django/utils.py,sha256=SYDQyHA5tTuVwdpZGsCtf0LpTTD0ilRKoxa8StfSTpQ,156
-terminusgps/django/validators.py,sha256=dnENfniiHRJjZhQQ76dIcjfwuq-mkjQahKegZYgmryc,3342
+terminusgps/django/validators.py,sha256=Gx-bpWkfI0fM4WXVRUpoC2ihPqs7agjdHAFO6gralCs,3341
 terminusgps/django/forms/__init__.py,sha256=hh8Z9AC_u2m2bu3h6sdmPyndfQneCEVovENPHmoTDC0,21
 terminusgps/django/forms/fields.py,sha256=BfuPzOZyGvWsEzONW2h4i01fhoL0IS0-gDdBKW4jHgI,2225
 terminusgps/django/forms/forms.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -54,7 +55,7 @@ terminusgps/wialon/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 terminusgps/wialon/tests/test_items.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/wialon/tests/test_session.py,sha256=9mBlYchMo9NeqRIZsmxYzrM1zBHorqu4ooxqSNppLpI,1336
 terminusgps/wialon/tests/test_utils.py,sha256=SK4PxJQGECFnzx_EQeRAQfsQ5_3FLaVcis2W9u_ibuI,1730
-python_terminusgps-34.0.0.dist-info/METADATA,sha256=OLumu5xwbGDw-7yR3niZdmytYWiKwS80xQMazYTcy5g,1616
-python_terminusgps-34.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_terminusgps-34.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_terminusgps-34.0.0.dist-info/RECORD,,
+python_terminusgps-35.0.0.dist-info/METADATA,sha256=FJGCV_uc4f3OcIqAv0Lyl2w9jSFw2X6a-0Ev1wNU3xc,1616
+python_terminusgps-35.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_terminusgps-35.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_terminusgps-35.0.0.dist-info/RECORD,,

terminusgps/aws/notifications.py

@@ -1,4 +1,5 @@
 import asyncio
+import os
 import uuid
 from collections.abc import Sequence
 from contextlib import AsyncExitStack
@@ -8,12 +9,138 @@ 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` if provided.
+        Sets :py:attr:`group_id` and :py:attr:`region_name`.
 
         :returns: Nothing.
         :rtype: :py:obj:`None`
@@ -76,6 +203,8 @@ class AsyncNotificationManager:
         """
         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.
@@ -86,53 +215,9 @@ class AsyncNotificationManager:
             other = str(uuid.uuid4())
         self._group_id = other
 
-    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, message_id=str(uuid.uuid4())
-                )
-                for arn in target_arns
-            ]
-        )
-
-    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, message_id=str(uuid.uuid4())
-                )
-                for num in to_numbers
-            ]
-        )
-
-    async def send_sms(self, to_number: str, message: str, message_id: str) -> None:
+    async def send_sms(
+        self, to_number: str, message: str, message_id: str | None = None
+    ) -> None:
         """
         Sends an sms to ``to_number``.
 
@@ -140,8 +225,8 @@ class AsyncNotificationManager:
         :type to_number: :py:obj:`str`
         :param message: A message body.
         :type message: :py:obj:`str`
-        :param message_id: A message deduplication id.
-        :type message_id: :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`
@@ -149,6 +234,9 @@ class AsyncNotificationManager:
         """
         validate_e164_phone_number(to_number)
 
+        if not message_id:
+            message_id = str(uuid.uuid4())
+
         await self._sns_client.publish(
             **{
                 "PhoneNumber": to_number,
@@ -158,7 +246,9 @@ class AsyncNotificationManager:
             }
         )
 
-    async def send_push(self, target_arn: str, message: str, message_id: str) -> None:
+    async def send_push(
+        self, target_arn: str, message: str, message_id: str | None = None
+    ) -> None:
         """
         Sends a push notification to ``target_arn``.
 
@@ -166,12 +256,15 @@ class AsyncNotificationManager:
         :type target_arn: :py:obj:`str`
         :param message: A message body.
         :type message: :py:obj:`str`
-        :param message_id: A message deduplication id.
-        :type message_id: :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,
@@ -181,13 +274,38 @@ class AsyncNotificationManager:
             }
         )
 
+    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`
 
-async def main() -> None:
-    async with AsyncNotificationManager(str(uuid.uuid4())) as manager:
-        await manager.send_sms_batch(
-            ["+17133049421", "+18324667085", "+18322835634"], "This is a test message."
+        """
+        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``.
 
-if __name__ == "__main__":
-    asyncio.run(main())
+        :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]
+        )

terminusgps/aws/speech.py

@@ -0,0 +1,146 @@
+import asyncio
+import os
+from collections.abc import Sequence
+from contextlib import AsyncExitStack
+
+from aiobotocore.session import AioSession
+
+
+class AsyncSpeechSynthesisManager:
+    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) -> "AsyncSpeechSynthesisManager":
+        """
+        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: The audio file URI.
+        :rtype: :py:obj:`str`
+
+        """
+        response = 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",
+            }
+        )
+        print(f"{response = }")
+        return response.get("SynthesisTask", {}).get("OutputUri", "")
+
+    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: A list of audio file URIs.
+        :rtype: :py:obj:`list`
+
+        """
+        await asyncio.gather(
+            *[
+                self.synthesize_speech(
+                    message=message,
+                    format=format,
+                    sample_rate=sample_rate,
+                    language_code=language_code,
+                )
+                for message in messages
+            ]
+        )
+
+
+async def main() -> None:
+    async with AsyncSpeechSynthesisManager() as manager:
+        uri = await manager.synthesize_speech(
+            "Oh yeah, I'm creating another test audio file."
+        )
+        print(f"{uri = }")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

terminusgps/django/validators.py

@@ -5,7 +5,7 @@ VALID_COUNTRY_CODES = ("+1", "+52")
 
 
 def validate_e164_phone_number(value: str) -> None:
-    """Raises :py:exec:`~django.core.exceptions.ValidationError` if the value is not a valid `E.164 <https://en.wikipedia.org/wiki/E.164>`_ formatted phone number."""
+    """Raises :py:exc:`~django.core.exceptions.ValidationError` if the value is not a valid `E.164 <https://en.wikipedia.org/wiki/E.164>`_ formatted phone number."""
     if not value.startswith("+"):
         raise ValidationError(
             _("E.164 phone number must begin with a '+', got '%(char)s'."),