Metadata-Version: 2.1
Name: jsonargon
Version: 0.1.0
Summary: Serialization and deserialization of JSON objects from/into Python objects (with validation and remapping capabilities)
Home-page: https://gitlab.com/federico_pugliese/jsonargon
Author: Federico Pugliese
License: Apache Software License, Version 2.0
Description: # JSON Argon
        
        **Serialization** and **deserialization** of **JSON** objects from/into **Python** objects (with **validation** and **remapping** capabilities).
        
        The underlying idea is to **annotate** a Python **Class** with metadata useful to serialize its objects into JSON strings and viceversa.
        
        Main features and goals are:
        
        - Concision
        - JSON Validation
        - Optional remapping of fields name
        - Familiar interface
        - Ease of development with IDE hints
        
        ## Installation
        
        To get the latest stable version, just run
        
        ```
        pip install jsonargon
        ```
        
        or
        
        ```
        pip install jsonargon==<version>
        ```
        
        if you require a specific version.
        
        ## Usage
        
        ### Basic Usage
        
        The basic requirement is to write the Python Class remapping your JSON.
        
        ```
        from jsonargon.decorators import jsonclass
        from jsonargon.fields.simple import Required, Nullable
        
        @jsonclass
        class Person:
            
            name: Required(str)
            age:  Nullable(int)
            
        ```
        
        As simple as that. The `name` field is a required string, while the `age` is a non-required integer.
        
        The `Required` type annotation will make sure that `name` is in your JSON string before deserializing it (a `KeyError` is thrown otherwise).
        
        If you have your JSON string, you can easily remap it into a Python object of that class, after you get your JSON string somehow (probably something like `{"name": "Jason Argonaut"}`):
        ```
        from jsonargon.deserializer import from_json
        
        person = from_json(your_json_string)
        
        print(person.name)  # Jason Argonaut
        print(person.age)   # None
        ```
        
        You can also serialize your object into a JSON string.
        
        ```
        from jsonargon.serializer import to_json
        
        person_json_string = to_json(person)
        ```
        
        ### Advanced usage
        
        JSON Argon also supports:
        
        - Nested objects
        - Lists and Dictionaries
        - JSON-Python names remapping
        
        #### Fields
        
        Each field annotation support these parameters:
        
        ```
        <field>(type: Any, json_name: str = None)
        ```
        
        - `type` is a simple type like `str`, `int`, `float` or a Class
        - `json_name` is an *optional* string representing the corresponding name in JSON
        
        
        | Field  | Meaning | JSON |
        |---|---|---|
        | `Required` | A required, simple attribute  | `"name": "Jason"`  |
        | `Nullable`  | A nullable (`None`) simple attribute | As above, or `"name": null` or no attribute at all |
        | `RequiredList`  | A required (but maybe empty) list of objects of the specified `type` | `"names": ["Argo", "Atalanta"]`, or `"names": []` or `"crew": [{"name": "Argo"}, {"name": "Atalanta"}]` |
        | `NullableList`  | A nullable list of objects of the specified `type` | As above, or `"names": null` or no attribute at all |
        | `RequiredStringDict`  | A required (but maybe empty) dict of string -> objects of the specified `type` | `"tags": {"scope": "dev"}`, or `"tags": {}` or `"documents": {"name": {"length":12}}` |
        | `NullableStringDict`  | A required (but maybe empty) list of objects of the specified `type` | As above, or `"tags": null` or no attribute at all |
        
        You can find a complete example here (with the JSON below):
        
        ```
        from jsonargon.decorators import jsonclass
        from jsonargon.fields.simple import Required, Nullable
        from jsonargon.fields.dict import RequiredStringDict
        from jsonargon.fields.list import RequiredList
        
        @jsonclass
        class Size:
            
            length: Required(float)
            width:  Required(float)
            height: Nullable(float, "heigth")  # Correct a JSON typo
        
        
        @jsonclass
        class Member:
        
            name: Required(str)
            role: Nullable(str)
            
        
        @jsonclass
        class Ship:
            
            name: Required(str, "shipName")
            size: Required(Size)
            crew: RequiredList(Member, "members")
            attributes: RequiredStringDict(str)
        
        ```
        
        To remap:
        ```
        {
            "shipName": "Argo",
            "size": {
                "width": 45.4,
                "length": 34.2
            },
            "members": [
                {
                    "name": "Atalanta"
                },
                {   
                    "name": "Jason",
                    "role": "leader"
                }
            ]
            "attributes": {
                "rarity": "mythological",
                "status": "destroyed"
            }
        }
        
        ```
        
        
        ## Origin of the name
        
        There are several reasons behind the name of this library.
        
        First of all, in Greek mythology, Jason was the leader of Argonauts.
        
        Jason is quite similar to JSON pronunciation. He was the hero who defeated the monstrous dragon (often depicted as a giant snake - a clear reference to Python) that guarded the Golden Fleece. 
        
        Also, his ship was Argo, and the Argonauts his crew.
        
        Argon, instead, is a noble gas. And with the same Class and style of a noble, this library aims to make you write a much cleaner code when dealing with JSON.
        
        *Make Jason proud of your code and join his crew of Argonauts.*
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
