udata 11.0.2.dev16__py3-none-any.whl → 11.0.2.dev18__py3-none-any.whl

udata/api_fields.py

@@ -1,39 +1,24 @@
-"""Enhance a MongoEngine document class to give it super powers by decorating it with @generate_fields.
+"""API field generation and metadata management for MongoEngine documents.
 
-The main goal of `generate_fields` is to remove duplication: we used to have fields declaration in
-- models.py
-- forms.py
-- api_fields.py
+This module provides tools to automatically generate Flask-RESTX fields from MongoEngine
+documents, reducing duplication between model definitions and API serialization.
 
-Now they're defined in models.py, and adding the `generate_fields` decorator makes them available in the format we need them for the forms or the API.
+Main components:
+- `@generate_fields`: Decorator that adds API field generation to document classes
+- `field()`: Universal function to add metadata to fields and methods
 
-- default_filterable_field: which field in this document should be the default filter, eg when filtering by Badge, you're actually filtering on `Badge.kind`
-- searchable: boolean, if True, the document can be full-text searched using MongoEngine text search
-- additional_sorts: add more sorts than the already available ones based on fields (see below). Eg, sort by metrics.
-- additional_filters: filter on a field of a field (aka "join"), eg filter on `Reuse__organization__badge=PUBLIC_SERVICE`.
+The `@generate_fields` decorator parameters:
+- default_filterable_field: Default field for filtering (e.g., Badge.kind)
+- searchable: Enables full-text search with param `q` via MongoEngine on indexed text fields
+- additional_sorts: Custom sort options beyond field-based sorts
+- additional_filters: Cross-document filtering (e.g., Reuse__organization__badge)
 
+Generated attributes on decorated classes:
+- ref_fields: Minimal fields for embedded/referenced documents
+- read_fields: All fields returned when querying a document
+- write_fields: Fields accepted when creating/updating a document
 
