Merge pull request #28 from DavideGalilei/dev

👨‍💻 Update 2.0.0
DavideGalilei · Dec 3, 2024 · a248601 · a248601
2 parents c0f59a3 + ea14253
commit a248601
Show file tree

Hide file tree

Showing 31 changed files with 887 additions and 640 deletions.
diff --git a/.github/workflows/test-suite.yml b/.github/workflows/test-suite.yml
@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        version: [ "3.7", "3.8", "3.9", "3.10", "3.11" ]
+        version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
 
     steps:
       - uses: "actions/checkout@v2"

diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,5 @@
 /.idea/
 /gpytranslate.egg-info/
 **/__pycache__
+.aider*
+.env
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Davide Galilei
+Copyright (c) 2024 Davide Galilei
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,7 +1,10 @@
 # gpytranslate
-A Python3 library for translating text using Google Translate API.
 
-----
+[![PyPI version](https://badge.fury.io/py/gpytranslate.svg)](https://badge.fury.io/py/gpytranslate)
+[![Python Versions](https://img.shields.io/pypi/pyversions/gpytranslate.svg)](https://pypi.org/project/gpytranslate/)
+[![License](https://img.shields.io/github/license/DavideGalilei/gpytranslate.svg)](https://github.com/DavideGalilei/gpytranslate/blob/master/LICENSE)
+
+A Python3 library for translating text using Google Translate API.
 ## Features
  - **Both Synchronous and Asynchronous**
  - **Dot accessible values**
@@ -14,12 +17,21 @@ A Python3 library for translating text using Google Translate API.
 ## Quick Start
 
 ### Installation
+
 Requirements:
-- Python 3.7 or higher.
+- Python 3.9 or higher
+- httpx[socks] >= 0.28.0
+- aiofiles >= 24.1.0
+- typing-extensions >= 4.12.2
 
+Install using pip:
+```bash
+python3 -m pip install -U gpytranslate
+```
 
+Or install with poetry:
 ```bash
-$ python3 -m pip install -U gpytranslate
+poetry add gpytranslate
 ```
 ----
 ### Usage
@@ -89,11 +101,47 @@ https://danpetrov.xyz/programming/2021/12/30/telegram-google-translate.html
 https://vielhuber.de/en/blog/google-translation-api-hacking/
 https://github.com/OwlGramDev/OwlGram/blob/b9bb8a247758adbf7be7aaf3eb150f680bec1269/TMessagesProj/src/main/java/it/owlgram/android/translator/GoogleAppTranslator.java
 
-----
+### Language Codes
+
+The library uses ISO 639-1 two-letter language codes. Some common examples:
+
+- English: 'en'
+- Spanish: 'es' 
+- French: 'fr'
+- German: 'de'
+- Italian: 'it'
+- Japanese: 'ja'
+- Chinese (Simplified): 'zh'
+
+### Error Handling
+
+The library raises `TranslationError` when translation fails:
+
+```python
+from gpytranslate import Translator, TranslationError
+
+translator = Translator()
+try:
+    result = await translator.translate("Hello", targetlang="invalid")
+except TranslationError as e:
+    print(f"Translation failed: {e}")
+```
+
 ## Development
-Want to contribute? Pull requests are accepted!
 
-----
+### Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run the tests (`pytest`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+Please make sure to update tests as appropriate and follow the existing code style.
 ## License
 Licensed under the MIT License.
 

diff --git a/examples/async/__init__.py b/examples/async/__init__.py
diff --git a/examples/async/example.py b/examples/async/example.py
@@ -1,34 +1,12 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 import asyncio
 
 from gpytranslate import Translator
 
+"""Example showing basic translation and language detection."""
+
 
-async def main():
+async def main() -> None:
+    """Demonstrate translation from Italian to English and language detection."""
     t = Translator()
     # Note: you can use proxies by passing proxies parameter to Translator
     translation = await t.translate("Ciao come stai? Io bene ahah.", targetlang="en")

diff --git a/examples/async/https_proxy.py b/examples/async/https_proxy.py
@@ -1,34 +1,12 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 import asyncio
 
 from gpytranslate import Translator
 
+"""Example showing how to use HTTPS proxy with the translator."""
+
 
-async def main():
+async def main() -> None:
+    """Demonstrate translation using an HTTPS proxy."""
     t = Translator(proxies={"https://": "https://{proxy_ip_here}"})
     # Check out https://www.python-httpx.org/compatibility/#proxy-keys
     translation = await t.translate("Ciao Mondo!", targetlang="en")

diff --git a/examples/async/socks5_proxy.py b/examples/async/socks5_proxy.py
@@ -1,39 +1,13 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 import asyncio
 
-from httpx_socks import AsyncProxyTransport
-
 from gpytranslate import Translator
 
+"""Example showing how to use SOCKS5 proxy with the translator."""
+
 
-async def main():
-    t = Translator(
-        transport=AsyncProxyTransport.from_url("socks5://user:[email protected]:1080")
-    )
+async def main() -> None:
+    """Demonstrate translation using a SOCKS5 proxy."""
+    t = Translator(proxies={"socks5": "socks5://user:[email protected]:1080"})
     # Check out https://pypi.org/project/httpx-socks/
     translation = await t.translate("Ciao Mondo!", targetlang="en")
     # Hello World!

diff --git a/examples/async/tts.py b/examples/async/tts.py
@@ -1,36 +1,14 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 import asyncio
 
 import aiofiles
 
 from gpytranslate import Translator
 
+"""Example showing how to use text-to-speech functionality."""
+
 
-async def main():
+async def main() -> None:
+    """Demonstrate text-to-speech generation."""
     translator = Translator()
 
     async with aiofiles.open("test.mp3", "wb") as file:

diff --git a/examples/sync/__init__.py b/examples/sync/__init__.py
diff --git a/examples/sync/example.py b/examples/sync/example.py
@@ -1,28 +1,3 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 from gpytranslate import SyncTranslator
 
 t = SyncTranslator()

diff --git a/examples/sync/https_proxy.py b/examples/sync/https_proxy.py
@@ -1,28 +1,3 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
 from gpytranslate import SyncTranslator
 
 t = SyncTranslator(proxies={"https://": "https://{proxy_ip_here}"})

diff --git a/examples/sync/socks5_proxy.py b/examples/sync/socks5_proxy.py
@@ -1,36 +1,7 @@
-"""
-    gpytranslate - A Python3 library for translating text using Google Translate API.
-    MIT License
-
-    Copyright (c) 2023 Davide Galilei
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-"""
-
-from httpx_socks import SyncProxyTransport
-
 from gpytranslate import SyncTranslator
 
-t = SyncTranslator(
-    transport=SyncProxyTransport.from_url("socks5://user:[email protected]:1080")
-)
+t = SyncTranslator(proxies={"socks5": "socks5://user:[email protected]:1080"})
 # Check out https://pypi.org/project/httpx-socks/
-translation = await t.translate("Ciao Mondo!", targetlang="en")
+translation = t.translate("Ciao Mondo!", targetlang="en")
 # Hello World!
 print(f"Translation: {translation.text}")
diff --git a/gpytranslate/__init__.py b/gpytranslate/__init__.py
@@ -1,7 +1,7 @@
+from .exceptions import GpytranslateException, TranslationError
 from .gpytranslate import Translator
 from .sync import SyncTranslator
 from .types import TranslatedObject
-from .exceptions import GpytranslateException, TranslationError
 
 __version__ = "1.5.1"
 __all__ = [
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,3 +2,5 @@ @@
     /.idea/
     /gpytranslate.egg-info/
     **/__pycache__
+    .aider*
+    .env