Merge pull request #6 from koenvervloesem/public_api

Change public API for easier importing
koenvervloesem · Dec 22, 2022 · dc9b492 · dc9b492
2 parents a110b00 + d30c60b
commit dc9b492
Show file tree

Hide file tree

Showing 19 changed files with 73 additions and 29 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -16,7 +16,6 @@ repos:
   hooks:
   - id: trailing-whitespace
     exclude: ^data/
-  - id: check-added-large-files
   - id: check-ast
   - id: check-json
   - id: check-merge-conflict

diff --git a/README.rst b/README.rst
@@ -49,15 +49,15 @@ Get the description of a company ID:
 
 .. code-block:: python
 
-	>>> from bluetooth_numbers.companies import company
+	>>> from bluetooth_numbers import company
 	>>> company[0x0499]
 	'Ruuvi Innovations Ltd.'
 
 Get the description of a service UUID:
 
 .. code-block:: python
 
-	>>> from bluetooth_numbers.services import service
+	>>> from bluetooth_numbers import service
 	>>> from uuid import UUID
 	>>> service[0x180F]
 	'Battery Service'
@@ -68,7 +68,7 @@ Get the description of a characteristic UUID:
 
 .. code-block:: python
 
-	>>> from bluetooth_numbers.characteristics import characteristic
+	>>> from bluetooth_numbers import characteristic
 	>>> from uuid import UUID
 	>>> characteristic[0x2A37]
 	'Heart Rate Measurement'
@@ -79,15 +79,15 @@ Get the description of a descriptor UUID:
 
 .. code-block:: python
 
-	>>> from bluetooth_numbers.descriptors import descriptor
+	>>> from bluetooth_numbers import descriptor
 	>>> descriptor[0x2901]
 	'Characteristic User Descriptor'
 
-Get the description of a OUI:
+Get the description of an OUI:
 
 .. code-block:: python
 
-	>>> from bluetooth_numbers.ouis import oui
+	>>> from bluetooth_numbers import oui
 	>>> oui["58:2D:34"]
 	'Qingping Electronics (Suzhou) Co., Ltd'
 