-On top of those functionalities added to the document by the `@generate_fields` decorator parameters,
-the document fields are parsed and enhanced if they are wrapped in the `field` helper.
-
-- sortable: boolean, if True, it'll be available in the list of sort options
-- show_as_ref: add to the list of `ref_fields` (see below)
-- readonly: don't add this field to the `write_fields`
-- markdown: use Mardown to format this field instead of plain old text
-- filterable: this field can be filtered on. It's either an empty dictionnary, either {`key`: `field_name`} if the `field_name` to use is different from the original field, eg `dataset` instead of `datasets`.
-- description: use as the info on the field in the swagger forms.
-- check: provide a function to validate the content of the field.
-- thumbnail_info: add additional info for a thumbnail, eg `{ "size": BIGGEST_IMAGE_SIZE }`.
-
-You may also use the `@function_field` decorator to treat a document method as a field.
-
-
-The following fields are added on the document class once decorated:
-
-- ref_fields: list of fields to return when embedding/referencing a document, eg when querying Reuse.organization, only return a subset of the org fields
-- read_fields: all of the fields to return when querying a document
-- write_fields: list of fields to provide when creating a document, eg when creating a Reuse, we only provide organization IDs, not all the org fields
-
+For field-specific metadata, see the `field()` function documentation.
 """
 
 import functools
@@ -401,7 +386,7 @@ def generate_fields(**kwargs) -> Callable:
 
         # The goal of this loop is to fetch all functions (getters) of the class
         # If a function has an `__additional_field_info__` attribute it means
-        # it has been decorated with `@function_field()` and should be included
+        # it has been decorated with `@field()` and should be included
         # in the API response.
         for method_name in dir(cls):
             if method_name == "objects":
@@ -558,22 +543,91 @@ def generate_fields(**kwargs) -> Callable:
     return wrapper
 
 
-def function_field(**info) -> Callable:
-    def inner(func):
-        func.__additional_field_info__ = info
-        return func
-
-    return inner
-
+def field(
+    inner=None,
+    sortable: bool | str | None = None,
+    filterable: dict[str, Any] | None = None,
+    readonly: bool | None = None,
+    show_as_ref: bool | None = None,
+    markdown: bool | None = None,
+    description: str | None = None,
+    auditable: bool | None = None,
+    checks: list[Callable] | None = None,
+    attribute: str | None = None,
+    thumbnail_info: dict[str, Any] | None = None,
+    example: str | None = None,
+    nested_fields: dict[str, Any] | None = None,
+    inner_field_info: dict[str, Any] | None = None,
+    size: int | None = None,
+    is_thumbnail: bool | None = None,
+    href: Callable | None = None,
+    generic: bool | None = None,
+    generic_key: str | None = None,
+    convert_to: Callable | None = None,
+    allow_null: bool | None = None,
+    **kwargs: Any,  # Accept any additional parameters, forward to flask rest x constructor.
+):
+    """Universal field decorator/wrapper for API field metadata.
+
+    Can be used in two ways:
+
+    1. As a wrapper for MongoEngine fields:
+        title = field(db.StringField(required=True),
+                     sortable=True,
+                     description="The title of the item")
+
+    2. As a decorator for computed fields:
+        @field(description="Link to the API endpoint", show_as_ref=True)
+        def uri(self):
+            return f"/api/items/{self.id}"
+
+    Args:
+        inner: The MongoEngine field to wrap (or None when used as decorator)
+        sortable: If True, field can be sorted. If str, use as custom sort key
+        filterable: Filter configuration dict
+        readonly: If True, exclude from write_fields
+        show_as_ref: If True, include in ref_fields
+        markdown: If True, use Markdown formatter
+        description: Field description for Swagger
+        auditable: If False, exclude from audit trail
+        checks: List of validation functions
+        attribute: Custom attribute name for serialization
+        thumbnail_info: Thumbnail configuration dict
+        example: Example value for documentation
+        nested_fields: RestX model for nested objects
+        inner_field_info: Additional info for list inner fields
+        size: Image size for thumbnails
+        is_thumbnail: If True, this is a thumbnail field
+        href: Function to generate API link
+        generic: If True, handle generic embedded documents
+        generic_key: Key for generic type discrimination
+        convert_to: Custom converter for RestX
+        allow_null: If True, field can be null
+        **kwargs: Any additional parameters not explicitly defined
+
+    Returns:
+        When used as wrapper: The field with __additional_field_info__ attached.
+        When used as decorator: A decorator function.
+    """
+    # Build field_info from non-None parameters, excluding 'inner' and 'kwargs'
+    field_info = {
+        k: v for k, v in locals().items() if v is not None and k not in ("inner", "kwargs")
+    }
 
-def field(inner, **kwargs):
-    """Simple wrapper to make a document field visible for the API.
+    # Add any extra kwargs passed
+    field_info.update(kwargs)
 
-    We can pass additional arguments that will be forwarded to the RestX field constructor.
+    if inner is None:
+        # Used as a decorator for methods
+        def decorator(func):
+            func.__additional_field_info__ = field_info
+            return func
 
