drf-react-by-schema 0.27.0__tar.gz → 0.27.2__tar.gz

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: drf_react_by_schema
-Version: 0.27.0
+Version: 0.27.2
 Summary: A Django app to easily integrate with React from models.
 Home-page: https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django
 Author: Cooperativa EITA
@@ -317,16 +317,42 @@ object with:
   version changes;
 * ``drbs_version`` — the installed ``drf-react-by-schema`` version;
 * ``system`` — apps, ``AUTH_USER_MODEL``, the ``DRF_REACT_BY_SCHEMA`` summary,
-  static permission hints (DRF defaults, global, per-model) and request
+  static permission hints (DRF defaults, global, per-model), request
   ``conventions`` (API base, pagination, ``ordering``/``search``/``sum_rows``
-  params, grid-filter operators);
+  params, grid-filter operators) and ``about`` (the project's ``ABOUT.md``,
+  trimmed — see below);
 * ``endpoints`` — every generated route (list and nested) with its
   ``path``/``kind``/``verbose_name``/``parent_model``/``related_model``;
 * ``models`` — each model's field ``schema`` (the same ``OPTIONS`` POST payload
-  the React app consumes), verbose names and generated TypeScript
-  ``interface``;
+  the React app consumes), verbose names, generated TypeScript ``interface`` and
+  the model class ``docstring`` (trimmed);
 * ``interfaces`` and ``enums`` — the generated TypeScript declarations.
 
+Documentation in the bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Free-form, non-UI documentation is folded into the bundle so an assistant can
+*understand* the system. It is kept out of the React artifacts on purpose:
+``sync_react``'s ``schemas/*.json`` stay **byte-identical** to before.
+
+* **Model docstrings** — a model class's *own* docstring (inherited docs are
+  ignored) is reported as ``models[<Model>].docstring``, trimmed at a word
+  boundary to ``schema_bundle.MODEL_DOCSTRING_MAX`` characters.
+* **Field descriptions** — pass ``description="..."`` to any package field
+  (``CharField``, ``ForeignKey``, ``DecimalField``, ...); it is reported as
+  ``models[<Model>].schema[<field>].description`` (trimmed to
+  ``FIELD_DESCRIPTION_MAX``). This is **not** ``help_text``: ``help_text`` is
+  rendered to end users by ``drf-react-by-schema-js``, while ``description``
+  documents the field for the API client / assistant. Only values passed
+  explicitly are reported — the field type's own ``description`` is never.
+* **Project ``ABOUT.md``** — a project-root ``ABOUT.md`` (``settings.BASE_DIR``)
+  is reported as ``system.about`` (trimmed to ``ABOUT_MAX``). Override the path
+  with ``DRF_REACT_BY_SCHEMA['ABOUT_PATH']``; a missing file yields ``null``.
+  Use it for *what the project is about* — not deploy/contribute instructions.
+
+All three feed the ``stamp``, so changing them invalidates an MCP client's
+cached copy; because the bundle is cached per process, a change also needs a
+process restart to be picked up.
+
 The endpoint sits behind the project's **existing auth** (the same permission
 source used by the generated viewsets — ``DRF_REACT_BY_SCHEMA['PERMISSIONS']``,
 defaulting to ``IsAuthenticated``; authentication comes from your DRF defaults,

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/README.rst

@@ -290,16 +290,42 @@ object with:
   version changes;
 * ``drbs_version`` — the installed ``drf-react-by-schema`` version;
 * ``system`` — apps, ``AUTH_USER_MODEL``, the ``DRF_REACT_BY_SCHEMA`` summary,
-  static permission hints (DRF defaults, global, per-model) and request
+  static permission hints (DRF defaults, global, per-model), request
   ``conventions`` (API base, pagination, ``ordering``/``search``/``sum_rows``
-  params, grid-filter operators);
+  params, grid-filter operators) and ``about`` (the project's ``ABOUT.md``,
+  trimmed — see below);
 * ``endpoints`` — every generated route (list and nested) with its
   ``path``/``kind``/``verbose_name``/``parent_model``/``related_model``;
 * ``models`` — each model's field ``schema`` (the same ``OPTIONS`` POST payload
-  the React app consumes), verbose names and generated TypeScript
-  ``interface``;
+  the React app consumes), verbose names, generated TypeScript ``interface`` and
+  the model class ``docstring`` (trimmed);
 * ``interfaces`` and ``enums`` — the generated TypeScript declarations.
 
