| Name | jsonstar JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | Extensible JSON module to serialize all objects. |
| upload_time | 2024-02-08 01:54:57 |
| maintainer | |
| docs_url | None |
| author | Henrique Bastos |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JSON* is an extensible json module to serialize all objects!
`jsonstar` extends Python's standard JSON encoder and decoder to easily handle your custom types.
This means you won't have to transform your custom types into dictionaries with primitive types before encoding them to
JSON. And you won't have to parse back the encoded strings into your custom types after decoding them from JSON.
## How to install it?
```bash
pip install jsonstar
````
## How to start using it?
The `jsonstar` module provides the same API as the standard `json` module, so you can use it as a drop in replacement.
Simply change your import from `import json` to `import jsonstar as json` and you're good to go.
## Why use it?
Consider you have a pydantic `Employee` class that you want to serialize to JSON.
```python
from decimal import Decimal
from datetime import date
from pydantic import BaseModel
class Employee(BaseModel):
name: str
salary: Decimal
birthday: date
roles: set
employee = Employee(
name="John Doe",
salary=Decimal("1000.00"),
birthday=date(1990, 1, 1),
roles={"A", "B", "C"},
)
```
The standard `json` module can't serialize the `employee` instance, requiring you to call its `dict` method.
This will not sufice, because the standard `json` module don't know how to encode `Decimal`, `date` and `set`.
Your solution would include some trasnfomation of the `employee` instance and its attributes before encoding it to JSON.
That is where `jsonstar` shines by providing default encoder for common types like `pydantic.BaseModel`,
`decimal.Decimal`, `datetime.date` and `set`. And allowing you to easily add your own encoders.
```python
from jsonstar as json
print(json.dumps(employee))
# {"name": "John Doe", "salary": "1000.00", "birthday": "1990-01-01", "roles": ["A", "B", "C"]}
```
## What default encoders are provided?
By default, `jsonstar` provides encoders for the following types:
- `attrs` classes
- `dataclasses.dataclass` classes
- `datetime.date`
- `datetime.datetime`
- `datetime.time`
- `datetime.timedelta`
- `decimal.Decimal`
- `frozenset`
- `pydantic.BaseModel`
- `set`
- `uuid.UUID`
### Configurable default encoders
For some complex types like Django Models, an opinionated default encoder would not work for everyone.
This is why instead of providing a default encoder for Django Models, `jsonstar` provides you a configurable
encoder class to allow you to define the desired encoding behavior.
```python
import jsonstar as json
from jsonstar import DjangoModelEncoder
json.register_default_encoder(Model, DjangoModelEncoder(exclude=[DjangoModelEncoder.RELATIONSHIPS]))
```
The above code will register a default encoder for the `Model` class that will return all fields, excluding
relationships.
### Can `jsonstar` add more default encoders?
Yes. If you think that a default encoder for a common type is missing, please open an issue or a pull request.
See the *How to contribute* section for more details.
## How do I add my own encoder?
First you need to decide if you want your encoder to be available everywhere on your project or just for a specific
code block.
- *Default encoders* are globally available and will be used anywhere in your project.
- *Instance encoders* are available only for the `JSONEncoderStar` instance that you register them.
Also you have two types of encoders to choose from:
- *Typed encoders* are used to encode a specific type identified by `isinstance`.
- *Functional encoders* are used to encode an object based on arbitraty logic.
### How to add a default encoder?
To add a default encoder use the `register_default_encoder` function on the `jsonstar` module.
```python
import jsonstar as json
from decimal import Decimal
def two_decimals_encoder(obj):
"""Encodes a decimal with only two decimal places."""
return str(obj.quantize(Decimal("1.00")))
json.register_default_encoder(Decimal, two_decimals_encoder)
```
### How to add an instance encoder?
An instance encoder can be added in three ways:
1. Using the `register` method on the `JSONEncoderStar` instance.
2. Passing the encoder to the `JSONEncoderStar` initialization.
3. Passing the encoder to the `dumps` function.
```python
import jsonstar as json
from decimal import Decimal
def two_decimals_encoder(obj):
"""Encodes a decimal with only two decimal places."""
return str(obj.quantize(Decimal("1.00")))
# 1. Using the `register` method on the `JSONEncoderStar` instance.
encoder1 = json.JSONEncoderStar()
encoder1.register(two_decimals_encoder, Decimal)
# 2. Passing the encoder to the `JSONEncoderStar` initialization.
encoder2 = json.JSONEncoderStar(typed_encoders={Decimal: two_decimals_encoder})
# 3. Passing the encoder to the `dumps` function.
print(json.dumps(data, cls={Decimal: two_decimas_encoder}))
```
### How to add a typed encoder?
*Typed encoders* are specific to a type and it's inherited types.
When registering a typed encoder, you simply pass the encoder and the type to the chosen registration method.
When you add a typed encoder, `jsonstar` will check if any base class already has a registered encoder make sure the
more generic encoder is used last, respecting Python's Method Resolution Order (MRO).
### How to add a functional encoder?
*Functional encoders* are used to encode an object based on arbitraty logic and not specific to a type.
To register a functional encoder, you simply pass the encoder to the chosen registration method omiting the type.
All functional encoders are called only for objects that do not have a registered typed encoder.
## Contributing
Pull requests are welcome and must have associated tests.
For major changes, please open an issue first to discuss what you would like to change.
## License
[MIT](https://choosealicense.com/licenses/mit/)
## Author
Henrique Bastos <henrique@bastos.net>
## Project links
- [Homepage](https://github.com/henriquebastos/python-jsonstar)
- [Repository](https://github.com/henriquebastos/python-jsonstar)
- [Documentation](https://github.com/henriquebastos/python-jsonstar)
Raw data
{
"_id": null,
"home_page": "",
"name": "jsonstar",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Henrique Bastos",
"author_email": "henrique@bastos.net",
"download_url": "https://files.pythonhosted.org/packages/00/1f/e478c4e9c4784ae0eaf6851c6c447a415620f1a98a3f34578988db74b48a/jsonstar-1.0.0.tar.gz",
"platform": null,
"description": "# JSON* is an extensible json module to serialize all objects!\n\n`jsonstar` extends Python's standard JSON encoder and decoder to easily handle your custom types.\n\nThis means you won't have to transform your custom types into dictionaries with primitive types before encoding them to\nJSON. And you won't have to parse back the encoded strings into your custom types after decoding them from JSON.\n\n## How to install it?\n\n```bash\npip install jsonstar\n````\n\n## How to start using it?\n\nThe `jsonstar` module provides the same API as the standard `json` module, so you can use it as a drop in replacement.\n\nSimply change your import from `import json` to `import jsonstar as json` and you're good to go.\n\n## Why use it?\n\nConsider you have a pydantic `Employee` class that you want to serialize to JSON.\n\n```python\nfrom decimal import Decimal\nfrom datetime import date\nfrom pydantic import BaseModel\n\nclass Employee(BaseModel):\n name: str\n salary: Decimal\n birthday: date\n roles: set\n\nemployee = Employee(\n name=\"John Doe\",\n salary=Decimal(\"1000.00\"),\n birthday=date(1990, 1, 1),\n roles={\"A\", \"B\", \"C\"},\n)\n```\n\nThe standard `json` module can't serialize the `employee` instance, requiring you to call its `dict` method.\nThis will not sufice, because the standard `json` module don't know how to encode `Decimal`, `date` and `set`.\nYour solution would include some trasnfomation of the `employee` instance and its attributes before encoding it to JSON.\n\nThat is where `jsonstar` shines by providing default encoder for common types like `pydantic.BaseModel`,\n`decimal.Decimal`, `datetime.date` and `set`. And allowing you to easily add your own encoders.\n\n```python\nfrom jsonstar as json\nprint(json.dumps(employee))\n# {\"name\": \"John Doe\", \"salary\": \"1000.00\", \"birthday\": \"1990-01-01\", \"roles\": [\"A\", \"B\", \"C\"]}\n```\n\n## What default encoders are provided?\n\nBy default, `jsonstar` provides encoders for the following types:\n\n- `attrs` classes\n- `dataclasses.dataclass` classes\n- `datetime.date`\n- `datetime.datetime`\n- `datetime.time`\n- `datetime.timedelta`\n- `decimal.Decimal`\n- `frozenset`\n- `pydantic.BaseModel`\n- `set`\n- `uuid.UUID`\n\n### Configurable default encoders\n\nFor some complex types like Django Models, an opinionated default encoder would not work for everyone.\n\nThis is why instead of providing a default encoder for Django Models, `jsonstar` provides you a configurable\nencoder class to allow you to define the desired encoding behavior.\n\n```python\nimport jsonstar as json\nfrom jsonstar import DjangoModelEncoder\n\njson.register_default_encoder(Model, DjangoModelEncoder(exclude=[DjangoModelEncoder.RELATIONSHIPS]))\n```\n\nThe above code will register a default encoder for the `Model` class that will return all fields, excluding\nrelationships.\n\n### Can `jsonstar` add more default encoders?\n\nYes. If you think that a default encoder for a common type is missing, please open an issue or a pull request.\nSee the *How to contribute* section for more details.\n\n## How do I add my own encoder?\n\nFirst you need to decide if you want your encoder to be available everywhere on your project or just for a specific\ncode block.\n\n- *Default encoders* are globally available and will be used anywhere in your project.\n- *Instance encoders* are available only for the `JSONEncoderStar` instance that you register them.\n\nAlso you have two types of encoders to choose from:\n\n- *Typed encoders* are used to encode a specific type identified by `isinstance`.\n- *Functional encoders* are used to encode an object based on arbitraty logic.\n\n### How to add a default encoder?\n\nTo add a default encoder use the `register_default_encoder` function on the `jsonstar` module.\n\n```python\nimport jsonstar as json\nfrom decimal import Decimal\n\n\ndef two_decimals_encoder(obj):\n \"\"\"Encodes a decimal with only two decimal places.\"\"\"\n return str(obj.quantize(Decimal(\"1.00\")))\n\n\njson.register_default_encoder(Decimal, two_decimals_encoder)\n```\n\n### How to add an instance encoder?\n\nAn instance encoder can be added in three ways:\n\n1. Using the `register` method on the `JSONEncoderStar` instance.\n2. Passing the encoder to the `JSONEncoderStar` initialization.\n3. Passing the encoder to the `dumps` function.\n\n```python\nimport jsonstar as json\nfrom decimal import Decimal\n\n\ndef two_decimals_encoder(obj):\n \"\"\"Encodes a decimal with only two decimal places.\"\"\"\n return str(obj.quantize(Decimal(\"1.00\")))\n\n\n# 1. Using the `register` method on the `JSONEncoderStar` instance.\nencoder1 = json.JSONEncoderStar()\nencoder1.register(two_decimals_encoder, Decimal)\n\n# 2. Passing the encoder to the `JSONEncoderStar` initialization.\nencoder2 = json.JSONEncoderStar(typed_encoders={Decimal: two_decimals_encoder})\n\n# 3. Passing the encoder to the `dumps` function.\nprint(json.dumps(data, cls={Decimal: two_decimas_encoder}))\n```\n\n### How to add a typed encoder?\n\n*Typed encoders* are specific to a type and it's inherited types.\n\nWhen registering a typed encoder, you simply pass the encoder and the type to the chosen registration method.\n\nWhen you add a typed encoder, `jsonstar` will check if any base class already has a registered encoder make sure the\nmore generic encoder is used last, respecting Python's Method Resolution Order (MRO).\n\n\n### How to add a functional encoder?\n\n*Functional encoders* are used to encode an object based on arbitraty logic and not specific to a type.\n\nTo register a functional encoder, you simply pass the encoder to the chosen registration method omiting the type.\n\nAll functional encoders are called only for objects that do not have a registered typed encoder.\n\n## Contributing\nPull requests are welcome and must have associated tests.\n\nFor major changes, please open an issue first to discuss what you would like to change.\n\n\n## License\n[MIT](https://choosealicense.com/licenses/mit/)\n\n## Author\nHenrique Bastos <henrique@bastos.net>\n\n## Project links\n- [Homepage](https://github.com/henriquebastos/python-jsonstar)\n- [Repository](https://github.com/henriquebastos/python-jsonstar)\n- [Documentation](https://github.com/henriquebastos/python-jsonstar)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extensible JSON module to serialize all objects.",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "001fe478c4e9c4784ae0eaf6851c6c447a415620f1a98a3f34578988db74b48a",
"md5": "efa49bea07fd63e51090e34939bb1b84",
"sha256": "af9dc5a160a098bf0138990612c53eb4e95df086c8948506d613fead49a32111"
},
"downloads": -1,
"filename": "jsonstar-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "efa49bea07fd63e51090e34939bb1b84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6006,
"upload_time": "2024-02-08T01:54:57",
"upload_time_iso_8601": "2024-02-08T01:54:57.823279Z",
"url": "https://files.pythonhosted.org/packages/00/1f/e478c4e9c4784ae0eaf6851c6c447a415620f1a98a3f34578988db74b48a/jsonstar-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-08 01:54:57",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "jsonstar"
}
