marshmallow-utils 0.15.1__py3-none-any.whl

marshmallow_utils/__init__.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2020-2025 CERN.
+# SPDX-FileCopyrightText: 2024-2026 Graz University of Technology.
+# SPDX-FileCopyrightText: 2025 KTH Royal Institute of Technology.
+# SPDX-FileCopyrightText: 2026 TU Wien.
+# SPDX-License-Identifier: MIT
+
+r"""Extras and utilities for Marshmallow.
+
+Currently, this library contains a couple of extra fields that helps with
+sanitizing data as shown in the following example:
+
+>>> from marshmallow_utils import fields
+>>> from marshmallow import Schema
+>>> class MySchema(Schema):
+...     trim = fields.TrimmedString()
+...     html = fields.SanitizedHTML()
+...     text = fields.SanitizedUnicode()
+...     isodate = fields.ISODateString()
+...
+>>> data = MySchema().load({
+...    'trim': '    whitespace   ',
+...    'html': '<script>evil()</script>',
+...    'text': 'PDF copy/paste\u200b\u000b\u001b\u0018 ',
+...    'isodate': '1999-10-27',
+... })
+>>> data['trim']
+'whitespace'
+>>> data['html']
+'evil()'
+>>> data['text']
+'PDF copy/paste'
+>>> data['isodate']
+'1999-10-27'
+
+Fields:
+
+- :py:class:`~fields.SanitizedUnicode`: Integrates the
+  `ftfy <https://pypi.org/project/ftfy/>`_ for fixing broken unicode text.
+- :py:class:`~fields.SanitizedHTML`: Integrates the
+  `bleach <https://pypi.org/project/bleach/>`_ for HTML sanitization.
+- :py:class:`~fields.ISODateString`: Integrates the
+  `arrow <https://pypi.org/project/arrow/>`_ for date parsing.
+"""
+
+__version__ = "0.15.1"
+
+__all__ = ("__version__",)

marshmallow_utils/context.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+
+"""Context."""
+
+from contextvars import ContextVar
+
+context_schema: ContextVar[dict] = ContextVar("context_schema")