diff --git a/scripts/generate_modules.py b/scripts/generate_modules.py
@@ -69,7 +69,7 @@ def generate_uuid_module(
     The parameter :param:`kind` should be "service", "characteristic", or "descriptor".
     """
     template = env.get_template(UUID_TEMPLATE)
-    with (Path(CODE_DIR) / f"{kind}s.py").open("w") as python_file:
+    with (Path(CODE_DIR) / f"_{kind}s.py").open("w") as python_file:
         python_file.write("# pylint: skip-file\n")
         python_file.write(
             template.render(uuids16=uuid16_dict, uuids128=uuid128_dict, uuid_dict=kind)
@@ -96,7 +96,7 @@ def generate_cic_dictionary() -> Dict[str, str]:
 def generate_cic_module(cic_dict: Dict[str, str]) -> None:
     """Generate Python module for Company ID Codes."""
     template = env.get_template(CIC_TEMPLATE)
-    with (Path(CODE_DIR) / "companies.py").open("w") as python_file:
+    with (Path(CODE_DIR) / "_companies.py").open("w") as python_file:
         python_file.write("# pylint: skip-file\n")
         python_file.write(template.render(cics=cic_dict))
 
@@ -120,7 +120,7 @@ def generate_oui_dictionary() -> Dict[str, str]:
 def generate_oui_module(oui_dict: Dict[str, str]) -> None:
     """Generate Python module for OUIs."""
     template = env.get_template(OUI_TEMPLATE)
-    with (Path(CODE_DIR) / "ouis.py").open("w") as python_file:
+    with (Path(CODE_DIR) / "_ouis.py").open("w") as python_file:
         python_file.write("# pylint: skip-file\n")
         python_file.write(template.render(ouis=oui_dict))
 

diff --git a/src/bluetooth_numbers/__init__.py b/src/bluetooth_numbers/__init__.py
@@ -5,9 +5,54 @@
 
 This project offers a Python package with a wide set of numbers related to Bluetooth,
 so Python projects can easily use these numbers.
+
+Get the description of a company ID:
+
+>>> from bluetooth_numbers import company
+>>> company[0x0499]
+'Ruuvi Innovations Ltd.'
+
+Get the description of a service UUID:
+
+>>> from bluetooth_numbers import service
+>>> from uuid import UUID
+>>> service[0x180F]
+'Battery Service'
+>>> service[UUID("6E400001-B5A3-F393-E0A9-E50E24DCCA9E")]
+'Nordic UART Service'
+
+Get the description of a characteristic UUID:
+
+>>> from bluetooth_numbers import characteristic
+>>> from uuid import UUID
+>>> characteristic[0x2A37]
+'Heart Rate Measurement'
+>>> characteristic[UUID("6E400002-B5A3-F393-E0A9-E50E24DCCA9E")]
+'UART RX Characteristic'
+
+Get the description of a descriptor UUID:
+
+>>> from bluetooth_numbers import descriptor
+>>> descriptor[0x2901]
+'Characteristic User Descriptor'
+
+Get the description of an OUI:
+
+>>> from bluetooth_numbers import oui
+>>> oui["58:2D:34"]
+'Qingping Electronics (Suzhou) Co., Ltd'
 """
 import sys
 
+# Public API for easier importing
+from ._characteristics import characteristic
+from ._companies import company
+from ._descriptors import descriptor
+from ._ouis import oui
+from ._services import service
+
+__all__ = ["characteristic", "company", "descriptor", "oui", "service"]
+
 if sys.version_info[:2] >= (3, 8):
     # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8`
     from importlib.metadata import PackageNotFoundError, version  # pragma: no cover

diff --git a/src/bluetooth_numbers/characteristics.py → src/bluetooth_numbers/_characteristics.py b/src/bluetooth_numbers/characteristics.py → src/bluetooth_numbers/_characteristics.py
@@ -3,7 +3,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.characteristics import characteristic
+>>> from bluetooth_numbers import characteristic
 >>> from uuid import UUID
 >>> characteristic[0x2A37]
 'Heart Rate Measurement'

diff --git a/src/bluetooth_numbers/companies.py → src/bluetooth_numbers/_companies.py b/src/bluetooth_numbers/companies.py → src/bluetooth_numbers/_companies.py
@@ -3,7 +3,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.companies import company
+>>> from bluetooth_numbers import company
 >>> company[0x0499]
 'Ruuvi Innovations Ltd.'
 """

diff --git a/src/bluetooth_numbers/descriptors.py → src/bluetooth_numbers/_descriptors.py b/src/bluetooth_numbers/descriptors.py → src/bluetooth_numbers/_descriptors.py
@@ -3,7 +3,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.descriptors import descriptor
+>>> from bluetooth_numbers import descriptor
 >>> descriptor[0x2901]
 'Characteristic User Descriptor'
 """

diff --git a/src/bluetooth_numbers/ouis.py → src/bluetooth_numbers/_ouis.py b/src/bluetooth_numbers/ouis.py → src/bluetooth_numbers/_ouis.py
@@ -3,7 +3,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.ouis import oui
+>>> from bluetooth_numbers import oui
 >>> oui["58:2D:34"]
 'Qingping Electronics (Suzhou) Co., Ltd'
 """

diff --git a/src/bluetooth_numbers/services.py → src/bluetooth_numbers/_services.py b/src/bluetooth_numbers/services.py → src/bluetooth_numbers/_services.py
@@ -3,7 +3,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.services import service
+>>> from bluetooth_numbers import service
 >>> from uuid import UUID
 >>> service[0x180F]
 'Battery Service'

diff --git a/src/bluetooth_numbers/dicts.py b/src/bluetooth_numbers/dicts.py
@@ -30,7 +30,7 @@ class CICDict(Dict[int, str]):
 
     Example:
 
-    >>> from bluetooth_numbers.companies import company
+    >>> from bluetooth_numbers import company
     >>> company[0x004C]
     'Apple, Inc.'
     >>> company[-1]
@@ -62,7 +62,7 @@ class OUIDict(Dict[str, str]):
 
     Example:
 
-    >>> from bluetooth_numbers.ouis import oui
+    >>> from bluetooth_numbers import oui
     >>> oui["98:E7:43"]
     'Dell Inc.'
     >>> oui["c4-29-96"]
@@ -100,7 +100,7 @@ class UUIDDict(Dict[Union[UUID, int], str]):
 
     Example:
 
-    >>> from bluetooth_numbers.services import service
+    >>> from bluetooth_numbers import service
     >>> from uuid import UUID
     >>> service[UUID("0000180F-0000-1000-8000-00805F9B34FB")]
     'Battery Service'

diff --git a/src/bluetooth_numbers/exceptions.py b/src/bluetooth_numbers/exceptions.py
@@ -18,7 +18,7 @@ class UnknownCICError(BluetoothNumbersError):
 
 
 class UnknownOUIError(BluetoothNumbersError):
-    """Exception raised when a OUI is not known."""
+    """Exception raised when an OUI is not known."""
 
 
 class UnknownUUIDError(BluetoothNumbersError):

diff --git a/templates/companies.py.jinja b/templates/companies.py.jinja
@@ -2,7 +2,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.companies import company
+>>> from bluetooth_numbers import company
 >>> company[0x0499]
 'Ruuvi Innovations Ltd.'
 """

diff --git a/templates/ouis.py.jinja b/templates/ouis.py.jinja
@@ -2,7 +2,7 @@
 
 Usage:
 
->>> from bluetooth_numbers.ouis import oui
+>>> from bluetooth_numbers import oui
 >>> oui["58:2D:34"]
 'Qingping Electronics (Suzhou) Co., Ltd'
 """

diff --git a/templates/uuids.py.jinja b/templates/uuids.py.jinja
@@ -2,17 +2,17 @@
 
 Usage:
 
-{% if uuid_dict == 'service' %}>>> from bluetooth_numbers.services import service
+{% if uuid_dict == 'service' %}>>> from bluetooth_numbers import service
 >>> from uuid import UUID
 >>> service[0x180F]
 'Battery Service'
 >>> service[UUID("6E400001-B5A3-F393-E0A9-E50E24DCCA9E")]
-'Nordic UART Service'{% elif uuid_dict == 'characteristic' %}>>> from bluetooth_numbers.characteristics import characteristic
+'Nordic UART Service'{% elif uuid_dict == 'characteristic' %}>>> from bluetooth_numbers import characteristic
 >>> from uuid import UUID
 >>> characteristic[0x2A37]
 'Heart Rate Measurement'
 >>> characteristic[UUID("6E400002-B5A3-F393-E0A9-E50E24DCCA9E")]
-'UART RX Characteristic'{% elif uuid_dict == 'descriptor' %}>>> from bluetooth_numbers.descriptors import descriptor
+'UART RX Characteristic'{% elif uuid_dict == 'descriptor' %}>>> from bluetooth_numbers import descriptor
 >>> descriptor[0x2901]
 'Characteristic User Descriptor'{% endif %}
 """

diff --git a/tests/test_characteristics.py b/tests/test_characteristics.py
@@ -3,7 +3,7 @@
 
 import pytest
 
-from bluetooth_numbers.characteristics import characteristic
+from bluetooth_numbers import characteristic
 from bluetooth_numbers.exceptions import No16BitIntegerError, UnknownUUIDError
 
 

diff --git a/tests/test_companies.py b/tests/test_companies.py
@@ -2,7 +2,7 @@
 """Test the bluetooth_numbers.companies module."""
 import pytest
 
-from bluetooth_numbers.companies import company
+from bluetooth_numbers import company
 from bluetooth_numbers.exceptions import No16BitIntegerError, UnknownCICError
 
 

diff --git a/tests/test_descriptors.py b/tests/test_descriptors.py
@@ -1,7 +1,7 @@
 """Test the bluetooth_numbers.descriptors module."""
 import pytest
 
-from bluetooth_numbers.descriptors import descriptor
+from bluetooth_numbers import descriptor
 from bluetooth_numbers.exceptions import No16BitIntegerError, UnknownUUIDError
 
 

diff --git a/tests/test_ouis.py b/tests/test_ouis.py
@@ -1,8 +1,8 @@
 """Test the bluetooth_numbers.ouis module."""
 import pytest
 
+from bluetooth_numbers import oui
 from bluetooth_numbers.exceptions import UnknownOUIError, WrongOUIFormatError
-from bluetooth_numbers.ouis import oui
 
 
 @pytest.mark.parametrize(

diff --git a/tests/test_services.py b/tests/test_services.py
@@ -3,8 +3,8 @@
 
 import pytest
 
+from bluetooth_numbers import service
 from bluetooth_numbers.exceptions import No16BitIntegerError, UnknownUUIDError
-from bluetooth_numbers.services import service
 
 
 @pytest.mark.parametrize(