marshmallow: simplified object serialization

marshmallow is an ORM/ODM/framework-agnostic library for converting complex datatypes, such as objects, to and from native Python datatypes.

``` {.sourceCode .python} from datetime import date from marshmallow import Schema, fields, pprint

class ArtistSchema(Schema): name = fields.Str()

class AlbumSchema(Schema): title = fields.Str() release_date = fields.Date() artist = fields.Nested(ArtistSchema())

bowie = dict(name=’David Bowie’) album = dict(artist=bowie, title=’Hunky Dory’, release_date=date(1971, 12, 17))

schema = AlbumSchema() result = schema.dump(album) pprint(result.data, indent=2)

{ ‘artist’: {‘name’: ‘David Bowie’},

‘release_date’: ‘1971-12-17’,

‘title’: ‘Hunky Dory’}

```

In short, marshmallow schemas can be used to:

• Validate input data.
• Deserialize input data to app-level objects.
• Serialize app-level objects to primitive Python types. The serialized objects can then be rendered to standard formats such as JSON for use in an HTTP API.

Get It Now

$ pip install -U marshmallow

Documentation

Full documentation is available at http://marshmallow.readthedocs.io/ .

Requirements

• Python >= 2.6 or >= 3.3

marshmallow has no external dependencies outside of the Python standard library, although python-dateutil is recommended for robust datetime deserialization.

Ecosystem

A list of marshmallow-related libraries can be found at the GitHub wiki here:

https://github.com/marshmallow-code/marshmallow/wiki/Ecosystem

Project Links

• Docs: http://marshmallow.readthedocs.io/
• Changelog: http://marshmallow.readthedocs.io/en/latest/changelog.html
• PyPI: https://pypi.python.org/pypi/marshmallow
• Issues: https://github.com/marshmallow-code/marshmallow/issues

License

MIT licensed. See the bundled LICENSE file for more details.

Contributing Guidelines

In General

• PEP 8, when sensible.
• Test ruthlessly. Write docs for new features.
• Even more important than Test-Driven Development--Human-Driven Development.

In Particular

Questions, Feature Requests, Bug Reports, and Feedback. . .

. . .should all be reported on the Github Issue Tracker .

Setting Up for Local Development

1. Fork marshmallow on Github. :

   $ git clone https://github.com/marshmallow-code/marshmallow.git
   $ cd marshmallow
   

2. Install development requirements. It is highly recommended that you use a virtualenv. :

   # After activating your virtualenv
   $ pip install -r dev-requirements.txt
   

3. Install marshmallow in develop mode. :

   $ pip install -e .
   

Git Branch Structure

Marshmallow abides by the following branching model:

dev

Current development branch. New features should branch off here.

pypi

Current production release on PyPI.

X.Y-line

Maintenance branch for release X.Y. Bug fixes should be sent to the most recent release branch.. The maintainer will forward-port the fix to dev. Note: exceptions may be made for bug fixes that introduce large code changes.

Always make a new branch for your work, no matter how small. Also, do not put unrelated changes in the same branch or pull request. This makes it more difficult to merge your changes.

Pull Requests

1. Create a new local branch. :

# For a new feature
$ git checkout -b name-of-feature dev

# For a bugfix
$ git checkout -b fix-something 1.2-line

2. Commit your changes. Write good commit messages. :

$ git commit -m "Detailed commit message"
$ git push origin name-of-feature

1. Before submitting a pull request, check the following:

• If the pull request adds functionality, it is tested and the docs are updated.
• You've added yourself to AUTHORS.rst.

1. Submit a pull request to marshmallow-code:dev or the appropriate maintenance branch. The Travis CI build must be passing before your pull request is merged.

Running tests

To run all tests: :

$ invoke test

To run tests on Python 2.6, 2.7, 3.3, 3.4, and PyPy virtual environments (must have each interpreter installed): :

$ tox

Documentation

Contributions to the documentation are welcome. Documentation is written in reStructured Text (rST). A quick rST reference can be found here. Builds are powered by Sphinx.

To install the packages for building the docs: :

$ pip install -r docs/requirements.txt

To build the docs: :

$ invoke docs -b

The -b (for "browse") automatically opens up the docs in your browser after building.

Contributing Examples

Have a usage example you'd like to share? A custom [Field]{.title-ref} that others might find useful? Feel free to add it to the examples directory and send a pull request.