-    """
-    inner.__additional_field_info__ = kwargs
-    return inner
+        return decorator
+    else:
+        # Used as a field wrapper
+        inner.__additional_field_info__ = field_info
+        return inner
 
 
 def patch(obj, request) -> type:

udata/core/dataservices/models.py

@@ -7,7 +7,7 @@ from mongoengine.signals import post_save
 
 import udata.core.contact_point.api_fields as contact_api_fields
 from udata.api import api, fields
-from udata.api_fields import field, function_field, generate_fields
+from udata.api_fields import field, generate_fields
 from udata.core.activity.models import Auditable
 from udata.core.dataservices.constants import (
     DATASERVICE_ACCESS_AUDIENCE_CONDITIONS,
@@ -284,7 +284,7 @@ class Dataservice(Auditable, WithMetrics, Linkable, Owned, db.Document):
         auditable=False,
     )
 
-    @function_field(description="Link to the API endpoint for this dataservice")
+    @field(description="Link to the API endpoint for this dataservice")
     def self_api_url(self, **kwargs):
         return url_for(
             "api.dataservice",
@@ -292,7 +292,7 @@ class Dataservice(Auditable, WithMetrics, Linkable, Owned, db.Document):
             **self._self_api_url_kwargs(**kwargs),
         )
 
-    @function_field(description="Link to the udata web page for this dataservice", show_as_ref=True)
+    @field(description="Link to the udata web page for this dataservice", show_as_ref=True)
     def self_web_url(self, **kwargs):
         return cdata_url(f"/dataservices/{self._link_id(**kwargs)}/", **kwargs)
 
@@ -309,7 +309,7 @@ class Dataservice(Auditable, WithMetrics, Linkable, Owned, db.Document):
         return self.private or self.deleted_at or self.archived_at
 
     @property
-    @function_field(
+    @field(
         nested_fields=dataservice_permissions_fields,
     )
     def permissions(self):

udata/core/pages/models.py

@@ -1,5 +1,5 @@
 from udata.api import api, fields
-from udata.api_fields import field, function_field, generate_fields
+from udata.api_fields import field, generate_fields
 from udata.core.activity.models import Auditable
 from udata.core.dataservices.models import Dataservice
 from udata.core.dataset.api_fields import dataset_fields
@@ -91,7 +91,7 @@ class Page(Auditable, Owned, Datetimed, db.Document):
     )
 
     @property
-    @function_field(
+    @field(
         nested_fields=page_permissions_fields,
     )
     def permissions(self):

udata/core/reports/models.py

@@ -4,7 +4,7 @@ from bson import DBRef
 from flask import url_for
 from mongoengine import DO_NOTHING, NULLIFY, signals
 
-from udata.api_fields import field, function_field, generate_fields
+from udata.api_fields import field, generate_fields
 from udata.core.user.api_fields import user_ref_fields
 from udata.core.user.models import User
 from udata.mongo import db
@@ -46,7 +46,7 @@ class Report(db.Document):
         readonly=True,
     )
 
-    @function_field(description="Link to the API endpoint for this report")
+    @field(description="Link to the API endpoint for this report")
     def self_api_url(self):
         return url_for("api.report", report=self, _external=True)
 

udata/core/reuse/models.py

@@ -3,7 +3,7 @@ from flask import url_for
 from mongoengine.signals import post_save, pre_save
 from werkzeug.utils import cached_property
 
-from udata.api_fields import field, function_field, generate_fields
+from udata.api_fields import field, generate_fields
 from udata.core.activity.models import Auditable
 from udata.core.dataset.api_fields import dataset_fields
 from udata.core.linkable import Linkable
@@ -197,16 +197,16 @@ class Reuse(db.Datetimed, Auditable, WithMetrics, ReuseBadgeMixin, Linkable, Own
             "api.reuse", reuse=self._link_id(**kwargs), **self._self_api_url_kwargs(**kwargs)
         )
 
-    @function_field(description="Link to the API endpoint for this reuse", show_as_ref=True)
+    @field(description="Link to the API endpoint for this reuse", show_as_ref=True)
     def uri(self, *args, **kwargs):
         return self.self_api_url(*args, **kwargs)
 
-    @function_field(description="Link to the udata web page for this reuse", show_as_ref=True)
+    @field(description="Link to the udata web page for this reuse", show_as_ref=True)
     def page(self, *args, **kwargs):
         return self.self_web_url(*args, **kwargs)
 
     @property
-    @function_field(
+    @field(
         nested_fields=reuse_permissions_fields,
     )
     def permissions(self):

udata/mail.py

@@ -49,7 +49,7 @@ def send(subject, recipients, template_base, **kwargs):
 
     debug = current_app.config.get("DEBUG", False)
     send_mail = current_app.config.get("SEND_MAIL", not debug)
-    connection = send_mail and mail.connect or dummyconnection
+    connection = mail.connect if send_mail else dummyconnection
     extras = get_mail_campaign_dict()
 
     with connection() as conn: