zish-antlr

A Python 3 library for the Zish format.


License
MIT
Install
pip install zish-antlr==0.0.13

Documentation

Python antlr implementation of Zish

A Python 3 library for the Zish format, released under the MIT Licence.

Build Status

Installation

It’s a good idea to set up a virtualenv:

virtualenv venv
source venv/bin/activate

then install Zish with pip:

pip install zish_antlr

Quickstart

To go from a Python object to an Zish string use zish.dumps. To go from an Zish string to a Python object use zish.loads. Eg.

>>> from zish import loads, dumps
>>> from datetime import datetime, timezone
>>> from decimal import Decimal
>>>
>>> # Take a Python object
>>> book = {
...     'title': 'A Hero of Our Time',
...     'read_date': datetime(2017, 7, 16, 14, 5, tzinfo=timezone.utc),
...     'would_recommend': True,
...     'description': None,
...     'number_of_novellas': 5,
...     'price': Decimal('7.99'),
...     'weight': 6.88,
...     'key': b'kshhgrl',
...     'tags': ['russian', 'novel', '19th century']}
>>>
>>> # Output it as an Zish string
>>> zish_str = dumps(book)
>>> print(zish_str)
{
  "description": null,
  "key": 'a3NoaGdybA==',
  "number_of_novellas": 5,
  "price": 7.99,
  "read_date": 2017-07-16T14:05:00Z,
  "tags": [
    "russian",
    "novel",
    "19th century"],
  "title": "A Hero of Our Time",
  "weight": 6.88e0,
  "would_recommend": true}
>>>
>>> # Load the Zish string, to give us back the Python object
>>> reloaded_book = loads(zish_str)
>>>
>>> # Print the title
>>> print(reloaded_book['title'])
A Hero of Our Time
Table 1. Python to Zish type mapping
Python Type Zish Type

bool

bool

int

integer

str

string

datetime.datetime

timestamp

dict

map

decimal.Decimal

decimal

float

float

bytearray, bytes

bytes

list, tuple

list

Release Notes

Version 0.0.9 (2017-08-24)

  • Fix bug where int was being parsed as Decimal.

  • Make bytes type return a bytes rather than a bytearray.

Version 0.0.8 (2017-08-24)

  • Container types aren’t allowed as map keys.

  • Performance improvements.

Version 0.0.7 (2017-08-22)

  • Fix bug with UTC timestamp formatting.

Version 0.0.6 (2017-08-22)

  • Fix bug in timestamp formatting.

  • Add note about comments.

Version 0.0.5 (2017-08-18)

  • Fix bug where dumps fails for a tuple.

Version 0.0.4 (2017-08-15)

  • Simplify integer types.

Version 0.0.3 (2017-08-09)

  • Fixed bug where interpreter couldn’t find the zish.antlr package in eggs.

  • Removed a few superfluous escape sequences.

Version 0.0.2 (2017-08-05)

  • Now uses RFC3339 for timestamps.

Version 0.0.1 (2017-08-03)

  • Fix bug where an EOF could cause an infinite loop.

Version 0.0.0 (2017-08-01)

  • First public release. Passes all the tests.

Contributing

Useful links:

To run the tests:

  • Change to the zish_python_antlr directory: cd zish_python_antlr

  • Create a virtual environment: virtualenv --python=python3 venv

  • Activate the virtual environment: source venv/bin/activate

  • Install tox: pip install tox

  • Run tox: tox

The core parser is created using ANTLR from the Zish grammar. To create the parser files, go to the antlr directory and download the ANTLR jar and then run the following command:

java -jar antlr-4.7-complete.jar -Dlanguage=Python3 Zish.g4

Making A New Release

Run tox to make sure all tests pass, then update the Release Notes section then do:

git tag -a x.y.z -m "version x.y.z"
python setup.py sdist bdist_wheel upload --sign