exdrf-rcv 0.1.17__tar.gz

exdrf_rcv-0.1.17/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: exdrf-rcv
+Version: 0.1.17
+Summary: Shared Python runtime for remote-controlled-view backends and exdrf-gen-al2rcv-generated modules.
+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: exdrf>=0.1.17
+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: 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"
+
+# exdrf-rcv
+
+The **remote-controlled-view (RCV)** stack renders **exdrf** resources and
+related data into a user interface that the front end drives over HTTP.
+
+**exdrf-rcv** is the **shared Python runtime** for RCV *backends*. It defines
+**`RcvPlan`**, discriminated **`RcvField`** types, and helpers that
+**`exdrf-gen-al2rcv`**-generated route modules import next to your FastAPI app.
+
+The browser UI that consumes those endpoints lives in **fr-one** under
+**`libs/rcv`**; this package stays on the **exdrf** / API side of that boundary.
+
+Python **3.12.2+** is required. Install next to **exdrf** in the same
+environment as **exdrf-gen-al2rcv** output.
+
+## Related packages
+
+- **exdrf-gen-al2rcv** — emits `{resource}_rcv_paths.py` scaffolds and root
+  **`api.py`** wired to your **`--get-db`** callable.
+- **exdrf-gen-al2r** — sibling FastAPI router codegen; similar category layout.

exdrf_rcv-0.1.17/README.md

@@ -0,0 +1,20 @@
+# exdrf-rcv
+
+The **remote-controlled-view (RCV)** stack renders **exdrf** resources and
+related data into a user interface that the front end drives over HTTP.
+
+**exdrf-rcv** is the **shared Python runtime** for RCV *backends*. It defines
+**`RcvPlan`**, discriminated **`RcvField`** types, and helpers that
+**`exdrf-gen-al2rcv`**-generated route modules import next to your FastAPI app.
+
+The browser UI that consumes those endpoints lives in **fr-one** under
+**`libs/rcv`**; this package stays on the **exdrf** / API side of that boundary.
+
+Python **3.12.2+** is required. Install next to **exdrf** in the same
+environment as **exdrf-gen-al2rcv** output.
+
+## Related packages
+
+- **exdrf-gen-al2rcv** — emits `{resource}_rcv_paths.py` scaffolds and root
+  **`api.py`** wired to your **`--get-db`** callable.
+- **exdrf-gen-al2r** — sibling FastAPI router codegen; similar category layout.

exdrf_rcv-0.1.17/exdrf_rcv/__init__.py

@@ -0,0 +1,30 @@
+"""Shared runtime for remote-controlled-view (RCV) backends.
+
+``exdrf-gen-al2rcv`` emits modules that should import shared symbols from this
+package as RCV behavior grows. The front-end RCV project is documented under
+``fr-one`` ``libs/rcv``.
+"""
+
+from exdrf_rcv.models import RcvField, RcvPlan, RcvResourceDataAccess
+from exdrf_rcv.plan_resolve import (
+    RcvPlanCache,
+    RcvPlanCacheKey,
+    clear_rcv_plan_overrides,
+    default_rcv_plan_cache,
+    register_rcv_plan_override,
+    resolve_rcv_plan,
+    unregister_rcv_plan_override,
+)
+
+__all__ = [
+    "RcvPlan",
+    "RcvField",
+    "RcvResourceDataAccess",
+    "RcvPlanCache",
+    "RcvPlanCacheKey",
+    "clear_rcv_plan_overrides",
+    "default_rcv_plan_cache",
+    "register_rcv_plan_override",
+    "resolve_rcv_plan",
+    "unregister_rcv_plan_override",
+]

exdrf_rcv-0.1.17/exdrf_rcv/__version__.py

