Restructure API docs and add usage guide to CORE

Author: NiklasRosenstein

databind.core/README.md

@@ -1,35 +1,8 @@
-# databind.core
+# `databind.core`
 
-`databind.core` provides a jackson-databind inspired framework for data de-/serialization in Python. Unless you
-are looking to implement support for de-/serializing new data formats, the `databind.core` package alone might
-not be what you are looking for (unless you want to use `databind.core.dataclasses` as a drop-in replacement to
-the standard library `dataclasses` module, for that check out the section at the bottom).
-
-### Known implementations
-
-* [databind.json](https://pypi.org/project/databind.json)
-
-### Dataclass extension
-
-The standard library `dataclasses` module does not allow to define non-default arguments after default arguments.
-You can use `databind.core.dataclasses` as a drop-in replacement to get this feature. It behaves exactly like the
-standard library, only that non-default arguments may follow default arguments. Such arguments can be passed to
-the constructor as positional or keyword arguments.
-
-```py
-from databind.core import dataclasses
-
-@dataclasses.dataclass
-class A:
-  value1: int = 42
-
-@dataclasses.dataclass
-class B(A):
-  value2: str
-
-print(B(0, 'Hello, World!'))
-print(B(value2='Answer to the universe'))
-```
+This library provides the core functionality to implement serialization functions to and from Python objects, with
+a great support for many features of the Python type system. A JSON implementation is provided by the `databind.json`
+package.
 
 ---
 

docs/build.novella

@@ -1,27 +1,35 @@
 
 template "mkdocs"
 
-def databind_modules = [
+def databind_core_modules = [
+  'databind.core',
   'databind.core.context',
   'databind.core.converter',
   'databind.core.dataclasses',
   'databind.core.mapper',
   'databind.core.schema',
   'databind.core.settings',
   'databind.core.union',
+]
+
+def databind_json_modules = [
   'databind.json',
   'databind.json.converters',
   'databind.json.direction',
   'databind.json.module',
+  'databind.json.settings',
 ]
 
 action "mkdocs-update-config" {
   site_name = "python-databind"
   update '$.theme.features' add: []
-  update '$.theme.palette' set: {'scheme': 'slate', 'primary': 'blue', 'accent': 'amber'}
+  update '$.theme.palette' set: {'primary': 'blue', 'accent': 'amber'}
   update_with config -> {
-    for module in databind_modules:
-      config['nav'][-2]['API'].append('api/' + module + '.md')
+    print(json.dumps(config, indent=2))
+    for module in databind_core_modules:
+      config['nav'][1]['CORE'][-1]['API'].append('core/api/' + module + '.md')
+    for module in databind_json_modules:
+      config['nav'][2]['JSON'][-1]['API'].append('json/api/' + module + '.md')
   }
 }
 
@@ -38,8 +46,12 @@ do
     precedes "preprocess-markdown"
   }
   action: {
-    for module in databind_modules:
-      def filename = directory / 'content' / 'api'/ (module + '.md')
+    for module in databind_core_modules:
+      def filename = directory / 'content' / 'core' / 'api'/ (module + '.md')
+      filename.parent.mkdir parents: True exist_ok: True
+      filename.write_text '---\ntitle: {0}\n---\n@pydoc {0}\n'.format(module)
+    for module in databind_json_modules:
+      def filename = directory / 'content' / 'json' / 'api'/ (module + '.md')
       filename.parent.mkdir parents: True exist_ok: True
       filename.write_text '---\ntitle: {0}\n---\n@pydoc {0}\n'.format(module)
   }

docs/content/core/basic-usage.md

@@ -0,0 +1,175 @@
+# Basic Usage
+
+## Implementing a custom converter
+
+Implementing your own serialization functions is easy. It's often needed, not only when implementing a new
+serialization format next to the `databind.json` module, but also to extend an existing serialization format. For
+example, you may want to add support for serializing your `URI` custom type to and from a string. You can do this
+by implementing a custom {@pylink databind.core.converter.Converter}.
+
+```python
+from dataclasses import dataclass
+from urllib.parse import urlparse
+from typing import Any
+
+from databind.core.context import Context
+from databind.core.converter import Converter
+
+
+@dataclass
+class URI:
+    scheme: str
+    host: str
+    path: str
+
+    def __str__(self) -> str:
+        return f'{self.scheme}://{self.host}{self.path}'
+
+    class URIConverter(Converter):
+
+        def convert(self, ctx: Context) -> Any:
+            if not isinstance(ctx.datatype, ClassTypeHint) or not issubclass(ctx.datatype.type, URI):
+                raise NotImplementedError
+            if ctx.direction.is_serialize():
+                return str(ctx.value)  # Always serialize into string
+            elif ctx.direction.is_deserialize():
+                if isinstance(ctx.value, str):
+                    parsed = urlparse(ctx.value)
+                    return URI(parsed.scheme, parsed.hostname, parsed.path)
+                # Fall back to other converters, such as default implementation for dataclasses
+                raise NotImplementedError
+            assert False, 'invalid direction'
+```
+
+To use this new converter, you need to register it to an {@pylink databind.core.mapper.ObjectMapper} instance.
+
+```python
+from databind.core.mapper import ObjectMapper
+
+mapper = ObjectMapper()
+mapper.module.register(URI.URIConverter())
+
+assert mapper.deserialize('https://example.com/foo', URI) == URI('https', 'example.com', '/foo')
+assert mapper.serialize(URI('https', 'example.com', '/foo'), URI) == 'https://example.com/foo'
+```
+
+## Supporting settings in your converter
+
+!!! info "What are settings?"
+
+    "Settings" are Python objects that are associated with types in the serialization process that can alter the behavior
+    of the converter. Go to [Settings](settings.md) to read more about it.
+
+Consuming settings in a converter is straight forward. The {@pylink databind.core.context.Context} class provides
+convenient methods to access settings that are relevant for the current value being processed.
+
+```python
+#  ...
+from databind.core.settings import BooleanSetting
+
+
+@dataclass
+class URI:
+    # ...
+
+    class SerializeAsString(BooleanSetting):
+        """
+        Specifies whether the URI should be serialized to a string.
+        """
+
+    class URIConverter(Converter):
+
+        def convert(self, ctx: Context) -> Any:
+            if not isinstance(ctx.datatype, ClassTypeHint) or not issubclass(ctx.datatype.type, URI):
+                raise NotImplementedError
+            if ctx.direction.is_serialize():
+                serialize_as_string = ctx.get_setting(URI.SerializeAsString).enabled
+                if serialize_as_string:
+                    return str(ctx.value)
+                raise NotImplementedError
+            elif ctx.direction.is_deserialize():
+                if isinstance(ctx.value, str):
+                    parsed = urlparse(ctx.value)
+                    return URI(parsed.scheme, parsed.hostname, parsed.path)
+                raise NotImplementedError
+            assert False, 'invalid direction'
+```
+
+The setting can now be specified when serializing a `URI` instance as a global setting:
+
+```python
+# ...
+
+from databind.core.converter import NoMatchingConverter
+from pytest import raises
+
+# When the setting is not enabled, the converter raises a NotImplementedError, having databind search for
+# another applicable converter. Since none exists with an otherwise empty ObjectMapper, this raises a
+# NoMatchingConverter exception.
+with raises(NoMatchingConverter):
+    mapper.serialize(URI('https', 'example.com', '/foo'), URI)
+
+# Using a global setting, affecting all URI instances being serialized unless a more local setting is specified.
+assert mapper.serialize(
+    URI('htps', 'example.com', '/foo'), URI, settings=[URI.SerializeAsString(True)]) == 'https://example.com/foo'
+```
+
+## Supporting `typing.Annotated` type hints
+
+Converters must explicitly support `typing.Annotated` type hints. They are often useful to associate settings with
+a type in a particular case only. There may also be other reasons that a user may want to use an `Annotated` type
+hint.
+
+```python
+class URI:
+    # ...
+
+    class URIConverter(Converter):
+
+        def convert(self, ctx: Context) -> Any:
+            # Check if the type to be converted is supposed to be a URI.
+            datatype = ctx.datatype
+            if isinstance(datatype, AnnotatedTypeHint):
+                datatype = datatype[0]
+            if not isinstance(datatype, ClassTypeHint) or not issubclass(datatype.type, URI):
+                raise NotImplementedError
+
+            # ...
+```
+
+Now the setting can be specified as an `Annotated` type hint:
+
+```python
+# Using the Annotated type hint to associate the setting with the type.
+assert mapper.serialize(
+    URI('https', 'example.com', '/foo'), Annoated[URI, URI.SerializeAsString(True)]) == 'https://example.com/foo'
+```
+
+## Class-decorator settings
+
+There is also a special class called {@pylink databind.core.settings.ClassDecoratorSetting}, which can be used to
+create setting types that can decorate classes. The `Context.get_settings()` method will automatically understand
+that setting as well.
+
+## Simplifying custom converts for users
+
+Implementing custom converters, especially to convert between strings and custom types, can be a bit tedious. Given
+that it is quite a common use case, it is usually recommended that a Databind serialization library provide specific
+settings to simplify the process for users.
+
+For example, the `databind.json` package provides a {@pylink databind.json.settings.JsonConverter} setting that users
+can use to very easily support the serialization of their custom types to and from strings in a JSON context.
+
+```python
+from databind.json.settings import JsonConverter
+
+@JsonConverter.using_classmethods(serialize="__str__", deserialize="of")
+class MyCustomType:
+
+    def __str__(self) -> str:
+        ...
+
+    @staticmethod
+    def of(s: str) -> MyCustomType:
+        ...
+```

docs/content/changelog/databind.core.md renamed to docs/content/core/changelog.md

@@ -1,5 +1,3 @@
----
-title: databind.core
----
+# Changelog
 
 @shell cd ../databind.core && slap changelog format --markdown --all

docs/content/core/dataclass-ext.md

@@ -0,0 +1,25 @@
+# Dataclass extension
+
+The standard library `dataclasses` module does not allow to define non-default arguments after default arguments.
+You can use `databind.core.dataclasses` as a drop-in replacement to get this feature. It behaves exactly like the
+standard library, only that non-default arguments may follow default arguments. Such arguments can be passed to
+the constructor as positional or keyword arguments.
+
+!!! note
+
+    You will loose Mypy type checking support for dataclasses decorated with `databind.core.dataclasses.dataclass`.
+
+```py
+from databind.core import dataclasses
+
+@dataclasses.dataclass
+class A:
+  value1: int = 42
+
+@dataclasses.dataclass
+class B(A):
+  value2: str
+
+print(B(0, 'Hello, World!'))
+print(B(value2='Answer to the universe'))
+```

docs/content/core/index.md

@@ -0,0 +1 @@
+@cat ../../../databind.core/README.md

docs/content/core/settings.md

@@ -0,0 +1,31 @@
+# Settings
+
+Settings in Databind are Python objects that convey additional information to the serialization process. A setting
+must be expicitly supported by a {@pylink databind.core.converter.Converter} in order to take effect. As such, all
+settings provided by `databind.core` merely provide a standard set of settings that should but may not all be supported
+by serialization lirbary implementations.
+
+Settings must be subclasses from {@pylink databind.core.settings.Setting}, {@pylink databind.core.settings.BooleanSetting}
+or {@pylink databind.core.settings.ClassDecoratedSetting}.
+
+## Specifying settings
+
+You can specify settings at various places in your code to make them apply at various stages during the serialization.
+The following list shows the order of precedence, from highest to lowest:
+
+1. Type-hint local settings specified in the metadata of `typing.Annotated` hints.
+2. Settings that were used to annotate a type.
+3. Global settings that are passed to {@pylink databind.core.mapper.ObjectMapper.convert}, or the respective
+  `serialize`/`deserialize` methods.
+
+## Settings priority
+
+The above precedence only takes effect within the same priority group. The priority of all setting defaults to `NORMAL`
+unless specified otherwise. The following priority groups exist:
+
+* `LOW`: Settings with this priority group are resolved after `NORMAL` settings.
+* `NORMAL`: The default priority group.
+* `HIGH`: Settings with this priority group are resolved before `NORMAL` settings.
+* `ULTIMATE`: Settings with this priority group are resolved before `HIGH` settings.
+
+Converters are usually only interested in the first instance of any setting type.