marshmallow 3.25.1__tar.gz → 3.26.1__tar.gz

{marshmallow-3.25.1 → marshmallow-3.26.1}/CHANGELOG.rst

@@ -1,6 +1,50 @@
 Changelog
 ---------
 
+3.26.1 (2025-02-03)
+*******************
+
+Bug fixes:
+
+- Typing: Fix type annotations for `class Meta <marshmallow.Schema.Meta>` options (:issue:`2804`).
+  Thanks :user:`lawrence-law` for reporting.
+
+Other changes:
+
+- Remove default value for the ``data`` param of `Nested._deserialize <marshmallow.fields.Nested._deserialize>` (:issue:`2802`).
+  Thanks :user:`gbenson` for reporting.
+
+
+3.26.0 (2025-01-22)
+*******************
+
+Features:
+
+- Typing: Add type annotations and improved documentation for `class Meta <marshmallow.Schema.Meta>` options (:pr:`2760`).
+- Typing: Improve type coverage of `marshmallow.Schema.SchemaMeta` (:pr:`2761`).
+- Typing: `marshmallow.Schema.loads` parameter allows `bytes` and `bytesarray` (:pr:`2769`).
+
+Bug fixes:
+
+- Respect ``data_key`` when schema validators raise a `ValidationError <marshmallow.exceptions.ValidationError>` 
+  with a ``field_name`` argument (:issue:`2170`). Thanks :user:`matejsp` for reporting.
+- Correctly handle multiple `@post_load <marshmallow.post_load>` methods where one method appends to
+  the data and another passes ``pass_original=True`` (:issue:`1755`).
+  Thanks :user:`ghostwheel42` for reporting.
+- ``URL`` fields now properly validate ``file`` paths (:issue:`2249`).
+  Thanks :user:`0xDEC0DE` for reporting and fixing.
+
+Documentation:
+
+- Add :doc:`upgrading guides <upgrading>` for 3.24 and 3.26 (:pr:`2780`).
+- Various documentation improvements (:pr:`2757`, :pr:`2759`, :pr:`2765`, :pr:`2774`, :pr:`2778`, :pr:`2783`, :pr:`2796`).
+
+Deprecations:
+
+- The ``ordered`` `class Meta <marshmallow.Schema.Meta>` option is deprecated (:issue:`2146`, :pr:`2762`).
+  Field order is already preserved by default. Set `marshmallow.Schema.dict_class` to `collections.OrderedDict`
+  to maintain the previous behavior.
+
 3.25.1 (2025-01-11)
 *******************
 

{marshmallow-3.25.1 → marshmallow-3.26.1}/CONTRIBUTING.rst

@@ -135,13 +135,13 @@ Documentation
 
 Contributions to the documentation are welcome. Documentation is written in `reStructuredText`_ (rST). A quick rST reference can be found `here <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_. Builds are powered by Sphinx_.
 
-To build the docs in "watch" mode:
+To build and serve the docs in "watch" mode:
 
 .. code-block:: shell-session
 
-   $ tox -e watch-docs
+   $ tox -e docs-serve
 
-Changes in the `docs/` directory will automatically trigger a rebuild.
+Changes to documentation will automatically trigger a rebuild.
 
 
 .. _contributing_examples:

{marshmallow-3.25.1 → marshmallow-3.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: marshmallow
-Version: 3.25.1
+Version: 3.26.1
 Summary: A lightweight library for converting complex datatypes to and from native Python datatypes.
 Author-email: Steven Loria <sloria1@gmail.com>
 Maintainer-email: Steven Loria <sloria1@gmail.com>, Jérôme Lafréchoux <jerome@jolimont.fr>, Jared Deckard <jared@shademaps.com>

{marshmallow-3.25.1 → marshmallow-3.26.1}/docs/_static/custom.css

@@ -10,12 +10,6 @@ h2, h3, h4, h5, h6 {
   font-family: -apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif;
 }
 
-/* Links */
-
-a:link, a:visited {
-  color: var(--color-link);
-}
-
 /* Hide ToC caption text within the main body (but leave them in the side-bar). */
 /* https://github.com/hynek/structlog/blob/b488a8bf589a01aabc41e3bf8df81a9848cd426c/docs/_static/custom.css#L17-L20 */
 #furo-main-content span.caption-text {

{marshmallow-3.25.1 → marshmallow-3.26.1}/docs/conf.py

@@ -22,7 +22,7 @@ source_suffix = ".rst"
 master_doc = "index"
 
 project = "marshmallow"
-copyright = "Steven Loria and contributors"
+copyright = "Steven Loria and contributors"  # noqa: A001
 
 version = release = importlib.metadata.version("marshmallow")
 
@@ -46,14 +46,25 @@ html_theme_options = {
     },
     "top_of_page_buttons": ["view"],
 }
+pygments_dark_style = "lightbulb"
 html_favicon = "_static/favicon.ico"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_show_sourcelink = False
+html_copy_source = False  # Don't copy source files to _build/sources
+html_show_sourcelink = False  # Don't link to source files
 ogp_image = "_static/marshmallow-logo-200.png"
 
 # Strip the dollar prompt when copying code
 # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells
 copybutton_prompt_text = "$ "
 
-autodoc_typehints = "both"
+autodoc_default_options = {
+    "exclude-members": "__new__",
+    # Don't show signatures in the summary tables
+    "autosummary-nosignatures": True,
+    # Don't render summaries for classes within modules
+    "autosummary-no-nesting": True,
+}
+# Only display type hints next to params but not within the signature
+# to avoid the signature from getting too long
+autodoc_typehints = "description"

{marshmallow-3.25.1 → marshmallow-3.26.1}/docs/custom_fields.rst

@@ -169,5 +169,5 @@ Error messages can also be passed to a `Field's` constructor.
 Next steps
 ----------
 
