Merge branch 'dev'

CHANGELOG.rst

@@ -15,6 +15,20 @@ are used for versioning (schema follows below):
   0.3.4 to 0.4).
 - All backwards incompatible changes are mentioned in this document.
 
+0.10.3
+------
+2023-01-07
+
+Improvements of the ``Mp3FileProvider`` module:
+
+- Pass active generator to the ``Mp3FileProvider`` in the ``generator``
+  argument if ``BaseMp3Generator`` (and all implementations).
+- Introduce ``handle_kwargs`` method in the ``BaseMp3Generator`` to handle
+  arbitrary provider specific tuning.
+- Add ``EdgeTtsMp3Generator`` MP3 generator.
+- Add ``mp3_generator_kwargs`` argument to the ``Mp3FileProvider.mp3_file``
+  method.
+
 0.10.2
 ------
 2023-01-06

README.rst

@@ -31,7 +31,7 @@ Prerequisites
 =============
 All of core dependencies of this package are `MIT` licensed.
 Most of optional dependencies of this package are `MIT` licensed, while
-a few are `BSD`- or `Apache 2` licensed. All licenses are mentioned
+a few are `BSD`-, `Apache 2`- or `GPLv3` licensed. All licenses are mentioned
 below between the brackets.
 
 - Core package requires Python 3.7, 3.8, 3.9, 3.10 or 3.11.
@@ -42,7 +42,7 @@ below between the brackets.
 - ``EPUB`` file support requires ``xml2epub`` (`MIT`) and ``jinja2`` (`BSD`).
 - ``ICO``, ``JPEG``, ``PNG``, ``SVG`` and ``WEBP`` files support
   requires ``imgkit`` (`MIT`).
-- ``MP3`` file support requires ``gtts`` (`MIT`).
+- ``MP3`` file support requires ``gtts`` (`MIT`) or ``edge-tts`` (`GPLv3`).
 - ``PDF`` file support requires ``pdfkit`` (`MIT`).
 - ``PPTX`` file support requires ``python-pptx`` (`MIT`).
 - ``ODS`` file support requires ``tablib`` (`MIT`) and ``odfpy`` (`Apache 2`).
@@ -264,7 +264,7 @@ Native file system storage. Does not have dependencies.
 
 `PathyFileSystemStorage` example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Native file system storage. Requires `pathy`.
+Native file system storage. Requires ``pathy``.
 
 .. code-block:: python
 
@@ -289,7 +289,7 @@ Native file system storage. Requires `pathy`.
 
 `AWSS3Storage` example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-AWS S3 storage. Requires `pathy`.
+AWS S3 storage. Requires ``pathy``.
 
 .. code-block:: python
 

docs/faker_file.providers.mp3_file.generators.rst

@@ -12,6 +12,14 @@ faker\_file.providers.mp3\_file.generators.base module
    :undoc-members:
    :show-inheritance:
 
+faker\_file.providers.mp3\_file.generators.edge\_tts\_generator module
+----------------------------------------------------------------------
+
+.. automodule:: faker_file.providers.mp3_file.generators.edge_tts_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 faker\_file.providers.mp3\_file.generators.gtts\_generator module
 -----------------------------------------------------------------
 

docs/recipes.rst

@@ -263,6 +263,83 @@ Create a MP3 file
 
     file = FAKER.mp3_file()
 
+Create a MP3 file by explicitly specifying MP3 generator class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Google Text-to-Speech
+^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: python
+
+    from faker import Faker
+    from faker_file.providers.mp3_file import Mp3FileProvider
+    from faker_file.providers.mp3_file.generators.gtts_generator import (
+        GttsMp3Generator,
+    )
+
+    FAKER = Faker()
+
+    file = Mp3FileProvider(FAKER).mp3_file(mp3_generator_cls=GttsMp3Generator)
+
+You can tune arguments too:
+
+.. code-block:: python
+
+    from faker import Faker
+    from faker_file.providers.mp3_file import Mp3FileProvider
+    from faker_file.providers.mp3_file.generators.gtts_generator import (
+        GttsMp3Generator,
+    )
+
+    FAKER = Faker()
+
+    file = Mp3FileProvider(FAKER).mp3_file(
+        mp3_generator_cls=GttsMp3Generator,
+        mp3_generator_kwargs={
+            "lang": "en",
+            "tld": "co.uk",
+        }
+    )
+
+Refer to https://gtts.readthedocs.io/en/latest/module.html#languages-gtts-lang
+for list of accepted values for ``lang`` argument.
+
+Refer to https://gtts.readthedocs.io/en/latest/module.html#localized-accents
+for list of accepted values for ``tld`` argument.
+
+Microsoft Edge Text-to-Speech
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: python
+
+    from faker import Faker
+    from faker_file.providers.mp3_file import Mp3FileProvider
+    from faker_file.providers.mp3_file.generators.edge_tts_generator import (
+        EdgeTtsMp3Generator,
+    )
+
+    FAKER = Faker()
+
+    file = Mp3FileProvider(FAKER).mp3_file(mp3_generator_cls=EdgeTtsMp3Generator)
+
+You can tune arguments too:
+
+.. code-block:: python
+
+    from faker import Faker
+    from faker_file.providers.mp3_file import Mp3FileProvider
+    from faker_file.providers.mp3_file.generators.edge_tts_generator import (
+        EdgeTtsMp3Generator,
+    )
+
+    FAKER = Faker()
+
+    file = Mp3FileProvider(FAKER).mp3_file(
+        mp3_generator_cls=EdgeTtsMp3Generator,
+        mp3_generator_kwargs={
+            "voice": "en-GB-LibbyNeural",
+        }
+    )
+
+Run ``edge-tts -l`` from terminal for list of available voices.
+
 Create a MP3 file with custom MP3 generator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Default MP3 generator class is ``GttsMp3Generator`` which uses Google