@@ -0,0 +1,24 @@
+"""Package version from PEP 621 or installed metadata."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from exdrf.pep621_version import distribution_version, version_tuple_from_string
+
+_PYPROJECT = Path(__file__).resolve().parents[1] / "pyproject.toml"
+_DIST_NAME = "exdrf-rcv"
+
+__version__ = version = distribution_version(_DIST_NAME, _PYPROJECT)
+__version_tuple__ = version_tuple = version_tuple_from_string(__version__)
+
+__commit_id__ = commit_id = None
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]

exdrf_rcv-0.1.17/exdrf_rcv/models.py

@@ -0,0 +1,435 @@
+"""Pydantic wire models for remote-controlled-view plans and field metadata.
+
+``kind`` values mirror ``FIELD_TYPE_*`` in ``exdrf.constants``; ``data`` carries
+type-specific options aligned with ``exdrf.field_types`` ``*Field`` /
+``*Info`` shapes.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from exdrf.constants import (
+    FIELD_TYPE_BLOB,
+    FIELD_TYPE_BOOL,
+    FIELD_TYPE_DATE,
+    FIELD_TYPE_DT,
+    FIELD_TYPE_DURATION,
+    FIELD_TYPE_ENUM,
+    FIELD_TYPE_FILTER,
+    FIELD_TYPE_FLOAT,
+    FIELD_TYPE_FLOAT_LIST,
+    FIELD_TYPE_FORMATTED,
+    FIELD_TYPE_INT_LIST,
+    FIELD_TYPE_INTEGER,
+    FIELD_TYPE_REF_MANY_TO_MANY,
+    FIELD_TYPE_REF_MANY_TO_ONE,
+    FIELD_TYPE_REF_ONE_TO_MANY,
+    FIELD_TYPE_REF_ONE_TO_ONE,
+    FIELD_TYPE_SORT,
+    FIELD_TYPE_STRING,
+    FIELD_TYPE_STRING_LIST,
+    FIELD_TYPE_TIME,
+    RelType,
+)
+
+
+class RcvFieldBase(BaseModel):
+    """Shared metadata for one field in an ``RcvPlan``.
+
+    Attributes:
+        name: Field name on the resource (snake_case).
+        title: Human-facing title when not inferred from ``name``.
+        description: Longer help text for the field.
+        category: Short logical grouping for layout.
+        pos_hint: UI ordering / placement hint from ``FieldInfo``.
+        required: Whether a value must be present for save/submit.
+        default: Wire default when omitted (type depends on ``kind``).
+        primary: Whether the field participates in record identity.
+        visible: Whether the field is shown to the user.
+        read_only: Whether the value is displayed but not editable.
+        nullable: Whether the underlying column allows null.
+        sortable: Whether list views may sort by this field.
+        filterable: Whether list views may filter by this field.
+        exportable: Whether user export may include this field.
+        qsearch: Whether quick-search uses this field.
+        resizable: Whether list column width is user-resizable.
+        derived: Optional ``(derivation_kind, source_field_name)`` tuple.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    title: str | None = None
+    description: str | None = None
+    category: str | None = None
+    pos_hint: str | None = None
+    required: bool = False
+    default: Any | None = None
+    primary: bool | None = None
+    visible: bool | None = None
+    read_only: bool | None = None
+    nullable: bool | None = None
+    sortable: bool | None = None
+    filterable: bool | None = None
+    exportable: bool | None = None
+    qsearch: bool | None = None
+    resizable: bool | None = None
+    derived: tuple[str, str] | None = None
+
+
+class RcvEmptyData(BaseModel):
+    """Placeholder ``data`` for field kinds without extra options."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RcvBlobFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_BLOB`` (see ``BlobInfo``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mime_type: str | None = None
+
+
+class RcvBoolFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_BOOL`` (see ``BoolInfo``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    true_str: str | None = None
+    false_str: str | None = None
+
+
+class RcvStringFieldData(BaseModel):
+    """Options for string-like kinds (see ``StrInfo`` / ``StrListInfo``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    multiline: bool | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    enum_values: list[tuple[str, str]] = Field(default_factory=list)
+    no_dia_field: str | None = None
+
+
+class RcvFormattedFieldData(RcvStringFieldData):
+    """Options for ``FIELD_TYPE_FORMATTED`` (see ``FormattedInfo``)."""
+
+    format: Literal["json", "html", "xml"] | None = None
+
+
+class RcvIntFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_INTEGER`` / ``FIELD_TYPE_INT_LIST``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: int | None = None
+    max: int | None = None
+    unit: str | None = None
+    unit_symbol: str | None = None
+    enum_values: list[tuple[int, str]] = Field(default_factory=list)
+
+
+class RcvFloatFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_FLOAT`` / ``FIELD_TYPE_FLOAT_LIST``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: float | None = None
+    max: float | None = None
+    precision: int | None = None
+    scale: int | None = None
+    unit: str | None = None
+    unit_symbol: str | None = None
+    enum_values: list[tuple[float, str]] = Field(default_factory=list)
+
+
+class RcvDateFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_DATE`` (see ``DateInfo`` + ``DateField``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: date | None = None
+    max: date | None = None
+    format: str | None = None
+
+
+class RcvDateTimeFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_DT`` (``DateTimeInfo`` / ``DateTimeField``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: datetime | None = None
+    max: datetime | None = None
+    format: str | None = None
+
+
+class RcvTimeFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_TIME`` (see ``TimeInfo`` + ``TimeField``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: time | None = None
+    max: time | None = None
+    format: str | None = None
+
+
+class RcvDurationFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_DURATION`` (see ``DurationInfo``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: float | None = None
+    max: float | None = None
+
+
+class RcvEnumFieldData(BaseModel):
+    """Options for ``FIELD_TYPE_ENUM`` (see ``EnumInfo`` / ``EnumField``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enum_values: list[str] = Field(default_factory=list)
+
+
+class RcvRefFieldData(BaseModel):
+    """Options for relation kinds (see ``RelExtraInfo`` / ``RefBaseField``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ref: str
+    direction: RelType | None = None
+    subordinate: bool | None = None
+    expect_lots: bool | None = None
+    provides: list[str] = Field(default_factory=list)
+    depends_on: list[tuple[str, str]] = Field(default_factory=list)
+    bridge: str | None = None
+
+
+class RcvBlobField(RcvFieldBase):
+    """RCV descriptor for a blob column."""
+
+    kind: Literal["blob"] = FIELD_TYPE_BLOB
+    data: RcvBlobFieldData = Field(default_factory=RcvBlobFieldData)
+
+
+class RcvBoolField(RcvFieldBase):
+    """RCV descriptor for a boolean column."""
+
+    kind: Literal["bool"] = FIELD_TYPE_BOOL
+    data: RcvBoolFieldData = Field(default_factory=RcvBoolFieldData)
+
+
+class RcvDateField(RcvFieldBase):
+    """RCV descriptor for a date column."""
+
+    kind: Literal["date"] = FIELD_TYPE_DATE
+    data: RcvDateFieldData = Field(default_factory=RcvDateFieldData)
+
+
+class RcvDateTimeField(RcvFieldBase):
+    """RCV descriptor for a date-time column."""
+
+    kind: Literal["date-time"] = FIELD_TYPE_DT
+    data: RcvDateTimeFieldData = Field(default_factory=RcvDateTimeFieldData)
+
+
+class RcvDurationField(RcvFieldBase):
+    """RCV descriptor for a duration column."""
+
+    kind: Literal["duration"] = FIELD_TYPE_DURATION
+    data: RcvDurationFieldData = Field(default_factory=RcvDurationFieldData)
+
+
+class RcvEnumField(RcvFieldBase):
+    """RCV descriptor for an enum-like column."""
+
+    kind: Literal["enum"] = FIELD_TYPE_ENUM
+    data: RcvEnumFieldData = Field(default_factory=RcvEnumFieldData)
+
+
+class RcvFilterField(RcvFieldBase):
+    """RCV descriptor for a filter pseudo-field."""
+
+    kind: Literal["filter"] = FIELD_TYPE_FILTER
+    data: RcvEmptyData = Field(default_factory=RcvEmptyData)
+
+
+class RcvFloatField(RcvFieldBase):
+    """RCV descriptor for a float column."""
+
+    kind: Literal["float"] = FIELD_TYPE_FLOAT
+    data: RcvFloatFieldData = Field(default_factory=RcvFloatFieldData)
+
+
+class RcvFloatListField(RcvFieldBase):
+    """RCV descriptor for a float list column."""
+
+    kind: Literal["float-list"] = FIELD_TYPE_FLOAT_LIST
+    data: RcvFloatFieldData = Field(default_factory=RcvFloatFieldData)
+
+
+class RcvFormattedField(RcvFieldBase):
+    """RCV descriptor for formatted (rich text / markup) string columns."""
+
+    kind: Literal["formatted"] = FIELD_TYPE_FORMATTED
+    data: RcvFormattedFieldData = Field(default_factory=RcvFormattedFieldData)
+
+
+class RcvIntField(RcvFieldBase):
+    """RCV descriptor for an integer column."""
+
+    kind: Literal["integer"] = FIELD_TYPE_INTEGER
+    data: RcvIntFieldData = Field(default_factory=RcvIntFieldData)
+
+
+class RcvIntListField(RcvFieldBase):
+    """RCV descriptor for an integer list column."""
+
+    kind: Literal["int-list"] = FIELD_TYPE_INT_LIST
+    data: RcvIntFieldData = Field(default_factory=RcvIntFieldData)
+
+
+class RcvManyToManyField(RcvFieldBase):
+    """RCV descriptor for a many-to-many relation field."""
+
+    kind: Literal["many-to-many"] = FIELD_TYPE_REF_MANY_TO_MANY
+    data: RcvRefFieldData
+
+
+class RcvManyToOneField(RcvFieldBase):
+    """RCV descriptor for a many-to-one relation field."""
+
+    kind: Literal["many-to-one"] = FIELD_TYPE_REF_MANY_TO_ONE
+    data: RcvRefFieldData
+
+
+class RcvOneToManyField(RcvFieldBase):
+    """RCV descriptor for a one-to-many relation field."""
+
+    kind: Literal["one-to-many"] = FIELD_TYPE_REF_ONE_TO_MANY
+    data: RcvRefFieldData
+
+
+class RcvOneToOneField(RcvFieldBase):
+    """RCV descriptor for a one-to-one relation field."""
+
+    kind: Literal["one-to-one"] = FIELD_TYPE_REF_ONE_TO_ONE
+    data: RcvRefFieldData
+
+
+class RcvStringField(RcvFieldBase):
+    """RCV descriptor for a string column."""
+
+    kind: Literal["string"] = FIELD_TYPE_STRING
+    data: RcvStringFieldData = Field(default_factory=RcvStringFieldData)
+
+
+class RcvStringListField(RcvFieldBase):
+    """RCV descriptor for a string list column."""
+
+    kind: Literal["string-list"] = FIELD_TYPE_STRING_LIST
+    data: RcvStringFieldData = Field(default_factory=RcvStringFieldData)
+
+
+class RcvSortField(RcvFieldBase):
+    """RCV descriptor for a sort pseudo-field."""
+
+    kind: Literal["sort"] = FIELD_TYPE_SORT
+    data: RcvEmptyData = Field(default_factory=RcvEmptyData)
+
+
+class RcvTimeField(RcvFieldBase):
+    """RCV descriptor for a time-of-day column."""
+
+    kind: Literal["time"] = FIELD_TYPE_TIME
+    data: RcvTimeFieldData = Field(default_factory=RcvTimeFieldData)
+
+
+RcvField = Annotated[
+    Union[
+        RcvBlobField,
+        RcvBoolField,
+        RcvDateField,
+        RcvDateTimeField,
+        RcvDurationField,
+        RcvEnumField,
+        RcvFilterField,
+        RcvFloatField,
+        RcvFloatListField,
+        RcvFormattedField,
+        RcvIntField,
+        RcvIntListField,
+        RcvManyToManyField,
+        RcvManyToOneField,
+        RcvOneToManyField,
+        RcvOneToOneField,
+        RcvSortField,
+        RcvStringField,
+        RcvStringListField,
+        RcvTimeField,
+    ],
+    Field(discriminator="kind"),
+]
+
+
+class RcvResourceDataAccess(BaseModel):
+    """Where and how to load row payloads for this plan over HTTP.
+
+    Used for list data, edit/view refresh, and similar flows. The client should
+    prepend its API base (including ``root_path``) to ``url_pattern`` when
+    building the final request URL.
+
+    Attributes:
+        url_pattern: Path under the API root, typically an exdrf-gen-al2r list
+            GET path such as ``/classic/{category}/{resource_plural}/``. May later include
+            placeholders (for example ``{record_id}``) documented alongside
+            those features.
+        requires_org_id: When true, the client must include an ``org_id`` query
+            parameter (or the convention documented for this deployment) when
+            calling ``url_pattern``.
+        requires_town_id: When true, the client must include a ``town_id`` query
+            parameter when calling ``url_pattern``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    url_pattern: str
+    requires_org_id: bool = False
+    requires_town_id: bool = False
+
+
+class RcvPlan(BaseModel):
+    """A plan for rendering a resource, record and view type.
+
+    Attributes:
+        category: The category of the resource. In most cases this will be the
+            same as the value passed by the front-end.
+        resource: The name of the resource. In most cases this will be the
+            same as the value passed by the front-end.
+        record_id: The ID of the record. In most cases this will be the
+            same as the value passed by the front-end.
+        view_type: The type of view that is requested. In most cases this
+            will be the same as the value passed by the front-end.
+        render_type: The type of renderer to use. When a generated module omits
+            ``RCV_RENDER_TYPE`` or sets it to the placeholder ``"default"``,
+            :func:`exdrf_rcv.plan_resolve.resolve_rcv_plan` sets this to the
+            same value as ``view_type``.
+        fields: The fields to render.
+        resource_data_access: Optional hint for loading tabular row data or
+            refreshing a record from HTTP; omitted when the generated module
+            does not define ``RCV_RESOURCE_DATA_ACCESS``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    category: str | None = None
+    resource: str | None = None
+    record_id: int | None = None
+    view_type: str | None = None
+    render_type: str
+    fields: list[RcvField]
+    resource_data_access: RcvResourceDataAccess | None = None

exdrf_rcv-0.1.17/exdrf_rcv/plan.py

@@ -0,0 +1,10 @@
+"""RCV plan types shared between FastAPI routes and ``exdrf_rcv`` consumers."""
+
+from __future__ import annotations
+
+from exdrf_rcv.models import RcvPlan, RcvResourceDataAccess
+
+__all__ = [
+    "RcvPlan",
+    "RcvResourceDataAccess",
+]