udata 11.0.2.dev17__py3-none-any.whl → 11.0.2.dev19__py3-none-any.whl

udata/api_fields.py

@@ -1,39 +1,25 @@
-"""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
 
+The `@generate_fields` decorator parameters:
 - 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`.
+- nested_filters: filter on a field of a field (aka "join"), eg filter on `Reuse__organization__badge=PUBLIC_SERVICE`.
+- standalone_filters: filter on something else than a field. Should be a list of dicts with filterable attributes, as returned by `compute_filter`.
 
+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
@@ -332,9 +318,9 @@ def generate_fields(**kwargs) -> Callable:
         ref_fields: dict = {}
         sortables: list = kwargs.get("additional_sorts", [])
 
-        filterables: list[dict] = []
-        additional_filters: dict[str, dict] = get_fields_with_additional_filters(
-            kwargs.get("additional_filters", {})
+        filterables: list[dict] = kwargs.get("standalone_filters", [])
+        nested_filters: dict[str, dict] = get_fields_with_nested_filters(
+            kwargs.get("nested_filters", {})
         )
 
         read_fields["id"] = restx_fields.String(required=True, readonly=True)
@@ -356,16 +342,16 @@ def generate_fields(**kwargs) -> Callable:
             if filterable is not None:
                 filterables.append(compute_filter(key, field, info, filterable))
 
-            additional_filter: dict | None = additional_filters.get(key, None)
-            if additional_filter:
+            nested_filter: dict | None = nested_filters.get(key, None)
+            if nested_filter:
                 if not isinstance(
                     field, mongo_fields.ReferenceField | mongo_fields.LazyReferenceField
                 ):
-                    raise Exception("Cannot use additional_filters on a field that is not a ref.")
+                    raise Exception("Cannot use nested_filters on a field that is not a ref.")
 
                 ref_model: db.Document = field.document_type
 
-                for child in additional_filter.get("children", []):
+                for child in nested_filter.get("children", []):
                     inner_field: str = getattr(ref_model, child["key"])
 
                     column: str = f"{key}__{child['key']}"
@@ -401,7 +387,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":
@@ -489,7 +475,7 @@ def generate_fields(**kwargs) -> Callable:
 
         for filterable in filterables:
             parser.add_argument(
-                # Use the custom label from `additional_filters` if there's one.
+                # Use the custom label from `nested_filters` if there's one.
                 filterable.get("label", filterable["key"]),
                 type=filterable["type"],
                 location="args",
@@ -520,7 +506,7 @@ def generate_fields(**kwargs) -> Callable:
                 base_query = base_query.search_text(phrase_query)
 
             for filterable in filterables:
-                # If it's from an `additional_filter`, use the custom label instead of the key,
+                # If it's from an `nested_filter`, use the custom label instead of the key,
                 # eg use `organization_badge` instead of `organization.badges` which is
                 # computed to `organization_badges`.
                 filter = args.get(filterable.get("label", filterable["key"]))
@@ -558,22 +544,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:
@@ -738,21 +793,18 @@ def wrap_primary_key(
         )
 
 
-def get_fields_with_additional_filters(additional_filters: dict[str, str]) -> dict[str, Any]:
+def get_fields_with_nested_filters(nested_filters: dict[str, str]) -> dict[str, Any]:
     """Filter on additional related fields.
 
-    Right now we only support additional filters with a depth of two, eg "organization.badges".
-
-    The goal of this function is to key by the additional filters by the first part (`organization`) to
     be able to compute them when we loop over all the fields (`title`, `organization`…)
 
 
