Merge pull request #59 from tharropoulos/stubs

Add type hints, testing suite and documentation

Author: kishorenc

.python-version

@@ -0,0 +1 @@
+3.8

Pipfile

@@ -0,0 +1,24 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+requests = "*"
+
+[dev-packages]
+mypy = "*"
+wemake-python-styleguide = "*"
+flake8 = "*"
+black = "*"
+pytest = "*"
+coverage = "*"
+pytest-mock = "*"
+requests-mock = "*"
+python-dotenv = "*"
+types-requests = "*"
+typing-extensions = {version = "*", markers = "python_version < '3.11'"}
+faker = "*"
+
+[requires]
+python_version = "3.8"

Pipfile.lock

@@ -32,3 +32,10 @@ version = {attr = "typesense.__version__"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.coverage.run]
+source = ["."]
+omit = ["examples/*.py","./venv/*","tests/*/*.py","*__init__.py","*/*test.py", "./src/typesense/types/*.py"]
+
+[tool.coverage.report]
+omit = ["examples/*.py","./venv/*","tests/*.py","*__init__.py","*/*test.py"]

pyproject.toml

@@ -1,2 +1,4 @@
 [pytest]
 pythonpath = src
+markers =
+    open_ai

pytest.ini

@@ -1,13 +1,2 @@
-certifi==2024.7.4
-chardet==3.0.4
-charset-normalizer==3.3.2
-idna==2.8
-iniconfig==2.0.0
-mypy==1.11.0
-mypy-extensions==1.0.0
-packaging==24.1
-pluggy==1.5.0
-pytest==8.3.2
-requests==2.32.3
-typing_extensions==4.12.2
-urllib3==2.2.2
+-i https://pypi.org/simple
+-r requirements/common.txt

requirements.txt

@@ -0,0 +1,6 @@
+-i https://pypi.org/simple
+certifi==2024.8.30; python_version >= '3.6'
+charset-normalizer==3.3.2; python_full_version >= '3.7.0'
+idna==3.8; python_version >= '3.6'
+requests==2.32.3; python_version >= '3.8'
+urllib3==2.2.2; python_version >= '3.8'

requirements/common.txt

@@ -0,0 +1,64 @@
+-i https://pypi.org/simple
+-r common.txt
+astor==0.8.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+attrs==24.2.0; python_version >= '3.7'
+bandit==1.7.9; python_version >= '3.8'
+black==24.8.0; python_version >= '3.8'
+certifi==2024.8.30; python_version >= '3.6'
+charset-normalizer==3.3.2; python_full_version >= '3.7.0'
+click==8.1.7; python_version >= '3.7'
+coverage==7.6.1; python_version >= '3.8'
+darglint==1.8.1; python_version >= '3.6' and python_version < '4.0'
+docutils==0.20.1; python_version >= '3.7'
+eradicate==2.3.0
+exceptiongroup==1.2.2; python_version < '3.11'
+faker==28.0.0; python_version >= '3.8'
+flake8==7.1.1; python_full_version >= '3.8.1'
+flake8-bandit==4.1.1; python_version >= '3.6'
+flake8-broken-line==1.0.0; python_version >= '3.8' and python_version < '4.0'
+flake8-bugbear==23.12.2; python_full_version >= '3.8.1'
+flake8-commas==2.1.0
+flake8-comprehensions==3.15.0; python_version >= '3.8'
+flake8-debugger==4.1.2; python_version >= '3.7'
+flake8-docstrings==1.7.0; python_version >= '3.7'
+flake8-eradicate==1.5.0; python_version >= '3.8' and python_version < '4.0'
+flake8-isort==6.1.1; python_version >= '3.8'
+flake8-quotes==3.4.0
+flake8-rst-docstrings==0.3.0; python_version >= '3.7'
+flake8-string-format==0.3.0
+idna==3.8; python_version >= '3.6'
+iniconfig==2.0.0; python_version >= '3.7'
+isort==5.13.2; python_full_version >= '3.8.0'
+markdown-it-py==3.0.0; python_version >= '3.8'
+mccabe==0.7.0; python_version >= '3.6'
+mdurl==0.1.2; python_version >= '3.7'
+mypy==1.11.2; python_version >= '3.8'
+mypy-extensions==1.0.0; python_version >= '3.5'
+packaging==24.1; python_version >= '3.8'
+pathspec==0.12.1; python_version >= '3.8'
+pbr==6.1.0; python_version >= '2.6'
+pep8-naming==0.13.3; python_version >= '3.7'
+platformdirs==4.2.2; python_version >= '3.8'
+pluggy==1.5.0; python_version >= '3.8'
+pycodestyle==2.12.1; python_version >= '3.8'
+pydocstyle==6.3.0; python_version >= '3.6'
+pyflakes==3.2.0; python_version >= '3.8'
+pygments==2.18.0; python_version >= '3.8'
+pytest==8.3.2; python_version >= '3.8'
+pytest-mock==3.14.0; python_version >= '3.8'
+python-dateutil==2.9.0.post0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+python-dotenv==1.0.1; python_version >= '3.8'
+pyyaml==6.0.2; python_version >= '3.8'
+requests==2.32.3; python_version >= '3.8'
+requests-mock==1.12.1; python_version >= '3.5'
+restructuredtext-lint==1.4.0
+rich==13.8.0; python_full_version >= '3.7.0'
+setuptools==74.0.0; python_version >= '3.8'
+six==1.16.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+snowballstemmer==2.2.0
+stevedore==5.3.0; python_version >= '3.8'
+tomli==2.0.1; python_version < '3.11'
+types-requests==2.32.0.20240712; python_version >= '3.8'
+typing-extensions==4.12.2; python_version < '3.11'
+urllib3==2.2.2; python_version >= '3.8'
+wemake-python-styleguide==0.18.0; python_version < '4.0' and python_full_version >= '3.8.1'

