Merge pull request #30 from mansenfranzen/bug_fix_json_schema#28

Bug fix json schema #28

changelog.rst

@@ -1,27 +1,48 @@
 Changelog
 =========
 
-v1.3.2 - 2021-07-XX
+v1.4.0 - 2021-XX-XX
 -------------------
 
-This is a minor release containing bug fixes.
+This is a feature and bug release.
+
+Added
+~~~~~
+
+- Include ``show-json-error-strategy`` for pydantic models and settings to define
+  error handling in case a pydantic field breaks the JSON schema generation
+  `#8 <https://github.com/mansenfranzen/autodoc_pydantic/issues/8>`__.
 
 Bugfix
 ~~~~~~
 
+- Improve handling of non serializable pydantic fields for JSON model generation.
+  Using ``pd.DataFrame`` as a type annotation raised an exception instead of being
+  handled appropriately `#28 <https://github.com/mansenfranzen/autodoc_pydantic/issues/28>`__.
 - Allow typed fields within doc strings to successfully reference pydantic models
-  and settings `#27 <https://github.com/mansenfranzen/autodoc_pydantic/issues/20>`__.
+  and settings `#27 <https://github.com/mansenfranzen/autodoc_pydantic/issues/27>`__.
 
 Testing
 ~~~~~~~
 
 - Add explicit tests for references originating from typed fields.
+- Add more diverse tests for handling non serializable fields breaking JSON model
+  generation.
+- Add tests for different error handling strategies regarding ``show-json-error-strategy``.
+
+Documentation
+~~~~~~~~~~~~~
+
+- Add sections in configuration page for describing ``show-json-error-strategy``.
 
 Contributors
 ~~~~~~~~~~~~
 
 - Thanks to `tahoward <https://github.com/tahoward>`__ for reporting a bug related to
-  missing references in typed fields `#27 <https://github.com/mansenfranzen/autodoc_pydantic/issues/20>`__.
+  missing references in typed fields `#27 <https://github.com/mansenfranzen/autodoc_pydantic/issues/27>`__.
+- Thanks to `thomas-pedot <https://github.com/thomas-pedot>`__ for reporting a bug related to
+  error handling of pydantic fields breaking JSON schema generation `#28 <https://github.com/mansenfranzen/autodoc_pydantic/issues/28>`__.
+
 
 v1.3.1 - 2021-07-21
 -------------------

docs/source/conf.py

@@ -31,7 +31,7 @@
 author = 'Franz Wöllert'
 
 # The full version, including alpha/beta/rc tags
-release = '1.3.2'
+release = '1.4.0'
 
 # -- General configuration ---------------------------------------------------
 

docs/source/configuration.rst

@@ -34,22 +34,6 @@ BaseModel
 
 Contains all modifications for pydantic `BaseModel`.
 
-.. tabdocconfig:: autopydantic_model
-   :title: Show Schema JSON
-   :path: target.configuration.ModelShowJson
-   :config: autodoc_pydantic_model_show_json
-   :option: model-show-json
-   :values: True, False
-
-   Show the schema json representation of a pydantic model within in the class
-   doc string as a collapsable code block.
-
-.. warning::
-
-   Fields containing custom objects may not be serializable which would break schema generation.
-   To prevent this, such fields are kept however their type is changed to *str* and their default
-   values are changed to :code:`ERROR: Not serializable`.
-
 
 .. tabdocconfig:: autopydantic_model
    :title: Show Config Summary
@@ -175,28 +159,48 @@ Contains all modifications for pydantic `BaseModel`.
    Define the signature prefix for pydantic models.
 
 
-------------
-BaseSettings
-------------
-
-Contains all modifications for pydantic `BaseSettings`.
-
-.. tabdocconfig:: autopydantic_settings
+.. tabdocconfig:: autopydantic_model
    :title: Show Schema JSON
-   :path: target.configuration.SettingsShowJson
-   :config: autodoc_pydantic_settings_show_json
-   :option: settings-show-json
+   :path: target.configuration.ModelShowJson
+   :config: autodoc_pydantic_model_show_json
+   :option: model-show-json
    :values: True, False
 
-   Show the schema json representation of pydantic settings within in the class
+   Show the schema json representation of a pydantic model within in the class
    doc string as a collapsable code block.
 
 .. warning::
 
-   Fields containing custom objects may not be serializable which would break schema generation.
-   To prevent this, such fields are kept however their type is changed to *str* and their default
-   values are changed to :code:`ERROR: Not serializable`.
+   Fields containing custom objects may not be JSON serializable. This will break
+   the schema generation by default. However, it can be handled via :ref:`Show Schema JSON Error Strategy <autodoc_pydantic_model_show_json_error_strategy>`.
+
+
+.. _autodoc_pydantic_model_show_json_error_strategy:
+
+Show Schema JSON Error Strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Define error handling in case a pydantic field breaks pydantic model schema
+generation. This occurs if a pydantic field is not JSON serializable.
 