-    The `additional_filters` property is a dict: {"label": "key"}, for example {"organization_badge": "organization.badges"}.
+    The `nested_filters` property is a dict: {"label": "key"}, for example {"organization_badge": "organization.badges"}.
     The `label` will be the name of the parser arg, like `?organization_badge=public-service`, which makes more
     sense than `?organization_badges=public-service`.
     """
     results: dict = {}
-    for label, key in additional_filters.items():
+    for label, key in nested_filters.items():
         parts = key.split(".")
         if len(parts) == 2:
             parent = parts[0]
@@ -770,7 +822,7 @@ def get_fields_with_additional_filters(additional_filters: dict[str, str]) -> di
                 }
             )
         else:
-            raise Exception(f"Do not support `additional_filters` without two parts: {key}.")
+            raise Exception(f"Do not support `nested_filters` without two parts: {key}.")
 
     return results
 

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,
@@ -134,9 +134,29 @@ def check_only_one_condition_per_role(access_audiences, **_kwargs):
         )
 
 
+def filter_by_topic(base_query, filter_value):
+    from udata.core.topic.models import Topic
+
+    try:
+        topic = Topic.objects.get(id=filter_value)
+    except Topic.DoesNotExist:
+        pass
+    else:
+        return base_query.filter(
+            id__in=[
+                elt.element.id
+                for elt in topic.elements
+                if elt.element.__class__.__name__ == "Dataservice"
+            ]
+        )
+
+
 @generate_fields(
     searchable=True,
-    additional_filters={"organization_badge": "organization.badges"},
+    nested_filters={"organization_badge": "organization.badges"},
+    standalone_filters=[
+        {"key": "topic", "constraints": "objectid", "query": filter_by_topic, "type": str}
+    ],
     additional_sorts=[
         {"key": "followers", "value": "metrics.followers"},
         {"key": "views", "value": "metrics.views"},
@@ -284,7 +304,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 +312,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 +329,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/dataservices/tasks.py

@@ -1,6 +1,7 @@
 from celery.utils.log import get_task_logger
 
 from udata.core.dataservices.models import Dataservice
+from udata.core.topic.models import TopicElement
 from udata.harvest.models import HarvestJob
 from udata.models import Discussion, Follow, Transfer
 from udata.tasks import job
@@ -20,5 +21,7 @@ def purge_dataservices(self):
         HarvestJob.objects(items__dataservice=dataservice).update(set__items__S__dataservice=None)
         # Remove associated Transfers
         Transfer.objects(subject=dataservice).delete()
+        # Remove dataservices references in Topics
+        TopicElement.objects(element=dataservice).update(element=None)
         # Remove dataservice
         dataservice.delete()

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
@@ -60,7 +60,7 @@ class ReuseBadgeMixin(BadgeMixin):
         {"key": "followers", "value": "metrics.followers"},
         {"key": "views", "value": "metrics.views"},
     ],
-    additional_filters={"organization_badge": "organization.badges"},
+    nested_filters={"organization_badge": "organization.badges"},
     mask="*,datasets{id,title,uri,page}",
 )
 class Reuse(db.Datetimed, Auditable, WithMetrics, ReuseBadgeMixin, Linkable, Owned, db.Document):
@@ -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/core/topic/factories.py

@@ -1,6 +1,7 @@
 import factory
 
 from udata import utils
+from udata.core.dataservices.factories import DataserviceFactory
 from udata.core.dataset.factories import DatasetFactory
 from udata.core.reuse.factories import ReuseFactory
 from udata.factories import ModelFactory
@@ -38,6 +39,10 @@ class TopicElementReuseFactory(TopicElementFactory):
     element = factory.SubFactory(ReuseFactory)
 
 
+class TopicElementDataserviceFactory(TopicElementFactory):
+    element = factory.SubFactory(DataserviceFactory)
+
+
 class TopicFactory(ModelFactory):
     class Meta:
         model = Topic
@@ -58,9 +63,10 @@ class TopicWithElementsFactory(TopicFactory):
         # Create associated elements
         TopicElementDatasetFactory.create_batch(2, topic=self)
         TopicElementReuseFactory.create(topic=self)
+        TopicElementDataserviceFactory.create(topic=self)
 
     @classmethod
-    def elements_as_payload(cls, elements: list) -> dict:
+    def elements_as_payload(cls, elements: list) -> list[dict]:
         return [
             {
                 "element": {"id": str(elt.element.id), "class": elt.element.__class__.__name__},

udata/core/topic/models.py

@@ -4,10 +4,8 @@ from mongoengine.signals import post_delete, post_save
 
 from udata.api_fields import field
 from udata.core.activity.models import Auditable
-from udata.core.dataset.models import Dataset
 from udata.core.linkable import Linkable
 from udata.core.owned import Owned, OwnedQuerySet
-from udata.core.reuse.models import Reuse
 from udata.models import SpatialCoverage, db
 from udata.search import reindex
 from udata.tasks import as_task_param
@@ -20,7 +18,7 @@ class TopicElement(Auditable, db.Document):
     description = field(db.StringField(required=False))
     tags = field(db.ListField(db.StringField()))
     extras = field(db.ExtrasField())
-    element = field(db.GenericReferenceField(choices=[Dataset, Reuse]))
+    element = field(db.GenericReferenceField(choices=["Dataset", "Reuse", "Dataservice"]))
     # Made optional to allow proper form handling with commit=False
     topic = field(db.ReferenceField("Topic", required=False))