Skip to main content

simple serializer based on annotations

Project description

# AJson (Annotations Json Serializer)

AJson is a serializer based on annotations that gives a lot of flexibility and configuration for you serialization process.

[![Build Status](https://travis-ci.org/JorgeGarciaIrazabal/ajson.svg?branch=master)](https://travis-ci.org/JorgeGarciaIrazabal/ajson)
[![codecov](https://codecov.io/gh/JorgeGarciaIrazabal/ajson/branch/master/graph/badge.svg)](https://codecov.io/gh/JorgeGarciaIrazabal/ajson)


### Install: (python3.6 or higher)

`pip install ajson`

#### Motivation:

There are amazing serialization libraries like [jsonpickle](https://jsonpickle.github.io/), and even more when the serialized object is meant to be used in python too.
But there are no libraries that let you filter fields to serialize or modify the names of the attributes. These features are super useful, mainly for http APIs

This library allows you to have those features in a simple and intuitive way.

#### Serialize Examples

##### Simple Serialization With "Groups"
If you want to filter some sensible data in some scenarios, you can define `groups` per attribute to control what is serialized and what is not.

```python
from ajson import AJson, ASerializer

@AJson()
class Restaurant:
location:str # @aj(groups=["public","admin"])
tables: int # @aj(groups=["public","admin"])
owner: str # @aj(groups=["admin"])
def __init__(self, location, tables, owner):
self.location = location
self.tables = tables
self.owner = owner

serializer = ASerializer()
restaurant = Restaurant("Manhattan", 30, "John Smith")
print(serializer.serialize(restaurant, groups=["public"]))
# {"location": "Manhattan", "tables": 30}
print(serializer.serialize(restaurant, groups=["admin"]))
# {"location": "Manhattan", "tables": 30, "owner": "John Smith"}
```

##### Rename Attributes With "Name"

```python
from ajson import AJson
from ajson.aserializer import ASerializer

@AJson()
class Customer:
name: str # @aj(name=firstName)
primary_email: str # @aj(name=email)
last_name: str # @aj(name=lastName)
def __init__(self):
self.name = "John"
self.last_name = "Smith"
self.primary_email = "john.smith@something.com"

serializer = ASerializer()
customer = Customer()
print(serializer.serialize(customer))
# {"firstName": "John", "lastName": "Smith", "email": "john.smith@something.com"}
```

##### Nested Objects With Groups And Names

```python
from typing import List
from ajson import AJson, ASerializer


@AJson()
class Customer:
name: str # @aj(name=firstName, groups=["public"])
primary_email: str
'''
You can also add the annotation in a multi-line docstr
@aj(
name=email,
groups=["public"]
)
'''

def __init__(self, name, primary_email):
self.name = name
self.primary_email = primary_email

@AJson()
class Restaurant:
location: str # @aj(groups=["public","admin"])
owner: str # @aj(groups=["admin"])
customer_list: List[Customer] # @aj(groups=["with_customers"] name=customers)

def __init__(self):
self.location = None
self.owner = "John Smith"
self.customer_list = [
Customer("Dani", "dani@something.com"),
Customer("Mike", "maki@something.com")
]

restaurant = Restaurant()
print(ASerializer().serialize(restaurant, groups=["public"]))
# '{"location": null}'

# if you want to get the dictionary instead of a string, you can call `to_dict` instead of `serialize`
print(ASerializer().to_dict(restaurant, groups=["public", "with_customers"]))
'''
{
"location": None,
"customers": [
{"firstName": "Dani", "email": "dani@something.com"},
{"firstName": "Mike", "email": "maki@something.com"}
]
}
'''
```

#### Unserialize Examples

##### UnSerialization With Custom Names
```python
from ajson import AJson, ASerializer

@AJson()
class Customer:
name: str # @aj(name=firstName)
primary_email: str # @aj(name=email)
last_name: str # @aj(name=lastName)

serializer = ASerializer()
serialize_str = '{"firstName": "John", "lastName": "Smith", "email": "john.smith@something.com"}'
customer = serializer.unserialize(serialize_str, Customer)
print(customer.name) # "John"
print(customer.last_name) # "Smith"
print(customer.primary_email) # "john.smith@something.com"
```

##### Nested Objects

```python
from typing import List, Optional
from ajson import AJson, ASerializer


@AJson()
class Customer:
def __init__(self):
# we can also create the @aj annotation in the attribute's definition
self.name = None # @aj(name=firstName)
self.primary_email = None # @aj(name=email)

@AJson()
class Restaurant:
customer_list: List[Customer] # if we want to have nested objects, we need to define the types hints
'''
@aj(name=customers)
we can create the @aj annotation in the attribute's definition
'''
owner: str = "John Smith"
location: Optional[str] = None


restaurant_str = '''
{
"location": "Spain",
"customers": [
{"firstName": "Dani", "email": "dani@something.com"},
{"firstName": "Mike", "email": "maki@something.com"}
]
}
'''

serializer = ASerializer()
restaurant = serializer.unserialize(restaurant_str, Restaurant)
print(restaurant.owner) # "John Smith"
print(restaurant.customer_list[0].name) # "Dani"
```

##### Known Limitations

1. Unserialize a Dict with types (Dict[str:MyObject]) is not supported, it will just unserialize it as a dict.

2. Unserialize a Dict with key different than a string (Dict[int:str])

#### Documentation

Documentation and additional information [here](https://jorgegarciairazabal.github.io/ajson/)

#### Contributing

Any contribution, feature request, or bug report is always welcome.

Please, feel free to create any issues or PRs.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ajson-0.12.0.tar.gz (15.0 kB view details)

Uploaded Source

Built Distribution

ajson-0.12.0-py3-none-any.whl (29.3 kB view details)

Uploaded Python 3

File details

Details for the file ajson-0.12.0.tar.gz.

File metadata

  • Download URL: ajson-0.12.0.tar.gz
  • Upload date:
  • Size: 15.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.6

File hashes

Hashes for ajson-0.12.0.tar.gz
Algorithm Hash digest
SHA256 fe347a387cfb79fc191128fb36f87ed86fe72c80e88c9be78cdec629da78aeea
MD5 0e8e4c36db6a60a1113df39669581708
BLAKE2b-256 8e15991f699304047072bd305a40813e1ed754cefd2a8c24302752e334537a1c

See more details on using hashes here.

File details

Details for the file ajson-0.12.0-py3-none-any.whl.

File metadata

  • Download URL: ajson-0.12.0-py3-none-any.whl
  • Upload date:
  • Size: 29.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.6

File hashes

Hashes for ajson-0.12.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7353afac07cf77337f4057aac0589f4bfcd30960b45424345104f9ae53917fa6
MD5 c3afd59890002c75f26f5d16e5cde8fe
BLAKE2b-256 24132cf9c7e49b4ab1d814bea33e49174f4fd0f2944d911c6e2d7d9c0390bfd6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page