exdrf 0.1.8__tar.gz

exdrf-0.1.8/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: exdrf
+Version: 0.1.8
+Summary: Describe datasets, resources and their fields.
+Author-email: Nicu Tofan <nicu.tofan@gmail.com>
+License-Expression: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.2
+Description-Content-Type: text/markdown
+Requires-Dist: attrs>=25.1.0
+Requires-Dist: inflect>=7.5.0
+Requires-Dist: SQLAlchemy>=2.0.38
+Requires-Dist: Unidecode>=1.4.0
+Provides-Extra: dev
+Requires-Dist: autoflake; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pyproject-flake8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: click<8.2.0,>=8.1.8; extra == "dev"
+
+# Datasets-Resources-Fields
+
+The library allows the user to define fields that make up a resource that is
+part of a dataset. The purpose is to construct an unified interface for
+describing these concepts, with supporting libraries for deriving the
+tree from various sources (e.g. SqlAlchemy, Pydantic, etc.) and for
+generating content from the tree.

exdrf-0.1.8/README.md

@@ -0,0 +1,7 @@
+# Datasets-Resources-Fields
+
+The library allows the user to define fields that make up a resource that is
+part of a dataset. The purpose is to construct an unified interface for
+describing these concepts, with supporting libraries for deriving the
+tree from various sources (e.g. SqlAlchemy, Pydantic, etc.) and for
+generating content from the tree.

exdrf-0.1.8/exdrf/__version__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.8'
+__version_tuple__ = version_tuple = (0, 1, 8)
+
+__commit_id__ = commit_id = 'g450ddaecd'

exdrf-0.1.8/exdrf/api.py

@@ -0,0 +1,51 @@
+from exdrf.dataset import ExDataset  # noqa: F401
+from exdrf.field import ExField  # noqa: F401
+from exdrf.field_types.api import (  # noqa: F401
+    BlobField,
+    BlobInfo,
+    BoolField,
+    BoolInfo,
+    DateField,
+    DateInfo,
+    DateTimeField,
+    DateTimeInfo,
+    DurationField,
+    DurationInfo,
+    EnumField,
+    EnumInfo,
+    FilterField,
+    FloatField,
+    FloatInfo,
+    FloatListField,
+    FloatListInfo,
+    FormattedField,
+    FormattedInfo,
+    IntField,
+    IntInfo,
+    IntListField,
+    IntListInfo,
+    RefBaseField,
+    RefManyToManyField,
+    RefManyToOneField,
+    RefOneToManyField,
+    RefOneToOneField,
+    RelExtraInfo,
+    SortField,
+    StrField,
+    StrInfo,
+    StrListField,
+    StrListInfo,
+    TimeField,
+    TimeInfo,
+)
+from exdrf.label_dsl import (  # noqa: F401
+    evaluate,
+    get_used_fields,
+    parse_expr,
+)
+from exdrf.resource import ExResource  # noqa: F401
+from exdrf.utils import (  # noqa: F401
+    doc_lines,
+    inflect_e,
+)
+from exdrf.visitor import ExVisitor  # noqa: F401

exdrf-0.1.8/exdrf/constants.py

@@ -0,0 +1,30 @@
+# Constants for field types
+from typing import Any, Final, Iterable, Literal, Union
+
+FIELD_TYPE_BLOB: Final[Literal["blob"]] = "blob"
+FIELD_TYPE_BOOL: Final[Literal["bool"]] = "bool"
+FIELD_TYPE_DT: Final[Literal["date-time"]] = "date-time"
+FIELD_TYPE_DATE: Final[Literal["date"]] = "date"
+FIELD_TYPE_TIME: Final[Literal["time"]] = "time"
+FIELD_TYPE_DURATION: Final[Literal["duration"]] = "duration"
+FIELD_TYPE_ENUM: Final[Literal["enum"]] = "enum"
+FIELD_TYPE_FLOAT: Final[Literal["float"]] = "float"
+FIELD_TYPE_INTEGER: Final[Literal["integer"]] = "integer"
+FIELD_TYPE_STRING: Final[Literal["string"]] = "string"
+FIELD_TYPE_STRING_LIST: Final[Literal["string-list"]] = "string-list"
+FIELD_TYPE_INT_LIST: Final[Literal["int-list"]] = "int-list"
+FIELD_TYPE_FLOAT_LIST: Final[Literal["float-list"]] = "float-list"
+FIELD_TYPE_FORMATTED: Final[Literal["formatted"]] = "formatted"
+FIELD_TYPE_FILTER: Final[Literal["filter"]] = "filter"
+FIELD_TYPE_SORT: Final[Literal["sort"]] = "sort"
+FIELD_TYPE_REF_ONE_TO_MANY: Final[Literal["one-to-many"]] = "one-to-many"
+FIELD_TYPE_REF_ONE_TO_ONE: Final[Literal["one-to-one"]] = "one-to-one"
+FIELD_TYPE_REF_MANY_TO_MANY: Final[Literal["many-to-many"]] = "many-to-many"
+FIELD_TYPE_REF_MANY_TO_ONE: Final[Literal["many-to-one"]] = "many-to-one"
+
+# This are the types of relations that we know of.
+RelType = Literal["OneToMany", "ManyToOne", "OneToOne", "ManyToMany"]
+
+# A record ID can be an int in the simple case or a list of various types
+# when there are multiple primary keys.
+RecIdType = Union[int, Iterable[Any]]

exdrf-0.1.8/exdrf/dataset.py

