v1.1.0

Resolves #1 fully (extends the fix of pull request #2). Introduces Descriptor class for descriptors with static/runtime typechecks, custom validation and optional readonly flag. Updates doc generation scripts. Sets typing_extensions>=4.6.0 in requirements.
hashberg-io · Dec 18, 2023 · ea5f5fb · ea5f5fb
1 parent f01a6a4
commit ea5f5fb
Show file tree

Hide file tree

Showing 28 changed files with 1,076 additions and 96 deletions.
diff --git a/.pylintrc b/.pylintrc
@@ -13,5 +13,6 @@ disable = too-many-ancestors,
           protected-access,
           useless-import-alias,
           duplicate-code,
+          using-final-decorator-in-unsupported-version,
 [FORMAT]
 max-line-length=160
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,4 @@
+{
+    "esbonio.sphinx.confDir": "${workspaceFolder}\\docs",
+    "workbench.colorTheme": "Default Dark+"
+}
diff --git a/autodoc_typehints.py b/autodoc_typehints.py
diff --git a/docs/api-toc.rst b/docs/api-toc.rst
@@ -3,5 +3,6 @@
     :caption: API Documentation
 
     api/typing_validation
+    api/typing_validation.descriptor
     api/typing_validation.validation
     api/typing_validation.validation_failure
diff --git a/docs/api/typing_validation.descriptor.rst b/docs/api/typing_validation.descriptor.rst
@@ -0,0 +1,29 @@
+typing_validation.descriptor
+============================
+
+.. automodule:: typing_validation.descriptor
+
+Descriptor
+----------
+
+.. autoclass:: typing_validation.descriptor.Descriptor
+    :show-inheritance:
+    :members:
+    :special-members: __init__, __set__, __get__
+
+T
+-
+
+.. autodata:: typing_validation.descriptor.T
+
+T_contra
+--------
+
+.. autodata:: typing_validation.descriptor.T_contra
+
+ValidatorFunction
+-----------------
+
+.. autoclass:: typing_validation.descriptor.ValidatorFunction
+    :show-inheritance:
+    :members:
diff --git a/docs/api/typing_validation.rst b/docs/api/typing_validation.rst
@@ -8,6 +8,7 @@ typing_validation.__all__
 
 The following members were explicitly reexported using ``__all__``:
 
+    - :py:class:`typing_validation.descriptor.Descriptor`
     - :py:class:`typing_validation.validation.TypeInspector`
     - :py:class:`typing_validation.validation.UnsupportedType`
     - :py:func:`typing_validation.validation.can_validate`

diff --git a/docs/api/typing_validation.validation.rst b/docs/api/typing_validation.validation.rst
@@ -7,12 +7,14 @@ TypeInspector
 -------------
 
 .. autoclass:: typing_validation.validation.TypeInspector
+    :show-inheritance:
     :members:
 
 UnsupportedType
 ---------------
 
 .. autoclass:: typing_validation.validation.UnsupportedType
+    :show-inheritance:
     :members:
 
 can_validate

diff --git a/docs/api/typing_validation.validation_failure.rst b/docs/api/typing_validation.validation_failure.rst
@@ -3,10 +3,23 @@ typing_validation.validation_failure
 
 .. automodule:: typing_validation.validation_failure
 
+Acc
+---
+
+.. autodata:: typing_validation.validation_failure.Acc
+
+FailureTreeVisitor
+------------------
+
+.. autoclass:: typing_validation.validation_failure.FailureTreeVisitor
+    :show-inheritance:
+    :members:
+
 ValidationFailure
 -----------------
 
 .. autoclass:: typing_validation.validation_failure.ValidationFailure
+    :show-inheritance:
     :members:
 
 get_validation_failure

diff --git a/docs/autodoc-type-aliases.json b/docs/autodoc-type-aliases.json
@@ -0,0 +1,3 @@
+{
+
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -11,14 +11,19 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+
+from __future__ import annotations
+
+import inspect
+import json
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 import sphinx_rtd_theme # type: ignore
 
 # -- Project information -----------------------------------------------------
 
-project = 'typing-validation'
+project = 'pt'
 copyright = '2023, Hashberg'
 author = 'Hashberg'
 
@@ -28,9 +33,9 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.0.0"
+release = "0.0.0"
 # The short X.Y version.
-version = "1.0.0"
+version = "0.0.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -43,17 +48,28 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.intersphinx',
     'sphinx_rtd_theme',
-    'sphinx_autodoc_typehints',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'autodoc_typehints',
 ]
 