-- Need to add schema-level validation, post-processing, or error handling behavior? See the :doc:`extending` page.
-- For example applications using marshmallow, check out the :doc:`examples` page.
+- Need to add schema-level validation, post-processing, or error handling behavior? See the :doc:`extending/index` page.
+- For example applications using marshmallow, check out the :doc:`examples/index` page.

marshmallow-3.26.1/docs/examples/index.rst

@@ -0,0 +1,16 @@
+********
+Examples
+********
+
+The below examples demonstrate how to use marshmallow in various contexts.
+To run each example, you will need to have `uv <https://docs.astral.sh/uv/getting-started/installation/>`_ installed.
+The examples use `PEP 723 inline metadata <https://peps.python.org/pep-0723/>`_
+to declare the dependencies of each script. ``uv`` will install the
+dependencies automatically when running these scripts.
+
+.. toctree::
+  :maxdepth: 1
+
+  validating_package_json
+  quotes_api
+  inflection

marshmallow-3.26.1/docs/examples/inflection.rst

@@ -0,0 +1,19 @@
+*****************************
+Inflection (camel-cased keys)
+*****************************
+
+HTTP APIs will often use camel-cased keys for their input and output representations. This example shows how you can use the
+`Schema.on_bind_field <marshmallow.Schema.on_bind_field>` hook to automatically inflect keys.
+
+.. literalinclude:: ../../examples/inflection_example.py
+    :language: python
+
+To run the example:
+
+.. code-block:: shell-session
+
+    $ uv run examples/inflection_example.py
+    Loaded data:
+    {'first_name': 'David', 'last_name': 'Bowie'}
+    Dumped data:
+    {'firstName': 'David', 'lastName': 'Bowie'}

marshmallow-3.26.1/docs/examples/quotes_api.rst

@@ -0,0 +1,96 @@
+*******************************
+Quotes API (Flask + SQLAlchemy)
+*******************************
+
+Below is a full example of a REST API for a quotes app using `Flask <http://flask.pocoo.org/>`_  and `SQLAlchemy <https://www.sqlalchemy.org/>`_  with marshmallow. It demonstrates a number of features, including:
+
+- Custom validation
+- Nesting fields
+- Using ``dump_only=True`` to specify read-only fields
+- Output filtering using the ``only`` parameter
+- Using `@pre_load <marshmallow.decorators.pre_load>` to preprocess input data.
+
+.. literalinclude:: ../../examples/flask_example.py
+    :language: python
+
+
+**Using The API**
+
+Run the app.
+
+.. code-block:: shell-session
+
+    $ uv run examples/flask_example.py
+
+We'll use the `httpie cli <https://httpie.io/cli>`_ to send requests
+Install it with ``uv``.
+
+.. code-block:: shell-session
+
+    $ uv tool install httpie
+
+First we'll POST some quotes.
+
+.. code-block:: shell-session
+
+    $ http POST :5000/quotes/ author="Tim Peters" content="Beautiful is better than ugly."
+    $ http POST :5000/quotes/ author="Tim Peters" content="Now is better than never."
+    $ http POST :5000/quotes/ author="Peter Hintjens" content="Simplicity is always better than functionality."
+
+
+If we provide invalid input data, we get 400 error response. Let's omit "author" from the input data.
+
+.. code-block:: shell-session
+
+    $ http POST :5000/quotes/ content="I have no author"
+    {
+        "author": [
+            "Data not provided."
+        ]
+    }
+
+Now we can GET a list of all the quotes.
+
+.. code-block:: shell-session
+
+    $ http :5000/quotes/
+    {
+        "quotes": [
+            {
+                "content": "Beautiful is better than ugly.",
+                "id": 1
+            },
+            {
+                "content": "Now is better than never.",
+                "id": 2
+            },
+            {
+                "content": "Simplicity is always better than functionality.",
+                "id": 3
+            }
+        ]
+    }
+
+We can also GET the quotes for a single author.
+
+.. code-block:: shell-session
+
+    $ http :5000/authors/1
+    {
+        "author": {
+            "first": "Tim",
+            "formatted_name": "Peters, Tim",
+            "id": 1,
+            "last": "Peters"
+        },
+        "quotes": [
+            {
+                "content": "Beautiful is better than ugly.",
+                "id": 1
+            },
+            {
+                "content": "Now is better than never.",
+                "id": 2
+            }
+        ]
+    }

