django-nifty-layout 0.1.1__py3-none-any.whl

django_nifty_layout-0.1.1.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: django-nifty-layout
+Version: 0.1.1
+Summary: A flexible data composition tool to simplify writing templates.
+Author-email: J Fall <email@example.com>
+License: MIT License
+        
+        Copyright (c) 2025 Joseph
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/powderflask/django-nifty-layout
+Project-URL: Repository, https://github.com/powderflask/django-nifty-layout
+Keywords: django-nifty-layout,nifty_layout
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django
+Provides-Extra: format
+Requires-Dist: black; extra == "format"
+Requires-Dist: isort; extra == "format"
+Provides-Extra: lint
+Requires-Dist: flake8; extra == "lint"
+Requires-Dist: flake8-bugbear; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-django; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-sugar; extra == "test"
+Provides-Extra: utils
+Requires-Dist: tox; extra == "utils"
+Requires-Dist: invoke; extra == "utils"
+Requires-Dist: bumpver; extra == "utils"
+Requires-Dist: pip-tools; extra == "utils"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# django-nifty-layout
+
+[![PyPI Version](https://img.shields.io/pypi/v/nifty_layout.svg)](https://pypi.python.org/pypi/django-nifty-layout) ![Test with tox](https://github.com/powderflask/django-nifty-layout/actions/workflows/tox.yaml/badge.svg) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/powderflask/django-nifty-layout)
+
+Version: 0.1.1
+
+A simple but flexible layout tool for composing and transforming data for structured template components.
+Inspired by `crispy-forms` Layout, but without the forms.
+
+django-nifty-layout is free software distributed under the MIT License.
+
+
+## Quick Start
+
+1. Install the `django-nifty-layout` package from PyPI
+    ```bash
+    $ pip install django-nifty-layout
+    ```
+
+2. Go grab a drink, you are all done!
+   
+
+## Sample Usage
+layout.py
+```
+from django.utils.formats import date_format
+
+from nifty_layout.components import (
+   DictCompositeNode as Dct,
+   FieldNode as Fld,   
+   Seq,
+)
+
+# ----- Safe Date Formatter ----- #
+date_formatter = lambda val: None if val is None else date_format(val, SHORT_DATE_FORMAT)
+
+layout = Dct(
+    dict(
+        overview=Seq(
+             "title",
+             Fld("date", formatter=date_formatter),
+             report_type",
+             "location",
+             labeller="Overview",
+        ),
+        contacts=Seq(
+            Dct(
+                dict(
+                    name="contact_name",
+                    contact_methods=Seq("contact_email"),
+                ),
+                dict(
+                    name="reported_by_name",
+                    contact_methods=Seq("reported_by_phone_num", "reported_by_email"),
+                    ),
+                )
+            ),
+            labeller="Contacts",
+        ),
+        ...
+    )
+)
+```
+
+views.py
+```
+def report_view(request, pk):
+   ...
+   obj = Report.objects.get(pk=pk)
+   ...
+   return render(request, "template.html", dict(report=layout.bind(obj)))
+```
+
+template.html
+```
+...
+<div class="report>
+  <h2>report.overview.label</h2>
+  {% for node in report.overview.children %}
+      <div class="row">
+         <div class="col label">{{ node.label }}</div>
+         <div class="col value">{{ node.value|default:"" }}</div>
+      {% endfor %}
+      </div>
+  {% endfor %}
+  <div class="row">
+    {% for contact in report.contacts.children %}
+      <div class="col">
+        {% include "contact_card.html" %}
+      </div>
+    {% endfor %}
+  </div>
+   ...
+</div>   
+```
+
+## Get Me Some of That
+* [Source Code](https://github.com/powderflask/django-nifty-layout)
+
+* [Issues](https://github.com/powderflask/django-nifty-layout/issues)
+* [PyPI](https://pypi.org/project/django-nifty-layout)
+
+[MIT License](https://github.com/powderflask/django-nifty-layout/blob/master/LICENSE)
+
+### Check Out the Demo App  ** coming soon **
+
+1. `pip install -e git+https://github.com/powderflask/django-nifty-layout.git#egg=django-nifty-layout`
+1. `python django-nifty-layout/manage.py install_demo`
+1. `python django-nifty-layout/manage.py runserver`
+
+
+### Acknowledgments
+This project would be impossible to maintain without the help of our generous [contributors](https://github.com/powderflask/django-nifty-layout/graphs/contributors)
+
+#### Technology Colophon
+
+Without django and the django dev team, the universe would have fewer rainbows and ponies.
+
+This package was originally created with [`cookiecutter`](https://www.cookiecutter.io/) 
+and the [`cookiecutter-powder-pypackage`](https://github.com/JacobTumak/CookiePowder) project template.
+
+
+## For Developers
+Install `invoke`, `pip-tools`, `tox` for all the CLI goodness
+  ```bash
+   pip install invoke pip-tools tox
+   ```
+
+Initialise the development environment using the invoke task
+   ```bash
+   inv tox.venv
+   ```
+Or create it with tox directly
+   ```bash
+   tox d -e dev .venv
+   ```
+Or build and install the dev requirements with pip
+   ```bash
+   inv deps.compile-dev
+   pip install -r requirements_dev.txt
+   ```
+
+### Tests
+   ```bash
+   pytest
+   ```
+or
+   ```bash
+   tox r
+   ```
+or run tox environments in parallel using
+   ```bash
+   tox p
+   ```
+
+### Code Style / Linting
+   ```bash
+   $ isort
+   $ black
+   $ flake8
+   ```
+
+### Versioning
+ * [Semantic Versioning](https://semver.org/)
+   ```bash
+   $ bumpver show
+   ```
+
+### Build / Deploy Automation
+ * [invoke](https://www.pyinvoke.org/)
+   ```bash
+   $ invoke -l
+   ```
+ * [GitHub Actions](https://docs.github.com/en/actions) (see [.github/workflows](https://github.com/powderflask/django-nifty-layout/tree/master/.github/workflows))
+ * [GitHub Webhooks](https://docs.github.com/en/webhooks)  (see [settings/hooks](https://github.com/powderflask/django-nifty-layout/settings/hooks))

django_nifty_layout-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+django_nifty_layout-0.1.1.dist-info/licenses/LICENSE,sha256=si8VKm8Qp6B1nIFTpCaRMFdHHq57NJ96nomGEANk4hQ,1063
+nifty_layout/__init__.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+nifty_layout/accessor.py,sha256=q6_nfZrPQuA6bjmIIjqbF1Uwu2VNOBCgC0frKB5IkqY,10741
+nifty_layout/apps.py,sha256=Q400xTUOKrqW30Yx-OzQNiUETp7XgUaa_YEe0_SyCF0,101
+nifty_layout/components.py,sha256=0GRPGECI4jhp-9wjTZza9Sx49M9S4U-p7yyeLqmnp4s,14695
+django_nifty_layout-0.1.1.dist-info/METADATA,sha256=GibfEgGmmpB7tyuSSl59I7T2kMOicswIcEYoOKOqqog,7391
+django_nifty_layout-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+django_nifty_layout-0.1.1.dist-info/entry_points.txt,sha256=JyWfou41kFy_j6OE38H9Yc-94NjpkSRaMrQqc9b4kCU,57
+django_nifty_layout-0.1.1.dist-info/top_level.txt,sha256=N6ONrGRmjlGCM1rVBt2zvALvtOjF1isVimaIjWunhLs,13
+django_nifty_layout-0.1.1.dist-info/RECORD,,

django_nifty_layout-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_nifty_layout-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+manage.py = nifty_layout:django_manage

django_nifty_layout-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_nifty_layout-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nifty_layout

nifty_layout/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

nifty_layout/accessor.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, Optional, Protocol, Type, TypeAlias, TypeVar
+
+from django.core.exceptions import FieldDoesNotExist
+from django.db import models
+
+AccessorContext: TypeAlias = object | Mapping[str, Any] | Sequence
+
+# Any type that implements the protocol
+AccessorType = TypeVar("AccessorType", bound="AccessorProtocol")
+
+# An AccessorSpec allows an accessor to be specified by its string representation
+AccessorSpec: TypeAlias = str | AccessorType
+
+
+class AccessorProtocol(Protocol):
+    """
+    A string that describes how to resolve a value from an arbitrarily deeply nested object, dictionary, or sequence.
+    E.g. hn.helpers.algorithms.Accessor implements this protocol
+
+    Design note: this combines API for a generic Accessor with API for a more specific "ModelFieldAccessor"
+    This violates SR principle a little, but keeps things simple and don't forsee any problems.
+    """
+
+    def __init__(self, value: str):
+        """Initialise the accessor with a string specifying the "path" used to resolve access to a value."""
+        ...
+
+    def resolve(self, context: AccessorContext) -> Any:
+        """Return the value of this accessor in the given context."""
+        ...
+
+    def get_field(self, model: models.Model | type[models.Model]) -> models.Field:
+        """Resolve this accessor using given model as context to return the model field rather than its value."""
+        ...
+
+    def get_label(self, model: models.Model | type[models.Model]) -> str:
+        """Resolve this accessor using given model as context to return the model field verbose name."""
+        ...  # Note: this method is not defined on base tables2 Accessor, see extension below.
+
+
+#####
+# BaseAccessor - copied directly from https://github.com/jieter/django-tables2/blob/master/django_tables2/utils.py
+#    to avoid otherwise unnecessary dependency on `table2`, but you should use tables2 anyhow, its awesome !!
+#    Licence:  https://github.com/jieter/django-tables2/blob/master/LICENSE
+#####
+
+
+class BaseAccessor(str):
+    """
+    A string describing a path from one object to another via attribute/index
+    accesses. For convenience, the class has an alias `.A` to allow for more concise code.
+
+    Relations are separated by a ``__`` character.
+
+    To support list-of-dicts from ``QuerySet.values()``, if the context is a dictionary,
+    and the accessor is a key in the dictionary, it is returned right away.
+    """
+
+    LEGACY_SEPARATOR = "."
+    SEPARATOR = "__"
+
+    ALTERS_DATA_ERROR_FMT = "Refusing to call {method}() because `.alters_data = True`"
+    LOOKUP_ERROR_FMT = "Failed lookup for key [{key}] in {context}, when resolving the accessor {accessor}"
+
+    def __init__(self, value, callable_args=None, callable_kwargs=None):
+        self.callable_args = (
+            callable_args or getattr(value, "callable_args", None) or []
+        )
+        self.callable_kwargs = (
+            callable_kwargs or getattr(value, "callable_kwargs", None) or {}
+        )
+        super().__init__()
+
+    def __new__(cls, value, callable_args=None, callable_kwargs=None):
+        instance = super().__new__(cls, value)
+        if cls.LEGACY_SEPARATOR in value:
+            instance.SEPARATOR = cls.LEGACY_SEPARATOR
+
+            message = (
+                f"Use '__' to separate path components, not '.' in accessor '{value}'"
+                " (fallback will be removed in django_tables2 version 3)."
+            )
+
+            warnings.warn(message, DeprecationWarning, stacklevel=3)
+
+        return instance
+
+    def resolve(self, context, safe=True, quiet=False):
+        """
+        Return an object described by the accessor by traversing the attributes of *context*.
+
+        Lookups are attempted in the following order:
+
+         - dictionary (e.g. ``obj[related]``)
+         - attribute (e.g. ``obj.related``)
+         - list-index lookup (e.g. ``obj[int(related)]``)
+
+        Callable objects are called, and their result is used, before
+        proceeding with the resolving.
+
+        Example::
+
+            >>> x = Accessor("__len__")
+            >>> x.resolve("brad")
+            4
+            >>> x = Accessor("0__upper")
+            >>> x.resolve("brad")
+            "B"
+
+        If the context is a dictionary and the accessor-value is a key in it,
+        the value for that key is immediately returned::
+
+            >>> x = Accessor("user__first_name")
+            >>> x.resolve({"user__first_name": "brad"})
+            "brad"
+
+
+        Arguments:
+            context : The root/first object to traverse.
+            safe (bool): Don't call anything with `alters_data = True`
+            quiet (bool): Smother all exceptions and instead return `None`
+
+        Returns:
+            target object
+
+        Raises:
+            TypeError`, `AttributeError`, `KeyError`, `ValueError`
+            (unless `quiet` == `True`)
+        """
+        # Short-circuit if the context contains a key with the exact name of the accessor,
+        # supporting list-of-dicts data returned from values_list("related_model__field")
+        if isinstance(context, dict) and self in context:
+            return context[self]
+
+        try:
+            current = context
+            for bit in self.bits:
+                try:  # dictionary lookup
+                    current = current[bit]
+                except (TypeError, AttributeError, KeyError):
+                    try:  # attribute lookup
+                        current = getattr(current, bit)
+                    except (TypeError, AttributeError):
+                        try:  # list-index lookup
+                            current = current[int(bit)]
+                        except (
+                            IndexError,  # list index out of range
+                            ValueError,  # invalid literal for int()
+                            KeyError,  # dict without `int(bit)` key
+                            TypeError,  # unsubscriptable object
+                        ):
+                            current_context = (
+                                type(current)
+                                if isinstance(current, models.Model)
+                                else current
+                            )
+
+                            raise ValueError(
+                                self.LOOKUP_ERROR_FMT.format(
+                                    key=bit, context=current_context, accessor=self
+                                )
+                            )
+                if callable(current):
+                    if safe and getattr(current, "alters_data", False):
+                        raise ValueError(
+                            self.ALTERS_DATA_ERROR_FMT.format(method=current.__name__)
+                        )
+                    if not getattr(current, "do_not_call_in_templates", False):
+                        current = current(*self.callable_args, **self.callable_kwargs)
+                # Important that we break in None case, or a relationship
+                # spanning across a null-key will raise an exception in the
+                # next iteration, instead of defaulting.
+                if current is None:
+                    break
+            return current
+        except Exception:
+            if not quiet:
+                raise
+
+    @property
+    def bits(self):
+        if self == "":
+            return ()
+        return self.split(self.SEPARATOR)
+
+    def get_field(self, model):
+        """
+        Return the django model field for model in context, following relations.
+        """
+        if not hasattr(model, "_meta"):
+            return
+
+        field = None
+        for bit in self.bits:
+            try:
+                field = model._meta.get_field(bit)
+            except FieldDoesNotExist:
+                break
+
+            if hasattr(field, "remote_field"):
+                rel = getattr(field, "remote_field", None)
+                model = getattr(rel, "model", model)
+
+        return field
+
+    def penultimate(self, context, quiet=True):
+        """
+        Split the accessor on the right-most separator ('__'), return a tuple with:
+         - the resolved left part.
+         - the remainder
+
+        Example::
+
+            >>> Accessor("a__b__c").penultimate({"a": {"a": 1, "b": {"c": 2, "d": 4}}})
+            ({"c": 2, "d": 4}, "c")
+
+        """
+        path, _, remainder = self.rpartition(self.SEPARATOR)
+        return BaseAccessor(path).resolve(context, quiet=quiet), remainder
+
+
+#####
+# Accessor - cornerstone building block - defines how to resolve a value from a string description.
+#####
+class Accessor(BaseAccessor):
+    """
+    A string describing a path from one object to another via attribute/index accesses.
+
+    Relations are separated by a ``__`` character.
+
+    Usage::
+
+        >>> x = Accessor("__len__")
+        >>> x.resolve("brad")
+        4
+        >>> x = Accessor("0__upper")
+        >>> x.resolve("brad")
+        "B"
+
+    This class is a placeholder in case we want to eliminate dependency on tables2.
+    While we have this dependency, why re-invent the wheel?
+    """
+
+    def get_label(self, model: models.Model | type[models.Model]) -> str:
+        """Resolve this accessor using given model as context to return the model field verbose name."""
+        if isinstance(model, models.Model):
+            model = type(model)
+        field = self.get_field(model)
+        if field and field.verbose_name:
+            return field.verbose_name
+        return self.bits[-1].replace("_", " ").title()
+
+
+class AccessorTransform:
+    """Provides a transform from standard accessor names to prefixed accessor names"""
+
+    def __init__(self, prefix: str = None):
+        self.prefix = prefix
+
+    def t(self, accessor: str) -> str:
+        """Transform key, if it exists in this KeyMap"""
+        return f"{self.prefix}__{accessor}" if self.prefix else accessor
+
+    def __call__(self, accessors: str | dict | Iterable) -> str | dict | list:
+        """Transform all value(s) in accessors and return an object of the same type"""
+        match accessors:
+            case str():
+                return self.t(accessors)
+            case dict():
+                return {
+                    self.t(accessor): value for accessor, value in accessors.items()
+                }
+            case _:
+                return [self.t(accessor) for accessor in accessors]
+
+
+def get_accessor(
+    accessor: Optional[AccessorSpec], accessor_type: Type[AccessorType] = Accessor
+) -> AccessorType | None:
+    """helper: return an Accessor instance from the given spec.  Returns None if input accessor is None."""
+    return accessor_type(accessor) if isinstance(accessor, str) else accessor

nifty_layout/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class NiftyLayoutAppConfig(AppConfig):
+    name = "nifty_layout"

nifty_layout/components.py

@@ -0,0 +1,382 @@
+"""Nifty Layout Components
+
+A micro-framework for defining re-usable layout components from the fields of an object
+
+- a "Layout Component" has 2 parts;
+  - Component Nodes define the hierarchical structure for a sub-set of object fields.
+    Each node encapsulates how to access, format, and label a field's value and its children.
+    Once bound to a data object (e.g., a model instance) the "bound node" provides a
+    uniform interface to access the value and label for one or more fields in an encapsulated object.
+  - One or more templates that use the interface defined by a Bound Node to render the component into HTML.
+
+- most layout components expect to work with django Models,
+  but can be adapted to any object type by injecting custom accessors
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Iterable, Mapping, Sequence
+from contextlib import contextmanager
+from functools import partial
+from typing import Any, Callable, Hashable, Iterator, Optional, Type, TypeAlias
+
+from django.db import models
+from django.template import Template
+from django.template.loader import get_template
+
+from .accessor import Accessor, AccessorSpec, AccessorType, get_accessor
+
+# A Formatter is a function that takes a value returns a formatted value
+Formatter: TypeAlias = Callable[[Any, ...], str]
+
+# A Labeller is a function that takes an accessor and returns string label for the attribute
+Labeller: TypeAlias = Callable[[AccessorSpec, ...], str]
+
+
+def field_labeller(obj: object | models.Model, accessor: AccessorSpec, **unused) -> str:
+    """Return a label for the given accessor of given object, which could be a django Model instance.
+
+    If `obj` is a model instance, returns the verbose name of the accessor field, if accessor is a model field.
+    Otherwise, looks for magic attribute / method:  `foo_label` or `get_foo_label` on obj.
+    In either case, if no labelling is provided by obj, defines a title-case label based on accessor.
+    """
+    accessor = Accessor(accessor) if isinstance(accessor, str) else accessor
+    if isinstance(obj, models.Model):
+        return accessor.get_label(obj)
+    # look for "foo_label" attribute or "get_foo_label" method on object, if there isn't one, use the attribute name
+    attr = accessor.bits[-1]
+    label = getattr(obj, f"{attr}_label", getattr(obj, f"get_{attr}_label", None))
+    if callable(label):
+        label = label()
+    label = label if label is not None else attr.replace("_", " ").title()
+    return label
+
+
+def get_formatted_labeller(
+    labeller, formatter
+):  # todo - add tests or change labelling/formatting logic
+    def formatted_labeller(*args, **kwargs):
+        return formatter(labeller(*args, **kwargs))
+
+    return formatted_labeller
+
+
+# Examples:
+
+
+#########
+# Component Nodes
+# A Bound Node is an adapter that provides a uniform interface for access to values and labels of encapsulated object
+# Its unbound Node defines access and formatting rules.
+#########
+#########
+# Important design note: although we are defining the type hierarchy with inheritance here, the behaviours for each
+#  type are assembled using composition.
+#  E.g., define reusable accessor, labeller, formatter to assemble custom node types.
+#  Custom node types are mainly for convenience - a commonly used assembly - think of them as syntactic sugar
+#  The key here is: don't build a deeply nested inheritance hierarchy!  Use composition to customize Node behaviours.
+#########
+
+
+# A TemplateType can be a Template object, the string template path, or a callable that takes a single parameter.
+TemplateType: TypeAlias = Template | str | Callable[["BoundNode"], Template]
+
+
+class BoundNode(Iterable):
+    """A node that is bound to a piece of data, usually a dict, iterable, object, or model instance
+    Defines the interface for accessing a "value" and "label" from the data, and iterating / accessing its children.
+
+    If node is a composite, all children are also bound to the same data.  Iteration is over the bound fixings nodes
+    Optional template is passed through to context, and **may** be used, if parent template is so configured.
+    """
+
+    def __init__(
+        self, data: Any, node: BaseNode, template: Optional[TemplateType] = None
+    ):
+        self.node = node
+        self.data = data
+        self.children = [child.bind(data) for child in node]
+        self.template = self._get_template(template) if template else None
+
+    def _get_template(self, template: TemplateType) -> Template:
+        """return a template for rendering this node with."""
+        match template:
+            case Template():
+                return template
+            case str():
+                return get_template(template)
+            case _ if callable(template):
+                return template(self)
+            case _:
+                raise ValueError(f"Unexpected value for template: {template}.")
+
+    @property
+    def value(self):
+        """Fetch the data value from data object and format it."""
+        return self.node.get_formatted_value(self.node.get_raw_value(self.data))
+
+    @property
+    def label(self):
+        """Fetch the label from the data object."""
+        return self.node.get_label(self.data)
+
+    # Iterable and Sequence interface
+
+    def __getitem__(self, index) -> BoundNode:
+        """Return the bound fixings node at given 0 <= index < len(self)"""
+        return self.children[index]
+
+    def __len__(self) -> int:
+        return len(self.children)
+
+    def __iter__(self) -> Iterator[BoundNode]:
+        """Iterate over bound fixings nodes."""
+        return iter(self.children)
+
+
+class BoundSequenceNode(BoundNode, Sequence):
+    """A BoundNode representing a linear sequence of bound nodes."""
+
+    def __init__(
+        self,
+        data: Any,
+        node: SequenceCompositeNode,
+        template: Optional[TemplateType] = None,
+    ):
+        """Narrowing Types only - exactly same as a BoundNode"""
+        self.node = node  # only to please the type checker, which otherwise thinks node is a BaseNode
+        super().__init__(data, node, template)
+
+
+class BoundDictNode(BoundNode, Mapping):
+    """A BoundNode representing a mapping of keys to bound nodes."""
+
+    def __init__(
+        self,
+        data: Any,
+        node: DictCompositeNode,
+        template: Optional[TemplateType] = None,
+    ):
+        self.node = node  # only to please the type checker, which otherwise thinks node is a BaseNode
+        with node.as_sequence():
+            super().__init__(data, node, template)
+        self.mapping = {k: v for k, v in zip(self.node.mapping.keys(), self.children)}
+
+    @contextmanager
+    def as_sequence(self):
+        """A context manager allowing direct iteration and numeric indexing on the fixings nodes"""
+        orig_class = type(self)
+        try:
+            self.__class__ = BoundSequenceNode
+            yield self  # Hand back control to the with-block
+        finally:
+            self.__class__ = orig_class
+
+    # Mapping interface
+    def __iter__(self) -> Iterator[Hashable]:
+        """Iterate over the map's ordered key set."""
+        return iter(self.mapping)
+
+    def __getitem__(self, key: Hashable) -> BoundNode:
+        """Lookup bound fixings node in dict by key"""
+        return self.mapping[key]
+
+
+##############
+# Unbound Nodes are a static description of the logic to access, format, and label a value.
+# The intent is to define a small, declarative syntax.
+# `bind` a Node to some data (and optionally a template) to get a BoundNode suitable for rendering.
+#############
+
+
+class BaseNode(Iterable, abc.ABC):
+    """Abstract Base class for all types of Spiffy Component Nodes"""
+
+    default_formatter: Formatter | bool = False  # default does no formatting
+    default_labeller: Labeller | str | bool = False  # default has no label
+    bound_node_type: type[BoundNode] = (
+        BoundNode  # data type returned by `bind` operation
+    )
+
+    def __init__(
+        self,
+        formatter: Optional[Formatter | bool] = None,
+        labeller: Optional[Labeller | str | bool] = None,
+        template: Optional[TemplateType] = None,
+    ):
+        """Parameters passed as None default to Node type's default values."""
+        self.formatter = (
+            formatter if formatter is not None else type(self).default_formatter
+        )
+        self.labeller = (
+            labeller if labeller is not None else type(self).default_labeller
+        )
+        self.template = template
+
+    def bind(self, data: Any, template: Optional[TemplateType] = None) -> BoundNode:
+        """Return a BoundNode that binds the given data (and template) to this node"""
+        template = template or self.template
+        return self.bound_node_type(data=data, node=self, template=template)
+
+    # Value / Label extraction API
+
+    def get_raw_value(self, data: Any) -> Any:
+        """Extract and return the raw value for this Node from the given data object"""
+        return data
+
+    def get_formatted_value(self, value: Any) -> str | Any:
+        """Return formatted version of given raw value"""
+        return self.formatter(value) if self.formatter else value
+
+    def get_label(self, data: Any) -> str | None:
+        """Return a label for the given data object"""
+        return (
+            self.labeller(data)
+            if callable(self.labeller)
+            else str(self.labeller) if self.labeller else None
+        )
+
+    # Iterable interface
+
+    def __iter__(self):
+        return iter([])
+
+
+# Concrete Node types fall in 2 basic classes: Atomic and Composite
+
+
+class AtomicNode(BaseNode, abc.ABC):
+    """Abstract Base class for an atomic Components (no children)"""
+
+    pass
+
+
+class FieldNode(AtomicNode):
+    """Basic atomic node for encapsulating access to the data for a single field using a Accessor"""
+
+    default_accessor_type: Type[AccessorType] = (
+        Accessor  # The Accessor type used to wrap naked accessor spec.
+    )
+    default_labeller: Labeller | str | bool = field_labeller
+
+    def __init__(
+        self,
+        accessor: AccessorSpec,
+        formatter: Optional[Formatter | bool] = None,
+        labeller: Optional[Labeller | str | bool] = None,
+        template: Optional[TemplateType] = None,
+    ):
+        """Parameters passed as None default to Node type's default values."""
+        labeller = (
+            labeller
+            if labeller is not None
+            else partial(type(self).default_labeller, accessor=accessor)
+        )
+        super().__init__(formatter=formatter, labeller=labeller, template=template)
+        self.accessor = get_accessor(accessor, type(self).default_accessor_type)
+
+    def get_raw_value(self, data: Any) -> Any:
+        """Extract and return the raw value for this Node from the given data object"""
+        return self.accessor.resolve(data)
+
+
+# define extended FieldNodes for common use-cases, assembled with custom labellers and formatters
+# E.g., CurrencyFieldNode, DecimalFieldNode, DateField, DateTimeField,...
+
+
+class CompositeNode(BaseNode, abc.ABC):
+    """Abstract Base class for a composite iterable component with zero or more ordered children"""
+
+    default_child_node_type: type[FieldNode] = (
+        FieldNode  # "naked" children are wrapped in this Node type.
+    )
+
+    def __init__(
+        self,
+        *children: BaseNode | AccessorSpec,
+        formatter: Optional[
+            Formatter | bool
+        ] = None,  # default: use class default_formatter
+        labeller: Optional[
+            Labeller | str | bool
+        ] = None,  # default: use class default_labeller
+        child_node_type: Optional[type[BaseNode]] = None,
+        **attributes: str,
+    ):
+        super().__init__(formatter=formatter, labeller=labeller, **attributes)
+        self.child_node_type = child_node_type or type(self).default_child_node_type
+        self.children = [self.wrap_child(child) for child in children]
+
+    def wrap_child(self, child: BaseNode | AccessorSpec) -> FieldNode:
+        return child if isinstance(child, BaseNode) else self.child_node_type(child)
+
+    # Iterable interface and Sequence interface
+    def __iter__(self):
+        return iter(self.children)
+
+    def __getitem__(self, index: int) -> FieldNode:
+        return self.children[index]
+
+    def __len__(self) -> int:
+        return len(self.children)
+
+
+class SequenceCompositeNode(CompositeNode, Sequence):
+    """A Composite node that behaves as an iterable of ordered fixings nodes"""
+
+    bound_node_type = BoundSequenceNode
+
+
+# A MappingElement can be defined by any dict-like object or by a 2-tuple (key, value)
+# When used to initialize a DictCompositeNode, all MappingElements are combined, in order, to form a single dict.
+MappingElement: TypeAlias = (
+    Mapping[Hashable, BaseNode | AccessorSpec]
+    | tuple[Hashable, BaseNode | AccessorSpec]
+)
+
+
+class DictCompositeNode(CompositeNode, Mapping):
+    """A Composite that allows fixings nodes to be looked up with a key. Caution: iteration is over keys not values!"""
+
+    bound_node_type = BoundDictNode
+
+    def __init__(self, *children: MappingElement, **kwargs):
+        """Children can be looked up by key, and iteration is over keys.  dict semantics."""
+        mappings = (
+            child if hasattr(child, "items") else dict((child,)) for child in children
+        )
+        mapping = {k: v for mapping in mappings for k, v in mapping.items()}
+
+        super().__init__(*mapping.values(), **kwargs)
+        assert len(mapping.keys()) == len(self.children)
+        self.mapping = {k: v for k, v in zip(mapping.keys(), self.children)}
+
+    @contextmanager
+    def as_sequence(self):
+        """A context manager allowing direct iteration and numeric indexing on the fixings nodes"""
+        orig_class = type(self)
+        try:
+            self.__class__ = SequenceCompositeNode
+            yield self  # Hand back control to the with-block
+        finally:
+            self.__class__ = orig_class
+
+    # Mapping interface
+    def __iter__(self) -> Iterator[Hashable]:
+        """Iterate over the map's ordered key set."""
+        return iter(self.mapping)
+
+    def __getitem__(self, key: Hashable) -> FieldNode:
+        """Lookup fixings node in map by key"""
+        return self.mapping[key]
+
+
+class Seq(SequenceCompositeNode):
+
+    def __init__(self, *children: BaseNode | AccessorSpec | Iterable, **kwargs):
+        if len(children) == 1 and isinstance(children[0], (list, tuple, set)):
+            # Instead of wrapping the iterable itself in `child_node_class`, we wrap each element individually
+            # enables us to use `child_node_class=Seq` to create a nested sequence
+            children = children[0]
+        super().__init__(*children, **kwargs)