-add_function_parentheses = False
-set_type_checking_flag = True
-typehints_fully_qualified = False
-typehints_document_rtype = True
-simplify_optional_unions = True
-add_module_names = False
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+nitpicky = True                  # warn about every broken reference
+add_function_parentheses = False # no parentheses after function names
+add_module_names = False         # no module names at start of classes
+set_type_checking_flag = False   # setting to True creates issues when dealing with circular dependencies introduced for static typechecking
+autodoc_typehints = "none"       # don't document type hints, extension 'autodoc_typehints' will take care of it
+
+with open("autodoc-type-aliases.json", "r") as f:
+    autodoc_type_aliases = json.load(f) # load type aliases generated by make-api.py
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', "./intersphinx/python-objects.inv"),
+    'typing_validation': ('https://typing-validation.readthedocs.io/en/latest', "./intersphinx/typing-validation-objects.inv"),
+    'numpy': ('https://numpy.org/doc/stable/', "./intersphinx/numpy-objects.inv"),
+    'scipy': ('https://scipy.github.io/devdocs/', "./intersphinx/scipy-objects.inv"),
+    'pandas': ('https://pandas.pydata.org/docs/', "./intersphinx/pandas-objects.inv"),
+    'networkx': ('https://networkx.org/documentation/stable/', "./intersphinx/networkx-objects.inv"),
+    'matplotlib': ('https://matplotlib.org/stable/', "./intersphinx/matplotlib-objects.inv"),
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -78,4 +94,21 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
+
+from sphinx.application import Sphinx
+from sphinx.environment import BuildEnvironment
+from sphinx.addnodes import pending_xref
+from typing import Any
+
+skip_missing_references: set[str] = {
+}
+
+def on_missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Any) -> Any:
+    if node['reftarget'] in skip_missing_references:
+        return contnode
+    else:
+        return None
+
+def setup(app: Sphinx) -> None:
+    app.connect('missing-reference', on_missing_reference)
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -80,8 +80,8 @@ tuple[
 
 The :func:`~typing_validation.validation.validation_aliases` can be used to define set simple type aliases that can be used by
 :func:`~typing_validation.validation.validate` to resolve forward references.
-For example, the following snippet validates a value against a recursive type alias for JSON-like objects, using :func:`validation_aliases` to create a
-context where :func:`validate` internally evaluates the forward reference ``"JSON"`` to the type alias ``JSON``:
+For example, the following snippet validates a value against a recursive type alias for JSON-like objects, using :func:`typing_validation.validation.validation_aliases` to create a
+context where :func:`typing_validation.validation.validate` internally evaluates the forward reference ``"JSON"`` to the type alias ``JSON``:
 
 >>> from typing import *
 >>> from typing_validation import validate, validation_aliases
@@ -104,4 +104,38 @@ False
 >>> import sys
 >>> sys.tracebacklimit = 0
 
+Descriptors
+-----------
+
+The class :class:`~typing_validation.descriptor.Descriptor` can be used to create descriptors with the following features:
+
+- static type checking for the descriptor value;
+- runtime type checking;
+- optional runtime validation;
+- the ability to make the descriptor read-only.
+
+The valida
+
+.. code-block:: python
+
+    from collections.abc import Sequence
+    from typing_validation import Descriptor
+
+    class MyClass:
+
+        x = Descriptor(int, lambda _, x: x >= 0, readonly=True)
+        y = Descriptor(Sequence[int], lambda self, y: len(y) <= self.x)
+
+        def __init__(self, x: int, y: Sequence[int]):
+            self.x = x
+            self.y = y
+
+    myobj = MyClass(3, [0, 2, 5]) # OK
+    myobj.y = (0, 1)              # OK
+    myobj.y = [0, 2, 4, 6]        # ValueError (lenght of y is not <= 3)
+    myobj.x = 5                   # AttributeError (readonly descriptor)
+    myobj.y = 5                   # TypeError (type of y is not 'Sequence')
+    myobj.y = ["hi", "bye"]       # TypeError (type of y is not 'Sequence[int]')
+
+
 GitHub repo: https://github.com/hashberg-io/typing-validation
diff --git a/docs/intersphinx/matplotlib-objects.inv b/docs/intersphinx/matplotlib-objects.inv
diff --git a/docs/intersphinx/networkx-objects.inv b/docs/intersphinx/networkx-objects.inv
diff --git a/docs/intersphinx/numpy-objects.inv b/docs/intersphinx/numpy-objects.inv
diff --git a/docs/intersphinx/pandas-objects.inv b/docs/intersphinx/pandas-objects.inv
diff --git a/docs/intersphinx/python-objects.inv b/docs/intersphinx/python-objects.inv
diff --git a/docs/intersphinx/scipy-objects.inv b/docs/intersphinx/scipy-objects.inv
diff --git a/docs/intersphinx/sympy-objects.inv b/docs/intersphinx/sympy-objects.inv
diff --git a/docs/intersphinx/typing-validation-objects.inv b/docs/intersphinx/typing-validation-objects.inv