+:conf.py: *autodoc_pydantic_model_show_json_error_strategy*
+
+:option: *model-show-json-error-strategy*
+
+**Available values:**
+
+- ``coerce``: Keep violating fields in resulting schema but only show the title. Do not
+  provide a warning during doc building process.
+- ``warn`` (default): Keep violating fields in resulting schema but only show the title. Provide
+  a warning during the doc building process.
+- ``raise``: Raises an ``sphinx.errors.ExtensionError`` during building process.
+
+
+------------
+BaseSettings
+------------
+
+Contains all modifications for pydantic `BaseSettings`.
 
 .. tabdocconfig:: autopydantic_settings
    :title: Show Config Summary
@@ -320,6 +324,43 @@ Contains all modifications for pydantic `BaseSettings`.
 
    Define the signature prefix for pydantic settings.
 
+
+.. tabdocconfig:: autopydantic_settings
+   :title: Show Schema JSON
+   :path: target.configuration.SettingsShowJson
+   :config: autodoc_pydantic_settings_show_json
+   :option: settings-show-json
+   :values: True, False
+
+   Show the schema json representation of pydantic settings within in the class
+   doc string as a collapsable code block.
+
+.. warning::
+
+   Fields containing custom objects may not be JSON serializable. This will break
+   the schema generation by default. However, it can be handled via  :ref:`Show Schema JSON Error Strategy <autodoc_pydantic_settings_show_json_error_strategy>`.
+
+.. _autodoc_pydantic_settings_show_json_error_strategy:
+
+Show Schema JSON Error Strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Define error handling in case a pydantic field breaks pydantic settings schema
+generation. This occurs if a pydantic field is not JSON serializable.
+
+:conf.py: *autodoc_pydantic_settings_show_json_error_strategy*
+
+:option: *settings-show-json-error-strategy*
+
+**Available values:**
+
+- ``coerce``: Keep violating fields in resulting schema but only show the title. Do not
+  provide a warning during doc building process.
+- ``warn`` (default): Keep violating fields in resulting schema but only show the title. Provide
+  a warning during the doc building process.
+- ``raise``: Raises an ``sphinx.errors.ExtensionError`` during building process.
+
+
 ------
 Fields
 ------

sphinxcontrib/autodoc_pydantic/__init__.py

@@ -13,7 +13,7 @@
     PydanticModelDocumenter,
     PydanticConfigClassDocumenter,
     PydanticFieldDocumenter,
-    PydanticSettingsDocumenter
+    PydanticSettingsDocumenter, OptionsFieldDocPolicy, OptionsJsonErrorStrategy
 )
 
 from sphinxcontrib.autodoc_pydantic.directives import (
@@ -24,7 +24,7 @@
     PydanticSettings
 )
 
-__version__ = "1.3.2"
+__version__ = "1.4.0"
 
 
 def add_css_file(app: Sphinx, exception: Exception):
@@ -67,11 +67,13 @@ def add_configuration_values(app: Sphinx):
 
     stem = "autodoc_pydantic_"
     add = app.add_config_value
+    json_strategy = OptionsJsonErrorStrategy.WARN
 
     add(f'{stem}config_signature_prefix', "model", True, str)
     add(f'{stem}config_members', True, True, bool)
 
     add(f'{stem}settings_show_json', True, True, bool)
+    add(f'{stem}settings_show_json_error_strategy', json_strategy, True, bool)
     add(f'{stem}settings_show_config_member', False, True, bool)
     add(f'{stem}settings_show_config_summary', True, True, bool)
     add(f'{stem}settings_show_validator_members', True, True, bool)
@@ -84,6 +86,7 @@ def add_configuration_values(app: Sphinx):
     add(f'{stem}settings_signature_prefix', "pydantic settings", True, str)
 
     add(f'{stem}model_show_json', True, True, bool)
+    add(f'{stem}model_show_json_error_strategy', json_strategy, True, bool)
     add(f'{stem}model_show_config_member', False, True, bool)
     add(f'{stem}model_show_config_summary', True, True, bool)
     add(f'{stem}model_show_validator_members', True, True, bool)
@@ -100,7 +103,7 @@ def add_configuration_values(app: Sphinx):
     add(f'{stem}validator_list_fields', False, True, bool)
 
     add(f'{stem}field_list_validators', True, True, bool)
-    add(f'{stem}field_doc_policy', 'both', True, str)
+    add(f'{stem}field_doc_policy', OptionsFieldDocPolicy.BOTH, True, str)
     add(f'{stem}field_show_constraints', True, True, bool)
     add(f'{stem}field_show_alias', True, True, bool)
     add(f'{stem}field_show_default', True, True, bool)