marshmallow-3.26.1/docs/examples/validating_package_json.rst

@@ -0,0 +1,51 @@
+***************************
+Validating ``package.json``
+***************************
+
+marshmallow can be used to validate configuration according to a schema.
+Below is a schema that could be used to validate
+``package.json`` files. This example demonstrates the following features:
+
+
+- Validation and deserialization using `Schema.load <marshmallow.Schema.load>`
+- :doc:`Custom fields <../custom_fields>`
+- Specifying deserialization keys using ``data_key``
+- Including unknown keys using ``unknown = INCLUDE``
+
+.. literalinclude:: ../../examples/package_json_example.py
+    :language: python
+
+
+Given the following ``package.json`` file...
+
+.. literalinclude:: ../../examples/package.json
+    :language: json
+
+
+We can validate it using the above script.
+
+.. code-block:: shell-session
+
+    $ uv run examples/package_json_example.py < examples/package.json
+    {'description': 'The Pythonic JavaScript toolkit',
+    'dev_dependencies': {'pest': '^23.4.1'},
+    'license': 'MIT',
+    'main': 'index.js',
+    'name': 'dunderscore',
+    'scripts': {'test': 'pest'},
+    'version': <Version('1.2.3')>}
+
+Notice that our custom field deserialized the version string to a ``Version`` object.
+
+But if we pass an invalid package.json file...
+
+.. literalinclude:: ../../examples/invalid_package.json
+    :language: json
+
+We see the corresponding error messages.
+
+.. code-block:: shell-session
+
+    $ uv run examples/package_json_example.py < examples/invalid_package.json
+    ERROR: package.json is invalid
+    {'homepage': ['Not a valid URL.'], 'version': ['Not a valid version.']}

marshmallow-3.26.1/docs/extending/custom_error_handling.rst

@@ -0,0 +1,28 @@
+Custom error handling
+=====================
+
+By default, `Schema.load <marshmallow.Schema.load>` will raise a :exc:`ValidationError <marshmallow.exceptions.ValidationError>` if passed invalid data.
+
+You can specify a custom error-handling function for a :class:`Schema` by overriding the `handle_error <marshmallow.Schema.handle_error>`  method. The method receives the :exc:`ValidationError <marshmallow.exceptions.ValidationError>` and the original input data to be deserialized.
+
+.. code-block:: python
+
+    import logging
+    from marshmallow import Schema, fields
+
+
+    class AppError(Exception):
+        pass
+
+
+    class UserSchema(Schema):
+        email = fields.Email()
+
+        def handle_error(self, exc, data, **kwargs):
+            """Log and raise our custom exception when (de)serialization fails."""
+            logging.error(exc.messages)
+            raise AppError("An error occurred with input: {0}".format(data))
+
+
+    schema = UserSchema()
+    schema.load({"email": "invalid-email"})  # raises AppError

marshmallow-3.26.1/docs/extending/custom_error_messages.rst

