stapel-attributes 0.1.1__tar.gz

stapel_attributes-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+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.

stapel_attributes-0.1.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: stapel-attributes
+Version: 0.1.1
+Summary: Typed attributes engine for the Stapel framework
+License: MIT
+Keywords: django,stapel,attributes
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: djangorestframework-dataclasses>=1.2
+Requires-Dist: drf-polymorphic<3,>=2.1
+Requires-Dist: drf-spectacular>=0.27
+Provides-Extra: all
+Dynamic: license-file
+
+# stapel-attributes
+
+Typed attributes engine for the [Stapel framework](https://github.com/usestapel) —
+a polymorphic type system for attribute ("feature") configurations: an open
+registry of feature types, Config/DTO/DAO layering per type, polymorphic DRF
+serializers with OpenAPI schemas, and a structured value-validation pipeline.
+
+This is an **L1 library**, not a module: it ships no models, migrations,
+views, urls or comm surface. Both `stapel-categories` (attribute schema) and
+`stapel-listings` (attribute values) import it — the code both need
+synchronously lives one layer down, like `stapel-core` itself.
+
+Provenance: port of the `categories/feature_types` engine and the
+`ads` validation pipeline from waylot-catalog (see CHANGELOG for what was
+fixed in transit).
+
+## Install
+
+```bash
+pip install stapel-attributes
+```
+
+No `INSTALLED_APPS` entry, no urls — just import it:
+
+```python
+from stapel_attributes import (
+    FeatureDef,
+    validate_dto,
+    normalize_to_dao,
+    validate_dto_structured,
+)
+
+configs = [
+    FeatureDef(slug="mileage", config={"type": "int", "min": 0, "postfix": "km"}),
+    FeatureDef(slug="condition", config={"type": "bool"}, mandatory=True),
+]
+payload = {"mileage": {"type": "int", "value": 120000},
+           "condition": {"type": "bool", "value": True}}
+
+validate_dto(configs, payload)              # raises ValidationError on failure
+dao = normalize_to_dao(configs, payload)    # {"mileage": {"type": "int", "value": 120000, "postfix": "km", "order": 0}, ...}
+result = validate_dto_structured(configs, payload)  # machine-readable batch result
+```
+
+## Built-in types
+
+`int`, `float`, `string`, `bool`, `hex_color`, `select`, `date`, `header`,
+`hierarchical_select`. Each type is a plugin: a Config dataclass (schema), a
+DTO (client input), a DAO (stored value + display metadata) and a handler
+(`BaseFeatureType[TConfig, TDto, TDao]`).
+
+Marketplace-specific types (size grids, convertible units, ...) are **not**
+shipped — hosts register their own via the open registry (see MODULE.md for
+the worked example).
+
+## Settings
+
+All configuration lives in the `STAPEL_ATTRIBUTES` namespace (dict setting,
+flat setting, or env var — resolved lazily):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `EXTRA_TYPES` | `[]` | Dotted paths of extra feature types, **merged** over the built-ins (each entry: a `BaseFeatureType` subclass or a module that registers types on import). |
+
+## Structured validation
+
+Every validation failure carries a machine code end-to-end
+(`ValidationErrorCode`) via `FeatureValidationError` — no message parsing.
+Batch validators return `ValidationBatchResult` rows with `error`,
+`ref_value`, `localizable_error` (an `error.400.feature_*` key) and `params`.
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(settings, the type registry, serializer factories, translation-key hooks).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_attributes-0.1.1/README.md

@@ -0,0 +1,87 @@
+# stapel-attributes
+
+Typed attributes engine for the [Stapel framework](https://github.com/usestapel) —
+a polymorphic type system for attribute ("feature") configurations: an open
+registry of feature types, Config/DTO/DAO layering per type, polymorphic DRF
+serializers with OpenAPI schemas, and a structured value-validation pipeline.
+
+This is an **L1 library**, not a module: it ships no models, migrations,
+views, urls or comm surface. Both `stapel-categories` (attribute schema) and
+`stapel-listings` (attribute values) import it — the code both need
+synchronously lives one layer down, like `stapel-core` itself.
+
+Provenance: port of the `categories/feature_types` engine and the
+`ads` validation pipeline from waylot-catalog (see CHANGELOG for what was
+fixed in transit).
+
+## Install
+
+```bash
+pip install stapel-attributes
+```
+
+No `INSTALLED_APPS` entry, no urls — just import it:
+
+```python
+from stapel_attributes import (
+    FeatureDef,
+    validate_dto,
+    normalize_to_dao,
+    validate_dto_structured,
+)
+
+configs = [
+    FeatureDef(slug="mileage", config={"type": "int", "min": 0, "postfix": "km"}),
+    FeatureDef(slug="condition", config={"type": "bool"}, mandatory=True),
+]
+payload = {"mileage": {"type": "int", "value": 120000},
+           "condition": {"type": "bool", "value": True}}
+
+validate_dto(configs, payload)              # raises ValidationError on failure
+dao = normalize_to_dao(configs, payload)    # {"mileage": {"type": "int", "value": 120000, "postfix": "km", "order": 0}, ...}
+result = validate_dto_structured(configs, payload)  # machine-readable batch result
+```
+
+## Built-in types
+
+`int`, `float`, `string`, `bool`, `hex_color`, `select`, `date`, `header`,
+`hierarchical_select`. Each type is a plugin: a Config dataclass (schema), a
+DTO (client input), a DAO (stored value + display metadata) and a handler
+(`BaseFeatureType[TConfig, TDto, TDao]`).
+
+Marketplace-specific types (size grids, convertible units, ...) are **not**
+shipped — hosts register their own via the open registry (see MODULE.md for
+the worked example).
+
+## Settings
+
+All configuration lives in the `STAPEL_ATTRIBUTES` namespace (dict setting,
+flat setting, or env var — resolved lazily):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `EXTRA_TYPES` | `[]` | Dotted paths of extra feature types, **merged** over the built-ins (each entry: a `BaseFeatureType` subclass or a module that registers types on import). |
+
+## Structured validation
+
+Every validation failure carries a machine code end-to-end
+(`ValidationErrorCode`) via `FeatureValidationError` — no message parsing.
+Batch validators return `ValidationBatchResult` rows with `error`,
+`ref_value`, `localizable_error` (an `error.400.feature_*` key) and `params`.
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(settings, the type registry, serializer factories, translation-key hooks).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_attributes-0.1.1/__init__.py

@@ -0,0 +1,133 @@
+"""stapel-attributes — typed attributes engine for the Stapel framework.
+
+A polymorphic type system for attribute (feature) configurations: an open
+registry of feature types, Config/DTO/DAO layering per type, polymorphic
+DRF serializers with OpenAPI schemas, and a structured value-validation
+pipeline (DTO -> DAO). Ported from waylot-catalog's ``categories/feature_types``
+engine; see MODULE.md for provenance and extension points.
+
+This is an L1 *library*: it has no models, migrations, views, urls or comm
+surface of its own. Both stapel-categories (schema side) and stapel-listings
+(value side) import it.
+
+Public API is lazily exported (PEP 562) — importing this package never pulls
+in Django or requires configured settings.
+"""
+
+__all__ = [
+    # Settings
+    "attributes_settings",
+    # Base abstractions
+    "BaseFeatureType",
+    "DaoMeta",
+    "DictDataclassSerializer",
+    "FeatureDef",
+    "dataclass_to_dict_no_none",
+    # Structured errors & results
+    "FeatureValidationError",
+    "FeatureValidationResult",
+    "ValidationBatchResult",
+    "ValidationErrorCode",
+    "ValidationStatus",
+    # Registry
+    "register_feature_type",
+    "registered_types",
+    "get_feature_type",
+    "get_all_feature_types",
+    "get_all_type_slugs",
+    # Parse / convert
+    "parse_config",
+    "parse_dto",
+    "dao_to_dict",
+    "validate_feature_config",
+    "validate_feature_dto",
+    "dto_to_dao",
+    "normalize_feature_dto",
+    "get_default_value",
+    "format_feature_value",
+    "collect_translation_keys_for_feature",
+    "collect_all_builtin_translation_keys",
+    # Validation pipeline (configs -> DTO -> DAO)
+    "coerce_feature_defs",
+    "get_feature_slug",
+    "build_feature_lookup",
+    "validate_dto",
+    "normalize_to_dao",
+    "validate_dto_structured",
+    "validate_configs_structured",
+    "validate_dao_structured",
+    "validate_description",
+    # Polymorphic serializer factories
+    "get_feature_config_serializer_class",
+    "get_feature_dto_serializer_class",
+    "get_feature_dao_serializer_class",
+    "get_feature_config_proxy_serializer",
+    "get_feature_dto_proxy_serializer",
+    "get_feature_dao_proxy_serializer",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_attributes` stays Django-free.
+_LAZY_EXPORTS = {
+    "attributes_settings": ".conf",
+    # base
+    "BaseFeatureType": ".base",
+    "DaoMeta": ".base",
+    "DictDataclassSerializer": ".base",
+    "FeatureDef": ".base",
+    "dataclass_to_dict_no_none": ".base",
+    # errors & results
+    "FeatureValidationError": ".exceptions",
+    "FeatureValidationResult": ".results",
+    "ValidationBatchResult": ".results",
+    "ValidationErrorCode": ".results",
+    "ValidationStatus": ".results",
+    # registry
+    "register_feature_type": ".registry",
+    "registered_types": ".registry",
+    "get_feature_type": ".registry",
+    "get_all_feature_types": ".registry",
+    "get_all_type_slugs": ".registry",
+    "parse_config": ".registry",
+    "parse_dto": ".registry",
+    "dao_to_dict": ".registry",
+    "validate_feature_config": ".registry",
+    "validate_feature_dto": ".registry",
+    "dto_to_dao": ".registry",
+    "normalize_feature_dto": ".registry",
+    "get_default_value": ".registry",
+    "format_feature_value": ".registry",
+    "collect_translation_keys_for_feature": ".registry",
+    "collect_all_builtin_translation_keys": ".registry",
+    # validation pipeline
+    "coerce_feature_defs": ".validation",
+    "get_feature_slug": ".validation",
+    "build_feature_lookup": ".validation",
+    "validate_dto": ".validation",
+    "normalize_to_dao": ".validation",
+    "validate_dto_structured": ".validation",
+    "validate_configs_structured": ".validation",
+    "validate_dao_structured": ".validation",
+    "validate_description": ".validation",
+    # serializer factories
+    "get_feature_config_serializer_class": ".serializers",
+    "get_feature_dto_serializer_class": ".serializers",
+    "get_feature_dao_serializer_class": ".serializers",
+    "get_feature_config_proxy_serializer": ".serializers",
+    "get_feature_dto_proxy_serializer": ".serializers",
+    "get_feature_dao_proxy_serializer": ".serializers",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))