@@ -0,0 +1,197 @@
+from collections import OrderedDict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    cast,
+)
+
+from attrs import define, field
+
+from exdrf.resource import ExResource
+
+if TYPE_CHECKING:
+    from exdrf.visitor import ExVisitor
+
+
+@define
+class ExDataset:
+    """A set of resources.
+
+    The resources are stored in a list to ensure a consistent enumeration
+    order. To access a resource in the dataset, you can use the `dataset[key]`
+    syntax, where `key` can be either the index of the resource in the list
+    of models or the name of the resource.
+
+    Attributes:
+        name: The name of the dataset.
+        resources: A list of resources in the dataset.
+        category_map: A tree of categories, where each key is a category and
+            the value is a dictionary of subcategories or resources.
+    """
+
+    name: str = field(default="Dataset")
+    resources: List["ExResource"] = field(factory=list, repr=False)
+    category_map: dict = field(factory=OrderedDict, repr=False)
+    res_class: Type["ExResource"] = field(default=ExResource, repr=False, kw_only=True)
+
+    def __hash__(self):
+        return hash(self.name)
+
+    def __getitem__(self, key: Union[int, str]) -> "ExResource":
+        # Attempt to use the key as an index first.
+        if isinstance(key, int):
+            return self.resources[key]
+
+        # If the key is not an index, treat it as a name.
+        for m in self.resources:
+            if m.name == key:
+                return m
+
+        raise KeyError(
+            f"No resource found for key: {key}; valid indices are "
+            f"from 0 to {len(self.resources) - 1}. "
+            f"Valid names are: {[m.name for m in self.resources]}"
+        )
+
+    def __contains__(self, key: str) -> bool:
+        """Check if a resource is in the dataset."""
+        for m in self.resources:
+            if m.name == key:
+                return True
+        return False
+
+    def add_resource(self, resource: "ExResource") -> None:
+        """Add a resource to the dataset.
+
+        Args:
+            resource: The resource to add.
+        """
+        if not isinstance(resource, self.res_class):
+            raise TypeError(
+                f"Expected resource of type {self.res_class}, but got {type(resource)}."
+            )
+        self.resources.append(resource)
+        resource.dataset = self  # type: ignore
+
+        # Place the resource in the category map.
+        crt = self.category_map
+        for part in resource.categories:
+            next_crt = crt.get(part)
+            if next_crt is None:
+                next_crt = OrderedDict()
+                crt[part] = next_crt
+            crt = next_crt
+        crt[resource.name] = resource
+
+    def visit(
+        self,
+        visitor: "ExVisitor",
+        omit_fields: Optional[bool] = False,
+        omit_categories: Optional[bool] = False,
+    ) -> bool:
+        """Visit the dataset and its resources.
+
+        Args:
+            visitor: The visitor to use.
+            omit_fields: If True, resource fields will not be visited.
+            omit_categories: If True, categories will not be visited.
+                This means that the visitor will only visit the resources in
+                the dataset, not the categories, making the process a bit more
+                efficient.
+
+        Returns:
+            bool: True if the visit should continue, False otherwise.
+        """
+        if not visitor.visit_dataset(self):  # type: ignore
+            return False
+
+        if omit_categories:
+            for res in self.resources:
+                if not res.visit(visitor, omit_fields=omit_fields):
+                    return False
+            return True
+
+        def do_category_map(crt_map: dict, level: int = 0) -> bool:
+            for k, v in crt_map.items():
+                if isinstance(v, dict):
+                    visitor.visit_category(k, level, v)
+                    if not do_category_map(v, level + 1):
+                        return False
+                else:
+                    resource = cast("ExResource", v)
+                    if not resource.visit(visitor, omit_fields=omit_fields):
+                        return False
+            return True
+
+        return do_category_map(self.category_map)
+
+    def zero_categories(self) -> List[Tuple[str, List["ExResource"]]]:
+        """Get a list of top level categories and their resources."""
+        result = []
+        for ctg, ctg_data in self.category_map.items():
+            models = []
+
+            def do_data(crt_data: Any) -> None:
+                if isinstance(crt_data, dict):
+                    for subset in crt_data.values():
+                        do_data(subset)
+                else:
+                    models.append(crt_data)
+
+            do_data(ctg_data)
+            result.append((ctg, models))
+        return result
+
+    def sorted_by_deps(self) -> List["ExResource"]:
+        # Build a dependency map where key is the resource name and value is a
+        # set of names of resources it depends on.
+        deps: Dict[str, List["ExResource"]] = {}
+        short_deps: Dict[str, List["ExResource"]] = {}
+        name_to_resource: Dict[str, "ExResource"] = {}
+        for resource in self.resources:
+            deps[resource.name] = list(resource.get_dependencies())
+            short_deps[resource.name] = list(resource.get_dependencies(fk_only=True))
+            name_to_resource[resource.name] = resource
+
+        # Start with those that have no dependencies.
+        result = OrderedDict(
+            (name, name_to_resource[name])
+            for name, deps in sorted(deps.items(), key=lambda x: x[0])
+            if len(deps) == 0
+        )
+
+        def recursive(name: str, visited: List[str], fk_only: bool = False):
+            """Examine the dependency chain of a resource."""
+            if name in visited:
+                print(
+                    f"Circular dependency detected: {name} -> " + " -> ".join(visited)
+                )
+                return
+
+            if name in result:
+                return
+
+            if fk_only:
+                my_deps = short_deps[name]
+            else:
+                my_deps = deps[name]
+            for dep in my_deps:
+                recursive(dep.name, visited + [name], fk_only=fk_only)
+
+            # Add the resource to the sorted list.
+            result[name] = name_to_resource[name]
+
+        for name in sorted(short_deps.keys()):
+            recursive(name, [], fk_only=True)
+
+        if len(result) != len(deps):
+            for name in sorted(deps.keys()):
+                recursive(name, [], fk_only=False)
+
+        return list(result.values())