marshmallow_utils/fields/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2016-2020 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Marshmallow fields."""
+
+from .babel import (
+    BabelGettextDictField,
+    FormatDate,
+    FormatDatetime,
+    FormatEDTF,
+    FormatTime,
+)
+from .contrib import Function, Method
+from .edtfdatestring import EDTFDateString, EDTFDateTimeString, EDTFLevel2DateString
+from .generated import GenFunction, GenMethod
+from .identifier import IdentifierSet, IdentifierValueSet
+from .isodate import ISODateString
+from .isolanguage import ISOLangString
+from .links import Link, Links
+from .nestedattr import NestedAttribute
+from .sanitizedhtml import ALLOWED_HTML_ATTRS, ALLOWED_HTML_TAGS, SanitizedHTML
+from .sanitizedunicode import SanitizedUnicode
+from .strippedhtml import StrippedHTML
+from .trimmed import TrimmedString
+from .tzdatetime import TZDateTime
+from .url import URL
+
+__all__ = (
+    "ALLOWED_HTML_ATTRS",
+    "ALLOWED_HTML_TAGS",
+    "BabelGettextDictField",
+    "EDTFDateString",
+    "EDTFDateTimeString",
+    "EDTFLevel2DateString",
+    "FormatDate",
+    "FormatDatetime",
+    "FormatEDTF",
+    "FormatTime",
+    "Function",
+    "GenFunction",
+    "GenMethod",
+    "IdentifierSet",
+    "IdentifierValueSet",
+    "ISODateString",
+    "ISOLangString",
+    "Link",
+    "Links",
+    "Method",
+    "NestedAttribute",
+    "SanitizedHTML",
+    "SanitizedUnicode",
+    "StrippedHTML",
+    "TrimmedString",
+    "TZDateTime",
+    "URL",
+)

marshmallow_utils/fields/babel.py

@@ -0,0 +1,214 @@
+# SPDX-FileCopyrightText: 2016-2024 CERN.
+# SPDX-FileCopyrightText: 2024-2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+
+"""Localized Extended Date(/Time) Format Level 0 date string field."""
+
+import arrow
+from babel import Locale
+from babel.core import negotiate_locale
+from babel.dates import LC_TIME, format_date, format_datetime, format_time
+from babel_edtf import format_edtf
+from marshmallow import fields
+
+
+class BabelFormatField(fields.String):
+    """Base classe for babel date and time formatting fields.
+
+    The babel format field is used only for dumping.
+    """
+
+    def __init__(self, format="medium", locale=LC_TIME, parse=True, **kwargs):
+        """Constructor.
+
+        :param format: The format to use (either ``short``, ``medium``,
+                       ``long`` or ``full``).
+        :param locale: The current locale or a callable returning the current
+                       locale.
+        """
+        self._format = format
+        self._locale = locale
+        self._parse = parse
+        kwargs.setdefault("dump_only", True)
+        super().__init__(**kwargs)
+
+    @property
+    def locale(self):
+        """Get the locale to use."""
+        return self._locale() if callable(self._locale) else self._locale
+
+    def parse(self, value, as_time=False, as_date=False, as_datetime=False):
+        """Parse the value if it's a string."""
+        if not self._parse or not isinstance(value, str):
+            return value
+
+        a = arrow.get(value)
+        if as_time:
+            return a.datetime
+        elif as_date:
+            return a.date()
+        elif as_datetime:
+            return a.datetime
+        else:
+            return a
+
+    def format_value(self, value):
+        """Format a given value using the chosen format function."""
+        raise NotImplementedError()
+
+    def _serialize(self, value, attr, data, **kwargs):
+        """Serialize the value."""
+        return super()._serialize(self.format_value(value), attr, data, **kwargs)
+
+
+class FormatDate(BabelFormatField):
+    """Format a date object."""
+
+    def format_value(self, value):
+        """Format an EDTF date."""
+        return format_date(
+            self.parse(value, as_date=True), format=self._format, locale=self.locale
+        )
+
+
+class FormatDatetime(BabelFormatField):
+    """Format a datetime object."""
+
+    def __init__(self, tzinfo=None, **kwargs):
+        """Constructor."""
+        self._tzinfo = tzinfo
+        super().__init__(**kwargs)
+
+    @property
+    def tzinfo(self):
+        """Get the timzone to use."""
+        return self._tzinfo() if callable(self._tzinfo) else self._tzinfo
+
+    def format_value(self, value):
+        """Format an EDTF date."""
+        return format_datetime(
+            self.parse(value, as_datetime=True),
+            format=self._format,
+            tzinfo=self.tzinfo,
+            locale=self.locale,
+        )
+
+
+class FormatTime(FormatDatetime):
+    """Format a time object."""
+
+    def format_value(self, value):
+        """Format an EDTF date."""
+        return format_time(
+            self.parse(value, as_time=True),
+            format=self._format,
+            tzinfo=self.tzinfo,
+            locale=self.locale,
+        )
+
+
+class FormatEDTF(BabelFormatField):
+    """Format an EDTF-formatted string."""
+
+    def format_value(self, value):
+        """Format an EDTF date."""
+        return format_edtf(value, format=self._format, locale=self.locale)
+
+
+class BabelGettextDictField(fields.String):
+    """Translation string field (dump only).
+
+    This field dumps a translation string as output, by looking up the
+    translation in the dictionary provided as input (the message catalog).
+
+    The lookup is performed via babel's locale negotiation (e.g. en_US will
+    also match en).
+
+    Basically the fields takes a data object like this::
+
+        {'title': {'en': 'Text', 'da': 'Tekst'}}
+
+    and dumps this (in case the locale is english)::
+
+        {'title': 'Text'}
+    """
+
+    default_error_messages = {
+        "invalid": "Not a valid dictionary.",
+        "missing_locale": "Translation not found for ",
+    }
+
+    def __init__(self, locale, default_locale, **kwargs):
+        """Initialize the field.
+
+        :param locale: The locale to lookup, or a function returning the
+            locale.
+        :param default_locale: The default locale in case the locale is not
+            found. Can be a callable that returns the default locale.
+        """
+        self._locale = locale
+        self._default_locale = default_locale
+        kwargs["dump_only"] = True
+        super().__init__(**kwargs)
+
+    @property
+    def locale(self):
+        """Get the locale to be used."""
+        return self._locale() if callable(self._locale) else self._locale
+
+    @property
+    def default_locale(self):
+        """Get the default locale to be used."""
+        return (
+            self._default_locale()
+            if callable(self._default_locale)
+            else self._default_locale
+        )
+
+    def _serialize(self, value, attr, obj, **kwargs):
+        """Serialize the dict into a string.
+
+        The dict is a message catalog with the keys being locale identifiers
+        and the values being the translated string.
+        """
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise self.make_error("invalid")
+        translated_str = gettext_from_dict(value, self.locale, self.default_locale)
+        if translated_str is None:
+            raise self.make_error("missing_locale")
+        return super()._serialize(translated_str, attr, obj, **kwargs)
+
+
+def gettext_from_dict(catalog, locale, default_locale):
+    """Get translation string from a dictionary."""
+    # First try with negotiate_locale. Negotiate locale will not properly
+    # negotiate e.g "en" when the available locales are "en_GB" and "da", even
+    # though "en_GB" could be used.
+    selected = negotiate_locale([str(locale)], catalog.keys())
+    if selected and selected in catalog:
+        return catalog[selected]
+
+    # In situations where negotiate locale doesn't work, we check if the
+    # language itself might be found.
+
+    # Extract language keys only.
+    catalog_langs = {Locale.parse(l).language: l for l in catalog}
+    if isinstance(locale, str):
+        locale = Locale.parse(locale)
+    if locale is not None and locale.language in catalog_langs:
+        # If primary language match, use that
+        catalog_key = catalog_langs[locale.language]
+        if catalog_key in catalog:
+            return catalog[catalog_key]
+    # If not, use default locale (must be defined it is defined)
+    # "en" is set as fallback language.
+    out = catalog.get(str(default_locale)) or catalog.get("en")
+    if out:
+        return out
+
+    # if all other things didn't worked, we are here, the real and only last
+    # option, use the first element in the dictionary. this one here is only
+    # used to not break frontend
+    return list(catalog.values())[0]

