add macro for non-guaranteed behavior directive

fix documentation
complete name mapping documentation

docs/conf.py

@@ -1,5 +1,6 @@
 import importlib.util
 import sys
+from datetime import date
 
 import git
 
@@ -23,8 +24,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'adaptix'
-copyright = '2020, Tishka17'
-author = 'Tishka17'
+copyright = f'{date.today().year}, Pavel'
+author = 'Pavel'
 master_doc = 'index'
 
 # -- General configuration ---------------------------------------------------
@@ -53,6 +54,7 @@
 
     # local extensions
     'custom_ext.bench_tools',
+    'custom_ext.macros',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/custom_ext/macros.py

@@ -0,0 +1,50 @@
+from abc import ABC, abstractmethod
+from textwrap import dedent, indent
+
+from docutils.statemachine import StringList
+from sphinx.util import docutils
+from sphinx.util.docutils import SphinxDirective
+
+from .utils import file_ascii_hash
+
+
+class SphinxMacroDirective(SphinxDirective, ABC):
+    @abstractmethod
+    def generate_string(self) -> str:
+        ...
+
+    def run(self):
+        content = self.generate_string()
+        rst = StringList(content.split('\n'), source='fake.rst')
+        node = docutils.nodes.paragraph()
+        self.state.nested_parse(rst, 0, node)
+        return node.children
+
+
+class CustomNonGuaranteedBehavior(SphinxMacroDirective):
+    required_arguments = 0
+    has_content = True
+
+    def generate_string(self) -> str:
+        result = dedent(
+            '''
+            .. admonition:: Non-guaranteed behavior
+              :class: caution
+
+            '''
+        )
+        content = indent(
+            '\n'.join(self.content),
+            '  ',
+        )
+        return result + content
+
+
+def setup(app):
+    app.add_directive("custom-non-guaranteed-behavior", CustomNonGuaranteedBehavior)
+
+    return {
+        'version': file_ascii_hash(__file__),
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/examples/loading-and-dumping/extended_usage/advanced_mapping.py

@@ -0,0 +1,57 @@
+import re
+from dataclasses import dataclass
+from typing import Iterable, List, Sequence
+
+from adaptix import P, Retort, name_mapping
+
+
+@dataclass
+class Document:
+    key: str
+
+    redirects: List[str]
+    edition_keys: List[str]
+    lcc_list: List[str]
+
+
+def create_plural_stripper(
+    *,
+    exclude: Sequence[str] = (),
+    suffixes: Iterable[str] = ('s', '_list'),
+):
+    pattern = '^(.*)(' + '|'.join(suffixes) + ')$'
+
+    def plural_stripper(shape, fld):
+        return re.sub(pattern, lambda m: m[1], fld.id)
+
+    return (
+        P[pattern] & ~P[tuple(exclude)],
+        plural_stripper,
+    )
+
+
+retort = Retort(
+    recipe=[
+        name_mapping(
+            Document,
+            map=[
+                {'key': 'name'},
+                create_plural_stripper(exclude=['redirects']),
+            ],
+        ),
+    ],
+)
+data = {
+    'name': 'The Lord of the Rings',
+    'redirects': ['1234'],
+    'edition_key': ['423', '4235'],
+    'lcc': ['675', '345'],
+}
+document = retort.load(data, Document)
+assert document == Document(
+    key='The Lord of the Rings',
+    redirects=['1234'],
+    edition_keys=['423', '4235'],
+    lcc_list=['675', '345'],
+)
+assert retort.dump(document) == data

docs/examples/loading-and-dumping/extended_usage/chaining.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from adaptix import NameStyle, Retort, name_mapping
+
+
+@dataclass
+class Person:
+    first_name: str
+    last_name: str
+    extra: Dict[str, Any]
+
+
+@dataclass
+class Book:
+    title: str
+    author: Person
+
+
+retort = Retort(
+    recipe=[
+        name_mapping(Person, name_style=NameStyle.CAMEL),
+        name_mapping('author', extra_in='extra', extra_out='extra'),
+    ]
+)
+
+data = {
+    'title': 'Lord of Light',
+    'author': {
+        'firstName': 'Roger',
+        'lastName': 'Zelazny',
+        'unknown_field': 1995,
+    },
+}
+book = retort.load(data, Book)
+assert book == Book(
+    title='Lord of Light',
+    author=Person(
+        first_name='Roger',
+        last_name='Zelazny',
+        extra={'unknown_field': 1995},
+    ),
+)
+assert retort.dump(book) == data

docs/examples/loading-and-dumping/extended_usage/chaining_overriding.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from adaptix import NameStyle, Retort, name_mapping
+
+
+@dataclass
+class Person:
+    first_name: str
+    last_name: str
+    extra: Dict[str, Any]
+
+
+@dataclass
+class Book:
+    title: str
+    author: Person
+
+
+retort = Retort(
+    recipe=[
+        name_mapping(Person, name_style=NameStyle.UPPER_SNAKE),
+        name_mapping(Person, name_style=NameStyle.CAMEL),
+        name_mapping('author', extra_in='extra', extra_out='extra'),
+    ]
+)
+
+data = {
+    'title': 'Lord of Light',
+    'author': {
+        'FIRST_NAME': 'Roger',
+        'LAST_NAME': 'Zelazny',
+        'UNKNOWN_FIELD': 1995,
+    },
+}
+book = retort.load(data, Book)
+assert book == Book(
+    title='Lord of Light',
+    author=Person(
+        first_name='Roger',
+        last_name='Zelazny',
+        extra={'UNKNOWN_FIELD': 1995},
+    ),
+)
+assert retort.dump(book) == data

docs/examples/loading-and-dumping/extended_usage/structure_flattening.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+
+from adaptix import Retort, name_mapping
+
+
+@dataclass
+class Book:
+    title: str
+    price: int
+    author: str
+
+
+retort = Retort(
+    recipe=[
+        name_mapping(
+            Book,
+            map={
+                'author': ['author', 'name'],
+                'title': ['book', 'title'],
+                'price': ['book', 'price'],
+            },
+        ),
+    ]
+)
+
+data = {
+    'book': {
+        'title': 'Fahrenheit 451',
+        'price': 100,
+    },
+    'author': {
+        'name': 'Ray Bradbury',
+    }
+}
+book = retort.load(data, Book)
+assert book == Book(
+    title='Fahrenheit 451',
+    price=100,
+    author='Ray Bradbury',
+)
+assert retort.dump(book) == data

docs/examples/loading-and-dumping/extended_usage/structure_flattening_compressed.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from adaptix import Retort, name_mapping
+
+
+@dataclass
+class Book:
+    title: str
+    price: int
+    author: str
+
+
+retort = Retort(
+    recipe=[
+        name_mapping(
+            Book,
+            map=[
+                ('author', (..., 'name')),
+                ('title|price', ('book', ...)),
+            ],
+        ),
+    ]
+)
+
+data = {
+    'book': {
+        'title': 'Fahrenheit 451',
+        'price': 100,
+    },
+    'author': {
+        'name': 'Ray Bradbury',
+    }
+}
+book = retort.load(data, Book)
+assert book == Book(
+    title='Fahrenheit 451',
+    price=100,
+    author='Ray Bradbury',
+)
+assert retort.dump(book) == data