@@ -0,0 +1,31 @@
+Custom error messages
+=====================
+
+To customize the schema-level error messages that `load <marshmallow.Schema.load>` and `loads <marshmallow.Schema.loads>` use when raising a `ValidationError <marshmallow.exceptions.ValidationError>`, override the `error_messages <marshmallow.Schema.error_messages>` class variable:
+
+.. code-block:: python
+
+    class MySchema(Schema):
+        error_messages = {
+            "unknown": "Custom unknown field error message.",
+            "type": "Custom invalid type error message.",
+        }
+
+
+Field-level error message defaults can be set on `Field.default_error_messages <marshmallow.fields.Field.default_error_messages>`.
+
+
+.. code-block:: python
+
+   from marshmallow import Schema, fields
+
+   fields.Field.default_error_messages["required"] = "You missed something!"
+
+
+   class ArtistSchema(Schema):
+       name = fields.Str(required=True)
+       label = fields.Str(required=True, error_messages={"required": "Label missing."})
+
+
+   print(ArtistSchema().validate({}))
+   # {'label': ['Label missing.'], 'name': ['You missed something!']}

marshmallow-3.26.1/docs/extending/custom_options.rst

@@ -0,0 +1,81 @@
+Custom `class Meta <marshmallow.Schema.Meta>` options
+=====================================================
+
+`class Meta <marshmallow.Schema.Meta>` options are a way to configure and modify a `Schema's <Schema>` behavior. See `marshmallow.Schema.Meta` for a listing of available options.
+
+You can add custom `class Meta <marshmallow.Schema.Meta>` options by subclassing `marshmallow.SchemaOpts`.
+
+Example: Enveloping, revisited
+------------------------------
+
+Let's build upon the :ref:`previous enveloping implementation <enveloping_1>` above for adding an envelope to serialized output. 
+This time, we will allow the envelope key to be customizable with `class Meta <marshmallow.Schema.Meta>` options.
+
+::
+
+    # Example outputs
+    {
+        'user': {
+            'name': 'Keith',
+            'email': 'keith@stones.com'
+        }
+    }
+    # List output
+    {
+        'users': [{'name': 'Keith'}, {'name': 'Mick'}]
+    }
+
+
+First, we'll add our namespace configuration to a custom options class.
+
+.. code-block:: python
+
+    from marshmallow import Schema, SchemaOpts
+
+
+    class NamespaceOpts(SchemaOpts):
+        """Same as the default class Meta options, but adds "name" and
+        "plural_name" options for enveloping.
+        """
+
+        def __init__(self, meta, **kwargs):
+            SchemaOpts.__init__(self, meta, **kwargs)
+            self.name = getattr(meta, "name", None)
+            self.plural_name = getattr(meta, "plural_name", self.name)
+
+
+Then we create a custom :class:`Schema` that uses our options class.
+
+.. code-block:: python
+
+    class NamespacedSchema(Schema):
+        OPTIONS_CLASS = NamespaceOpts
+
+        @pre_load(pass_many=True)
+        def unwrap_envelope(self, data, many, **kwargs):
+            key = self.opts.plural_name if many else self.opts.name
+            return data[key]
+
+        @post_dump(pass_many=True)
+        def wrap_with_envelope(self, data, many, **kwargs):
+            key = self.opts.plural_name if many else self.opts.name
+            return {key: data}
+
+
+Our application schemas can now inherit from our custom schema class.
+
+.. code-block:: python
+
+    class UserSchema(NamespacedSchema):
+        name = fields.String()
+        email = fields.Email()
+
+        class Meta:
+            name = "user"
+            plural_name = "users"
+
+
+    ser = UserSchema()
+    user = User("Keith", email="keith@stones.com")
+    result = ser.dump(user)
+    result  # {"user": {"name": "Keith", "email": "keith@stones.com"}}

marshmallow-3.26.1/docs/extending/index.rst

@@ -0,0 +1,16 @@
+Extending schemas
+=================
+
+The guides below demonstrate how to extend schemas in various ways.
+
+.. toctree::
+  :maxdepth: 1
+
+  pre_and_post_processing_methods
+  schema_validation
+  using_original_input_data
+  overriding_attribute_access
+  custom_error_handling
+  custom_options
+  using_context
+  custom_error_messages

marshmallow-3.26.1/docs/extending/overriding_attribute_access.rst

@@ -0,0 +1,17 @@
+Overriding how attributes are accessed
+======================================
+
+By default, marshmallow uses `utils.get_value <marshmallow.utils.get_value>` to pull attributes from various types of objects for serialization. This will work for *most* use cases.
+
+However, if you want to specify how values are accessed from an object, you can override the :meth:`get_attribute <marshmallow.Schema.get_attribute>` method.
+
+.. code-block:: python
+
+    class UserDictSchema(Schema):
+        name = fields.Str()
+        email = fields.Email()
+
+        # If we know we're only serializing dictionaries, we can
+        # use dict.get for all input objects
+        def get_attribute(self, obj, key, default):
+            return obj.get(key, default)