marshmallow_utils/fields/contrib.py

@@ -0,0 +1,126 @@
+# SPDX-FileCopyrightText: 2018-2019 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Contributed Marshmallow fields."""
+
+import functools
+from inspect import getfullargspec, isfunction, ismethod
+
+from marshmallow import fields, utils
+
+
+def _get_func_args(func):
+    """Get a list of the arguments a function or method has."""
+    if isinstance(func, functools.partial):
+        return _get_func_args(func.func)
+    if isfunction(func) or ismethod(func):
+        return list(getfullargspec(func).args)
+    if callable(func):
+        return list(getfullargspec(func.__call__).args)
+
+
+class Function(fields.Function):
+    """Enhanced marshmallow Function field.
+
+    The main difference between the original marshmallow.fields.Function is for
+    the ``deserialize`` function, which can now also point to a three-argument
+    function, with the third argument being the original data that was passed
+    to ``Schema.load``. The following example better demonstrates how this
+    works:
+
+    .. code-block:: python
+
+        def serialize_foo(obj, context):
+            return {'serialize_args': {'obj': obj, 'context': context}}
+
+        def deserialize_foo(value, context, data):
+            return {'deserialize_args': {
+                'value': value, 'context': context, 'data': data}}
+
+        class FooSchema(marshmallow.Schema):
+
+            foo = Function(serialize_foo, deserialize_foo)
+
+        FooSchema().dump({'foo': 42})
+        {'foo': {
+            'serialize_args': {
+                'obj': {'foo': 42},
+                'context': {}  # no context was passed
+            }
+        }}
+
+        FooSchema().load({'foo': 42}).data
+        {'foo': {
+            'deserialize_args': {
+                'value': 42,
+                'context': {},  # no context was passed
+                'data': {'foo': 42},
+            }
+        }}
+    """
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        if self.deserialize_func:
+            return self._call_or_raise(self.deserialize_func, value, attr, data)
+        return value
+
+    def _call_or_raise(self, func, value, attr, data=None):
+        func_args_len = len(_get_func_args(func))
+        if func_args_len > 2:
+            return func(value, self.parent.context, data)
+        elif func_args_len > 1:
+            return func(value, self.parent.context)
+        else:
+            return func(value)
+
+
+class Method(fields.Method):
+    """Enhanced marshmallow Method field.
+
+    The main difference between the original marshmallow.fields.Method is for
+    the ``deserialize`` method, which can now also point to a two-argument
+    method, with the second argument being the original data that was passed to
+    ``Schema.load``. The following example better demonstrates how this works:
+
+    .. code-block:: python
+
+        class BarSchema(marshmallow.Schema):
+
+            bar = Method('serialize_bar', 'deserialize_bar')
+
+            # Exactly the same behavior as in ``marshmallow.fields.Method``
+            def serialize_bar(self, obj):
+                return {'serialize_args': {'obj': obj}}
+
+            def deserialize_bar(self, value, data):
+                return {'deserialize_args': {'value': value, 'data': data}}
+
+        BarSchema().dump({'bar': 42})
+        {'bar': {
+            'serialize_args': {
+                'obj': {'bar': 42}
+            }
+        }}
+
+        BarSchema().load({'bar': 42})
+        {'bar': {
+            'deserialize_args': {
+                'data': {'bar': 42},
+                'value': 42
+            }
+        }}
+    """
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        if self.deserialize_method_name:
+            try:
+                method = utils.callable_or_raise(
+                    getattr(self.parent, self.deserialize_method_name, None)
+                )
+                method_args_len = len(_get_func_args(method))
+                if method_args_len > 2:
+                    return method(value, data)
+                return method(value)
+            except AttributeError:
+                pass
+        return value

