Merge pull request #142 from python-odin/development

Release 2.4

Author: timsavage

.readthedocs.yaml

@@ -0,0 +1,12 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"

HISTORY

@@ -1,3 +1,19 @@
+2.4
+===
+
+- Add contrib.rich to provide pre-built rich integration for rendering ``ValidationErrors`` as a tree
+- Improve ValidationError
+    - Add ``for_field`` class method to simplify creating an exception related to a specific field.
+    - Improve type annotations
+- Improve error handling of Validator rendering in sphinx contrib.
+- Improve description of validators for documentation.
+- Improve type annotations in validators.
+- Updates to documentation
+    - Add decorators to docs
+    - Additional docs for validators
+    - Additional docs for Sphinx extension
+
+
 2.3.1
 =====
 

docs/conf.py

@@ -54,7 +54,7 @@
 
 # General information about the project.
 project = u"Odin"
-copyright = u"2021, Tim Savage"
+copyright = u"2023, Tim Savage"
 author = "Tim Savage <tim@savage.company>"
 
 # The version info for the project you're documenting, acts as replacement for

docs/ref/contrib/arrow/index.rst

@@ -0,0 +1,29 @@
+#####
+Arrow
+#####
+
+Better dates & times for Python
+
+.. note::
+
+    This contrib module depends on the `Arrow <https://arrow.readthedocs.io/en/latest/>`_ library::
+
+        pip install arrow
+
+Fields
+******
+
+.. _field-arrow_field:
+
+ArrowField
+===========
+
+``class ArrowField([assume_local: bool = False, **options])``
+
+An amount.
+
+ArrowField has one extra argument:
+
+:py:attr:`ArrowField.assume_local`
+    Customise how naive (datetime values with no timezone) are handled and also how dates are decoded. If
+    ``assume_local`` is True naive dates are assumed to represent the current system timezone.

docs/ref/contrib/doc_gen/index.rst

@@ -11,8 +11,9 @@ This code lives in ``odin/contrib`` in the Odin distribution.
 .. toctree::
    :maxdepth: 1
 
-   doc_gen/index
+   sphinx/index
+   rich/index
+   arrow/index
    geo/index
    money/index
    pint/index
-   sphinx/index

docs/ref/contrib/index.rst

@@ -2,22 +2,29 @@
 Physical Quantities with Pint
 #############################
 
-Additional resources fields that include a unit.
+Additional resources fields that include units.
 
 .. note::
 
     This contrib module depends on the `Pint units library <http://pint.readthedocs.org/>`_ this can be installed with::
 
         pip install pint
 
+
 Fields
 ******
 
-FloatField
-==========
+.. _field-pint_field:
+
+ArrowField
+===========
+
+``class ArrowField([assume_local: bool = False, **options])``
 
-``class FloatField([max_length=None, **options])``
+An amount.
 
-A float.
+ArrowField has one extra argument:
 
-FloatField has one extra argument:
+:py:attr:`ArrowField.assume_local`
+    Customise how naive (datetime values with no timezone) are handled and also how dates are decoded. If
+    ``assume_local`` is True naive dates are assumed to represent the current system timezone.

docs/ref/contrib/pint/index.rst

@@ -0,0 +1,33 @@
+####
+Rich
+####
+
+Better CLI's with Rich!
+
+.. note::
+
+    This contrib module depends on the `Rich <https://rich.readthedocs.io/en/latest/introduction.html>`_ library::
+
+        pip install rich
+
+
+
+Render Validation Errors
+========================
+
+Generate a tree or extend an existing one from a ``ValidationError`` exception.
+
+.. code-block:: python
+
+    from rich import print
+    from odin.contrib.rich.validation_tree import validation_error_tree
+
+    try:
+        ...
+    except ValidationError as ex:
+        tree = validation_error_tree(ex)
+        print(tree)
+
+.. note::
+    A tree instance can be provided as the second argument to allow for customisations
+    to the tree root label and styles.

docs/ref/contrib/rich/index.rst

@@ -0,0 +1,8 @@
+##################
+Helpful Decorators
+##################
+
+
+.. automodule:: odin.decorators
+
+.. autofunction:: returns_resource

docs/ref/decorators.rst

@@ -13,4 +13,5 @@ API Reference
    adapters
    validators
    traversal
+   decorators
    utils