Merge pull request #83 from hitblast/async

✨ `async` / `await` implementation and restructure of documentation

.github/dependabot.yml

@@ -13,4 +13,4 @@ updates:
   - package-ecosystem: "github-actions" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
-      interval: "weekly"
+      interval: "monthly"

.github/workflows/nightly.yml

@@ -24,7 +24,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Setup Python
-        run: uv python install
+        run: uv python install 3.9
 
       - name: Install project & build
         run: uv sync --all-extras && uv build
@@ -33,4 +33,4 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           path: dist/*
-          retention-days: 10
+          retention-days: 3

.github/workflows/release.yml

@@ -23,7 +23,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Setup Python
-        run: uv python install
+        run: uv python install 3.9
 
       - name: Install project & build
         run: uv sync --all-extras && uv build

.github/workflows/unit-tests.yml

@@ -27,7 +27,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Setup Python
-        run: uv python install
+        run: uv python install 3.9
 
       - name: Install project
         run: uv sync --all-extras --dev

README.md

@@ -61,54 +61,52 @@ This small tour guide will describe how you can use avro.py back and forth to op
 
 #### 1. `parse()`
 
-Let's assume I want to parse some English text to Bengali, which is "ami banglay gan gai.", so in this case to convert it to Bengali, we can use this snippet:
+Let's assume I want to parse some English text to Bengali, which is "ami banglay gan gai.", so in this case to convert it to Bengali, we can use this starter code and follow along with the other examples to add further features:
 
 ```python
-# Import the package.
+import asyncio
 import avro
 
-# Our dummy text.
-dummy = 'ami banglay gan gai.'
+async def main() -> None:
+    dummy = 'ami banglay gan gai.'
 
-# Parsing the text.
-avro_output = avro.parse(dummy)
-print(output)  # Output: আমি বাংলায় গান গাই।
+    avro_output = await avro.parse(dummy)
+    print(output)  # Output: আমি বাংলায় গান গাই।
+
+if __name__ == '__main__':
+    asyncio.run(main())
 ```
 
 #### 2. `parse(bijoy=True)`
 
-Alternatively, I can also do it in Bijoy Keyboard format:
+Alternatively, I can also do it in **Bijoy Keyboard format**:
 
 ```python
-# Parsing in Bijoy.
-bijoy_output = avro.parse(dummy, bijoy=True)  # Output: Avwg evsjvh় Mvb MvB।
+bijoy_output = await avro.parse(dummy, bijoy=True)  # Output: Avwg evsjvh় Mvb MvB।
 ```
 
 #### 3. `to_bijoy()`
 
 Or, we can take the previous `avro_output` and convert it to Bijoy if we want to, like this:
 
 ```python
-# Converting to Bijoy.
-bijoy_text = avro.to_bijoy(avro_output)  # Output: Avwg evsjvh় Mvb MvB।
+bijoy_text = await avro.to_bijoy(avro_output)  # Output: Avwg evsjvh় Mvb MvB।
 ```
 
 #### 4. `to_unicode()`
 
 Conversely, we can convert the Bijoy text we got just now and convert it back to Unicode Bengali:
 
 ```python
-# Converting back!
-unicode_text = avro.to_unicode(bijoy_text)  # Output: আমি বাংলায় গান গাই।
+unicode_text = await avro.to_unicode(bijoy_text)  # Output: আমি বাংলায় গান গাই।
 ```
 
 #### 4. `reverse()`
 
 Finally, we can just reverse back to the original text we passed as input in the first place:
 
 ```python
-# Reversing back!
-reversed_text = avro.reverse(uncode_text)  # Output: ami banglay gan gai.
+reversed_text = await avro.reverse(uncode_text)  # Output: ami banglay gan gai.
 ```
 
 <br>

REFERENCES.md

@@ -0,0 +1,5 @@
+## Important References / Links
+Note: This file has only been created for storing important resources related to the development of the project.
+
+- NumPy-themed documentation (Sphinx-compatible): https://numpydoc.readthedocs.io/en/latest/format.html
+- Projects concept (uv): https://docs.astral.sh/uv/concepts/projects/init/

examples/simple.py

@@ -1,28 +1,34 @@
-# Import the package.
+# Imports.
+import asyncio
+
 import avro
 
-# Let's assume we'd like to convert "amar sOnar bangla" to Unicode.
-dummy_text = "amar sOnar bangla"
-print("Original English Text:", dummy_text)
 
-# Parse the text to Avro.
-parsed_text = avro.parse(dummy_text)
-print("Parsed Unicode Output:", parsed_text)
+# Please follow the detailed guidelines given in the README.md file about each function to learn more.
+async def main() -> None:
+    dummy_text = "amar sOnar bangla"  # Dummy text.
+    print("Original English Text:", dummy_text)
+
+    parsed_text = await avro.parse(dummy_text)  # Parse the text to Bengali.
+    print("Parsed Unicode Output:", parsed_text)
+
+    # We can parse it directly to Bijoy, or use the to_bijoy function to convert it.
+    # Both should return the same result.
+    bijoy_text_direct = await avro.parse(dummy_text, bijoy=True)
+    bijoy_text_function = await avro.to_bijoy(parsed_text)
+
+    if bijoy_text_direct == bijoy_text_function:
+        print(f"Bijoy Output: {bijoy_text_direct}")
 
-# We can parse it directly to Bijoy, or use the to_bijoy function to convert it.
-# Both should return the same result.
-bijoy_text_direct = avro.parse(dummy_text, bijoy=True)
-bijoy_text_function = avro.to_bijoy(parsed_text)
+    # Now, we can return the Bijoy text to Unicode since we'd like the original output (assuming).
+    # This should be the same as the old parsed_text variable.
+    unicode_text = await avro.to_unicode(bijoy_text_direct)
+    print("Reversed Unicode Output:", unicode_text)
 
-# Print the Bijoy text.
-if bijoy_text_direct == bijoy_text_function:
-    print(f"Bijoy Output: {bijoy_text_direct}")
+    # Finally, we can reverse the Bengali text, back to English!
+    reversed = await avro.reverse(unicode_text)
+    print("Reversed English Output:", reversed)
 
-# Now, we can return the Bijoy text to Unicode since we'd like the original output (assuming).
-# This should be the same as the old parsed_text variable.
-unicode_text = avro.to_unicode(bijoy_text_direct)
-print("Reversed Unicode Output:", unicode_text)
 
-# Finally, we can reverse the Bengali text, back to English!
-reversed = avro.reverse(unicode_text)
-print("Reversed English Output:", reversed)
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -4,7 +4,7 @@
 # uv-specific things
 [project]
 name = "avro-py"
-version = "2024.10.30"
+version = "2024.12.5"
 description = "A modern Pythonic implementation of Avro Phonetic."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -31,6 +31,7 @@ classifiers = [
     'Programming Language :: Python :: 3.13',
     'Topic :: Software Development :: Libraries :: Python Modules',
 ]
+dependencies = []
 
 
 # project links
@@ -42,14 +43,14 @@ Repository = "https://github.com/hitblast/avro.py"
 
 # dependency groups
 [dependency-groups]
-dev = ["pytest>=8.3.3", "ruff>=0.7.1"]
+dev = ["pytest-asyncio>=0.24.0", "pytest>=8.3.3", "ruff>=0.7.1"]
 docs = ["pdoc3>=0.11.1", "setuptools>=75.3.0"]
 
 
 # ruff-specific things
 [tool.ruff]
 target-version = "py39"
-line-length = 110
+line-length = 79
 exclude = ["venv"]
 
 [tool.ruff.lint.per-file-ignores]

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+asyncio_mode = auto

src/avro/core/config.py

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: MIT
 
 
-# Import local modules.
+# Imports.
 from ..resources import DICT
 
 # Shortcuts to vowels, constants, case-sensitives and numbers.

src/avro/core/count.py

@@ -1,22 +1,44 @@
 # SPDX-License-Identifier: MIT
 
 
-# Import local modules.
+# Imports.
 from avro.core import config
 
 
 # Functions.
 def count_vowels(text: str) -> int:
-    """
-    Count number of occurrences of vowels in a given string.
+    """Count number of occurrences of vowels in a given string.
+
+    Parameters:
+    -----------
+
+    text: str
+        The text to count vowels from.
+
+    Returns:
+    --------
+
+    int
+        The number of vowels in the given text.
     """
 
     return sum(1 for i in text if i.lower() in config.AVRO_VOWELS)
 
 
 def count_consonants(text: str) -> int:
-    """
-    Count number of occurrences of consonants in a given string.
+    """Count number of occurrences of consonants in a given string.
+
+    Parameters:
+    -----------
+
+    text: str
+        The text to count consonants from.
+
+    Returns:
+    --------
+
+    int
+        The number of consonants in the given text.
     """
 
     return sum(1 for i in text if i.lower() in config.AVRO_CONSONANTS)