+Documentation in the bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Free-form, non-UI documentation is folded into the bundle so an assistant can
+*understand* the system. It is kept out of the React artifacts on purpose:
+``sync_react``'s ``schemas/*.json`` stay **byte-identical** to before.
+
+* **Model docstrings** — a model class's *own* docstring (inherited docs are
+  ignored) is reported as ``models[<Model>].docstring``, trimmed at a word
+  boundary to ``schema_bundle.MODEL_DOCSTRING_MAX`` characters.
+* **Field descriptions** — pass ``description="..."`` to any package field
+  (``CharField``, ``ForeignKey``, ``DecimalField``, ...); it is reported as
+  ``models[<Model>].schema[<field>].description`` (trimmed to
+  ``FIELD_DESCRIPTION_MAX``). This is **not** ``help_text``: ``help_text`` is
+  rendered to end users by ``drf-react-by-schema-js``, while ``description``
+  documents the field for the API client / assistant. Only values passed
+  explicitly are reported — the field type's own ``description`` is never.
+* **Project ``ABOUT.md``** — a project-root ``ABOUT.md`` (``settings.BASE_DIR``)
+  is reported as ``system.about`` (trimmed to ``ABOUT_MAX``). Override the path
+  with ``DRF_REACT_BY_SCHEMA['ABOUT_PATH']``; a missing file yields ``null``.
+  Use it for *what the project is about* — not deploy/contribute instructions.
+
+All three feed the ``stamp``, so changing them invalidates an MCP client's
+cached copy; because the bundle is cached per process, a change also needs a
+process restart to be picked up.
+
 The endpoint sits behind the project's **existing auth** (the same permission
 source used by the generated viewsets — ``DRF_REACT_BY_SCHEMA['PERMISSIONS']``,
 defaulting to ``IsAuthenticated``; authentication comes from your DRF defaults,

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/array.py

@@ -4,7 +4,11 @@ from django.contrib.postgres.fields import ArrayField
 class ArrayField(ArrayField):
     description = "Extended PostgreSQL ArrayField"
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/boolean.py

@@ -4,7 +4,11 @@ from django.db import models
 class BooleanField(models.BooleanField):
     description = "Extended BooleanField"
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/date.py