@@ -286,7 +363,11 @@ Usage with custom MP3 generator class.
     # Define custom MP3 generator
     class MerryTtsMp3Generator(BaseMp3Generator):
         def generate(self) -> bytes:
-            # ... your implementation here
+            # Your implementation here. Note, that `self.content`
+            # in this context is the text to make MP3 from.
+            # `self.generator` would be the `Faker` or `Generator`
+            # instance from which you could extract information on
+            # active locale.
 
     # Generate MP3 file from random text
     file = FAKER.mp3_file(

examples/requirements/common.in

@@ -1,4 +1,4 @@
-https://github.com/barseghyanartur/gTTS/archive/refs/heads/loosen-click-version-reqs.zip
+edge-tts
 imgkit
 odfpy
 openpyxl
@@ -8,3 +8,5 @@ python-docx
 python-pptx
 tablib
 xml2epub
+
+https://github.com/barseghyanartur/gTTS/archive/refs/heads/loosen-click-version-reqs.zip

examples/requirements/common.txt

@@ -4,8 +4,16 @@
 #
 #    pip-compile examples/requirements/common.in
 #
+aiohttp==3.8.3
+    # via edge-tts
+aiosignal==1.3.1
+    # via aiohttp
+async-timeout==4.0.2
+    # via aiohttp
 attrs==22.1.0
-    # via pytest
+    # via
+    #   aiohttp
+    #   pytest
 azure-core==1.26.1
     # via
     #   azure-storage-blob
@@ -29,7 +37,9 @@ certifi==2022.12.7
 cffi==1.15.1
     # via cryptography
 charset-normalizer==2.1.1
-    # via requests
+    # via
+    #   aiohttp
+    #   requests
 click==7.1.2
     # via
     #   gtts
@@ -42,10 +52,16 @@ cryptography==38.0.4
     # via azure-storage-blob
 defusedxml==0.7.1
     # via odfpy
+edge-tts==6.0.8
+    # via -r examples/requirements/common.in
 et-xmlfile==1.1.0
     # via openpyxl
 exceptiongroup==1.0.4
     # via pytest
+frozenlist==1.3.3
+    # via
+    #   aiohttp
+    #   aiosignal
 google-api-core==2.11.0
     # via
     #   google-cloud-core
@@ -68,7 +84,9 @@ googleapis-common-protos==1.57.0
 gtts @ https://github.com/barseghyanartur/gTTS/archive/refs/heads/loosen-click-version-reqs.zip
     # via -r examples/requirements/common.in
 idna==3.4
-    # via requests
+    # via
+    #   requests
+    #   yarl
 imgkit==1.2.2
     # via -r examples/requirements/common.in
 iniconfig==1.1.1
@@ -92,6 +110,10 @@ mock==4.0.3
     # via pathy
 msrest==0.7.1
     # via azure-storage-blob
+multidict==6.0.4
+    # via
+    #   aiohttp
+    #   yarl
 oauthlib==3.2.2
     # via requests-oauthlib
 odfpy==1.4.1
@@ -189,3 +211,5 @@ xlsxwriter==3.0.3
     # via python-pptx
 xml2epub==2.6.2
     # via -r examples/requirements/common.in
+yarl==1.8.2
+    # via aiohttp

examples/requirements/dev.txt

@@ -4,10 +4,18 @@
 #
 #    pip-compile examples/requirements/dev.in
 #
+aiohttp==3.8.3
+    # via edge-tts
+aiosignal==1.3.1
+    # via aiohttp
 asgiref==3.5.2
     # via django
+async-timeout==4.0.2
+    # via aiohttp
 attrs==22.1.0
-    # via pytest
+    # via
+    #   aiohttp
+    #   pytest
 azure-core==1.26.1
     # via
     #   azure-storage-blob
@@ -33,7 +41,9 @@ certifi==2022.9.24
 cffi==1.15.1
     # via cryptography
 charset-normalizer==2.1.1
-    # via requests
+    # via
+    #   aiohttp
+    #   requests
 click==7.1.2
     # via
     #   gtts
@@ -65,6 +75,8 @@ django-storages==1.13.1
     # via -r examples/requirements/django_3_2.in
 docutils==0.19
     # via readme-renderer
+edge-tts==6.0.8
+    # via -r examples/requirements/common.in
 et-xmlfile==1.1.0
     # via openpyxl
 factory-boy==3.2.1
@@ -77,6 +89,10 @@ filelock==3.8.0
     # via
     #   tox
     #   virtualenv
+frozenlist==1.3.3
+    # via
+    #   aiohttp
+    #   aiosignal
 google-api-core==2.11.0
     # via
     #   google-cloud-core
@@ -99,7 +115,9 @@ googleapis-common-protos==1.57.0
 gtts @ https://github.com/barseghyanartur/gTTS/archive/refs/heads/loosen-click-version-reqs.zip
     # via -r examples/requirements/common.in
 idna==3.4
-    # via requests
+    # via
+    #   requests
+    #   yarl
 imgkit==1.2.2
     # via -r examples/requirements/common.in
 importlib-metadata==5.1.0
@@ -137,6 +155,10 @@ more-itertools==9.0.0
     # via jaraco-classes
 msrest==0.7.1
     # via azure-storage-blob
+multidict==6.0.4
+    # via
+    #   aiohttp
+    #   yarl
 oauthlib==3.2.2
     # via requests-oauthlib
 odfpy==1.4.1
@@ -302,5 +324,7 @@ xlsxwriter==3.0.3
     # via python-pptx
 xml2epub==2.6.2
     # via -r examples/requirements/common.in
+yarl==1.8.2
+    # via aiohttp
 zipp==3.11.0
     # via importlib-metadata