apocrypha

========= Apocrypha

.. image:: https://img.shields.io/pypi/v/apocrypha.svg :target: https://pypi.python.org/pypi/apocrypha :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/apocrypha.svg :target: https://pypi.python.org/pypi/apocrypha :alt: Supported Python Versions

.. image:: https://travis-ci.org/Gandalf-/apocrypha.svg?branch=master :target: https://travis-ci.org/Gandalf-/apocrypha

.. image:: https://codecov.io/gh/Gandalf-/apocrypha/branch/master/graph/badge.svg :target: https://codecov.io/gh/Gandalf-/apocrypha

Apocrypha is a lightweight, flexible JSON server and client written in Python 3. It includes a client library for easy interaction through Python, and it's simple query format allows APIs to easily written in other languages.

You can install Apocrypha with pip: pip3 install apocrypha

Then you're ready to start the server: python3 -m apocrypha.server

If you're comfortable with Haskell, there is a Haskell Implementation_.

.. _Haskell Implementation: https://github.com/Gandalf-/apocrypha-haskell

Features

• multithreaded Thread safe server and client. All queries are atomic.

• caching Writes clear the cache, any query will be served out of the cache if possible.

• nosql No schemas, no overhead, just your data in the format you provided.

• json Serve any existing JSON file to the network or start from scratch. Supports unlimited nested dictionaries.

• fast Serve up to 20,000 queries per second on cache hit heavy workloads. Database is kept in memory, no disk reads are made after startup.

• persistance Writes are queued and saved to disk once per second.

• lightweight Less than 2,000 lines of Python and no external dependencies outside of the standard library.

Example Python API usage, check pydoc3 apocrypha.client for full usage and more examples.

.. code-block:: python

from apocrypha.client import Client db = Client()

apocrypha supports lists, strings, and dictionaries

for i in range(0, 100): db.append('numbers', value=i)

print(db.get('numbers')[:10])

nested dictionaries are allowed!

customers = { 'alice': { 'age': 30 }, 'bob' : { 'age': 20 } }

db.set('customers', value=customers) print(db.keys('customers'))

query for sub keys with a simple syntax

print(db.get('customers', 'alice', 'age'))

for customer in db.keys('customers'): print(db.get('customers', customer, 'age'))

A simple C client is available here_ if you want faster start up times than Python for client applications, like shell scripts.

.. _here: https://github.com/Gandalf-/DotFiles/blob/master/bin/d.c

The network protocol is simple: send the length of the message in bytes, then the message. Query elements are delimited by newlines. Each message ends in a newline, and newlines are included in the length calculation of the message.

index

index further into the database through a key, then recursively display all keys and values under the key. this is the usual way to traverse the database and gather information

::

(dict a, str b, b in a) => a b -> IO

$ d apples granny = good $ d apples {'granny': 'good'} $ d apples granny good

append

append a list or string to an existing string or list. create the left side if it doesn't already exist

::

(none a | str a | list a, str b | list b) => a + b -> none | error

$ d toppings = mushrooms $ d toppings + pineapple $ d toppings mushrooms pineapple

remove

remove one or more elements from a list. if the resulting list now only contains one element, it's converted to a singleton

::

(list a, str b | list b, b in a) => a - b -> none | error

$ d sweets = cake pie pizza $ d sweets - pizza $ d sweets cake pie

assign

assign the value of an element. if multiple arguments are given on the right side of the assignment, the result is list assignment

::

(any a, str b | list b) => a = b -> none

$ d apple = sauce pie $ d apple sauce pie

search

recursively search the current level for a value. displays all the keys that correspond have the value's value

::

(str a) => IO

$ d rasp = berry $ d blue = berry $ d @ berry rasp blue

keys

show the keys immediately under this value. doesn't recursively print all keys and values underneathe

::

dict a => a --keys -> IO | error

$ d stone sand = weak $ d stone lime = tough $ d stone --keys sand lime

set

replace the value of an index with raw JSON

::

(any a, str b, JSON b) => a --set b -> none | error

$ d pasta --set '["spaghetti", "lasgna"]' $ d pasta spaghetti lasagna

edit

dump the raw JSON value of a key.

::

any a => a --edit -> IO

$ d pasta = spaghetti sauce $ d pasta --edit '["spaghetti", "sauce"]'

delete

delete any element from it's parent dictionary

::

any a => a --del -> none

$ d apple sauce = good $ d apple pie = great $ d apple sauce --del $ d apple {'pie': 'great'}