requirements/dev.txt

@@ -1,7 +1,60 @@
 [flake8]
-max-line-length = 160
+# flake8 configuration:
+# https://flake8.pycqa.org/en/latest/user/configuration.html
+format = wemake
+show-source = true
+statistics = false
+doctests = true
+enable-extensions = G
+max-line-length = 88
+extend-select = B950
+extend-ignore = E203,E501,E701
+
+# darglint configuration:
+# https://github.com/terrencepreilly/darglint
+strictness = long
+docstring-style = sphinx
+
+# Flake plugins:
+max-complexity = 6
+
+# # Excluding some directories:
+exclude = .git,__pycache__,venv,.eggs,*.egg
+ignore = Q000, WPS602, WPS432, WPS305, WPS221, WPS230, WPS234, WPS433, WPS440, W503, WPS331, WPS306, WPS237, WPS202, RST301, RST306, WPS214, WPS235, WPS226, WPS337, WPS320, F821, WPS201
+per-file-ignores = 
+  tests/*.py: S101, WPS226, WPS118, WPS202, WPS204, WPS218, WPS211, WPS604, WPS431, WPS210, WPS201, WPS437
+  src/typesense/types/*.py: B950, WPS215, WPS111, WPS462, WPS322, WPS428, WPS114, WPS110, WPS202 
+  src/typesense/documents.py: WPS320, E704, D102, WPS428, WPS220
+  src/typesense/api_call.py: WPS110, WPS211
+  src/typesense/request_handler.py: WPS110, WPS211
+
 
 [metadata]
 license_file = LICENSE
 
-[isort]
+[isort]
+# isort configuration:
+# https://github.com/PyCQA/isort/wiki/isort-Settings
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+ensure_newline_before_comments = True
+line_length = 88
+
+[mypy]
+# Mypy configuration:
+# https://mypy.readthedocs.io/en/latest/config_file.html
+enable_error_code =
+  truthy-bool,
+  truthy-iterable,
+  redundant-expr,
+  unused-awaitable,
+  ignore-without-code,
+  possibly-undefined,
+  redundant-self,
+
+explicit_package_bases = true
+ignore_missing_imports = true
+strict = true
+warn_unreachable = true

setup.cfg

@@ -1,14 +1,84 @@
+"""
+This module provides functionality for managing individual aliases in Typesense.
+
+Classes:
+    - Alias: Handles operations related to a specific alias.
+
+Methods:
+    - __init__: Initializes the Alias object.
+    - retrieve: Retrieves the details of this specific alias.
+    - delete: Deletes this specific alias.
+    - _endpoint_path: Constructs the API endpoint path for this specific alias.
+
+The Alias class interacts with the Typesense API to manage operations on a
+specific alias. It provides methods to retrieve and delete individual aliases.
+
+For more information on collection aliases, refer to the Collection Alias
+[documentation](https://typesense.org/docs/27.0/api/collection-alias.html#create-or-update-an-alias)
+
+This module uses type hinting and is compatible with Python 3.11+ as well as earlier
+versions through the use of the typing_extensions library.
+"""
+
+from typesense.api_call import ApiCall
+from typesense.types.alias import AliasSchema
+
+
 class Alias(object):
-    def __init__(self, api_call, name):
+    """
+    Class for managing individual aliases in Typesense.
+
+    This class provides methods to interact with a specific alias,
+    including retrieving and deleting it.
+
+    Attributes:
+        api_call (ApiCall): The API call object for making requests.
+        name (str): The name of the alias.
+    """
+
+    def __init__(self, api_call: ApiCall, name: str):
+        """
+        Initialize the Alias object.
+
+        Args:
+            api_call (ApiCall): The API call object for making requests.
+            name (str): The name of the alias.
+        """
         self.api_call = api_call
         self.name = name
 
-    def _endpoint_path(self):
-        from .aliases import Aliases
-        return u"{0}/{1}".format(Aliases.RESOURCE_PATH, self.name)
+    def retrieve(self) -> AliasSchema:
+        """
+        Retrieve this specific alias.
+
+        Returns:
+            AliasSchema: The schema containing the alias details.
+        """
+        response: AliasSchema = self.api_call.get(
+            self._endpoint_path,
+            entity_type=AliasSchema,
+            as_json=True,
+        )
+        return response
+
+    def delete(self) -> AliasSchema:
+        """
+        Delete this specific alias.
+
+        Returns:
+            AliasSchema: The schema containing the deletion response.
+        """
+        response = self.api_call.delete(self._endpoint_path, entity_type=AliasSchema)
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific alias.
 
-    def retrieve(self):
-        return self.api_call.get(self._endpoint_path())
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.aliases import Aliases
 
-    def delete(self):
-        return self.api_call.delete(self._endpoint_path())
+        return "/".join([Aliases.resource_path, self.name])