# serious
[][pypi]
[](https://dev.azure.com/misha-drachuk/serious/_build/latest?definitionId=1&branchName=master)
[](https://coveralls.io/github/mdrachuk/serious)
[][pypi]
[][docs]
A dataclass model toolkit: serialization, validation, and more.
[Documentation][docs]
## Features
- Model definitions in pure Python.
- Validation showing up in code coverage.
- Type annotations for all public-facing APIs.
- (Optionally) ensures immutability.
- Easily extensible.
- Made for people.
- Documented rigorously.
## Basics
### Installation
Available from [PyPI][pypi]:
```shell
pip install serious
```
### Quick Example
Central part of Serious API are different [Models][doc-models].
Given a regular dataclass:
```python
from dataclasses import dataclass
@dataclass
class Person:
name: str
```
Let’s create a `JsonModel`:
```python
from serious.json import JsonModel
model = JsonModel(Person)
```
And use its [dump/load methods][doc-serialization]:
```python
person = Person('Albert Einstein')
model.dump(person) # {"name": "Albert Einstein"}
```
### Validation
To add validation to the example above all we need is to add `__validate__` method to person:
```python
from dataclasses import dataclass
from typing import Optional
from serious import ValidationError, Email
@dataclass
class Person:
name: str
email: Optional[Email]
phone: Optional[str]
def __validate__(self):
if len(self.name) == 0:
raise ValidationError('Every person needs a name')
if self.phone is None and self.email is None:
raise ValidationError('At least some contact should be present')
```
[More on validation.][doc-validation]
### Supported formats:
- [x] [JSON][doc-json-model]
- [x] [Python Dictionaries][doc-dict-model]
- [ ] YAML
- [ ] Form data
### Supported field types
[More in docs.][doc-types]
- Other dataclasses
- Primitives: `str`, `int`, `float`, `bool`
- Dictionaries: only with string keys: `Dict[str, Any]`
- Lists, [sets][set], [deques][deque]: python collections of any serializable type
- [Tuples][tuple] both with and without ellipsis:
- tuples as set of independent elements (e.g. `Tuple[str, int, date]`)
- with ellipses, acting as a frozen list (`Tuple[str, ...]`)
- [Enumerations][enum] by value:
- of primitives (e.g. `OperatingSystem(Enum)`)
- typed enums (`Color(str, Enum)` and `FilePermission(IntFlag)`)
- [Decimal][decimal]: encoded to JSON as string
- [Datetime][datetime], [date][date] and [time][time]: encoded to the [ISO 8601][iso8601] formatted string
- [UUID][uuid]
- `serious.types.Timestamp`: a UTC timestamp since [UNIX epoch][epoch] as float ms value
- `serious.types.Email`: a string Tiny Type that supports validation and contains additional properties
- custom immutable alternatives to native python types in `serious.types`: `FrozenList`, `FrozenDict`
## A bigger example
```python
from dataclasses import dataclass
from serious import JsonModel, ValidationError
from typing import List
from enum import Enum
class Specialty(Enum):
Worker = 1
Fool = 2
@dataclass(frozen=True)
class Minion:
name: str
type: Specialty
@dataclass(frozen=True)
class Boss:
name: str
minions: List[Minion]
def __validate__(self):
if len(self.minions) < 2:
raise ValidationError('What kind of boss are you?')
boss = Boss("me", [Minion('evil minion', Specialty.Fool), Minion('very evil minion', Specialty.Worker)])
boss_json = """{
"name": "me",
"minions": [
{
"name": "evil minion",
"type": "Fool"
},
{
"name": "very evil minion",
"type": "Worker"
}
]
}"""
model = JsonModel(Boss, indent=4)
assert model.dump(boss) == boss_json
assert model.load(boss_json) == boss
```
## Acknowledgements
Initially, a fork of [@lidatong/dataclasses-json](https://github.com/lidatong/dataclasses-json).
[pypi]: https://pypi.org/project/serious/
[dataclass]: https://docs.python.org/3/library/dataclasses.html
[iso8601]: https://en.wikipedia.org/wiki/ISO_8601
[epoch]: https://en.wikipedia.org/wiki/Unix_time
[enum]: https://docs.python.org/3/library/enum.html
[decimal]: https://docs.python.org/3/library/decimal.html
[tuple]: https://docs.python.org/3/library/stdtypes.html#tuple
[list]: https://docs.python.org/3/library/stdtypes.html#list
[set]: https://docs.python.org/3/library/stdtypes.html#set
[deque]: https://docs.python.org/3.7/library/collections.html#collections.deque
[datetime]: https://docs.python.org/3.7/library/datetime.html#datetime.datetime
[date]: https://docs.python.org/3.7/library/datetime.html#datetime.date
[time]: https://docs.python.org/3.7/library/datetime.html#datetime.time
[uuid]: https://docs.python.org/3.7/library/uuid.html?highlight=uuid#uuid.UUID
[doc-types]: https://serious.readthedocs.io/en/latest/types/
[doc-models]: https://serious.readthedocs.io/en/latest/models/
[doc-json-model]: https://serious.readthedocs.io/en/latest/models/#jsonmodel
[doc-dict-model]: https://serious.readthedocs.io/en/latest/models/#dictmodel
[doc-serialization]: https://serious.readthedocs.io/en/latest/serialization/ (Serialization documentation)
[doc-validation]: https://serious.readthedocs.io/en/latest/validation/ (Validation documentation)
[docs]: https://serious.readthedocs.io/en/latest/
Raw data
{
"_id": null,
"home_page": "https://github.com/mdrachuk/serious",
"name": "serious",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "dataclasses json serialization",
"author": "mdrachuk",
"author_email": "misha@drach.uk",
"download_url": "https://files.pythonhosted.org/packages/59/97/ce4a906a60138ad11cb3cb0d30229e1ce87946fbbebe7c966c2f69e22229/serious-1.2.6.tar.gz",
"platform": null,
"description": "# serious\n[][pypi]\n[](https://dev.azure.com/misha-drachuk/serious/_build/latest?definitionId=1&branchName=master)\n[](https://coveralls.io/github/mdrachuk/serious)\n[][pypi]\n[][docs]\n\nA dataclass model toolkit: serialization, validation, and more.\n\n[Documentation][docs]\n\n\n## Features\n- Model definitions in pure Python.\n- Validation showing up in code coverage.\n- Type annotations for all public-facing APIs.\n- (Optionally) ensures immutability.\n- Easily extensible.\n- Made for people.\n- Documented rigorously.\n\n## Basics\n### Installation\nAvailable from [PyPI][pypi]:\n```shell\npip install serious\n```\n\n### Quick Example\n\nCentral part of Serious API are different [Models][doc-models].\n\nGiven a regular dataclass:\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Person:\n name: str\n```\n\nLet\u2019s create a `JsonModel`: \n```python\nfrom serious.json import JsonModel\n \nmodel = JsonModel(Person)\n```\n\nAnd use its [dump/load methods][doc-serialization]:\n```python\nperson = Person('Albert Einstein')\n\nmodel.dump(person) # {\"name\": \"Albert Einstein\"}\n```\n\n### Validation\nTo add validation to the example above all we need is to add `__validate__` method to person:\n```python\nfrom dataclasses import dataclass\nfrom typing import Optional\nfrom serious import ValidationError, Email\n\n@dataclass\nclass Person:\n name: str\n email: Optional[Email]\n phone: Optional[str]\n\n def __validate__(self):\n if len(self.name) == 0:\n raise ValidationError('Every person needs a name')\n if self.phone is None and self.email is None:\n raise ValidationError('At least some contact should be present')\n```\n\n[More on validation.][doc-validation]\n\n\n### Supported formats:\n- [x] [JSON][doc-json-model]\n- [x] [Python Dictionaries][doc-dict-model]\n- [ ] YAML\n- [ ] Form data\n\n\n### Supported field types\n[More in docs.][doc-types]\n\n- Other dataclasses\n- Primitives: `str`, `int`, `float`, `bool`\n- Dictionaries: only with string keys: `Dict[str, Any]` \n- Lists, [sets][set], [deques][deque]: python collections of any serializable type\n- [Tuples][tuple] both with and without ellipsis:\n - tuples as set of independent elements (e.g. `Tuple[str, int, date]`) \n - with ellipses, acting as a frozen list (`Tuple[str, ...]`)\n- [Enumerations][enum] by value:\n - of primitives (e.g. `OperatingSystem(Enum)`) \n - typed enums (`Color(str, Enum)` and `FilePermission(IntFlag)`)\n- [Decimal][decimal]: encoded to JSON as string \n- [Datetime][datetime], [date][date] and [time][time]:\u00a0encoded to the [ISO 8601][iso8601] formatted string\n- [UUID][uuid]\n- `serious.types.Timestamp`: a UTC timestamp since [UNIX epoch][epoch] as float ms value \n- `serious.types.Email`: a string Tiny Type that supports validation and contains additional properties \n- custom immutable alternatives to native python types in `serious.types`: `FrozenList`, `FrozenDict`\n\n## A bigger example\n\n```python\nfrom dataclasses import dataclass\nfrom serious import JsonModel, ValidationError\nfrom typing import List\nfrom enum import Enum\n\nclass Specialty(Enum):\n Worker = 1\n Fool = 2\n\n\n@dataclass(frozen=True)\nclass Minion:\n name: str\n type: Specialty\n\n\n@dataclass(frozen=True)\nclass Boss:\n name: str\n minions: List[Minion]\n \n def __validate__(self):\n if len(self.minions) < 2:\n raise ValidationError('What kind of boss are you?')\n\n\nboss = Boss(\"me\", [Minion('evil minion', Specialty.Fool), Minion('very evil minion', Specialty.Worker)])\nboss_json = \"\"\"{\n \"name\": \"me\",\n \"minions\": [\n {\n \"name\": \"evil minion\",\n \"type\": \"Fool\"\n },\n {\n \"name\": \"very evil minion\",\n \"type\": \"Worker\"\n }\n ]\n}\"\"\"\n\nmodel = JsonModel(Boss, indent=4)\n\nassert model.dump(boss) == boss_json\nassert model.load(boss_json) == boss\n```\n\n\n## Acknowledgements\nInitially, a fork of [@lidatong/dataclasses-json](https://github.com/lidatong/dataclasses-json).\n\n[pypi]: https://pypi.org/project/serious/\n[dataclass]: https://docs.python.org/3/library/dataclasses.html\n[iso8601]: https://en.wikipedia.org/wiki/ISO_8601\n[epoch]: https://en.wikipedia.org/wiki/Unix_time\n[enum]: https://docs.python.org/3/library/enum.html\n[decimal]: https://docs.python.org/3/library/decimal.html\n[tuple]: https://docs.python.org/3/library/stdtypes.html#tuple\n[list]: https://docs.python.org/3/library/stdtypes.html#list\n[set]: https://docs.python.org/3/library/stdtypes.html#set\n[deque]: https://docs.python.org/3.7/library/collections.html#collections.deque\n[datetime]: https://docs.python.org/3.7/library/datetime.html#datetime.datetime\n[date]: https://docs.python.org/3.7/library/datetime.html#datetime.date\n[time]: https://docs.python.org/3.7/library/datetime.html#datetime.time\n[uuid]: https://docs.python.org/3.7/library/uuid.html?highlight=uuid#uuid.UUID\n[doc-types]: https://serious.readthedocs.io/en/latest/types/\n[doc-models]: https://serious.readthedocs.io/en/latest/models/\n[doc-json-model]: https://serious.readthedocs.io/en/latest/models/#jsonmodel\n[doc-dict-model]: https://serious.readthedocs.io/en/latest/models/#dictmodel\n[doc-serialization]: https://serious.readthedocs.io/en/latest/serialization/ (Serialization documentation)\n[doc-validation]: https://serious.readthedocs.io/en/latest/validation/ (Validation documentation)\n[docs]: https://serious.readthedocs.io/en/latest/ \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Easily serialize dataclasses to and from JSON",
"version": "1.2.6",
"project_urls": {
"Homepage": "https://github.com/mdrachuk/serious",
"Issues": "https://github.com/mdrachuk/serious/issues",
"Pipelines": "https://dev.azure.com/misha-drachuk/serious",
"Source": "https://github.com/mdrachuk/serious/"
},
"split_keywords": [
"dataclasses",
"json",
"serialization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "624eafdb17287a57c90af0d08bcf2b367659a768f2987c172d05fd11348a64f7",
"md5": "a538811bc17068a4f69d143bfbc36191",
"sha256": "a194b81a480bdb1b626f0a3e1e2af87aef577f601df1c71fc391a81141d562c7"
},
"downloads": -1,
"filename": "serious-1.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a538811bc17068a4f69d143bfbc36191",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 31903,
"upload_time": "2023-12-04T14:38:41",
"upload_time_iso_8601": "2023-12-04T14:38:41.373629Z",
"url": "https://files.pythonhosted.org/packages/62/4e/afdb17287a57c90af0d08bcf2b367659a768f2987c172d05fd11348a64f7/serious-1.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5997ce4a906a60138ad11cb3cb0d30229e1ce87946fbbebe7c966c2f69e22229",
"md5": "bbb73abd4905a80aa2c5b22225fbb76c",
"sha256": "38a0df8468a440a5624a360eec488443c0649d0f6d20e994f51afab49c952e4b"
},
"downloads": -1,
"filename": "serious-1.2.6.tar.gz",
"has_sig": false,
"md5_digest": "bbb73abd4905a80aa2c5b22225fbb76c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26317,
"upload_time": "2023-12-04T14:38:43",
"upload_time_iso_8601": "2023-12-04T14:38:43.033911Z",
"url": "https://files.pythonhosted.org/packages/59/97/ce4a906a60138ad11cb3cb0d30229e1ce87946fbbebe7c966c2f69e22229/serious-1.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 14:38:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdrachuk",
"github_project": "serious",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "serious"
}
JSON