marshmallow_utils/fields/edtfdatestring.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: 2016-2020 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Extended Date(/Time) Format Level 0 date string field."""
+
+from babel_edtf import parse_edtf
+from edtf import (
+    Date,
+    DateAndTime,
+    Interval,
+    Level1Interval,
+    Level2Interval,
+    OneOfASet,
+    UncertainOrApproximate,
+)
+from edtf.parser.grammar import ParseException
+from marshmallow import ValidationError, fields
+from marshmallow.validate import Validator
+
+
+class EDTFValidator(Validator):
+    """EDTF validator."""
+
+    default_message = "Please provide a valid date or interval."
+
+    def __init__(
+        self,
+        types=[Date, DateAndTime, Interval],
+        chronological_interval=True,
+        error=None,
+    ):
+        """Constructor.
+
+        :params types: List of EDTFObject subclasses that you accept. Use
+            EDTFObject to accept all levels.
+        """
+        self._types = types or []
+        self._chronological_interval = chronological_interval
+        self._error = error or self.default_message
+
+    def _format_error(self, value, e):
+        return self._error.format(input=value, edtf=e)
+
+    def __call__(self, value):
+        """Validate."""
+        try:
+            e = parse_edtf(value)
+        except ParseException:
+            raise ValidationError(self._format_error(value, None))
+
+        if self._types:
+            if not any([isinstance(e, t) for t in self._types]):
+                raise ValidationError(self._format_error(value, e))
+
+        if self._chronological_interval:
+            # We require intervals to be chronological. EDTF Date and Interval
+            # both have same interface and
+            # date.lower_strict() <= date.upper_strict() is always True for a
+            # Date
+            if e.upper_strict() < e.lower_strict():
+                raise ValidationError(self._format_error(value, e))
+
+        return value
+
+
+class EDTFDateString(fields.Str):
+    """
+    Extended Date Format Level 0 date string field.
+
+    A string field which is using the EDTF Validator.
+    """
+
+    def __init__(self, **kwargs):
+        """Constructor."""
+        kwargs.setdefault("validate", EDTFValidator(types=[Date, Interval]))
+        super().__init__(**kwargs)
+
+
+class EDTFDateTimeString(fields.Str):
+    """
+    Extended Date(/Time) Format Level 0 date string field.
+
+    A string field which is using the EDTF Validator.
+    """
+
+    def __init__(self, **kwargs):
+        """Constructor."""
+        kwargs.setdefault("validate", EDTFValidator())
+        super().__init__(**kwargs)
+
+
+class EDTFLevel2DateString(fields.Str):
+    """
+    Extended Date Format Level 2 date string field.
+
+    A string field which is using the EDTF Validator.
+    """
+
+    def __init__(self, **kwargs):
+        """Constructor."""
+        kwargs.setdefault(
+            "validate",
+            EDTFValidator(
+                types=[
+                    Date,
+                    Interval,
+                    Level1Interval,
+                    UncertainOrApproximate,
+                    OneOfASet,
+                    Level2Interval,
+                ]
+            ),
+        )
+        super().__init__(**kwargs)

marshmallow_utils/fields/generated.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2016-2020 CERN.
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+
+"""Generated field."""
+
+from .contrib import Function, Method
+
+
+class GeneratedValue(object):
+    """Sentinel value class forcing marshmallow missing field generation."""
+
+    pass
+
+
+class ForcedFieldDeserializeMixin(object):
+    """Mixin that forces deserialization of marshmallow fields."""
+
+    # Overriding default deserializer since we need to deserialize an
+    # initially non-existent field. In this implementation the checks are
+    # removed since we expect our deserializer to provide the value.
+    def deserialize(self, *args, **kwargs):
+        """Deserialize field."""
+        # Proceed with _deserialization, skipping all checks.
+        output = self._deserialize(*args, **kwargs)
+        self._validate(output)
+        return output
+
+
+class GenFunction(ForcedFieldDeserializeMixin, Function):
+    """Function field which is always deserialized."""
+
+    pass
+
+
+class GenMethod(ForcedFieldDeserializeMixin, Method):
+    """Method field which is always deserialized."""
+
+    pass

marshmallow_utils/fields/identifier.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2021-2022 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Identifier field."""
+
+from marshmallow.fields import List
+
+
+class IdentifierSet(List):
+    """Identifier list with deduplication.
+
+    It assumes the items of the list contain a *scheme* property.
+    """
+
+    default_error_messages = {
+        "multiple_values": "Only one identifier per scheme is allowed.",
+    }
+
+    def _validate(self, value):
+        """Validates the list of identifiers."""
+        schemes = [identifier["scheme"] for identifier in value]
+        if len(value) != len(set(schemes)):
+            raise self.make_error(key="multiple_values")
+
+
+class IdentifierValueSet(List):
+    """Identifier list with deduplication.
+
+    It assumes the items of the list contain a *scheme* property.
+    """
+
+    default_error_messages = {
+        "multiple_values": "Duplicated identifier entry is not allowed.",
+    }
+
+    def _validate(self, value):
+        """Validates the list of identifiers."""
+        identifiers = [
+            (identifier["scheme"], identifier["identifier"]) for identifier in value
+        ]
+        if len(value) != len(set(identifiers)):
+            raise self.make_error(key="multiple_values")

marshmallow_utils/fields/isodate.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2016-2021 CERN.
+# SPDX-FileCopyrightText: 2021 Northwestern University.
+# SPDX-License-Identifier: MIT
+
+"""Date string field."""
+
+import arrow
+from arrow.parser import ParserError
+from marshmallow import fields, missing
+
+
+class ISODateString(fields.Date):
+    """ISO8601-formatted date string.
+
+    ISODateString serializes to a date string and if it can't, the field is
+    ignored (missing).
+
+    NOTE: It serializes None to None.
+    """
+
+    def _serialize(self, value, attr, obj, **kwargs):
+        """Serialize an ISO8601-formatted date."""
+        # WHY: arrow.get(None) returns a date but we don't want it to
+        if value is None:
+            return missing
+
+        try:
+            return super()._serialize(arrow.get(value).date(), attr, obj, **kwargs)
+        except ParserError:
+            return missing
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        """Deserialize an ISO8601-formatted date."""
+        return super()._deserialize(value, attr, data, **kwargs).isoformat()