# Piri
Configurable Data Mapping for mortals
___
[](https://codecov.io/gh/greenbird/piri)
[](https://pypi.org/project/piri/)
[](https://github.com/wemake-services/wemake-python-styleguide)
___
**Documentation
([Stable](https://piri.readthedocs.io/) |
[Latest](https://piri.readthedocs.io/en/latest/)) |
[Source Code](https://github.com/greenbird/piri) |
[Task Tracker](https://github.com/greenbird/piri/issues)**
## What is Piri
Piri is a JSON to JSON mapper. That means that we read input JSON and create output JSON. How the output is created is based on instructions from a configuration file. The configuration file governs the the output structure and tells piri where in the input to find data and where to place it in the output. In addition to this Piri supports data transformation with `data casting`, `if conditions`, `combination of data from multiple places` and of course setting `default` values.
__This enables you to change any input into the output you desire.__
## Typical usecases
* You `GET` data from api, but need to transform it for your backend system
* `POST`ing data to an api that needs data on a different format than what your system produces
* All your backends speak different language? pipe it through __Piri__
* Customer delivers weirdly formatted data? Use __Piri__ to make it sexy
* Have CSV but need nicely structured JSON? make CSV into a JSON list and transform it with __Piri__
* Have XML but need to change it? make it into JSON, transform it with __Piri__ and then dump it to XML again.
* Customers legacy system needs CSV. Use __Piri__ to transform your nicely structured JSON data into a JSON List that can be easily dumped to CSV
## Official Open Piri Solutions
[piri-cli](https://github.com/greenbird/piri-cli), commandline interface for file to file mapping.
[piri-web](https://github.com/greenbird/piri-web), One Click deploy Web REST API for Piri JSON mapping.
## Enterprise solutions
Coming...
## Goal
The goal of this library is to make JSON to JSON transformation/mapping easy, configurable and documentable. We achieve this by using a simple but feature-rich JSON configuration which then also acts as documentation and as a contract between parties.
## Why
Piri was born because we really dislike mapping. Documenting whatever decisions made in your code so that some product owner understands it is also _no me gusto_. Transforming data from one format to another is something software engineers do allmost daily... It should be easy! And documenting it shouldn't be something you have to worry about.
After the Worst POC in History we never wanted to do mapping by scripts and code again. This lead to the idea that it should be possible to create a file which governs how the structure should look and how the data should be transformed. This would then be the `single source of truth` and with Piri we have achieved this.
We believe that this will make collaboration between teams faster and easier. Use Piri to agree with data formats between Front-end and Back-end. Between the 3rd party system and your back-end. You can even use Piri for testing existing integrations ;-)
## Features
* Mapping with configuration File.
* [JSON Schema](https://json-schema.org/) validation of the config file.
* Structurally Transform JSON
* Combine multiple values to one.
* Default values
* If statements
* is, contains, not
* casting
* integer, decimal, iso date
## Contributing
Please see [contribute](https://piri.readthedocs.io/en/stable/contributing)
## Installation
Package is on pypi. Use pip or poetry to install
```sh
pip install piri
```
```sh
poetry add piri
```
## Introduction
Have a look at our introduction course [here](https://piri.readthedocs.io/en/stable/introduction)
## Quickstart
```python
import simplejson
from piri3.process import process
my_config = {
'name': 'schema',
'array': False,
'objects': [
{
'name': 'invoices',
'array': True,
'iterables': [
{
'alias': 'invoices',
'path': ['root', 'invoices'],
},
],
'attributes': [
{
'name': 'amount',
'mappings': [
{
'path': ['invoices', 'amount'],
},
],
'casting': {
'to': 'decimal',
'original_format': 'integer_containing_decimals',
},
'default': 0,
},
{
'name': 'debtor',
'mappings': [
{
'path': ['root', 'customer', 'first_name'],
},
{
'path': ['root', 'customer', 'last_name'],
},
],
'separator': ' ',
},
],
'objects': [],
},
],
}
example_data = {
'root': {
'customer': {
'first_name': 'John',
'last_name': 'Smith',
},
'invoices': [
{
'amount': 10050,
},
{
'amount': 20050,
},
{
'amount': -15005,
},
],
},
}
mapped_data = process(example_data, my_config)
with open('resultfile.json', 'w') as output_file:
output_file.write(simplejson.dumps(mapped_data))
```
contents of resultfile.json
```json
{
"invoices": [
{
"amount": 100.5,
"debtor": "John Smith"
},
{
"amount": 200.5,
"debtor": "John Smith"
},
{
"amount": -150.05,
"debtor": "John Smith"
}
]
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/greenbird/piri",
"name": "piri3",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "Json mapping,data transformation,json to json,dict to dict,configurable",
"author": "Shaun Patterson",
"author_email": "thomas.borgen@greenbird.com",
"download_url": "https://files.pythonhosted.org/packages/10/a4/2bac5ea58ea355f064a8f5648a5df9e0ec16c903b88a99bf6731b7141ec9/piri3-3.0.4.tar.gz",
"platform": null,
"description": "# Piri\nConfigurable Data Mapping for mortals\n___\n\n[](https://codecov.io/gh/greenbird/piri)\n[](https://pypi.org/project/piri/)\n[](https://github.com/wemake-services/wemake-python-styleguide)\n___\n\n**Documentation\n([Stable](https://piri.readthedocs.io/) |\n[Latest](https://piri.readthedocs.io/en/latest/)) |\n[Source Code](https://github.com/greenbird/piri) |\n[Task Tracker](https://github.com/greenbird/piri/issues)**\n\n## What is Piri\n\nPiri is a JSON to JSON mapper. That means that we read input JSON and create output JSON. How the output is created is based on instructions from a configuration file. The configuration file governs the the output structure and tells piri where in the input to find data and where to place it in the output. In addition to this Piri supports data transformation with `data casting`, `if conditions`, `combination of data from multiple places` and of course setting `default` values.\n\n__This enables you to change any input into the output you desire.__\n\n## Typical usecases\n\n* You `GET` data from api, but need to transform it for your backend system\n* `POST`ing data to an api that needs data on a different format than what your system produces\n* All your backends speak different language? pipe it through __Piri__\n* Customer delivers weirdly formatted data? Use __Piri__ to make it sexy\n* Have CSV but need nicely structured JSON? make CSV into a JSON list and transform it with __Piri__\n* Have XML but need to change it? make it into JSON, transform it with __Piri__ and then dump it to XML again.\n* Customers legacy system needs CSV. Use __Piri__ to transform your nicely structured JSON data into a JSON List that can be easily dumped to CSV\n\n## Official Open Piri Solutions\n\n[piri-cli](https://github.com/greenbird/piri-cli), commandline interface for file to file mapping.\n\n[piri-web](https://github.com/greenbird/piri-web), One Click deploy Web REST API for Piri JSON mapping.\n\n## Enterprise solutions\n\nComing...\n\n## Goal\n\nThe goal of this library is to make JSON to JSON transformation/mapping easy, configurable and documentable. We achieve this by using a simple but feature-rich JSON configuration which then also acts as documentation and as a contract between parties.\n\n## Why\n\nPiri was born because we really dislike mapping. Documenting whatever decisions made in your code so that some product owner understands it is also _no me gusto_. Transforming data from one format to another is something software engineers do allmost daily... It should be easy! And documenting it shouldn't be something you have to worry about.\n\nAfter the Worst POC in History we never wanted to do mapping by scripts and code again. This lead to the idea that it should be possible to create a file which governs how the structure should look and how the data should be transformed. This would then be the `single source of truth` and with Piri we have achieved this.\n\nWe believe that this will make collaboration between teams faster and easier. Use Piri to agree with data formats between Front-end and Back-end. Between the 3rd party system and your back-end. You can even use Piri for testing existing integrations ;-)\n\n## Features\n\n* Mapping with configuration File.\n* [JSON Schema](https://json-schema.org/) validation of the config file.\n* Structurally Transform JSON\n* Combine multiple values to one.\n* Default values\n* If statements\n * is, contains, not\n* casting\n * integer, decimal, iso date\n\n## Contributing\nPlease see [contribute](https://piri.readthedocs.io/en/stable/contributing)\n\n## Installation\n\nPackage is on pypi. Use pip or poetry to install\n\n```sh\npip install piri\n```\n```sh\npoetry add piri\n```\n\n## Introduction\n\nHave a look at our introduction course [here](https://piri.readthedocs.io/en/stable/introduction)\n\n## Quickstart\n```python\nimport simplejson\n\nfrom piri3.process import process\n\nmy_config = {\n 'name': 'schema',\n 'array': False,\n 'objects': [\n {\n 'name': 'invoices',\n 'array': True,\n 'iterables': [\n {\n 'alias': 'invoices',\n 'path': ['root', 'invoices'],\n },\n ],\n 'attributes': [\n {\n 'name': 'amount',\n 'mappings': [\n {\n 'path': ['invoices', 'amount'],\n },\n ],\n 'casting': {\n 'to': 'decimal',\n 'original_format': 'integer_containing_decimals',\n },\n 'default': 0,\n },\n {\n 'name': 'debtor',\n 'mappings': [\n {\n 'path': ['root', 'customer', 'first_name'],\n },\n {\n 'path': ['root', 'customer', 'last_name'],\n },\n ],\n 'separator': ' ',\n },\n ],\n 'objects': [],\n },\n ],\n}\n\nexample_data = {\n 'root': {\n 'customer': {\n 'first_name': 'John',\n 'last_name': 'Smith',\n },\n 'invoices': [\n {\n 'amount': 10050,\n },\n {\n 'amount': 20050,\n },\n {\n 'amount': -15005,\n },\n ],\n },\n}\n\nmapped_data = process(example_data, my_config)\n\nwith open('resultfile.json', 'w') as output_file:\n output_file.write(simplejson.dumps(mapped_data))\n\n```\n\ncontents of resultfile.json\n```json\n{\n \"invoices\": [\n {\n \"amount\": 100.5,\n \"debtor\": \"John Smith\"\n },\n {\n \"amount\": 200.5,\n \"debtor\": \"John Smith\"\n },\n {\n \"amount\": -150.05,\n \"debtor\": \"John Smith\"\n }\n ]\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Configurable and documentable Json transformation and mapping",
"version": "3.0.4",
"project_urls": {
"Documentation": "https://greenbird.github.io/piri/",
"Homepage": "https://github.com/greenbird/piri",
"Repository": "https://github.com/greenbird/piri"
},
"split_keywords": [
"json mapping",
"data transformation",
"json to json",
"dict to dict",
"configurable"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c549cf5602e3ded325f1d05a0c7c0bc973d4721517c0ee1d65cc35772cd4af4",
"md5": "84b2059caa745ff1c2a44270d96d0694",
"sha256": "19da9b8186cd6d92947cde38069ab087dfbf16556a2c9f5cc5f6614dfe20b386"
},
"downloads": -1,
"filename": "piri3-3.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84b2059caa745ff1c2a44270d96d0694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 18956,
"upload_time": "2023-10-31T14:57:15",
"upload_time_iso_8601": "2023-10-31T14:57:15.158380Z",
"url": "https://files.pythonhosted.org/packages/4c/54/9cf5602e3ded325f1d05a0c7c0bc973d4721517c0ee1d65cc35772cd4af4/piri3-3.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10a42bac5ea58ea355f064a8f5648a5df9e0ec16c903b88a99bf6731b7141ec9",
"md5": "9beb06907cae3f5c52813020967b0bc2",
"sha256": "4ba60cf7ea3a0a8af0622d6fe26149516601505c8cbebb924677da91530b740a"
},
"downloads": -1,
"filename": "piri3-3.0.4.tar.gz",
"has_sig": false,
"md5_digest": "9beb06907cae3f5c52813020967b0bc2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 17296,
"upload_time": "2023-10-31T14:57:20",
"upload_time_iso_8601": "2023-10-31T14:57:20.951472Z",
"url": "https://files.pythonhosted.org/packages/10/a4/2bac5ea58ea355f064a8f5648a5df9e0ec16c903b88a99bf6731b7141ec9/piri3-3.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 14:57:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "greenbird",
"github_project": "piri",
"github_not_found": true,
"lcname": "piri3"
}
JSON
