pax_global_header 0000666 0000000 0000000 00000000064 14633310012 0014503 g ustar 00root root 0000000 0000000 52 comment=e945ee4319db49da9f7b8ede614e988cc8c8956b
mashumaro-3.13.1/ 0000775 0000000 0000000 00000000000 14633310012 0013564 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/.editorconfig 0000664 0000000 0000000 00000000715 14633310012 0016244 0 ustar 00root root 0000000 0000000 # EditorConfig is awesome: http://EditorConfig.org
# top-most EditorConfig file
root = true
# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 4
trim_trailing_whitespace = true
charset = utf-8
max_line_length=79
[Makefile]
indent_style = tab
[*.{yml,yaml,feature,json,toml}]
indent_size = 2
[*.{tsv,csv}]
trim_trailing_whitespace = false
[*.rst]
max_line_length = 80
mashumaro-3.13.1/.github/ 0000775 0000000 0000000 00000000000 14633310012 0015124 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/.github/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000012147 14633310012 0017730 0 ustar 00root root 0000000 0000000 # Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socioeconomic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
random.gauss@gmail.com.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
mashumaro-3.13.1/.github/CONTRIBUTING.md 0000664 0000000 0000000 00000030643 14633310012 0017363 0 ustar 00root root 0000000 0000000
# Contributing to mashumaro
First off, thanks for taking the time to contribute! ❤️
All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉
> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
> - Star the project
> - Tweet about it
> - Refer this project in your project's readme
> - Mention the project at local meetups and tell your friends/colleagues
## Table of Contents
- [I Have a Question](#i-have-a-question)
- [I Want To Contribute](#i-want-to-contribute)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Enhancements](#suggesting-enhancements)
- [Your First Code Contribution](#your-first-code-contribution)
- [Improving The Documentation](#improving-the-documentation)
## I Have a Question
> If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/Fatal1ty/mashumaro/blob/master/README.md).
Before you ask a question, it is best to search for existing [Issues](https://github.com/Fatal1ty/mashumaro/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
If you then still feel the need to ask a question and need clarification, we recommend the following:
- Open an [Issue](https://github.com/Fatal1ty/mashumaro/issues/new).
- Provide as much context as you can about what you're running into.
- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant.
- Tag your issue with the `question` tag
We will then take care of the issue as soon as possible.
## I Want To Contribute
> ### Legal Notice
> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project licence.
### Reporting Bugs
#### Before Submitting a Bug Report
A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
- Make sure that you are using the latest version.
- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](https://github.com/Fatal1ty/mashumaro/blob/master/README.md). If you are looking for support, you might want to check [this section](#i-have-a-question)).
- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/Fatal1ty/mashumaro/issues?q=label%3Abug).
- Also make sure to search the internet (including Stack Overflow) to see if users outside the GitHub community have discussed the issue.
- Collect information about the bug:
- Stack trace (Traceback)
- OS, Platform and Version (Windows, Linux, macOS, x86, ARM)
- Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant.
- Possibly your input and the output
- Can you reliably reproduce the issue? And can you also reproduce it with older versions?
#### How Do I Submit a Good Bug Report?
> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be reported in accordance with our [security policy](https://github.com/Fatal1ty/mashumaro/security/policy).
We use GitHub issues to track bugs and errors. If you run into an issue with the project:
- Open an [Issue](https://github.com/Fatal1ty/mashumaro/issues/new?template=bug_report.md). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
- Explain the behavior you would expect and the actual behavior.
- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
- Provide the information you collected in the previous section.
Once it's filed:
- The project team will label the issue accordingly.
- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs information`. Bugs with the `needs information` tag will not be addressed until they are reproduced.
- If the team is able to reproduce the issue, it will be labeled with the `bug` tag, as well as possibly other tags, and the issue will be left to be [implemented by someone](#your-first-code-contribution).
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for mashumaro, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
#### Before Submitting an Enhancement
- Make sure that you are using the latest version.
- Read the [documentation](https://github.com/Fatal1ty/mashumaro/blob/master/README.md) carefully and find out if the functionality is already covered, maybe by an individual configuration.
- Perform a [search](https://github.com/Fatal1ty/mashumaro/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library.
#### How Do I Submit a Good Enhancement Suggestion?
Enhancement suggestions are tracked as [GitHub issues](https://github.com/Fatal1ty/mashumaro/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) with the `enhancement` tag.
- Open an [Feature Request](https://github.com/Fatal1ty/mashumaro/issues/new?template=feature_request.md).
- Use a **clear and descriptive title** for the issue to identify the suggestion.
- Provide a **step-by-step description of the suggested enhancement** in as many details as possible.
- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you.
- **Explain why this enhancement would be useful** to most mashumaro users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
### Your First Code Contribution
> Please, refrain from creating a new pull request without an existing related issue that your pull request solves. Minor corrections, such as spelling errors, may be an exception.
#### How to Get Started
1. Finding an Issue: Browse through our repository and look for issues you may help with. If you're new to open source and looking for a good starting point, we have a special label called [`good first issue`](https://github.com/Fatal1ty/mashumaro/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that highlights issues that are ideal for beginners to tackle.
2. Understanding the Issue: Once you've found a good issue, take the time to read through the description and understand what needs to be done. Feel free to ask questions if anything is unclear.
3. Setting up your Development Environment: Follow [the instructions](#setting-up-your-development-environment) to set up your development environment. Make sure you have all the necessary tools and dependencies installed.
4. Making your Contribution: Fork the repository, create a new branch for your changes, and start working on the issue. Make sure to follow our coding guidelines and best practices.
5. Submitting your Pull Request: Once you're done with your changes, submit a pull request back to the main repository. Be sure to reference the issue you're addressing in your pull request description.
### What Can You Help With?
Here are some common areas where you can make contributions:
- Fixing bugs or issues reported by users
- Implementing new features or enhancements
- Improving the documentation
- Refactoring code for better readability and performance
Remember, everyone starts somewhere, and we're here to support you on your journey to becoming a contributor. If you have any questions or need help along the way, feel free to reach out to our team or community members for assistance.
#### Setting up your Development Environment
Before getting started, you will need to have already installed:
* [python](https://www.python.org) (3.8+ only)
* [git](https://git-scm.com)
* [just](https://github.com/casey/just)
Once you have those installed, you're ready to:
* Clone the repository
* Create a virtual environment
* Install all development dependencies
* Install a development version of mashumaro
> Please note that you can use any virtual management tool you like. Here we show the basic instructions using the standard `venv` library.
```shell
# Clone the repository
git clone https://github.com/Fatal1ty/mashumaro
# cd into the repo root directory
cd mashumaro/
# Create and activate a virtual environment (recommended)
python -m venv env && source env/bin/activate
# Install mashumaro and all development dependencies
just build
```
#### Linters
To run linters, use the following command:
```shell
just lint
```
#### Format the code
To format the code according to style guides, use the following command:
```shell
just format
```
#### Testing
Tests are located in the `tests/` directory. Any code changes should include additional tests or modification of existing tests to ensure correctness.
To run tests locally, use the following command:
```shell
just test
```
Please make sure that test coverage has not decreased after your changes. Also note that test coverage depends on the Python version that your virtual environment was created with, since not all functionality works on every supported version of Python. To run tests with coverage report, you can use the following command:
```shell
just test-with-coverage
```
#### Continuous integration
We use GitHub Actions to provide "continuous integration" testing for all pull requests. When submitting a pull request, please check that all tests are passing and fix any issues that may arise.
### Improving The Documentation
We welcome contributions to improve the documentation of this project. Whether it's fixing typos, clarifying instructions, adding examples, or creating new sections, your help is greatly appreciated. Here are some ways you can contribute to improving the documentation:
1. Fixing Typos and Grammar: If you notice any typos or grammatical errors in the documentation, feel free to submit a pull request with the corrections.
2. Clarifying Instructions: If you find any instructions that are unclear or ambiguous, you can suggest improvements to make them more understandable for other users.
3. Adding Examples: Providing code examples or step-by-step guides can be very helpful for users trying to understand how to use the project. Feel free to add examples where needed.
4. Creating New Sections: If you think there are important topics missing from the documentation, you can create new sections to cover those topics.
5. Updating Outdated Information: If any information in the documentation is outdated or no longer accurate, please update it with the correct information.
mashumaro-3.13.1/.github/FUNDING.yml 0000664 0000000 0000000 00000000053 14633310012 0016737 0 ustar 00root root 0000000 0000000 custom: ['https://coindrop.to/tikhonov_a']
mashumaro-3.13.1/.github/ISSUE_TEMPLATE/ 0000775 0000000 0000000 00000000000 14633310012 0017307 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/.github/ISSUE_TEMPLATE/bug_report.md 0000664 0000000 0000000 00000000656 14633310012 0022010 0 ustar 00root root 0000000 0000000 ---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
* mashumaro version:
* Python version:
* Operating System:
### Description
Describe what you were trying to get done.
Tell us what happened, what went wrong, and what you expected to happen.
### What I Did
```
Paste the code, command(s) you ran and the output.
If there was a crash, please include the traceback here.
```
mashumaro-3.13.1/.github/ISSUE_TEMPLATE/feature_request.md 0000664 0000000 0000000 00000001104 14633310012 0023030 0 ustar 00root root 0000000 0000000 ---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context about the feature request here.
mashumaro-3.13.1/.github/SECURITY.md 0000664 0000000 0000000 00000003071 14633310012 0016716 0 ustar 00root root 0000000 0000000 At our GitHub project, we take security seriously and strive to maintain
the highest level of security for our users. We encourage all members of our
community to report any security-related bugs they discover to us as soon as
possible. In order to ensure that these reports are handled in a secure and
efficient manner, we have established the following policy:
1. Reporting Security-Related Bugs: If you believe that you have discovered
a security-related bug in our project, please report it to us immediately
by sending an email to random.gauss@gmail.com. Please do not open
a GitHub issue for security-related bugs, as this may put our users at risk.
2. Providing Details: When reporting a security-related bug, please provide
as much detail as possible, including a detailed description of the issue,
steps to reproduce the problem, and any relevant code or screenshots.
This will help us to quickly identify and address the issue.
3. Confidentiality: We take the confidentiality of security-related bug reports
very seriously. We will keep all information related to the bug confidential
and will not share it with anyone outside of our team without your
permission, except as required by law.
4. Resolution: We will work diligently to resolve the issue as quickly as
possible and will keep you informed of our progress throughout the process.
5. Public Disclosure: Once the issue has been resolved, we will make a release
and announce the security fix through our normal communication channels.
When it makes sense we may also obtain a CVE ID.
mashumaro-3.13.1/.github/workflows/ 0000775 0000000 0000000 00000000000 14633310012 0017161 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/.github/workflows/main.yml 0000664 0000000 0000000 00000006114 14633310012 0020632 0 ustar 00root root 0000000 0000000 name: tests
on:
push:
branches:
- '*'
pull_request:
branches:
- master
jobs:
test-code-style:
name: Code style tests
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- name: Install dependencies
run: |
pip install --upgrade pip
pip install .
pip install -r requirements-dev.txt
- name: Run ruff
run: ruff check mashumaro
- name: Run mypy
run: mypy mashumaro
- name: Run black
run: black --check .
- name: Run codespell
run: codespell mashumaro tests README.md .github/*.md
test-posix:
name: Tests on Posix
needs:
- test-code-style
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- name: Install dependencies
run: |
pip install --upgrade pip
pip install .
pip install -r requirements-dev.txt
- name: Run tests with coverage
run: pytest --cov=mashumaro --cov=tests
- name: Upload Coverage
run: coveralls --service=github
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COVERALLS_FLAG_NAME: posix-${{ matrix.python-version }}
COVERALLS_PARALLEL: true
test-windows:
name: Tests on Windows
needs:
- test-code-style
runs-on: windows-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- name: Install dependencies
run: |
pip install --upgrade pip
pip install .
pip install -r requirements-dev.txt
pip install tzdata
- name: Run tests with coverage
run: pytest --cov=mashumaro --cov=tests
- name: Upload Coverage
run: coveralls --service=github
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COVERALLS_FLAG_NAME: windows-${{ matrix.python-version }}
COVERALLS_PARALLEL: true
coveralls:
name: Finish Coveralls
needs:
- test-posix
- test-windows
runs-on: ubuntu-latest
steps:
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: 3.11
- name: Install dependencies
run: pip install coveralls
- name: Finish coveralls
run: coveralls --service=github --finish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
mashumaro-3.13.1/.gitignore 0000664 0000000 0000000 00000001371 14633310012 0015556 0 ustar 00root root 0000000 0000000 # Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
# C extensions
*.so
# Distribution / packaging
.Python
env/
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*,cover
# Translations
*.mo
*.pot
# Django stuff:
*.log
# Sphinx documentation
docs/_build/
# PyBuilder
target/
# PyCharm
.idea
# pyenv
.python-version
# OSX
.DS_Store
mashumaro-3.13.1/LICENSE 0000664 0000000 0000000 00000025013 14633310012 0014572 0 ustar 00root root 0000000 0000000 Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Copyright 2017 Alexander Tikhonov
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
mashumaro-3.13.1/README.md 0000664 0000000 0000000 00000334530 14633310012 0015053 0 ustar 00root root 0000000 0000000
###### Fast and well tested serialization library
[](https://github.com/Fatal1ty/mashumaro/actions)
[](https://coveralls.io/github/Fatal1ty/mashumaro?branch=master)
[](https://pypi.python.org/pypi/mashumaro)
[](https://pypi.python.org/pypi/mashumaro)
[](https://opensource.org/licenses/Apache-2.0)
In Python, you often need to dump and load objects based on the schema you
have. It can be a dataclass model, a list of third-party generic classes or
whatever. Mashumaro not only lets you save and load things in different ways,
but it also does it _super quick_.
**Key features**
* 🚀 One of the fastest libraries
* ☝️ Mature and time-tested
* 👶 Easy to use out of the box
* ⚙️ Highly customizable
* 🎉 Built-in support for JSON, YAML, TOML, MessagePack
* 📦 Built-in support for almost all Python types including typing-extensions
* 📝 JSON Schema generation
Table of contents
-------------------------------------------------------------------------------
* [Table of contents](#table-of-contents)
* [Introduction](#introduction)
* [Installation](#installation)
* [Changelog](#changelog)
* [Supported data types](#supported-data-types)
* [Usage example](#usage-example)
* [How does it work?](#how-does-it-work)
* [Benchmark](#benchmark)
* [Supported serialization formats](#supported-serialization-formats)
* [Basic form](#basic-form)
* [JSON](#json)
* [json library](#json-library)
* [orjson library](#orjson-library)
* [YAML](#yaml)
* [TOML](#toml)
* [MessagePack](#messagepack)
* [Customization](#customization)
* [SerializableType interface](#serializabletype-interface)
* [User-defined types](#user-defined-types)
* [User-defined generic types](#user-defined-generic-types)
* [SerializationStrategy](#serializationstrategy)
* [Third-party types](#third-party-types)
* [Third-party generic types](#third-party-generic-types)
* [Field options](#field-options)
* [`serialize` option](#serialize-option)
* [`deserialize` option](#deserialize-option)
* [`serialization_strategy` option](#serialization_strategy-option)
* [`alias` option](#alias-option)
* [Config options](#config-options)
* [`debug` config option](#debug-config-option)
* [`code_generation_options` config option](#code_generation_options-config-option)
* [`serialization_strategy` config option](#serialization_strategy-config-option)
* [`aliases` config option](#aliases-config-option)
* [`serialize_by_alias` config option](#serialize_by_alias-config-option)
* [`allow_deserialization_not_by_alias` config option](#allow_deserialization_not_by_alias-config-option)
* [`omit_none` config option](#omit_none-config-option)
* [`omit_default` config option](#omit_default-config-option)
* [`namedtuple_as_dict` config option](#namedtuple_as_dict-config-option)
* [`allow_postponed_evaluation` config option](#allow_postponed_evaluation-config-option)
* [`dialect` config option](#dialect-config-option)
* [`orjson_options` config option](#orjson_options-config-option)
* [`discriminator` config option](#discriminator-config-option)
* [`lazy_compilation` config option](#lazy_compilation-config-option)
* [`sort_keys` config option](#sort_keys-config-option)
* [`forbid_extra_keys` config option](#forbid_extra_keys-config-option)
* [Passing field values as is](#passing-field-values-as-is)
* [Extending existing types](#extending-existing-types)
* [Field aliases](#field-aliases)
* [Dialects](#dialects)
* [`serialization_strategy` dialect option](#serialization_strategy-dialect-option)
* [`serialize_by_alias` dialect option](#serialize_by_alias-dialect-option)
* [`omit_none` dialect option](#omit_none-dialect-option)
* [`omit_default` dialect option](#omit_default-dialect-option)
* [`namedtuple_as_dict` dialect option](#namedtuple_as_dict-dialect-option)
* [`no_copy_collections` dialect option](#no_copy_collections-dialect-option)
* [Changing the default dialect](#changing-the-default-dialect)
* [Discriminator](#discriminator)
* [Subclasses distinguishable by a field](#subclasses-distinguishable-by-a-field)
* [Subclasses without a common field](#subclasses-without-a-common-field)
* [Class level discriminator](#class-level-discriminator)
* [Working with union of classes](#working-with-union-of-classes)
* [Using a custom variant tagger function](#using-a-custom-variant-tagger-function)
* [Code generation options](#code-generation-options)
* [Add `omit_none` keyword argument](#add-omit_none-keyword-argument)
* [Add `by_alias` keyword argument](#add-by_alias-keyword-argument)
* [Add `dialect` keyword argument](#add-dialect-keyword-argument)
* [Add `context` keyword argument](#add-context-keyword-argument)
* [Generic dataclasses](#generic-dataclasses)
* [Generic dataclass inheritance](#generic-dataclass-inheritance)
* [Generic dataclass in a field type](#generic-dataclass-in-a-field-type)
* [GenericSerializableType interface](#genericserializabletype-interface)
* [Serialization hooks](#serialization-hooks)
* [Before deserialization](#before-deserialization)
* [After deserialization](#after-deserialization)
* [Before serialization](#before-serialization)
* [After serialization](#after-serialization)
* [JSON Schema](#json-schema)
* [Building JSON Schema](#building-json-schema)
* [JSON Schema constraints](#json-schema-constraints)
* [Extending JSON Schema](#extending-json-schema)
* [JSON Schema and custom serialization methods](#json-schema-and-custom-serialization-methods)
Introduction
-------------------------------------------------------------------------------
This library provides two fundamentally different approaches to converting
your data to and from various formats. Each of them is useful in different
situations:
* Codecs
* Mixins
Codecs are represented by a set of decoder / encoder classes and
decode / encode functions for each supported format. You can use them
to convert data of any python built-in and third-party type to JSON, YAML,
TOML, MessagePack or a basic form accepted by other serialization formats.
For example, you can convert a list of datetime objects to JSON array
containing string-represented datetimes and vice versa.
Mixins are primarily for dataclass models. They are represented by mixin
classes that add methods for converting to and from JSON, YAML, TOML,
MessagePack or a basic form accepted by other serialization formats.
If you have a root dataclass model, then it will be the easiest way to make it
serializable. All you have to do is inherit a particular mixin class.
In addition to serialization functionality, this library also provides JSON
Schema builder that can be used in places where interoperability matters.
Installation
-------------------------------------------------------------------------------
Use pip to install:
```shell
$ pip install mashumaro
```
The current version of `mashumaro` supports Python versions 3.8 — 3.13.
It's not recommended to use any version of Python that has reached its
[end of life](https://devguide.python.org/versions/) and is no longer receiving
security updates or bug fixes from the Python development team.
For convenience, there is a table below that outlines the
last version of `mashumaro` that can be installed on unmaintained versions
of Python.
| Python Version | Last Version of mashumaro | Python EOL |
|----------------|--------------------------------------------------------------------|------------|
| 3.7 | [3.9.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.9.1) | 2023-06-27 |
| 3.6 | [3.1.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.1.1) | 2021-12-23 |
Changelog
-------------------------------------------------------------------------------
This project follows the principles of [Semantic Versioning](https://semver.org).
Changelog is available on [GitHub Releases page](https://github.com/Fatal1ty/mashumaro/releases).
Supported data types
-------------------------------------------------------------------------------
There is support for generic types from the standard [`typing`](https://docs.python.org/3/library/typing.html) module:
* [`List`](https://docs.python.org/3/library/typing.html#typing.List)
* [`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)
* [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
* [`Set`](https://docs.python.org/3/library/typing.html#typing.Set)
* [`FrozenSet`](https://docs.python.org/3/library/typing.html#typing.FrozenSet)
* [`Deque`](https://docs.python.org/3/library/typing.html#typing.Deque)
* [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)
* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)
* [`DefaultDict`](https://docs.python.org/3/library/typing.html#typing.DefaultDict)
* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)
* [`Mapping`](https://docs.python.org/3/library/typing.html#typing.Mapping)
* [`MutableMapping`](https://docs.python.org/3/library/typing.html#typing.MutableMapping)
* [`Counter`](https://docs.python.org/3/library/typing.html#typing.Counter)
* [`ChainMap`](https://docs.python.org/3/library/typing.html#typing.ChainMap)
* [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)
for standard generic types on [PEP 585](https://www.python.org/dev/peps/pep-0585/) compatible Python (3.9+):
* [`list`](https://docs.python.org/3/library/stdtypes.html#list)
* [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)
* [`namedtuple`](https://docs.python.org/3/library/collections.html#collections.namedtuple)
* [`set`](https://docs.python.org/3/library/stdtypes.html#set)
* [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)
* [`collections.abc.Set`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Set)
* [`collections.abc.MutableSet`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet)
* [`collections.deque`](https://docs.python.org/3/library/collections.html#collections.deque)
* [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)
* [`collections.OrderedDict`](https://docs.python.org/3/library/collections.html#collections.OrderedDict)
* [`collections.defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict)
* [`collections.abc.Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)
* [`collections.abc.MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)
* [`collections.Counter`](https://docs.python.org/3/library/collections.html#collections.Counter)
* [`collections.ChainMap`](https://docs.python.org/3/library/collections.html#collections.ChainMap)
* [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)
* [`collections.abc.MutableSequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence)
for special primitives from the [`typing`](https://docs.python.org/3/library/typing.html) module:
* [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)
* [`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)
* [`Union`](https://docs.python.org/3/library/typing.html#typing.Union)
* [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)
* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)
* [`NewType`](https://docs.python.org/3/library/typing.html#newtype)
* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)
* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)
* [`Final`](https://docs.python.org/3/library/typing.html#typing.Final)
* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)
* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)
for standard interpreter types from [`types`](https://docs.python.org/3/library/types.html#standard-interpreter-types) module:
* [`NoneType`](https://docs.python.org/3/library/types.html#types.NoneType)
* [`UnionType`](https://docs.python.org/3/library/types.html#types.UnionType)
* [`MappingProxyType`](https://docs.python.org/3/library/types.html#types.MappingProxyType)
for enumerations based on classes from the standard [`enum`](https://docs.python.org/3/library/enum.html) module:
* [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum)
* [`IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum)
* [`StrEnum`](https://docs.python.org/3/library/enum.html#enum.StrEnum)
* [`Flag`](https://docs.python.org/3/library/enum.html#enum.Flag)
* [`IntFlag`](https://docs.python.org/3/library/enum.html#enum.IntFlag)
for common built-in types:
* [`int`](https://docs.python.org/3/library/functions.html#int)
* [`float`](https://docs.python.org/3/library/functions.html#float)
* [`bool`](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values)
* [`str`](https://docs.python.org/3/library/stdtypes.html#str)
* [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)
* [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)
for built-in datetime oriented types (see [more](#deserialize-option) details):
* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)
* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)
* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)
* [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta)
* [`timezone`](https://docs.python.org/3/library/datetime.html#datetime.timezone)
* [`ZoneInfo`](https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo)
for pathlike types:
* [`PurePath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath)
* [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)
* [`PurePosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePosixPath)
* [`PosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PosixPath)
* [`PureWindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PureWindowsPath)
* [`WindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.WindowsPath)
* [`os.PathLike`](https://docs.python.org/3/library/os.html#os.PathLike)
for other less popular built-in types:
* [`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)
* [`decimal.Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal)
* [`fractions.Fraction`](https://docs.python.org/3/library/fractions.html#fractions.Fraction)
* [`ipaddress.IPv4Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address)
* [`ipaddress.IPv6Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Address)
* [`ipaddress.IPv4Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Network)
* [`ipaddress.IPv6Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Network)
* [`ipaddress.IPv4Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Interface)
* [`ipaddress.IPv6Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Interface)
for backported types from [`typing-extensions`](https://github.com/python/typing_extensions):
* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)
* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)
* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)
* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)
* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)
* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)
* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)
for arbitrary types:
* [user-defined types](#user-defined-types)
* [third-party types](#third-party-types)
* [user-defined generic types](#user-defined-generic-types)
* [third-party generic types](#third-party-generic-types)
Usage example
-------------------------------------------------------------------------------
Suppose we're developing a financial application and we operate with currencies
and stocks:
```python
from dataclasses import dataclass
from enum import Enum
class Currency(Enum):
USD = "USD"
EUR = "EUR"
@dataclass
class CurrencyPosition:
currency: Currency
balance: float
@dataclass
class StockPosition:
ticker: str
name: str
balance: int
```
Now we want a dataclass for portfolio that will be serialized to and from JSON.
We inherit `DataClassJSONMixin` that adds this functionality:
```python
from mashumaro.mixins.json import DataClassJSONMixin
...
@dataclass
class Portfolio(DataClassJSONMixin):
currencies: list[CurrencyPosition]
stocks: list[StockPosition]
```
Let's create a portfolio instance and check methods `from_json` and `to_json`:
```python
portfolio = Portfolio(
currencies=[
CurrencyPosition(Currency.USD, 238.67),
CurrencyPosition(Currency.EUR, 361.84),
],
stocks=[
StockPosition("AAPL", "Apple", 10),
StockPosition("AMZN", "Amazon", 10),
]
)
portfolio_json = portfolio.to_json()
assert Portfolio.from_json(portfolio_json) == portfolio
```
If we need to serialize something different from a root dataclass,
we can use codecs. In the following example we create a JSON decoder and encoder
for a list of currencies:
```python
from mashumaro.codecs.json import JSONDecoder, JSONEncoder
...
decoder = JSONDecoder(list[CurrencyPosition])
encoder = JSONEncoder(list[CurrencyPosition])
currencies = [
CurrencyPosition(Currency.USD, 238.67),
CurrencyPosition(Currency.EUR, 361.84),
]
currencies_json = encoder.encode(currencies)
assert decoder.decode(currencies_json) == currencies
```
How does it work?
-------------------------------------------------------------------------------
This library works by taking the schema of the data and generating a
specific decoder and encoder for exactly that schema, taking into account the
specifics of serialization format. This is much faster than inspection of
data types on every call of decoding or encoding at runtime.
These specific decoders and encoders are generated by
[codecs and mixins](#supported-serialization-formats):
* When using codecs, these methods are compiled during the creation of the
decoder or encoder.
* When using serialization
mixins, these methods are compiled during import time (or at runtime in some
cases) and are set as attributes to your dataclasses. To minimize the import
time, you can explicitly enable
[lazy compilation](#lazy_compilation-config-option).
Benchmark
-------------------------------------------------------------------------------
* macOS 14.0 Sonoma
* Apple M1
* 16GB RAM
* Python 3.12.0
Benchmark using [pyperf](https://github.com/psf/pyperf) with GitHub Issue model. Please note that the
following charts use logarithmic scale, as it is convenient for displaying
very large ranges of values.
> [!NOTE]\
> Benchmark results may vary depending on the specific configuration and
> parameters used for serialization and deserialization. However, we have made
> an attempt to use the available options that can speed up and smooth out the
> differences in how libraries work.
To run benchmark in your environment:
```bash
git clone git@github.com:Fatal1ty/mashumaro.git
cd mashumaro
python3 -m venv env && source env/bin/activate
pip install -e .
pip install -r requirements-dev.txt
./benchmark/run.sh
```
Supported serialization formats
-------------------------------------------------------------------------------
This library has built-in support for multiple popular formats:
* [JSON](https://www.json.org)
* [YAML](https://yaml.org)
* [TOML](https://toml.io)
* [MessagePack](https://msgpack.org)
There are preconfigured codecs and mixin classes. However, you're free
to override some settings if necessary.
> [!IMPORTANT]\
> As for codecs, you are
> offered to choose between convenience and efficiency. When you need to decode
> or encode typed data more than once, it's highly recommended to create
> and reuse a decoder or encoder specifically for that data type. For one-time
> use with default settings it may be convenient to use global functions that
> create a disposable decoder or encoder under the hood. Remember that you
> should not use these convenient global functions more that once for the same
> data type if performance is important to you.
### Basic form
Basic form denotes a python object consisting only of basic data types
supported by most serialization formats. These types are:
[`str`](https://docs.python.org/3/library/stdtypes.html#str),
[`int`](https://docs.python.org/3/library/functions.html#int),
[`float`](https://docs.python.org/3/library/functions.html#float),
[`bool`](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values),
[`list`](https://docs.python.org/3/library/stdtypes.html#list),
[`dict`](https://docs.python.org/3/library/stdtypes.html#dict).
This is also a starting point you can play with for a comprehensive
transformation of your data.
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs import BasicDecoder, BasicEncoder
# or from mashumaro.codecs.basic import BasicDecoder, BasicEncoder
decoder = BasicDecoder(, ...)
decoder.decode(...)
encoder = BasicEncoder(, ...)
encoder.encode(...)
```
Convenient functions are recommended to be used as follows:
```python
import mashumaro.codecs.basic as basic_codec
basic_codec.decode(..., )
basic_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro import DataClassDictMixin
# or from mashumaro.mixins.dict import DataClassDictMixin
@dataclass
class MyModel(DataClassDictMixin):
...
MyModel.from_dict(...)
MyModel(...).to_dict()
```
> [!TIP]\
> You don't need to inherit `DataClassDictMixin` along with other serialization
> mixins because it's a base class for them.
### JSON
[JSON](https://www.json.org) is a lightweight data-interchange format. You can
choose between standard library
[json](https://docs.python.org/3/library/json.html) for compatibility and
third-party dependency [orjson](https://pypi.org/project/orjson/) for better
performance.
#### json library
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs.json import JSONDecoder, JSONEncoder
decoder = JSONDecoder(, ...)
decoder.decode(...)
encoder = JSONEncoder(, ...)
encoder.encode(...)
```
Convenient functions can be used as follows:
```python
from mashumaro.codecs.json import json_decode, json_encode
json_decode(..., )
json_encode(..., )
```
Convenient function aliases are recommended to be used as follows:
```python
import mashumaro.codecs.json as json_codec
json_codec.decode(...)
json_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro.mixins.json import DataClassJSONMixin
@dataclass
class MyModel(DataClassJSONMixin):
...
MyModel.from_json(...)
MyModel(...).to_json()
```
#### orjson library
In order to use [`orjson`](https://pypi.org/project/orjson/) library, it must
be installed manually or using an extra option for `mashumaro`:
```shell
pip install mashumaro[orjson]
```
The following data types will be handled by
[`orjson`](https://pypi.org/project/orjson/) library by default:
* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)
* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)
* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)
* [`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs.orjson import ORJSONDecoder, ORJSONEncoder
decoder = ORJSONDecoder(, ...)
decoder.decode(...)
encoder = ORJSONEncoder(, ...)
encoder.encode(...)
```
Convenient functions can be used as follows:
```python
from mashumaro.codecs.orjson import json_decode, json_encode
json_decode(..., )
json_encode(..., )
```
Convenient function aliases are recommended to be used as follows:
```python
import mashumaro.codecs.orjson as json_codec
json_codec.decode(...)
json_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro.mixins.orjson import DataClassORJSONMixin
@dataclass
class MyModel(DataClassORJSONMixin):
...
MyModel.from_json(...)
MyModel(...).to_json()
MyModel(...).to_jsonb()
```
### YAML
[YAML](https://yaml.org) is a human-friendly data serialization language for
all programming languages. In order to use this format, the
[`pyyaml`](https://pypi.org/project/PyYAML/) package must be installed.
You can install it manually or using an extra option for `mashumaro`:
```shell
pip install mashumaro[yaml]
```
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs.yaml import YAMLDecoder, YAMLEncoder
decoder = YAMLDecoder(, ...)
decoder.decode(...)
encoder = YAMLEncoder(, ...)
encoder.encode(...)
```
Convenient functions can be used as follows:
```python
from mashumaro.codecs.yaml import yaml_decode, yaml_encode
yaml_decode(..., )
yaml_encode(..., )
```
Convenient function aliases are recommended to be used as follows:
```python
import mashumaro.codecs.yaml as yaml_codec
yaml_codec.decode(...)
yaml_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro.mixins.yaml import DataClassYAMLMixin
@dataclass
class MyModel(DataClassYAMLMixin):
...
MyModel.from_yaml(...)
MyModel(...).to_yaml()
```
### TOML
[TOML](https://toml.io) is config file format for humans.
In order to use this format, the [`tomli`](https://pypi.org/project/tomli/) and
[`tomli-w`](https://pypi.org/project/tomli-w/) packages must be installed.
In Python 3.11+, `tomli` is included as
[`tomlib`](https://docs.python.org/3/library/tomllib.html) standard library
module and is used for this format. You can install the missing packages
manually or using an extra option
for `mashumaro`:
```shell
pip install mashumaro[toml]
```
The following data types will be handled by
[`tomli`](https://pypi.org/project/tomli/)/
[`tomli-w`](https://pypi.org/project/tomli-w/) library by default:
* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)
* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)
* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)
Fields with value `None` will be omitted on serialization because TOML
doesn't support null values.
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs.toml import TOMLDecoder, TOMLEncoder
decoder = TOMLDecoder(, ...)
decoder.decode(...)
encoder = TOMLEncoder(, ...)
encoder.encode(...)
```
Convenient functions can be used as follows:
```python
from mashumaro.codecs.toml import toml_decode, toml_encode
toml_decode(..., )
toml_encode(..., )
```
Convenient function aliases are recommended to be used as follows:
```python
import mashumaro.codecs.toml as toml_codec
toml_codec.decode(...)
toml_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro.mixins.toml import DataClassTOMLMixin
@dataclass
class MyModel(DataClassTOMLMixin):
...
MyModel.from_toml(...)
MyModel(...).to_toml()
```
### MessagePack
[MessagePack](https://msgpack.org) is an efficient binary serialization format.
In order to use this mixin, the [`msgpack`](https://pypi.org/project/msgpack/)
package must be installed. You can install it manually or using an extra
option for `mashumaro`:
```shell
pip install mashumaro[msgpack]
```
The following data types will be handled by
[`msgpack`](https://pypi.org/project/msgpack/) library by default:
* [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)
* [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)
Efficient decoder and encoder can be used as follows:
```python
from mashumaro.codecs.msgpack import MessagePackDecoder, MessagePackEncoder
decoder = MessagePackDecoder(, ...)
decoder.decode(...)
encoder = MessagePackEncoder(, ...)
encoder.encode(...)
```
Convenient functions can be used as follows:
```python
from mashumaro.codecs.msgpack import msgpack_decode, msgpack_encode
msgpack_decode(..., )
msgpack_encode(..., )
```
Convenient function aliases are recommended to be used as follows:
```python
import mashumaro.codecs.msgpack as msgpack_codec
msgpack_codec.decode(...)
msgpack_codec.encode(..., )
```
Mixin can be used as follows:
```python
from mashumaro.mixins.msgpack import DataClassMessagePackMixin
@dataclass
class MyModel(DataClassMessagePackMixin):
...
MyModel.from_msgpack(...)
MyModel(...).to_msgpack()
```
Customization
-------------------------------------------------------------------------------
Customization options of `mashumaro` are extensive and will most likely cover your needs.
When it comes to non-standard data types and non-standard serialization support, you can do the following:
* Turn an existing regular or generic class into a serializable one
by inheriting the [`SerializableType`](#serializabletype-interface) class
* Write different serialization strategies for an existing regular or generic type that is not under your control
using [`SerializationStrategy`](#serializationstrategy) class
* Define serialization / deserialization methods:
* for a specific dataclass field by using [field options](#field-options)
* for a specific data type used in the dataclass by using [`Config`](#config-options) class
* Alter input and output data with serialization / deserialization [hooks](#serialization-hooks)
* Separate serialization scheme from a dataclass in a reusable manner using [dialects](#dialects)
* Choose from predefined serialization engines for the specific data types, e.g. `datetime` and `NamedTuple`
### SerializableType interface
If you have a custom class or hierarchy of classes whose instances you want
to serialize with `mashumaro`, the first option is to implement
`SerializableType` interface.
#### User-defined types
Let's look at this not very practicable example:
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.types import SerializableType
class Airport(SerializableType):
def __init__(self, code, city):
self.code, self.city = code, city
def _serialize(self):
return [self.code, self.city]
@classmethod
def _deserialize(cls, value):
return cls(*value)
def __eq__(self, other):
return self.code, self.city == other.code, other.city
@dataclass
class Flight(DataClassDictMixin):
origin: Airport
destination: Airport
JFK = Airport("JFK", "New York City")
LAX = Airport("LAX", "Los Angeles")
input_data = {
"origin": ["JFK", "New York City"],
"destination": ["LAX", "Los Angeles"]
}
my_flight = Flight.from_dict(input_data)
assert my_flight == Flight(JFK, LAX)
assert my_flight.to_dict() == input_data
```
You can see how `Airport` instances are seamlessly created from lists of two
strings and serialized into them.
By default `_deserialize` method will get raw input data without any
transformations before. This should be enough in many cases, especially when
you need to perform non-standard transformations yourself, but let's extend
our example:
```python
class Itinerary(SerializableType):
def __init__(self, flights):
self.flights = flights
def _serialize(self):
return self.flights
@classmethod
def _deserialize(cls, flights):
return cls(flights)
@dataclass
class TravelPlan(DataClassDictMixin):
budget: float
itinerary: Itinerary
input_data = {
"budget": 10_000,
"itinerary": [
{
"origin": ["JFK", "New York City"],
"destination": ["LAX", "Los Angeles"]
},
{
"origin": ["LAX", "Los Angeles"],
"destination": ["SFO", "San Fransisco"]
}
]
}
```
If we pass the flight list as is into `Itinerary._deserialize`, our itinerary
will have something that we may not expect — `list[dict]` instead of
`list[Flight]`. The solution is quite simple. Instead of calling
`Flight._deserialize` yourself, just use annotations:
```python
class Itinerary(SerializableType, use_annotations=True):
def __init__(self, flights):
self.flights = flights
def _serialize(self) -> list[Flight]:
return self.flights
@classmethod
def _deserialize(cls, flights: list[Flight]):
return cls(flights)
my_plan = TravelPlan.from_dict(input_data)
assert isinstance(my_plan.itinerary.flights[0], Flight)
assert isinstance(my_plan.itinerary.flights[1], Flight)
assert my_plan.to_dict() == input_data
```
Here we add annotations to the only argument of `_deserialize` method and
to the return value of `_serialize` method as well. The latter is needed for
correct serialization.
> [!IMPORTANT]\
> The importance of explicit passing `use_annotations=True` when defining a
> class is that otherwise implicit using annotations might break compatibility
> with old code that wasn't aware of this feature. It will be enabled by
> default in the future major release.
#### User-defined generic types
The great thing to note about using annotations in `SerializableType` is that
they work seamlessly with [generic](https://docs.python.org/3/library/typing.html#user-defined-generic-types)
and [variadic generic](https://peps.python.org/pep-0646/) types.
Let's see how this can be useful:
```python
from datetime import date
from typing import TypeVar
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.types import SerializableType
KT = TypeVar("KT")
VT = TypeVar("VT")
class DictWrapper(dict[KT, VT], SerializableType, use_annotations=True):
def _serialize(self) -> dict[KT, VT]:
return dict(self)
@classmethod
def _deserialize(cls, value: dict[KT, VT]) -> 'DictWrapper[KT, VT]':
return cls(value)
@dataclass
class DataClass(DataClassDictMixin):
x: DictWrapper[date, str]
y: DictWrapper[str, date]
input_data = {
"x": {"2022-12-07": "2022-12-07"},
"y": {"2022-12-07": "2022-12-07"}
}
obj = DataClass.from_dict(input_data)
assert obj == DataClass(
x=DictWrapper({date(2022, 12, 7): "2022-12-07"}),
y=DictWrapper({"2022-12-07": date(2022, 12, 7)})
)
assert obj.to_dict() == input_data
```
You can see that formatted date is deserialized to `date` object before passing
to `DictWrapper._deserialize` in a key or value according to the generic
parameters.
If you have generic dataclass types, you can use `SerializableType` for them as well, but it's not necessary since
they're [supported](#generic-dataclasses) out of the box.
### SerializationStrategy
If you want to add support for a custom third-party type that is not under your control,
you can write serialization and deserialization logic inside `SerializationStrategy` class,
which will be reusable and so well suited in case that third-party type is widely used.
`SerializationStrategy` is also good if you want to create strategies that are slightly different from each other,
because you can add the strategy differentiator in the `__init__` method.
#### Third-party types
To demonstrate how `SerializationStrategy` works let's write a simple strategy for datetime serialization
in different formats. In this example we will use the same strategy class for two dataclass fields,
but a string representing the date and time will be different.
```python
from dataclasses import dataclass, field
from datetime import datetime
from mashumaro import DataClassDictMixin, field_options
from mashumaro.types import SerializationStrategy
class FormattedDateTime(SerializationStrategy):
def __init__(self, fmt):
self.fmt = fmt
def serialize(self, value: datetime) -> str:
return value.strftime(self.fmt)
def deserialize(self, value: str) -> datetime:
return datetime.strptime(value, self.fmt)
@dataclass
class DateTimeFormats(DataClassDictMixin):
short: datetime = field(
metadata=field_options(
serialization_strategy=FormattedDateTime("%d%m%Y%H%M%S")
)
)
verbose: datetime = field(
metadata=field_options(
serialization_strategy=FormattedDateTime("%A %B %d, %Y, %H:%M:%S")
)
)
formats = DateTimeFormats(
short=datetime(2019, 1, 1, 12),
verbose=datetime(2019, 1, 1, 12),
)
dictionary = formats.to_dict()
# {'short': '01012019120000', 'verbose': 'Tuesday January 01, 2019, 12:00:00'}
assert DateTimeFormats.from_dict(dictionary) == formats
```
Similarly to `SerializableType`, `SerializationStrategy` could also take advantage of annotations:
```python
from dataclasses import dataclass
from datetime import datetime
from mashumaro import DataClassDictMixin
from mashumaro.types import SerializationStrategy
class TsSerializationStrategy(SerializationStrategy, use_annotations=True):
def serialize(self, value: datetime) -> float:
return value.timestamp()
def deserialize(self, value: float) -> datetime:
# value will be converted to float before being passed to this method
return datetime.fromtimestamp(value)
@dataclass
class Example(DataClassDictMixin):
dt: datetime
class Config:
serialization_strategy = {
datetime: TsSerializationStrategy(),
}
example = Example.from_dict({"dt": "1672531200"})
print(example)
# Example(dt=datetime.datetime(2023, 1, 1, 3, 0))
print(example.to_dict())
# {'dt': 1672531200.0}
```
Here the passed string value `"1672531200"` will be converted to `float` before being passed to `deserialize` method
thanks to the `float` annotation.
> [!IMPORTANT]\
> As well as for `SerializableType`, the value of `use_annotatons` will be
> `True` by default in the future major release.
#### Third-party generic types
To create a generic version of a serialization strategy you need to follow these steps:
* inherit [`Generic[...]`](https://docs.python.org/3/library/typing.html#typing.Generic) type
with the number of parameters matching the number of parameters
of the target generic type
* Write generic annotations for `serialize` method's return type and for `deserialize` method's argument type
* Use the origin type of the target generic type in the [`serialization_strategy`](#serialization_strategy-config-option) config section
([`typing.get_origin`](https://docs.python.org/3/library/typing.html#typing.get_origin) might be helpful)
There is no need to add `use_annotations=True` here because it's enabled implicitly
for generic serialization strategies.
For example, there is a third-party [multidict](https://pypi.org/project/multidict/) package that has a generic `MultiDict` type.
A generic serialization strategy for it might look like this:
```python
from dataclasses import dataclass
from datetime import date
from pprint import pprint
from typing import Generic, List, Tuple, TypeVar
from mashumaro import DataClassDictMixin
from mashumaro.types import SerializationStrategy
from multidict import MultiDict
T = TypeVar("T")
class MultiDictSerializationStrategy(SerializationStrategy, Generic[T]):
def serialize(self, value: MultiDict[T]) -> List[Tuple[str, T]]:
return [(k, v) for k, v in value.items()]
def deserialize(self, value: List[Tuple[str, T]]) -> MultiDict[T]:
return MultiDict(value)
@dataclass
class Example(DataClassDictMixin):
floats: MultiDict[float]
date_lists: MultiDict[List[date]]
class Config:
serialization_strategy = {
MultiDict: MultiDictSerializationStrategy()
}
example = Example(
floats=MultiDict([("x", 1.1), ("x", 2.2)]),
date_lists=MultiDict(
[("x", [date(2023, 1, 1), date(2023, 1, 2)]),
("x", [date(2023, 2, 1), date(2023, 2, 2)])]
),
)
pprint(example.to_dict())
# {'date_lists': [['x', ['2023-01-01', '2023-01-02']],
# ['x', ['2023-02-01', '2023-02-02']]],
# 'floats': [['x', 1.1], ['x', 2.2]]}
assert Example.from_dict(example.to_dict()) == example
```
### Field options
In some cases creating a new class just for one little thing could be
excessive. Moreover, you may need to deal with third party classes that you are
not allowed to change. You can use [`dataclasses.field`](https://docs.python.org/3/library/dataclasses.html#dataclasses.field) function to
configure some serialization aspects through its `metadata` parameter. Next
section describes all supported options to use in `metadata` mapping.
If you don't want to remember the names of the options you can use
`field_options` helper function:
```python
from dataclasses import dataclass, field
from mashumaro import field_options
@dataclass
class A:
x: int = field(metadata=field_options(...))
```
#### `serialize` option
This option allows you to change the serialization method. When using
this option, the serialization behaviour depends on what type of value the
option has. It could be either `Callable[[Any], Any]` or `str`.
A value of type `Callable[[Any], Any]` is a generic way to specify any callable
object like a function, a class method, a class instance method, an instance
of a callable class or even a lambda function to be called for serialization.
A value of type `str` sets a specific engine for serialization. Keep in mind
that all possible engines depend on the data type that this option is used
with. At this moment there are next serialization engines to choose from:
| Applicable data types | Supported engines | Description |
|:---------------------------|:---------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `NamedTuple`, `namedtuple` | `as_list`, `as_dict` | How to pack named tuples. By default `as_list` engine is used that means your named tuple class instance will be packed into a list of its values. You can pack it into a dictionary using `as_dict` engine. |
| `Any` | `omit` | Skip the field during serialization |
> [!TIP]\
> You can pass a field value as is without changes on serialization using
[`pass_through`](#passing-field-values-as-is).
Example:
```python
from datetime import datetime
from dataclasses import dataclass, field
from typing import NamedTuple
from mashumaro import DataClassDictMixin
class MyNamedTuple(NamedTuple):
x: int
y: float
@dataclass
class A(DataClassDictMixin):
dt: datetime = field(
metadata={
"serialize": lambda v: v.strftime('%Y-%m-%d %H:%M:%S')
}
)
t: MyNamedTuple = field(metadata={"serialize": "as_dict"})
```
#### `deserialize` option
This option allows you to change the deserialization method. When using
this option, the deserialization behaviour depends on what type of value the
option has. It could be either `Callable[[Any], Any]` or `str`.
A value of type `Callable[[Any], Any]` is a generic way to specify any callable
object like a function, a class method, a class instance method, an instance
of a callable class or even a lambda function to be called for deserialization.
A value of type `str` sets a specific engine for deserialization. Keep in mind
that all possible engines depend on the data type that this option is used
with. At this moment there are next deserialization engines to choose from:
| Applicable data types | Supported engines | Description |
|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `datetime`, `date`, `time` | [`ciso8601`](https://github.com/closeio/ciso8601#supported-subset-of-iso-8601), [`pendulum`](https://github.com/sdispater/pendulum) | How to parse datetime string. By default native [`fromisoformat`](https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat) of corresponding class will be used for `datetime`, `date` and `time` fields. It's the fastest way in most cases, but you can choose an alternative. |
| `NamedTuple`, `namedtuple` | `as_list`, `as_dict` | How to unpack named tuples. By default `as_list` engine is used that means your named tuple class instance will be created from a list of its values. You can unpack it from a dictionary using `as_dict` engine. |
> [!TIP]\
> You can pass a field value as is without changes on deserialization using
[`pass_through`](#passing-field-values-as-is).
Example:
```python
from datetime import datetime
from dataclasses import dataclass, field
from typing import List, NamedTuple
from mashumaro import DataClassDictMixin
import ciso8601
import dateutil
class MyNamedTuple(NamedTuple):
x: int
y: float
@dataclass
class A(DataClassDictMixin):
x: datetime = field(
metadata={"deserialize": "pendulum"}
)
class B(DataClassDictMixin):
x: datetime = field(
metadata={"deserialize": ciso8601.parse_datetime_as_naive}
)
@dataclass
class C(DataClassDictMixin):
dt: List[datetime] = field(
metadata={
"deserialize": lambda l: list(map(dateutil.parser.isoparse, l))
}
)
@dataclass
class D(DataClassDictMixin):
x: MyNamedTuple = field(metadata={"deserialize": "as_dict"})
```
#### `serialization_strategy` option
This option is useful when you want to change the serialization logic
for a dataclass field depending on some defined parameters using a reusable
serialization scheme. You can find an example in the
[`SerializationStrategy`](#serializationstrategy) chapter.
> [!TIP]\
> You can pass a field value as is without changes on
> serialization / deserialization using
[`pass_through`](#passing-field-values-as-is).
#### `alias` option
This option can be used to assign [field aliases](#field-aliases):
```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin, field_options
@dataclass
class DataClass(DataClassDictMixin):
a: int = field(metadata=field_options(alias="FieldA"))
b: int = field(metadata=field_options(alias="#invalid"))
x = DataClass.from_dict({"FieldA": 1, "#invalid": 2}) # DataClass(a=1, b=2)
```
### Config options
If inheritance is not an empty word for you, you'll fall in love with the
`Config` class. You can register `serialize` and `deserialize` methods, define
code generation options and other things just in one place. Or in some
classes in different ways if you need flexibility. Inheritance is always on the
first place.
There is a base class `BaseConfig` that you can inherit for the sake of
convenience, but it's not mandatory.
In the following example you can see how
the `debug` flag is changed from class to class: `ModelA` will have debug mode enabled but
`ModelB` will not.
```python
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
class BaseModel(DataClassDictMixin):
class Config(BaseConfig):
debug = True
class ModelA(BaseModel):
a: int
class ModelB(BaseModel):
b: int
class Config(BaseConfig):
debug = False
```
Next section describes all supported options to use in the config.
#### `debug` config option
If you enable the `debug` option the generated code for your data class
will be printed.
#### `code_generation_options` config option
Some users may need functionality that wouldn't exist without extra cost such
as valuable cpu time to execute additional instructions. Since not everyone
needs such instructions, they can be enabled by a constant in the list,
so the fastest basic behavior of the library will always remain by default.
The following table provides a brief overview of all the available constants
described below.
| Constant | Description |
|:----------------------------------------------------------------|:---------------------------------------------------------------------|
| [`TO_DICT_ADD_OMIT_NONE_FLAG`](#add-omit_none-keyword-argument) | Adds `omit_none` keyword-only argument to `to_*` methods. |
| [`TO_DICT_ADD_BY_ALIAS_FLAG`](#add-by_alias-keyword-argument) | Adds `by_alias` keyword-only argument to `to_*` methods. |
| [`ADD_DIALECT_SUPPORT`](#add-dialect-keyword-argument) | Adds `dialect` keyword-only argument to `from_*` and `to_*` methods. |
| [`ADD_SERIALIZATION_CONTEXT`](#add-context-keyword-argument) | Adds `context` keyword-only argument to `to_*` methods. |
#### `serialization_strategy` config option
You can register custom [`SerializationStrategy`](#serializationstrategy), `serialize` and `deserialize`
methods for specific types just in one place. It could be configured using
a dictionary with types as keys. The value could be either a
[`SerializationStrategy`](#serializationstrategy) instance or a dictionary with `serialize` and
`deserialize` values with the same meaning as in the
[field options](#field-options).
```python
from dataclasses import dataclass
from datetime import datetime, date
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
from mashumaro.types import SerializationStrategy
class FormattedDateTime(SerializationStrategy):
def __init__(self, fmt):
self.fmt = fmt
def serialize(self, value: datetime) -> str:
return value.strftime(self.fmt)
def deserialize(self, value: str) -> datetime:
return datetime.strptime(value, self.fmt)
@dataclass
class DataClass(DataClassDictMixin):
x: datetime
y: date
class Config(BaseConfig):
serialization_strategy = {
datetime: FormattedDateTime("%Y"),
date: {
# you can use specific str values for datetime here as well
"deserialize": "pendulum",
"serialize": date.isoformat,
},
}
instance = DataClass.from_dict({"x": "2021", "y": "2021"})
# DataClass(x=datetime.datetime(2021, 1, 1, 0, 0), y=Date(2021, 1, 1))
dictionary = instance.to_dict()
# {'x': '2021', 'y': '2021-01-01'}
```
Note that you can register different methods for multiple logical types which
are based on the same type using `NewType` and `Annotated`,
see [Extending existing types](#extending-existing-types) for details.
It's also possible to define a generic (de)serialization method for a generic
type by registering a method for its
[origin](https://docs.python.org/3/library/typing.html#typing.get_origin) type.
Although this technique is widely used when working with [third-party generic
types](#third-party-generic-types) using generic strategies, it can also be
applied in simple scenarios:
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
@dataclass
class C(DataClassDictMixin):
ints: list[int]
floats: list[float]
class Config:
serialization_strategy = {
list: { # origin type for list[int] and list[float] is list
"serialize": lambda x: list(map(str, x)),
}
}
assert C([1], [2.2]).to_dict() == {'ints': ['1'], 'floats': ['2.2']}
```
#### `aliases` config option
Sometimes it's better to write the [field aliases](#field-aliases) in one place. You can mix
aliases here with [aliases in the field options](#alias-option), but the last ones will always
take precedence.
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
@dataclass
class DataClass(DataClassDictMixin):
a: int
b: int
class Config(BaseConfig):
aliases = {
"a": "FieldA",
"b": "FieldB",
}
DataClass.from_dict({"FieldA": 1, "FieldB": 2}) # DataClass(a=1, b=2)
```
#### `serialize_by_alias` config option
All the fields with [aliases](#field-aliases) will be serialized by them by
default when this option is enabled. You can mix this config option with
[`by_alias`](#add-by_alias-keyword-argument) keyword argument.
```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin, field_options
from mashumaro.config import BaseConfig
@dataclass
class DataClass(DataClassDictMixin):
field_a: int = field(metadata=field_options(alias="FieldA"))
class Config(BaseConfig):
serialize_by_alias = True
DataClass(field_a=1).to_dict() # {'FieldA': 1}
```
#### `allow_deserialization_not_by_alias` config option
When using aliases, the deserializer defaults to requiring the keys to match
what is defined as the alias.
If the flexibility to deserialize aliased and unaliased keys is required then
the config option `allow_deserialization_not_by_alias ` can be set to
enable the feature.
```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
@dataclass
class AliasedDataClass(DataClassDictMixin):
foo: int = field(metadata={"alias": "alias_foo"})
bar: int = field(metadata={"alias": "alias_bar"})
class Config(BaseConfig):
allow_deserialization_not_by_alias = True
alias_dict = {"alias_foo": 1, "alias_bar": 2}
t1 = AliasedDataClass.from_dict(alias_dict)
no_alias_dict = {"foo": 1, "bar": 2}
# This would raise `mashumaro.exceptions.MissingField`
# if allow_deserialization_not_by_alias was False
t2 = AliasedDataClass.from_dict(no_alias_dict)
assert t1 == t2
```
#### `omit_none` config option
All the fields with `None` values will be skipped during serialization by
default when this option is enabled. You can mix this config option with
[`omit_none`](#add-omit_none-keyword-argument) keyword argument.
```python
from dataclasses import dataclass
from typing import Optional
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
@dataclass
class DataClass(DataClassDictMixin):
x: Optional[int] = 42
class Config(BaseConfig):
omit_none = True
DataClass(x=None).to_dict() # {}
```
#### `omit_default` config option
When this option enabled, all the fields that have values equal to the defaults
or the default_factory results will be skipped during serialization.
```python
from dataclasses import dataclass, field
from typing import List, Optional, Tuple
from mashumaro import DataClassDictMixin, field_options
from mashumaro.config import BaseConfig
@dataclass
class Foo:
foo: str
@dataclass
class DataClass(DataClassDictMixin):
a: int = 42
b: Tuple[int, ...] = field(default=(1, 2, 3))
c: List[Foo] = field(default_factory=lambda: [Foo("foo")])
d: Optional[str] = None
class Config(BaseConfig):
omit_default = True
DataClass(a=42, b=(1, 2, 3), c=[Foo("foo")]).to_dict() # {}
```
#### `namedtuple_as_dict` config option
Dataclasses are a great way to declare and use data models. But it's not the only way.
Python has a typed version of [namedtuple](https://docs.python.org/3/library/collections.html#collections.namedtuple)
called [NamedTuple](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
which looks similar to dataclasses:
```python
from typing import NamedTuple
class Point(NamedTuple):
x: int
y: int
```
the same with a dataclass will look like this:
```python
from dataclasses import dataclass
@dataclass
class Point:
x: int
y: int
```
At first glance, you can use both options. But imagine that you need to create
a bunch of instances of the `Point` class. Due to how dataclasses work you will
have more memory consumption compared to named tuples. In such a case it could
be more appropriate to use named tuples.
By default, all named tuples are packed into lists. But with `namedtuple_as_dict`
option you have a drop-in replacement for dataclasses:
```python
from dataclasses import dataclass
from typing import List, NamedTuple
from mashumaro import DataClassDictMixin
class Point(NamedTuple):
x: int
y: int
@dataclass
class DataClass(DataClassDictMixin):
points: List[Point]
class Config:
namedtuple_as_dict = True
obj = DataClass.from_dict({"points": [{"x": 0, "y": 0}, {"x": 1, "y": 1}]})
print(obj.to_dict()) # {"points": [{"x": 0, "y": 0}, {"x": 1, "y": 1}]}
```
If you want to serialize only certain named tuple fields as dictionaries, you
can use the corresponding [serialization](#serialize-option) and
[deserialization](#deserialize-option) engines.
#### `allow_postponed_evaluation` config option
[PEP 563](https://www.python.org/dev/peps/pep-0563/) solved the problem of forward references by postponing the evaluation
of annotations, so you can write the following code:
```python
from __future__ import annotations
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
@dataclass
class A(DataClassDictMixin):
x: B
@dataclass
class B(DataClassDictMixin):
y: int
obj = A.from_dict({'x': {'y': 1}})
```
You don't need to write anything special here, forward references work out of
the box. If a field of a dataclass has a forward reference in the type
annotations, building of `from_*` and `to_*` methods of this dataclass
will be postponed until they are called once. However, if for some reason you
don't want the evaluation to be possibly postponed, you can disable it using
`allow_postponed_evaluation` option:
```python
from __future__ import annotations
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
@dataclass
class A(DataClassDictMixin):
x: B
class Config:
allow_postponed_evaluation = False
# UnresolvedTypeReferenceError: Class A has unresolved type reference B
# in some of its fields
@dataclass
class B(DataClassDictMixin):
y: int
```
In this case you will get `UnresolvedTypeReferenceError` regardless of whether
class B is declared below or not.
#### `dialect` config option
This option is described [below](#changing-the-default-dialect) in the
Dialects section.
#### `orjson_options` config option
This option changes default options for `orjson.dumps` encoder which is
used in [`DataClassORJSONMixin`](#dataclassorjsonmixin). For example, you can
tell orjson to handle non-`str` `dict` keys as the built-in `json.dumps`
encoder does. See [orjson documentation](https://github.com/ijl/orjson#option)
to read more about these options.
```python
import orjson
from dataclasses import dataclass
from typing import Dict
from mashumaro.config import BaseConfig
from mashumaro.mixins.orjson import DataClassORJSONMixin
@dataclass
class MyClass(DataClassORJSONMixin):
x: Dict[int, int]
class Config(BaseConfig):
orjson_options = orjson.OPT_NON_STR_KEYS
assert MyClass({1: 2}).to_json() == {"1": 2}
```
#### `discriminator` config option
This option is described in the
[Class level discriminator](#class-level-discriminator) section.
#### `lazy_compilation` config option
By using this option, the compilation of the `from_*` and `to_*` methods will
be deferred until they are called first time. This will reduce the import time
and, in certain instances, may enhance the speed of deserialization
by leveraging the data that is accessible after the class has been created.
> [!CAUTION]\
> If you need to save a reference to `from_*` or `to_*` method, you should
> do it after the method is compiled. To be safe, you can always use lambda
> function:
> ```python
> from_dict = lambda x: MyModel.from_dict(x)
> to_dict = lambda x: x.to_dict()
> ```
#### `sort_keys` config option
When set, the keys on serialized dataclasses will be sorted in alphabetical order.
Unlike the `sort_keys` option in the standard library's `json.dumps` function, this option acts at class creation time and has no effect on the performance of serialization.
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
@dataclass
class SortedDataClass(DataClassDictMixin):
foo: int
bar: int
class Config(BaseConfig):
sort_keys = True
t = SortedDataClass(1, 2)
assert t.to_dict() == {"bar": 2, "foo": 1}
```
#### `forbid_extra_keys` config option
When set, the deserialization of dataclasses will fail if the input dictionary contains keys that are not present in the dataclass.
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
@dataclass
class DataClass(DataClassDictMixin):
a: int
class Config(BaseConfig):
forbid_extra_keys = True
DataClass.from_dict({"a": 1, "b": 2}) # ExtraKeysError: Extra keys: {'b'}
```
It plays well with `aliases` and `allow_deserialization_not_by_alias` options.
### Passing field values as is
In some cases it's needed to pass a field value as is without any changes
during serialization / deserialization. There is a predefined
[`pass_through`](https://github.com/Fatal1ty/mashumaro/blob/master/mashumaro/helper.py#L58)
object that can be used as `serialization_strategy` or
`serialize` / `deserialize` options:
```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin, pass_through
class MyClass:
def __init__(self, some_value):
self.some_value = some_value
@dataclass
class A1(DataClassDictMixin):
x: MyClass = field(
metadata={
"serialize": pass_through,
"deserialize": pass_through,
}
)
@dataclass
class A2(DataClassDictMixin):
x: MyClass = field(
metadata={
"serialization_strategy": pass_through,
}
)
@dataclass
class A3(DataClassDictMixin):
x: MyClass
class Config:
serialization_strategy = {
MyClass: pass_through,
}
@dataclass
class A4(DataClassDictMixin):
x: MyClass
class Config:
serialization_strategy = {
MyClass: {
"serialize": pass_through,
"deserialize": pass_through,
}
}
my_class_instance = MyClass(42)
assert A1.from_dict({'x': my_class_instance}).x == my_class_instance
assert A2.from_dict({'x': my_class_instance}).x == my_class_instance
assert A3.from_dict({'x': my_class_instance}).x == my_class_instance
assert A4.from_dict({'x': my_class_instance}).x == my_class_instance
a1_dict = A1(my_class_instance).to_dict()
a2_dict = A2(my_class_instance).to_dict()
a3_dict = A3(my_class_instance).to_dict()
a4_dict = A4(my_class_instance).to_dict()
assert a1_dict == a2_dict == a3_dict == a4_dict == {"x": my_class_instance}
```
### Extending existing types
There are situations where you might want some values of the same type to be
treated as their own type. You can create new logical types with
[`NewType`](https://docs.python.org/3/library/typing.html#newtype),
[`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
or [`TypeAliasType`](https://docs.python.org/3/library/typing.html#typing.TypeAliasType)
and register serialization strategies for them:
```python
from typing import Mapping, NewType, Annotated
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
SessionID = NewType("SessionID", str)
AccountID = Annotated[str, "AccountID"]
type DeviceID = str
@dataclass
class Context(DataClassDictMixin):
account_sessions: Mapping[AccountID, SessionID]
account_devices: list[DeviceID]
class Config:
serialization_strategy = {
AccountID: {
"deserialize": lambda x: ...,
"serialize": lambda x: ...,
},
SessionID: {
"deserialize": lambda x: ...,
"serialize": lambda x: ...,
},
DeviceID: {
"deserialize": lambda x: ...,
"serialize": lambda x: ...,
}
}
```
Although using `NewType` is usually the most reliable way to avoid logical
errors, you have to pay for it with notable overhead. If you are creating
dataclass instances manually, then you know that type checkers will
enforce you to enclose a value in your `"NewType"` callable, which leads
to performance degradation:
```python
python -m timeit -s "from typing import NewType; MyInt = NewType('MyInt', int)" "MyInt(42)"
10000000 loops, best of 5: 31.1 nsec per loop
python -m timeit -s "from typing import NewType; MyInt = NewType('MyInt', int)" "42"
50000000 loops, best of 5: 4.35 nsec per loop
```
However, when you create dataclass instances using the `from_*` method provided
by one of the mixins or using one of the decoders, there will be no performance
degradation, because the value won't be enclosed in the callable in the
generated code. Therefore, if performance is more important to you than
catching logical errors by type checkers, and you are actively creating or
changing dataclasses manually, then you should take a closer look at using
`Annotated`.
### Field aliases
In some cases it's better to have different names for a field in your dataclass
and in its serialized view. For example, a third-party legacy API you are
working with might operate with camel case style, but you stick to snake case
style in your code base. Or you want to load data with keys that are
invalid identifiers in Python. Aliases can solve this problem.
There are multiple ways to assign an alias:
* Using `Alias(...)` annotation in a field type
* Using `alias` parameter in field metadata
* Using `aliases` parameter in a dataclass config
By default, aliases only affect deserialization, but it can be extended to
serialization as well. If you want to serialize all the fields by aliases you
have two options to do so:
* [`serialize_by_alias` config option](#serialize_by_alias-config-option)
* [`serialize_by_alias` dialect option](#serialize_by_alias-dialect-option)
* [`by_alias` keyword argument in `to_*` methods](#add-by_alias-keyword-argument)
Here is an example with `Alias` annotation in a field type:
```python
from dataclasses import dataclass
from typing import Annotated
from mashumaro import DataClassDictMixin
from mashumaro.types import Alias
@dataclass
class DataClass(DataClassDictMixin):
foo_bar: Annotated[int, Alias("fooBar")]
obj = DataClass.from_dict({"fooBar": 42}) # DataClass(foo_bar=42)
obj.to_dict() # {"foo_bar": 42} # no aliases on serialization by default
```
The same with field metadata:
```python
from dataclasses import dataclass, field
from mashumaro import field_options
@dataclass
class DataClass:
foo_bar: str = field(metadata=field_options(alias="fooBar"))
```
And with a dataclass config:
```python
from dataclasses import dataclass
from mashumaro.config import BaseConfig
@dataclass
class DataClass:
foo_bar: str
class Config(BaseConfig):
aliases = {"foo_bar": "fooBar"}
```
> [!TIP]\
> If you want to deserialize all the fields by its names along with aliases,
> there is [a config option](#allow_deserialization_not_by_alias-config-option)
> for that.
### Dialects
Sometimes it's needed to have different serialization and deserialization
methods depending on the data source where entities of the dataclass are
stored or on the API to which the entities are being sent or received from.
There is a special `Dialect` type that may contain all the differences from the
default serialization and deserialization methods. You can create different
dialects and use each of them for the same dataclass depending on
the situation.
Suppose we have the following dataclass with a field of type `date`:
```python
@dataclass
class Entity(DataClassDictMixin):
dt: date
```
By default, a field of `date` type serializes to a string in ISO 8601 format,
so the serialized entity will look like `{'dt': '2021-12-31'}`. But what if we
have, for example, two sensitive legacy Ethiopian and Japanese APIs that use
two different formats for dates — `dd/mm/yyyy` and `yyyy年mm月dd日`? Instead of
creating two similar dataclasses we can have one dataclass and two dialects:
```python
from dataclasses import dataclass
from datetime import date, datetime
from mashumaro import DataClassDictMixin
from mashumaro.config import ADD_DIALECT_SUPPORT
from mashumaro.dialect import Dialect
from mashumaro.types import SerializationStrategy
class DateTimeSerializationStrategy(SerializationStrategy):
def __init__(self, fmt: str):
self.fmt = fmt
def serialize(self, value: date) -> str:
return value.strftime(self.fmt)
def deserialize(self, value: str) -> date:
return datetime.strptime(value, self.fmt).date()
class EthiopianDialect(Dialect):
serialization_strategy = {
date: DateTimeSerializationStrategy("%d/%m/%Y")
}
class JapaneseDialect(Dialect):
serialization_strategy = {
date: DateTimeSerializationStrategy("%Y年%m月%d日")
}
@dataclass
class Entity(DataClassDictMixin):
dt: date
class Config:
code_generation_options = [ADD_DIALECT_SUPPORT]
entity = Entity(date(2021, 12, 31))
entity.to_dict(dialect=EthiopianDialect) # {'dt': '31/12/2021'}
entity.to_dict(dialect=JapaneseDialect) # {'dt': '2021年12月31日'}
Entity.from_dict({'dt': '2021年12月31日'}, dialect=JapaneseDialect)
```
#### `serialization_strategy` dialect option
This dialect option has the same meaning as the
[similar config option](#serialization_strategy-config-option)
but for the dialect scope. You can register custom [`SerializationStrategy`](#serializationstrategy),
`serialize` and `deserialize` methods for the specific types.
#### `serialize_by_alias` dialect option
This dialect option has the same meaning as the
[similar config option](#serialize_by_alias-config-option)
but for the dialect scope.
#### `omit_none` dialect option
This dialect option has the same meaning as the
[similar config option](#omit_none-config-option) but for the dialect scope.
#### `omit_default` dialect option
This dialect option has the same meaning as the
[similar config option](#omitdefault-config-option) but for the dialect scope.
#### `namedtuple_as_dict` dialect option
This dialect option has the same meaning as the
[similar config option](#namedtuple_as_dict-config-option)
but for the dialect scope.
#### `no_copy_collections` dialect option
By default, all collection data types are serialized as a copy to prevent
mutation of the original collection. As an example, if a dataclass contains
a field of type `list[str]`, then it will be serialized as a copy of the
original list, so you can safely mutate it after. The downside is that copying
is always slower than using a reference to the original collection. In some
cases we know beforehand that mutation doesn't take place or is even desirable,
so we can benefit from avoiding unnecessary copies by setting
`no_copy_collections` to a sequence of origin collection data types.
This is applicable only for collections containing elements that do not
require conversion.
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
from mashumaro.dialect import Dialect
class NoCopyDialect(Dialect):
no_copy_collections = (list, dict, set)
@dataclass
class DataClass(DataClassDictMixin):
simple_list: list[str]
simple_dict: dict[str, str]
simple_set: set[str]
class Config(BaseConfig):
dialect = NoCopyDialect
obj = DataClass(["foo"], {"bar": "baz"}, {"foobar"})
data = obj.to_dict()
assert data["simple_list"] is obj.simple_list
assert data["simple_dict"] is obj.simple_dict
assert data["simple_set"] is obj.simple_set
```
This option is enabled for `list` and `dict` in the default dialects that
belong to mixins and codecs for the following formats:
* [JSON (orjson library)](#orjson-library)
* [TOML](#toml)
* [MessagePack](#messagepack)
#### Changing the default dialect
You can change the default serialization and deserialization methods not only
in the [`serialization_strategy`](#serialization_strategy-config-option) config
option but also using the `dialect` config option. If you have multiple
dataclasses without a common parent class the default dialect can help you
to reduce the number of code lines written:
```python
@dataclass
class Entity(DataClassDictMixin):
dt: date
class Config:
dialect = JapaneseDialect
entity = Entity(date(2021, 12, 31))
entity.to_dict() # {'dt': '2021年12月31日'}
assert Entity.from_dict({'dt': '2021年12月31日'}) == entity
```
Default dialect can also be set when using codecs:
```python
from mashumaro.codecs import BasicDecoder, BasicEncoder
@dataclass
class Entity:
dt: date
decoder = BasicDecoder(Entity, default_dialect=JapaneseDialect)
encoder = BasicEncoder(Entity, default_dialect=JapaneseDialect)
entity = Entity(date(2021, 12, 31))
encoder.encode(entity) # {'dt': '2021年12月31日'}
assert decoder.decode({'dt': '2021年12月31日'}) == entity
```
### Discriminator
There is a special `Discriminator` class that allows you to customize how
a union of dataclasses or their hierarchy will be deserialized.
It has the following parameters that affects class selection rules:
* `field` — optional name of the input dictionary key (also known as tag)
by which all the variants can be distinguished
* `include_subtypes` — allow to deserialize subclasses
* `include_supertypes` — allow to deserialize superclasses
* `variant_tagger_fn` — a custom function used to generate tag values
associated with a variant
By default, each variant that you want to discriminate by tags should have a
class-level attribute containing an associated tag value. This attribute should
have a name defined by `field` parameter. The tag value coule be in the
following forms:
* without annotations: `type = 42`
* annotated as ClassVar: `type: ClassVar[int] = 42`
* annotated as Final: `type: Final[int] = 42`
* annotated as Literal: `type: Literal[42] = 42`
* annotated as StrEnum: `type: ResponseType = ResponseType.OK`
> [!NOTE]\
> Keep in mind that by default only Final, Literal and StrEnum fields are
> processed during serialization.
However, it is possible to use discriminator without the class-level
attribute. You can provide a custom function that generates one or many variant
tag values. This function should take a class as the only argument and return
either a single value of the basic type like `str` or `int` or a list of them
to associate multiple tags with a variant. The common practice is to use
a class name as a single tag value:
```python
variant_tagger_fn = lambda cls: cls.__name__
```
Next, we will look at different use cases, as well as their pros and cons.
#### Subclasses distinguishable by a field
Often you have a base dataclass and multiple subclasses that are easily
distinguishable from each other by the value of a particular field.
For example, there may be different events, messages or requests with
a discriminator field "event_type", "message_type" or just "type". You could've
listed all of them within `Union` type, but it would be too verbose and
impractical. Moreover, deserialization of the union would be slow, since we
need to iterate over each variant in the list until we find the right one.
We can improve subclass deserialization using `Discriminator` as annotation
within `Annotated` type. We will use `field` parameter and set
`include_subtypes` to `True`.
> [!IMPORTANT]\
> The discriminator field should be accessible from the `__dict__` attribute
> of a specific descendant, i.e. defined at the level of that descendant.
> A descendant class without a discriminator field will be ignored, but
> its descendants won't.
Suppose we have a hierarchy of client events distinguishable by a class
attribute "type":
```python
from dataclasses import dataclass
from ipaddress import IPv4Address
from mashumaro import DataClassDictMixin
@dataclass
class ClientEvent(DataClassDictMixin):
pass
@dataclass
class ClientConnectedEvent(ClientEvent):
type = "connected"
client_ip: IPv4Address
@dataclass
class ClientDisconnectedEvent(ClientEvent):
type = "disconnected"
client_ip: IPv4Address
```
We use base dataclass `ClientEvent` for a field of another dataclass:
```python
from typing import Annotated, List
# or from typing_extensions import Annotated
from mashumaro.types import Discriminator
@dataclass
class AggregatedEvents(DataClassDictMixin):
list: List[
Annotated[
ClientEvent, Discriminator(field="type", include_subtypes=True)
]
]
```
Now we can deserialize events based on "type" value:
```python
events = AggregatedEvents.from_dict(
{
"list": [
{"type": "connected", "client_ip": "10.0.0.42"},
{"type": "disconnected", "client_ip": "10.0.0.42"},
]
}
)
assert events == AggregatedEvents(
list=[
ClientConnectedEvent(client_ip=IPv4Address("10.0.0.42")),
ClientDisconnectedEvent(client_ip=IPv4Address("10.0.0.42")),
]
)
```
#### Subclasses without a common field
In rare cases you have to deal with subclasses that don't have a common field
name which they can be distinguished by. Since `Discriminator` can be
initialized without "field" parameter you can use it with only
`include_subclasses` enabled. The drawback is that we will have to go through all
the subclasses until we find the suitable one. It's almost like using `Union`
type but with subclasses support.
Suppose we're making a brunch. We have some ingredients:
```python
@dataclass
class Ingredient(DataClassDictMixin):
name: str
@dataclass
class Hummus(Ingredient):
made_of: Literal["chickpeas", "beet", "artichoke"]
grams: int
@dataclass
class Celery(Ingredient):
pieces: int
```
Let's create a plate:
```python
@dataclass
class Plate(DataClassDictMixin):
ingredients: List[
Annotated[Ingredient, Discriminator(include_subtypes=True)]
]
```
And now we can put our ingredients on the plate:
```python
plate = Plate.from_dict(
{
"ingredients": [
{
"name": "hummus from the shop",
"made_of": "chickpeas",
"grams": 150,
},
{"name": "celery from my garden", "pieces": 5},
]
}
)
assert plate == Plate(
ingredients=[
Hummus(name="hummus from the shop", made_of="chickpeas", grams=150),
Celery(name="celery from my garden", pieces=5),
]
)
```
In some cases it's necessary to fall back to the base class if there is no
suitable subclass. We can set `include_supertypes` to `True`:
```python
@dataclass
class Plate(DataClassDictMixin):
ingredients: List[
Annotated[
Ingredient,
Discriminator(include_subtypes=True, include_supertypes=True),
]
]
plate = Plate.from_dict(
{
"ingredients": [
{
"name": "hummus from the shop",
"made_of": "chickpeas",
"grams": 150,
},
{"name": "celery from my garden", "pieces": 5},
{"name": "cumin"} # <- new unknown ingredient
]
}
)
assert plate == Plate(
ingredients=[
Hummus(name="hummus from the shop", made_of="chickpeas", grams=150),
Celery(name="celery from my garden", pieces=5),
Ingredient(name="cumin"), # <- unknown ingredient added
]
)
```
#### Class level discriminator
It may often be more convenient to specify a `Discriminator` once at the class
level and use that class without `Annotated` type for subclass deserialization.
Depending on the `Discriminator` parameters, it can be used as a replacement for
[subclasses distinguishable by a field](#subclasses-distinguishable-by-a-field)
as well as for [subclasses without a common field](#subclasses-without-a-common-field).
The only difference is that you can't use `include_supertypes=True` because
it would lead to a recursion error.
Reworked example will look like this:
```python
from dataclasses import dataclass
from ipaddress import IPv4Address
from typing import List
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
from mashumaro.types import Discriminator
@dataclass
class ClientEvent(DataClassDictMixin):
class Config(BaseConfig):
discriminator = Discriminator( # <- add discriminator
field="type",
include_subtypes=True,
)
@dataclass
class ClientConnectedEvent(ClientEvent):
type = "connected"
client_ip: IPv4Address
@dataclass
class ClientDisconnectedEvent(ClientEvent):
type = "disconnected"
client_ip: IPv4Address
@dataclass
class AggregatedEvents(DataClassDictMixin):
list: List[ClientEvent] # <- use base class here
```
And now we can deserialize events based on "type" value as we did earlier:
```python
events = AggregatedEvents.from_dict(
{
"list": [
{"type": "connected", "client_ip": "10.0.0.42"},
{"type": "disconnected", "client_ip": "10.0.0.42"},
]
}
)
assert events == AggregatedEvents(
list=[
ClientConnectedEvent(client_ip=IPv4Address("10.0.0.42")),
ClientDisconnectedEvent(client_ip=IPv4Address("10.0.0.42")),
]
)
```
What's more interesting is that you can now deserialize subclasses simply by
calling the superclass `from_*` method, which is very useful:
```python
disconnected_event = ClientEvent.from_dict(
{"type": "disconnected", "client_ip": "10.0.0.42"}
)
assert disconnected_event == ClientDisconnectedEvent(IPv4Address("10.0.0.42"))
```
The same is applicable for subclasses without a common field:
```python
@dataclass
class Ingredient(DataClassDictMixin):
name: str
class Config:
discriminator = Discriminator(include_subtypes=True)
...
celery = Ingredient.from_dict({"name": "celery from my garden", "pieces": 5})
assert celery == Celery(name="celery from my garden", pieces=5)
```
#### Working with union of classes
Deserialization of union of types distinguishable by a particular field will
be much faster using `Discriminator` because there will be no traversal
of all classes and an attempt to deserialize each of them.
Usually this approach can be used when you have multiple classes without a
common superclass or when you only need to deserialize some of the subclasses.
In the following example we will use `include_supertypes=True` to
deserialize two subclasses out of three:
```python
from dataclasses import dataclass
from typing import Annotated, Literal, Union
# or from typing_extensions import Annotated
from mashumaro import DataClassDictMixin
from mashumaro.types import Discriminator
@dataclass
class Event(DataClassDictMixin):
pass
@dataclass
class Event1(Event):
code: Literal[1] = 1
...
@dataclass
class Event2(Event):
code: Literal[2] = 2
...
@dataclass
class Event3(Event):
code: Literal[3] = 3
...
@dataclass
class Message(DataClassDictMixin):
event: Annotated[
Union[Event1, Event2],
Discriminator(field="code", include_supertypes=True),
]
event1_msg = Message.from_dict({"event": {"code": 1, ...}})
event2_msg = Message.from_dict({"event": {"code": 2, ...}})
assert isinstance(event1_msg.event, Event1)
assert isinstance(event2_msg.event, Event2)
# raises InvalidFieldValue:
Message.from_dict({"event": {"code": 3, ...}})
```
Again, it's not necessary to have a common superclass. If you have a union of
dataclasses without a field that they can be distinguishable by, you can still
use `Discriminator`, but deserialization will almost be the same as for `Union`
type without `Discriminator` except that it could be possible to deserialize
subclasses with `include_subtypes=True`.
> [!IMPORTANT]\
> When both `include_subtypes` and `include_supertypes` are enabled,
> all subclasses will be attempted to be deserialized first,
> superclasses — at the end.
In the following example you can see how priority works — first we try
to deserialize `ChickpeaHummus`, and if it fails, then we try `Hummus`:
```python
@dataclass
class Hummus(DataClassDictMixin):
made_of: Literal["chickpeas", "artichoke"]
grams: int
@dataclass
class ChickpeaHummus(Hummus):
made_of: Literal["chickpeas"]
@dataclass
class Celery(DataClassDictMixin):
pieces: int
@dataclass
class Plate(DataClassDictMixin):
ingredients: List[
Annotated[
Union[Hummus, Celery],
Discriminator(include_subtypes=True, include_supertypes=True),
]
]
plate = Plate.from_dict(
{
"ingredients": [
{"made_of": "chickpeas", "grams": 100},
{"made_of": "artichoke", "grams": 50},
{"pieces": 4},
]
}
)
assert plate == Plate(
ingredients=[
ChickpeaHummus(made_of='chickpeas', grams=100), # <- subclass
Hummus(made_of='artichoke', grams=50), # <- superclass
Celery(pieces=4),
]
)
```
#### Using a custom variant tagger function
Sometimes it is impractical to have a class-level attribute with a tag value,
especially when you have a lot of classes. We can have a custom tagger
function instead. This method is applicable for all scenarios of using
the discriminator, but for demonstration purposes, let's focus only on one
of them.
Suppose we want to use the middle part of `Client*Event` as a tag value:
```python
from dataclasses import dataclass
from ipaddress import IPv4Address
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig
from mashumaro.types import Discriminator
def client_event_tagger(cls):
# not the best way of doing it, it's just a demo
return cls.__name__[6:-5].lower()
@dataclass
class ClientEvent(DataClassDictMixin):
class Config(BaseConfig):
discriminator = Discriminator(
field="type",
include_subtypes=True,
variant_tagger_fn=client_event_tagger,
)
@dataclass
class ClientConnectedEvent(ClientEvent):
client_ip: IPv4Address
@dataclass
class ClientDisconnectedEvent(ClientEvent):
client_ip: IPv4Address
```
We can now deserialize subclasses as we did it earlier
[without variant tagger](#class-level-discriminator):
```python
disconnected_event = ClientEvent.from_dict(
{"type": "disconnected", "client_ip": "10.0.0.42"}
)
assert disconnected_event == ClientDisconnectedEvent(IPv4Address("10.0.0.42"))
```
If we need to associate multiple tags with a single variant, we can return
a list of tags:
```python
def client_event_tagger(cls):
name = cls.__name__[6:-5]
return [name.lower(), name.upper()]
```
### Code generation options
#### Add `omit_none` keyword argument
If you want to have control over whether to skip `None` values on serialization
you can add `omit_none` parameter to `to_*` methods using the
`code_generation_options` list. The default value of `omit_none`
parameter depends on whether the [`omit_none`](#omit_none-config-option)
config option or [`omit_none`](#omit_none-dialect-option) dialect option is enabled.
```python
from dataclasses import dataclass
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig, TO_DICT_ADD_OMIT_NONE_FLAG
@dataclass
class Inner(DataClassDictMixin):
x: int = None
# "x" won't be omitted since there is no TO_DICT_ADD_OMIT_NONE_FLAG here
@dataclass
class Model(DataClassDictMixin):
x: Inner
a: int = None
b: str = None # will be omitted
class Config(BaseConfig):
code_generation_options = [TO_DICT_ADD_OMIT_NONE_FLAG]
Model(x=Inner(), a=1).to_dict(omit_none=True) # {'x': {'x': None}, 'a': 1}
```
#### Add `by_alias` keyword argument
If you want to have control over whether to serialize fields by their
[aliases](#field-aliases) you can add `by_alias` parameter to `to_*` methods
using the `code_generation_options` list. The default value of `by_alias`
parameter depends on whether the [`serialize_by_alias`](#serialize_by_alias-config-option)
config option is enabled.
```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin, field_options
from mashumaro.config import BaseConfig, TO_DICT_ADD_BY_ALIAS_FLAG
@dataclass
class DataClass(DataClassDictMixin):
field_a: int = field(metadata=field_options(alias="FieldA"))
class Config(BaseConfig):
code_generation_options = [TO_DICT_ADD_BY_ALIAS_FLAG]
DataClass(field_a=1).to_dict() # {'field_a': 1}
DataClass(field_a=1).to_dict(by_alias=True) # {'FieldA': 1}
```
#### Add `dialect` keyword argument
Support for [dialects](#dialects) is disabled by default for performance reasons. You can enable
it using a `ADD_DIALECT_SUPPORT` constant:
```python
from dataclasses import dataclass
from datetime import date
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig, ADD_DIALECT_SUPPORT
@dataclass
class Entity(DataClassDictMixin):
dt: date
class Config(BaseConfig):
code_generation_options = [ADD_DIALECT_SUPPORT]
```
#### Add `context` keyword argument
Sometimes it's needed to pass a "context" object to the serialization hooks
that will take it into account. For example, you could want to have an option
to remove sensitive data from the serialization result if you need to.
You can add `context` parameter to `to_*` methods that will be passed to
[`__pre_serialize__`](#before-serialization) and
[`__post_serialize__`](#after-serialization) hooks. The type of this context
as well as its mutability is up to you.
```python
from dataclasses import dataclass
from typing import Dict, Optional
from uuid import UUID
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig, ADD_SERIALIZATION_CONTEXT
class BaseModel(DataClassDictMixin):
class Config(BaseConfig):
code_generation_options = [ADD_SERIALIZATION_CONTEXT]
@dataclass
class Account(BaseModel):
id: UUID
username: str
name: str
def __pre_serialize__(self, context: Optional[Dict] = None):
return self
def __post_serialize__(self, d: Dict, context: Optional[Dict] = None):
if context and context.get("remove_sensitive_data"):
d["username"] = "***"
d["name"] = "***"
return d
@dataclass
class Session(BaseModel):
id: UUID
key: str
account: Account
def __pre_serialize__(self, context: Optional[Dict] = None):
return self
def __post_serialize__(self, d: Dict, context: Optional[Dict] = None):
if context and context.get("remove_sensitive_data"):
d["key"] = "***"
return d
foo = Session(
id=UUID('03321c9f-6a97-421e-9869-918ff2867a71'),
key="VQ6Q9bX4c8s",
account=Account(
id=UUID('4ef2baa7-edef-4d6a-b496-71e6d72c58fb'),
username="john_doe",
name="John"
)
)
assert foo.to_dict() == {
'id': '03321c9f-6a97-421e-9869-918ff2867a71',
'key': 'VQ6Q9bX4c8s',
'account': {
'id': '4ef2baa7-edef-4d6a-b496-71e6d72c58fb',
'username': 'john_doe',
'name': 'John'
}
}
assert foo.to_dict(context={"remove_sensitive_data": True}) == {
'id': '03321c9f-6a97-421e-9869-918ff2867a71',
'key': '***',
'account': {
'id': '4ef2baa7-edef-4d6a-b496-71e6d72c58fb',
'username': '***',
'name': '***'
}
}
```
### Generic dataclasses
Along with [user-defined generic types](#user-defined-generic-types)
implementing `SerializableType` interface, generic and variadic
generic dataclasses can also be used. There are two applicable scenarios
for them.
#### Generic dataclass inheritance
If you have a generic dataclass and want to serialize and deserialize its
instances depending on the concrete types, you can use inheritance for that:
```python
from dataclasses import dataclass
from datetime import date
from typing import Generic, Mapping, TypeVar, TypeVarTuple
from mashumaro import DataClassDictMixin
KT = TypeVar("KT")
VT = TypeVar("VT", date, str)
Ts = TypeVarTuple("Ts")
@dataclass
class GenericDataClass(Generic[KT, VT, *Ts]):
x: Mapping[KT, VT]
y: Tuple[*Ts, KT]
@dataclass
class ConcreteDataClass(
GenericDataClass[str, date, *Tuple[float, ...]],
DataClassDictMixin,
):
pass
ConcreteDataClass.from_dict({"x": {"a": "2021-01-01"}, "y": [1, 2, "a"]})
# ConcreteDataClass(x={'a': datetime.date(2021, 1, 1)}, y=(1.0, 2.0, 'a'))
```
You can override `TypeVar` field with a concrete type or another `TypeVar`.
Partial specification of concrete types is also allowed. If a generic dataclass
is inherited without type overriding the types of its fields remain untouched.
#### Generic dataclass in a field type
Another approach is to specify concrete types in the field type hints. This can
help to have different versions of the same generic dataclass:
```python
from dataclasses import dataclass
from datetime import date
from typing import Generic, TypeVar
from mashumaro import DataClassDictMixin
T = TypeVar('T')
@dataclass
class GenericDataClass(Generic[T], DataClassDictMixin):
x: T
@dataclass
class DataClass(DataClassDictMixin):
date: GenericDataClass[date]
str: GenericDataClass[str]
instance = DataClass(
date=GenericDataClass(x=date(2021, 1, 1)),
str=GenericDataClass(x='2021-01-01'),
)
dictionary = {'date': {'x': '2021-01-01'}, 'str': {'x': '2021-01-01'}}
assert DataClass.from_dict(dictionary) == instance
```
### GenericSerializableType interface
There is a generic alternative to [`SerializableType`](#serializabletype-interface)
called `GenericSerializableType`. It makes it possible to decide yourself how
to serialize and deserialize input data depending on the types provided:
```python
from dataclasses import dataclass
from datetime import date
from typing import Dict, TypeVar
from mashumaro import DataClassDictMixin
from mashumaro.types import GenericSerializableType
KT = TypeVar("KT")
VT = TypeVar("VT")
class DictWrapper(Dict[KT, VT], GenericSerializableType):
__packers__ = {date: lambda x: x.isoformat(), str: str}
__unpackers__ = {date: date.fromisoformat, str: str}
def _serialize(self, types) -> Dict[KT, VT]:
k_type, v_type = types
k_conv = self.__packers__[k_type]
v_conv = self.__packers__[v_type]
return {k_conv(k): v_conv(v) for k, v in self.items()}
@classmethod
def _deserialize(cls, value, types) -> "DictWrapper[KT, VT]":
k_type, v_type = types
k_conv = cls.__unpackers__[k_type]
v_conv = cls.__unpackers__[v_type]
return cls({k_conv(k): v_conv(v) for k, v in value.items()})
@dataclass
class DataClass(DataClassDictMixin):
x: DictWrapper[date, str]
y: DictWrapper[str, date]
input_data = {
"x": {"2022-12-07": "2022-12-07"},
"y": {"2022-12-07": "2022-12-07"},
}
obj = DataClass.from_dict(input_data)
assert obj == DataClass(
x=DictWrapper({date(2022, 12, 7): "2022-12-07"}),
y=DictWrapper({"2022-12-07": date(2022, 12, 7)}),
)
assert obj.to_dict() == input_data
```
As you can see, the code turns out to be massive compared to the
[alternative](#user-defined-generic-types) but in rare cases such flexibility
can be useful. You should think twice about whether it's really worth using it.
### Serialization hooks
In some cases you need to prepare input / output data or do some extraordinary
actions at different stages of the deserialization / serialization lifecycle.
You can do this with different types of hooks.
#### Before deserialization
For doing something with a dictionary that will be passed to deserialization
you can use `__pre_deserialize__` class method:
```python
@dataclass
class A(DataClassJSONMixin):
abc: int
@classmethod
def __pre_deserialize__(cls, d: Dict[Any, Any]) -> Dict[Any, Any]:
return {k.lower(): v for k, v in d.items()}
print(DataClass.from_dict({"ABC": 123})) # DataClass(abc=123)
print(DataClass.from_json('{"ABC": 123}')) # DataClass(abc=123)
```
#### After deserialization
For doing something with a dataclass instance that was created as a result
of deserialization you can use `__post_deserialize__` class method:
```python
@dataclass
class A(DataClassJSONMixin):
abc: int
@classmethod
def __post_deserialize__(cls, obj: 'A') -> 'A':
obj.abc = 456
return obj
print(DataClass.from_dict({"abc": 123})) # DataClass(abc=456)
print(DataClass.from_json('{"abc": 123}')) # DataClass(abc=456)
```
#### Before serialization
For doing something before serialization you can use `__pre_serialize__`
method:
```python
@dataclass
class A(DataClassJSONMixin):
abc: int
counter: ClassVar[int] = 0
def __pre_serialize__(self) -> 'A':
self.counter += 1
return self
obj = DataClass(abc=123)
obj.to_dict()
obj.to_json()
print(obj.counter) # 2
```
Note that you can add an additional `context` argument using the
[corresponding](#add-context-keyword-argument) code generation option.
#### After serialization
For doing something with a dictionary that was created as a result of
serialization you can use `__post_serialize__` method:
```python
@dataclass
class A(DataClassJSONMixin):
user: str
password: str
def __post_serialize__(self, d: Dict[Any, Any]) -> Dict[Any, Any]:
d.pop('password')
return d
obj = DataClass(user="name", password="secret")
print(obj.to_dict()) # {"user": "name"}
print(obj.to_json()) # '{"user": "name"}'
```
Note that you can add an additional `context` argument using the
[corresponding](#add-context-keyword-argument) code generation option.
JSON Schema
-------------------------------------------------------------------------------
You can build JSON Schema not only for dataclasses but also for any other
[supported](#supported-data-types) data
types. There is support for the following standards:
* [Draft 2020-12](https://json-schema.org/specification.html)
* [OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)
### Building JSON Schema
For simple one-time cases it's recommended to start from using a configurable
`build_json_schema` function. It returns `JSONSchema` object that can be
serialized to json or to dict:
```python
from dataclasses import dataclass, field
from typing import List
from uuid import UUID
from mashumaro.jsonschema import build_json_schema
@dataclass
class User:
id: UUID
name: str = field(metadata={"description": "User name"})
print(build_json_schema(List[User]).to_json())
```
Click to show the result
```json
{
"type": "array",
"items": {
"type": "object",
"title": "User",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "User name"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
}
}
```
Additional validation keywords ([see below](#json-schema-constraints))
can be added using annotations:
```python
from typing import Annotated, List
from mashumaro.jsonschema import build_json_schema
from mashumaro.jsonschema.annotations import Maximum, MaxItems
print(
build_json_schema(
Annotated[
List[Annotated[int, Maximum(42)]],
MaxItems(4)
]
).to_json()
)
```
Click to show the result
```json
{
"type": "array",
"items": {
"type": "integer",
"maximum": 42
},
"maxItems": 4
}
```
The [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-schema-keyword)
keyword can be added by setting `with_dialect_uri` to True:
```python
print(build_json_schema(str, with_dialect_uri=True).to_json())
```
Click to show the result
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "string"
}
```
By default, Draft 2022-12 dialect is being used, but you can change it to
another one by setting `dialect` parameter:
```python
from mashumaro.jsonschema import OPEN_API_3_1
print(
build_json_schema(
str, dialect=OPEN_API_3_1, with_dialect_uri=True
).to_json()
)
```
Click to show the result
```json
{
"$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
"type": "string"
}
```
All dataclass JSON Schemas can or can not be placed in the
[definitions](https://json-schema.org/draft/2020-12/json-schema-core.html#name-schema-re-use-with-defs)
section, depending on the `all_refs` parameter, which default value comes
from a dialect used (`False` for Draft 2022-12, `True` for OpenAPI
Specification 3.1.0):
```python
print(build_json_schema(List[User], all_refs=True).to_json())
```
Click to show the result
```json
{
"type": "array",
"$defs": {
"User": {
"type": "object",
"title": "User",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
}
},
"items": {
"$ref": "#/$defs/User"
}
}
```
The definitions section can be omitted from the final document by setting
`with_definitions` parameter to `False`:
```python
print(
build_json_schema(
List[User], dialect=OPEN_API_3_1, with_definitions=False
).to_json()
)
```
Click to show the result
```json
{
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
```
Reference prefix can be changed by using `ref_prefix` parameter:
```python
print(
build_json_schema(
List[User],
all_refs=True,
with_definitions=False,
ref_prefix="#/components/responses",
).to_json()
)
```
Click to show the result
```json
{
"type": "array",
"items": {
"$ref": "#/components/responses/User"
}
}
```
The omitted definitions could be found later in the `Context` object that
you could have created and passed to the function, but it could be easier
to use `JSONSchemaBuilder` for that. For example, you might found it handy
to build OpenAPI Specification step by step passing your models to the builder
and get all the registered definitions later. This builder has reasonable
defaults but can be customized if necessary.
```python
from mashumaro.jsonschema import JSONSchemaBuilder, OPEN_API_3_1
builder = JSONSchemaBuilder(OPEN_API_3_1)
@dataclass
class User:
id: UUID
name: str
@dataclass
class Device:
id: UUID
model: str
print(builder.build(List[User]).to_json())
print(builder.build(List[Device]).to_json())
print(builder.get_definitions().to_json())
```
Click to show the result
```json
{
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
```
```json
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Device"
}
}
```
```json
{
"User": {
"type": "object",
"title": "User",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
},
"Device": {
"type": "object",
"title": "Device",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"model": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"model"
]
}
}
```
### JSON Schema constraints
Apart from required keywords, that are added automatically for certain data
types, you're free to use additional validation keywords.
They're presented by the corresponding classes in
[`mashumaro.jsonschema.annotations`](https://github.com/Fatal1ty/mashumaro/blob/master/mashumaro/jsonschema/annotations.py):
Number constraints:
* [`Minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minimum)
* [`Maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maximum)
* [`ExclusiveMinimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-exclusiveminimum)
* [`ExclusiveMaximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-exclusivemaximum)
* [`MultipleOf`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-multipleof)
String constraints:
* [`MinLength`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minlength)
* [`MaxLength`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxlength)
* [`Pattern`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-pattern)
Array constraints:
* [`MinItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minitems)
* [`MaxItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxitems)
* [`UniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-uniqueitems)
* [`Contains`](https://json-schema.org/draft/2020-12/json-schema-core.html#name-contains)
* [`MinContains`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-mincontains)
* [`MaxContains`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxcontains)
Object constraints:
* [`MaxProperties`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxproperties)
* [`MinProperties`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minproperties)
* [`DependentRequired`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dependentrequired)
### Extending JSON Schema
Using a `Config` class it is possible to override some parts of the schema.
Currently, you can do the following:
* override some field schemas using the "properties" key
* change `additionalProperties` using the "additionalProperties" key
```python
from dataclasses import dataclass
from mashumaro.jsonschema import build_json_schema
@dataclass
class FooBar:
foo: str
bar: int
class Config:
json_schema = {
"properties": {
"foo": {
"type": "string",
"description": "bar"
}
},
"additionalProperties": True,
}
print(build_json_schema(FooBar).to_json())
```
Click to show the result
```json
{
"type": "object",
"title": "FooBar",
"properties": {
"foo": {
"type": "string",
"description": "bar"
},
"bar": {
"type": "integer"
}
},
"additionalProperties": true,
"required": [
"foo",
"bar"
]
}
```
You can also change the "additionalProperties" key to a specific schema
by passing it a `JSONSchema` instance instead of a bool value.
### JSON Schema and custom serialization methods
Mashumaro provides different ways to override default serialization methods for
dataclass fields or specific data types. In order for these overrides to be
reflected in the schema, you need to make sure that the methods have
annotations of the return value type.
```python
from dataclasses import dataclass, field
from mashumaro.config import BaseConfig
from mashumaro.jsonschema import build_json_schema
def str_as_list(s: str) -> list[str]:
return list(s)
def int_as_str(i: int) -> str:
return str(i)
@dataclass
class FooBar:
foo: str = field(metadata={"serialize": str_as_list})
bar: int
class Config(BaseConfig):
serialization_strategy = {
int: {
"serialize": int_as_str
}
}
print(build_json_schema(FooBar).to_json())
```
Click to show the result
```json
{
"type": "object",
"title": "FooBar",
"properties": {
"foo": {
"type": "array",
"items": {
"type": "string"
}
},
"bar": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"foo",
"bar"
]
}
```
mashumaro-3.13.1/benchmark/ 0000775 0000000 0000000 00000000000 14633310012 0015516 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/benchmark/__init__.py 0000664 0000000 0000000 00000000000 14633310012 0017615 0 ustar 00root root 0000000 0000000 mashumaro-3.13.1/benchmark/charts/ 0000775 0000000 0000000 00000000000 14633310012 0017002 5 ustar 00root root 0000000 0000000 mashumaro-3.13.1/benchmark/charts/dump_dark.svg 0000664 0000000 0000000 00000025331 14633310012 0021475 0 ustar 00root root 0000000 0000000