{
    "info": {
        "author": "Marko Ristin",
        "author_email": "marko.ristin@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6"
        ],
        "description": ".. image:: https://raw.githubusercontent.com/Parquery/mapry/master/logo-640x320.png\n   :alt: Mapry\n\n.. image:: https://travis-ci.com/Parquery/mapry.svg?branch=master\n    :target: https://travis-ci.com/Parquery/mapry\n\n.. image:: https://coveralls.io/repos/github/Parquery/mapry/badge.svg?branch=master\n    :target: https://coveralls.io/github/Parquery/mapry\n\n.. image:: https://readthedocs.org/projects/mapry/badge/?version=latest\n    :target: https://mapry.readthedocs.io/en/latest/\n    :alt: Documentation Status\n\n.. image:: https://badge.fury.io/py/mapry.svg\n    :target: https://pypi.org/project/mapry/\n    :alt: PyPI - version\n\n.. image:: https://img.shields.io/pypi/pyversions/mapry.svg\n    :target: https://pypi.org/project/mapry/\n    :alt: PyPI - Python Version\n\nMapry generates polyglot code for de/serializing object graphs from\nJSONable structures.\n\n**Story**. We needed a yet another domain-specific language for internal data\nexchange and configuration of the system. The existing solutions mostly focused\non modeling the configuration as *object trees* in which the data is nested in\nhierarchies with no **cross-references** between the objects.\n\nFor example, think of object trees as JSON objects or arrays. We found this\nstructure to be highly limiting for most of the complex messages and system\nconfigurations. Our use cases required objects in the data to be referenced\namong each other -- instead of object trees we needed **object graphs**.\n\nMoreover, we wanted the serialization itself to be **readable** so that an\noperator can edit it using a simple text editor. JSONable structure offered\nitself as a good fit with a lot of existing tools (JSON and\nYAML modules *etc*.).\n\nHowever, JSON allows only a limited set of data types (numbers, strings, arrays\nand objects/maps). We found that most of our data relied on\n**a richer set of primitives** than provided by standard JSON. This\nextended set includes:\n\n* date,\n* datetime,\n* time of day,\n* time zone,\n* duration and\n* path.\n\nWhile there exist polyglot serializers of object trees (*e.g.*,\n`Protocol Buffers <https://developers.google.com/protocol-buffers/>`_),\nlanguage-specific serializers of object graphs (*e.g.,*\n`Gob in Go <https://golang.org/pkg/encoding/gob/>`_ or\n`Pickle in Python <https://docs.python.org/3/library/pickle.html>`_) or polyglot\nones with a limited set of primitives (*e.g.,*\n`Flatbuffers <https://google.github.io/flatbuffers/>`_), to the best of our\nknowledge there is currently no serializer of **object graphs** that operates\nwith **readable representations** and provides a\n**rich set of primitive data types** consistently **across multiple languages**.\n\nHence we developed Mapry, a generator of polyglot de/serialization code\nfor object graphs from JSONable structures.\n\nThe **schema** of the object graph is stored in a separate JSON file and defines\nall the data types used in the object graph including the object graph itself.\nThe code is generated based on the schema. You define the schema once and\ngenerate code in all supported languages automatically. Schemas can be\nevolved and backward compatibility is supported through optional properties.\n\nSupported languages\n-------------------\nCurrently, Mapry implements the following language bindings:\n\n* C++11, \n* Go 1 and \n* Python 3.\n\nSince the serialization needs to operate in different languages, only the\nintersection of language features is supported. For example, since Go does not\nsupport inheritance or union types, they are not supported in Mapry either.\n\nWorkflow\n--------\nThe following diagram illustrates the workflow.\n\n.. image:: https://raw.githubusercontent.com/Parquery/mapry/master/diagram.png\n\nDocumentation\n=============\n\nThis document gives only a brief summary of Mapry. The full documentation can be\nfound `here <https://mapry.readthedocs.io/en/latest/>`_.\n\nIntroduction\n============\n\nLet us introduce Mapry here by presenting a short example in order to give you a first\nimpression on how the generator can be used. To get the full picture, please consult the\n`documentation <https://mapry.readthedocs.io/en/latest/>`__.\n\nThe schema starts with the name and a description, followed by the\nlanguage-specific settings (specifying the non-standard parts of the code\ngeneration), the definition of the graph structure and finally the definition of the properties of\nthe object graph itself.\n\nHere is an example schema to give you an overview:\n\n.. code-block:: json\n\n    {\n      \"name\": \"Pipeline\",\n      \"description\": \"defines an address book.\",\n      \"cpp\": {\n        \"namespace\": \"book::address\",\n        \"path_as\": \"boost::filesystem::path\",\n        \"optional_as\": \"std::experimental::optional\",\n        \"datetime_library\": \"ctime\"\n      },\n      \"go\": {\n        \"package\": \"address\"\n      },\n      \"py\": {\n        \"module_name\": \"book.address\",\n        \"path_as\": \"pathlib.Path\",\n        \"timezone_as\": \"pytz.timezone\"\n      },\n      \"classes\": [\n        {\n          \"name\": \"Person\",\n          \"description\": \"defines a contactable person.\",\n          \"properties\": {\n            \"full_name\": {\n              \"type\": \"string\",\n              \"description\": \"gives the full name (including middle names).\"\n            },\n            \"birthday\": {\n              \"type\": \"date\",\n              \"description\": \"indicates the birthday in UTC.\"\n            },\n            \"address\": {\n              \"type\": \"Address\",\n              \"description\": \"notes where the person lives.\"\n            }\n          }\n        }\n      ],\n      \"embeds\": [\n        {\n          \"name\": \"Address\",\n          \"description\": \"defines an address.\",\n          \"properties\": {\n            \"text\": {\n              \"type\": \"string\",\n              \"description\": \"gives the full address.\"\n            }\n          }\n        }\n      ],\n      \"properties\": {\n        \"maintainer\": {\n          \"type\": \"Person\",\n          \"description\": \"indicates the maintainer of the address book.\"\n        }\n      }\n    }\n\nOnce you generated the de/serialization code with Mapry, you can use it\nto obtain the object graph from a JSONable.\n\nFor example, assume a JSONable stored in ``/path/to/the/file.json``:\n\n.. code-block:: json\n\n    {\n      \"persons\": {\n        \"alice\": {\n          \"full_name\": \"Alice Doe\",\n          \"birthday\": \"1983-10-24\",\n          \"address\": {\n            \"text\": \"Some street 12, Some City, Some Country\"\n          }\n        },\n        \"bob\": {\n          \"full_name\": \"Bob Johnson\",\n          \"birthday\": \"2016-07-03\",\n          \"address\": {\n            \"text\": \"Another street 36, Another City, Another Country\"\n          }\n        }\n      },\n      \"maintainer\": \"alice\"\n    } \n\nYou can parse the object graph in, say, Python:\n\n.. code-block:: Python\n\n    # Obtain a JSONable\n    pth = '/path/to/the/file.json'\n    with open(pth, 'rt') as fid:\n        value = json.load(fid)\n\n    # Parse the JSONable\n    errors = book.address.parse.Errors(cap=10)\n\n    pipeline = book.address.fromjsonable.pipeline_from(\n        value=value,\n        ref=pth + '#',\n        errors=errors)\n\n    if not errors.empty():\n        for error in errors.values():\n            print(\"{}: {}\".format(error.ref, error.message), file=sys.stderr)\n\n        return 1\n\nand access the object graph as ``pipeline``:\n\n.. code-block:: Python\n\n    print('Persons are:')\n    for person in pipeline.persons:\n        print('{} (full name: {}, address: {}, birthday: {})'.format(\n            person.id,\n            person.full_name,\n            person.address.text,\n            person.birthday.strftime(\"%d.%m.%Y\")))\n\n    print('The maintainer is: {}'.format(\n        pipeline.maintainer.id))\n\n\nThe generated code for this schema can be downloaded for\n`C++ <https://github.com/Parquery/mapry/blob/master/test_cases/docs/schema/introductory_example/cpp/test_generate>`_,\n`Go <https://github.com/Parquery/mapry/blob/master/test_cases/docs/schema/introductory_example/py/test_generate>`_ and\n`Python <https://github.com/Parquery/mapry/blob/master/test_cases/docs/schema/introductory_example/py/test_generate>`_.\n\nUsage\n=====\n\nMapry provides a single point-of-entry for all code generation through\n``mapry-to`` command.\n\nTo generate the code in different languages, invoke:\n\nFor **C++**:\n\n.. code-block:: bash\n\n    mapry-to cpp \\\n        --schema /path/to/schema.json \\\n        --outdir /path/to/cpp/code\n\nFor **Go**:\n\n.. code-block:: bash\n\n    mapry-to go \\\n        --schema /path/to/schema.json \\\n        --outdir /path/to/go/code\n\nFor **Python**:\n\n.. code-block:: bash\n\n    mapry-to py \\\n        --schema /path/to/schema.json \\\n        --outdir /path/to/py/code\n\nIf the output directory does not exist, it will be created. Any existing\nfiles will be silently overwritten.\n\nInstallation\n============\nWe provide a prepackaged PEX file that can be readily downloaded and executed.\nPlease see the `Releases section <https://github.com/Parquery/mapry/releases>`_.\n\nIf you prefer to use Mapry as a library (*e.g.*, as part of your Python-based\nbuild system), install it with pip:\n\n.. code-block:: bash\n\n    pip3 install mapry\n\nContributing\n============\nAll contributions are highly welcome. Please consult this\n`page <https://mapry.readthedocs.io/en/latest/contributing.html>`_\nin the documentation to see how you can contribute.\n\nVersioning\n==========\nWe follow `Semantic Versioning <http://semver.org/spec/v1.0.0.html>`_.\nWe extended the standard semantic versioning with an additional format version.\nThe version W.X.Y.Z indicates:\n\n* W is the format version (data representation is backward-incompatible),\n* X is the major version (library interface is backward-incompatible),\n* Y is the minor version (library interface is extended, but\n  backward-compatible), and\n* Z is the patch version (backward-compatible bug fix).\n\nRelated Projects\n================\nWe compiled an extensive list of related projects and how they compare to Mapry\nin the\n`documentation <https://mapry.readthedocs.io/en/latest/related_projects.html>`__.\n\nWe present here only the most prominent projects and their main differences\nto Mapry:\n\nStandard JSON libraries\n    support only object *trees*, not graphs. They usually lack a schema (*e.g.,*\n    `json module in Python <https://docs.python.org/3/library/json.html>`_).\n\nDe/serializers based on annotations\n    handle object graphs through custom logic (*e.g.,*\n    `Jackson in Java <https://github.com/FasterXML/jackson>`_). Since they are\n    based on annotations in source code, a polyglot code base would require\n    a duplication across different languages which can be cumbersome and\n    error-prone to keep synchronized.\n\nStandard or widely used serialization libraries\n    handle object graphs well and provide a rich set of primitives. However, the serialization\n    format differs accross languagues (*e.g.*,\n    `Boost.Serialization in C++ <https://www.boost.org/doc/libs/1_70_0/libs/serialization/doc/index.html>`_\n    or `Pickle in Python <https://docs.python.org/3/library/pickle.html>`_\n    would need to be supported in Go).\n\nPopular serializers based on generated code\n    usually do not de/serialize object graphs, but only object trees (*e.g.,*\n    `Protocol Buffers <https://developers.google.com/protocol-buffers/>`_ or\n    `Cap'n Proto <https://capnproto.org/>`_).\n\n    `Flatbuffers <https://google.github.io/flatbuffers/>`_ being the exception\n    handle object graphs natively, but lack support for sophisticated types such as\n    maps and datetimes, durations *etc.*",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/Parquery/mapry",
        "keywords": "object mapping json serialization deserialization graph",
        "license": "License :: OSI Approved :: MIT License",
        "maintainer": "",
        "maintainer_email": "",
        "name": "mapry",
        "package_url": "https://pypi.org/project/mapry/",
        "platform": "",
        "project_url": "https://pypi.org/project/mapry/",
        "project_urls": {
            "Homepage": "http://github.com/Parquery/mapry"
        },
        "release_url": "https://pypi.org/project/mapry/1.0.0.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Generate polyglot code for de/serializing object graphs from JSONable structures.",
        "version": "1.0.0.0"
    },
    "last_serial": 5599770,
    "releases": {
        "1.0.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b7820aa586178dd801feddb2beedc688",
                    "sha256": "9dcedec8b2825a420ed80552e9b834d8e1ec828ec31e354ffd0f778025eb6059"
                },
                "downloads": -1,
                "filename": "mapry-1.0.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "b7820aa586178dd801feddb2beedc688",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 80790,
                "upload_time": "2019-07-29T14:21:35",
                "url": "https://files.pythonhosted.org/packages/86/1d/396edc5e38592da5184ddbef7eb6562a5812f0d212ea53d95e0b9b9886e0/mapry-1.0.0.0.tar.gz"
            }
        ],
        "1.0.0.0rc1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "56b51b110e21daa1b6650d9ab54482eb",
                    "sha256": "26a0750b766d3a6e198edf50a0ca4c910a2e2c6eb519b40d07b46266753c4335"
                },
                "downloads": -1,
                "filename": "mapry-1.0.0.0rc1.tar.gz",
                "has_sig": false,
                "md5_digest": "56b51b110e21daa1b6650d9ab54482eb",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 94825,
                "upload_time": "2019-06-02T07:54:14",
                "url": "https://files.pythonhosted.org/packages/51/80/62be21c08f754754ceef9420617b092a151241b3c85b074196797941d1d1/mapry-1.0.0.0rc1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "b7820aa586178dd801feddb2beedc688",
                "sha256": "9dcedec8b2825a420ed80552e9b834d8e1ec828ec31e354ffd0f778025eb6059"
            },
            "downloads": -1,
            "filename": "mapry-1.0.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "b7820aa586178dd801feddb2beedc688",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 80790,
            "upload_time": "2019-07-29T14:21:35",
            "url": "https://files.pythonhosted.org/packages/86/1d/396edc5e38592da5184ddbef7eb6562a5812f0d212ea53d95e0b9b9886e0/mapry-1.0.0.0.tar.gz"
        }
    ]
}