@@ -5,9 +5,17 @@ class DateField(models.DateField):
     description = "Extended DateField"
 
     def __init__(
-        self, *args, views=None, ui_required=False, conditional_visible=None, **kwargs
+        self,
+        *args,
+        views=None,
+        ui_required=False,
+        conditional_visible=None,
+        description=None,
+        **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         if views:
             self.views = views
         self.ui_required = ui_required
@@ -17,7 +25,11 @@ class DateField(models.DateField):
 class DateTimeField(models.DateTimeField):
     description = "Extended DateTimeField"
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/file.py

@@ -12,9 +12,12 @@ class ImageField(models.ImageField):
         max_file_size=None,
         allowed_mime_types=None,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.max_file_size = max_file_size
         self.allowed_mime_types = allowed_mime_types
 
@@ -45,9 +48,12 @@ class FileField(models.FileField):
         allowed_mime_types=None,
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.max_file_size = max_file_size
         self.allowed_mime_types = allowed_mime_types
         self.ui_required = ui_required

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/geometry.py

@@ -25,9 +25,13 @@ SRID = 4326
 def _geometry_field(cls):
     """Build an extended GIS model field class adding ui_required support."""
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         kwargs.setdefault("srid", SRID)
         cls.__init__(self, *args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible
 

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/number.py

@@ -12,9 +12,12 @@ class DecimalField(models.DecimalField):
         suffix="",
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.is_currency = is_currency and prefix == "" and suffix == ""
         self.prefix = prefix
         self.suffix = suffix
@@ -31,9 +34,12 @@ class IntegerField(models.IntegerField):
         pattern_format=None,
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.pattern_format = pattern_format
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/relational.py

@@ -29,9 +29,12 @@ class ForeignKey(models.ForeignKey):
         verbose_name="",
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.related_editable = related_editable
         self.label = label  # deprecated! Remove in jan2024
         self.verbose_name = verbose_name
@@ -49,9 +52,12 @@ class ManyToManyField(models.ManyToManyField):
         label="",
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.related_editable = related_editable
         self.label = label  # deprecated! Remove in jan2024
         self.ui_required = ui_required
@@ -68,9 +74,12 @@ class OneToOneField(models.OneToOneField):
         label="",
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.related_editable = related_editable
         self.label = label  # deprecated! Remove in jan2024
         self.ui_required = ui_required

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/serializers.py

@@ -4,7 +4,16 @@ from rest_framework import serializers
 class TypedSerializerMethodField(serializers.SerializerMethodField):
     description = "Extended SerializerMethodField"
 
-    def __init__(self, *args, return_type="string", conditional_visible=None, **kwargs):
+    def __init__(
+        self,
+        *args,
+        return_type="string",
+        conditional_visible=None,
+        description=None,
+        **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.return_type = return_type
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/fields/text.py

@@ -15,9 +15,12 @@ class CharField(models.CharField):
         pattern_format=None,
         ui_required=False,
         conditional_visible=None,
+        description=None,
         **kwargs,
     ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.pattern_format = pattern_format
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible
@@ -41,8 +44,12 @@ class CharField(models.CharField):
 class TextField(models.TextField):
     description = "Extended TextField allowing ui required"
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible
 
@@ -50,7 +57,11 @@ class TextField(models.TextField):
 class EmailField(models.EmailField):
     description = "Extended EmailField allowing ui required"
 
-    def __init__(self, *args, ui_required=False, conditional_visible=None, **kwargs):
+    def __init__(
+        self, *args, ui_required=False, conditional_visible=None, description=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
+        if description is not None:
+            self.description = description
         self.ui_required = ui_required
         self.conditional_visible = conditional_visible

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/schema_bundle.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 
 import hashlib
 import importlib
+import inspect
 import json
 import os
 import traceback
@@ -80,6 +81,14 @@ GRID_FILTER_OPERATORS = (
 #: Number of hex characters kept from the bundle SHA-256.
 STAMP_LENGTH = 16
 
+#: Caps for free-form documentation folded into the MCP bundle (kept short so the
+#: schema an assistant receives stays lean). Longer values are truncated at a
+#: word boundary with an ellipsis. These docs are MCP-only: they are NOT written
+#: to the React artifacts (``write_react_artifacts``), which stay byte-identical.
+MODEL_DOCSTRING_MAX = 800
+FIELD_DESCRIPTION_MAX = 300
+ABOUT_MAX = 2000
+
 
 def configured_apps() -> list[str]:
     """Return the apps to introspect (``DRF_REACT_BY_SCHEMA["APPS"]``)."""
@@ -100,6 +109,10 @@ class SchemaArtifacts:
     * ``interfaces_by_model`` — the interface string keyed by model name.
     * ``permissions`` — the static (class-level) DRF permission classes per model.
     * ``index_exports`` — the ``index.ts`` export lines.
+    * ``model_docstrings`` — the model class's own docstring per model (trimmed),
+      for the MCP bundle only.
+    * ``field_descriptions`` — per model, the ``description=`` kwarg of each field
+      that carries one, for the MCP bundle only.
     """
 
     models: dict = field(default_factory=dict)
@@ -109,6 +122,8 @@ class SchemaArtifacts:
     interfaces_by_model: dict = field(default_factory=dict)
     permissions: dict = field(default_factory=dict)
     index_exports: list = field(default_factory=list)
+    model_docstrings: dict = field(default_factory=dict)
+    field_descriptions: dict = field(default_factory=dict)
 
 
 def _mock_request() -> Request:
@@ -207,6 +222,11 @@ def generate_artifacts(apps_to_sync: list[str] | None = None) -> SchemaArtifacts
                     artifacts.permissions[model_name] = _describe_permissions(
                         getattr(viewset, "permission_classes", None)
                     )
+                    model = getattr(view_instance, "model", None)
+                    artifacts.model_docstrings[model_name] = _class_docstring(model)
+                    artifacts.field_descriptions[model_name] = _field_descriptions(
+                        model, view_instance
+                    )
 
                     # B. Generate the TypeScript interface.
                     interface_code = artifacts.ts_gen.generate_interface(
@@ -244,14 +264,27 @@ def build_schema_bundle(
     models = {}
     for model_name in artifacts.model_order:
         payload = artifacts.models[model_name]
-        schema = payload["schema"]
-        if structural:
-            schema = _strip_data_defaults(schema)
+        schema = (
+            _strip_data_defaults(payload["schema"])
+            if structural
+            else dict(payload["schema"])
+        )
+        # Field ``description`` kwargs are documentation-only; fold them into the
+        # MCP bundle's copy of the schema (never the React artifact's).
+        for field_name, description in (
+            artifacts.field_descriptions.get(model_name) or {}
+        ).items():
+            entry = schema.get(field_name)
+            if isinstance(entry, dict):
+                entry = dict(entry)
+                entry.setdefault("description", description)
+                schema[field_name] = entry
         models[model_name] = {
             "schema": schema,
             "verbose_name": payload["verbose_name"],
             "verbose_name_plural": payload["verbose_name_plural"],
             "interface": artifacts.interfaces_by_model.get(model_name),
+            "docstring": artifacts.model_docstrings.get(model_name),
         }
 
     body = {
@@ -335,6 +368,7 @@ def _system_metadata(apps_to_sync, drf_settings, permissions) -> dict:
             "per_model": permissions,
         },
         "conventions": _conventions(drf_settings),
+        "about": _project_about(drf_settings),
     }
 
 
@@ -362,6 +396,77 @@ def _conventions(drf_settings) -> dict:
     }
 
 
+def _trim_text(text, limit: int) -> str | None:
+    """Collapse a docstring's indentation and truncate it at a word boundary."""
+    if not text:
+        return None
+    cleaned = inspect.cleandoc(str(text)).strip()
+    if not cleaned:
+        return None
+    if len(cleaned) <= limit:
+        return cleaned
+    clipped = cleaned[:limit].rstrip()
+    space = clipped.rfind(" ")
+    if space > limit // 2:
+        clipped = clipped[:space].rstrip()
+    return clipped + "…"
+
+
+def _class_docstring(model) -> str | None:
+    """The model class's own docstring (trimmed). Inherited docs are ignored."""
+    if model is None:
+        return None
+    return _trim_text(
+        getattr(model, "__dict__", {}).get("__doc__"), MODEL_DOCSTRING_MAX
+    )
+
+
+def _field_descriptions(model, view_instance) -> dict:
+    """Map each field carrying a ``description=`` kwarg to its trimmed text.
+
+    Only ``description`` values the author passed explicitly are reported; a
+    field's class-level ``Field.description`` (the Django field-type label) is
+    not, because the lookup reads the instance ``__dict__``. Model fields are
+    read first, then declared serializer fields (e.g.
+    ``TypedSerializerMethodField``) fill any name the model did not cover.
+    """
+    descriptions: dict = {}
+    if model is not None:
+        for field in model._meta.get_fields():
+            name = getattr(field, "name", None)
+            value = getattr(field, "__dict__", {}).get("description")
+            if name and value:
+                descriptions[name] = _trim_text(value, FIELD_DESCRIPTION_MAX)
+    try:
+        serializer = view_instance.get_serializer()
+    except Exception:
+        serializer = None
+    if serializer is not None:
+        for name, field in serializer.fields.items():
+            value = getattr(field, "__dict__", {}).get("description")
+            if name not in descriptions and value:
+                descriptions[name] = _trim_text(value, FIELD_DESCRIPTION_MAX)
+    return descriptions
+
+
+def _project_about(drf_settings) -> str | None:
+    """The project's ``ABOUT.md`` — ``BASE_DIR/ABOUT.md`` or ``ABOUT_PATH``.
+
+    Returns ``None`` when neither path resolves or the file is missing/empty.
+    """
+    path = drf_settings.get("ABOUT_PATH")
+    if not path:
+        base_dir = getattr(settings, "BASE_DIR", None)
+        if not base_dir:
+            return None
+        path = os.path.join(str(base_dir), "ABOUT.md")
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return _trim_text(handle.read(), ABOUT_MAX)
+    except OSError:
+        return None
+
+
 def _describe_permissions(permission_classes) -> list | None:
     """Render static permission classes as dotted paths (or ``None``)."""
     if not permission_classes:

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/tests.py

@@ -159,6 +159,17 @@ class SchemaBundleEndpointTest(TestCase):
         ):
             self.assertIn(key, response.data)
 
+    def test_viewset_style_permission_reading_action(self):
+        """A viewset permission branching on ``view.action`` must not crash."""
+        from rest_framework.permissions import BasePermission
+
+        class ActionAware(BasePermission):
+            def has_permission(self, request, view):
+                return view.action == "list"
+
+        with self.settings(DRF_REACT_BY_SCHEMA={"PERMISSIONS": [ActionAware]}):
+            self.assertEqual(self._get().status_code, 200)
+
     def test_if_none_match_returns_304(self):
         etag = self._get()["ETag"]
 
@@ -208,6 +219,112 @@ class SchemaBundleEndpointTest(TestCase):
             self.assertTrue(schema_endpoint_enabled())
 
 
+class SchemaDocumentationTest(TestCase):
+    """Model docstrings, field ``description`` and ``ABOUT.md`` in the bundle."""
+
+    def tearDown(self):
+        from drf_react_by_schema.views import reset_schema_bundle_cache
+
+        reset_schema_bundle_cache()
+
+    def test_trim_text_collapses_and_truncates(self):
+        from drf_react_by_schema.schema_bundle import _trim_text
+
+        self.assertIsNone(_trim_text(None, 10))
+        self.assertIsNone(_trim_text("   ", 10))
+        self.assertEqual(_trim_text("short", 10), "short")
+        self.assertEqual(_trim_text("Title.\n\n    body", 50), "Title.\n\nbody")
+        trimmed = _trim_text("palavra " * 50, 30)
+        self.assertLessEqual(len(trimmed), 31)
+        self.assertTrue(trimmed.endswith("…"))
+
+    def test_class_docstring_uses_own_docs_only(self):
+        from drf_react_by_schema.schema_bundle import _class_docstring
+
+        class Documented:
+            """Real docs."""
+
+        class Inheriting(Documented):
+            pass
+
+        class ExplicitlyEmpty(Documented):
+            __doc__ = None
+
+        self.assertEqual(_class_docstring(Documented), "Real docs.")
+        self.assertIsNone(_class_docstring(Inheriting))
+        self.assertIsNone(_class_docstring(ExplicitlyEmpty))
+        self.assertIsNone(_class_docstring(None))
+
+    def test_field_descriptions_reads_explicit_kwarg_only(self):
+        from types import SimpleNamespace
+
+        from drf_react_by_schema import fields
+        from drf_react_by_schema.schema_bundle import _field_descriptions
+
+        described = fields.CharField("N", max_length=10, description="Do campo")
+        described.set_attributes_from_name("nome")
+        # A plain package field must not surface its class-level ``description``.
+        plain = fields.CharField("X", max_length=3)
+        plain.set_attributes_from_name("sem_descricao")
+        model = SimpleNamespace(
+            _meta=SimpleNamespace(get_fields=lambda: [described, plain])
+        )
+        no_serializer = SimpleNamespace(
+            get_serializer=lambda: SimpleNamespace(fields={})
+        )
+        self.assertEqual(
+            _field_descriptions(model, no_serializer), {"nome": "Do campo"}
+        )
+
+        # A declared serializer field (not a model field) is picked up too.
+        method = fields.TypedSerializerMethodField(description="Calculado")
+        with_serializer = SimpleNamespace(
+            get_serializer=lambda: SimpleNamespace(fields={"extra": method})
+        )
+        self.assertEqual(
+            _field_descriptions(None, with_serializer), {"extra": "Calculado"}
+        )
+
+    def test_project_about_from_base_dir_and_path(self):
+        import os
+        import tempfile
+
+        from django.test import override_settings
+
+        from drf_react_by_schema.schema_bundle import _project_about
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with open(os.path.join(tmp, "ABOUT.md"), "w", encoding="utf-8") as handle:
+                handle.write("# Sobre\n\nProjeto de teste.")
+            with override_settings(BASE_DIR=tmp):
+                self.assertEqual(_project_about({}), "# Sobre\n\nProjeto de teste.")
+        self.assertIsNone(_project_about({"ABOUT_PATH": "/no/such/ABOUT.md"}))
+
+    def test_bundle_exposes_documentation(self):
+        import os
+        import tempfile
+
+        from django.test import override_settings
+
+        from drf_react_by_schema.views import (
+            get_schema_bundle,
+            reset_schema_bundle_cache,
+        )
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with open(os.path.join(tmp, "ABOUT.md"), "w", encoding="utf-8") as handle:
+                handle.write("# Meu projeto\n\nDescrição curta.")
+            with override_settings(BASE_DIR=tmp):
+                reset_schema_bundle_cache()
+                bundle = get_schema_bundle()
+
+        self.assertEqual(
+            bundle["system"]["about"], "# Meu projeto\n\nDescrição curta."
+        )
+        for payload in bundle["models"].values():
+            self.assertIn("docstring", payload)
+
+
 class PasswordResetFlowTest(TestCase):
     """End-to-end password reset (request -> confirm) and authenticated change."""
 

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema/views.py

@@ -65,6 +65,11 @@ def _etag_matches(if_none_match: str | None, etag: str) -> bool:
 class SchemaBundleView(APIView):
     """``GET /drbs/schema/`` — serve the cached bundle with ETag/304 handling."""
 
+    #: Project ``PERMISSIONS`` are written for the generated viewsets and may
+    #: branch on ``view.action``; this plain ``APIView`` exposes the read
+    #: action so such permission classes (e.g. CTA's) do not raise here.
+    action = "list"
+
     def get_permissions(self):
         # Re-read the setting per request so hosts can toggle PERMISSIONS in tests
         # (mirrors the permission source used by the generated viewsets).

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/drf_react_by_schema.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: drf-react-by-schema
-Version: 0.27.0
+Version: 0.27.2
 Summary: A Django app to easily integrate with React from models.
 Home-page: https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django
 Author: Cooperativa EITA
@@ -317,16 +317,42 @@ object with:
   version changes;
 * ``drbs_version`` — the installed ``drf-react-by-schema`` version;
 * ``system`` — apps, ``AUTH_USER_MODEL``, the ``DRF_REACT_BY_SCHEMA`` summary,
-  static permission hints (DRF defaults, global, per-model) and request
+  static permission hints (DRF defaults, global, per-model), request
   ``conventions`` (API base, pagination, ``ordering``/``search``/``sum_rows``
-  params, grid-filter operators);
+  params, grid-filter operators) and ``about`` (the project's ``ABOUT.md``,
+  trimmed — see below);
 * ``endpoints`` — every generated route (list and nested) with its
   ``path``/``kind``/``verbose_name``/``parent_model``/``related_model``;
 * ``models`` — each model's field ``schema`` (the same ``OPTIONS`` POST payload
-  the React app consumes), verbose names and generated TypeScript
-  ``interface``;
+  the React app consumes), verbose names, generated TypeScript ``interface`` and
+  the model class ``docstring`` (trimmed);
 * ``interfaces`` and ``enums`` — the generated TypeScript declarations.
 
+Documentation in the bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Free-form, non-UI documentation is folded into the bundle so an assistant can
+*understand* the system. It is kept out of the React artifacts on purpose:
+``sync_react``'s ``schemas/*.json`` stay **byte-identical** to before.
+
+* **Model docstrings** — a model class's *own* docstring (inherited docs are
+  ignored) is reported as ``models[<Model>].docstring``, trimmed at a word
+  boundary to ``schema_bundle.MODEL_DOCSTRING_MAX`` characters.
+* **Field descriptions** — pass ``description="..."`` to any package field
+  (``CharField``, ``ForeignKey``, ``DecimalField``, ...); it is reported as
+  ``models[<Model>].schema[<field>].description`` (trimmed to
+  ``FIELD_DESCRIPTION_MAX``). This is **not** ``help_text``: ``help_text`` is
+  rendered to end users by ``drf-react-by-schema-js``, while ``description``
+  documents the field for the API client / assistant. Only values passed
+  explicitly are reported — the field type's own ``description`` is never.
+* **Project ``ABOUT.md``** — a project-root ``ABOUT.md`` (``settings.BASE_DIR``)
+  is reported as ``system.about`` (trimmed to ``ABOUT_MAX``). Override the path
+  with ``DRF_REACT_BY_SCHEMA['ABOUT_PATH']``; a missing file yields ``null``.
+  Use it for *what the project is about* — not deploy/contribute instructions.
+
+All three feed the ``stamp``, so changing them invalidates an MCP client's
+cached copy; because the bundle is cached per process, a change also needs a
+process restart to be picked up.
+
 The endpoint sits behind the project's **existing auth** (the same permission
 source used by the generated viewsets — ``DRF_REACT_BY_SCHEMA['PERMISSIONS']``,
 defaulting to ``IsAuthenticated``; authentication comes from your DRF defaults,

{drf_react_by_schema-0.27.0 → drf_react_by_schema-0.27.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = drf_react_by_schema
-version = 0.27.0
+version = 0.27.2
 description = A Django app to easily integrate with React from models.
 long_description = file: README.rst
 url = https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django