PyMDict
#######

.. image:: https://badge.fury.io/py/pymdict.svg
    :target: https://badge.fury.io/py/pymdict
.. image:: https://travis-ci.org/ipazc/pymdict.svg?branch=master
    :target: https://travis-ci.org/ipazc/pymdict


Advanced Python Mongo Dict.
A Python dictionary based on a MongoDB. It allows to treat a collection as a dictionary in Python, with extensive capabilities, like allowing basic queries, bulk operations and versioning (forks).

INSTALLATION
############

Currently it is only supported Python3.4 onwards. It can be installed through pip:

.. code:: bash

    $ pip3 install pymdict


USAGE
#####

In order to run, a MongoDB server is required.

A Mongo-based dictionary can be instantiated as follows:

.. code:: python

    >>> from pymdict.mongo_dict import MongoDict
    >>>
    >>> m = MongoDict("custom_id", mongo_host="localhost", mongo_port=27017)


Once `m` is instantiated, it can be used as a normal dictionary.

.. code:: python

    >>> m["key"] = "value"
    >>> m[44] = "value2"
    >>> m["key2"] = "value3"
    >>> m["number"] = 44

    >>> print(list(m.keys()))
    ["key", 44, "key2, "number"]

    >>> for key, value in m.items():
    ...     print("{}: {}".format(key, value))
    key: value
    44: value2
    key2: value3
    number: 44


In addition, there are advanced functionalities like queries:

.. code:: python

    >>> for key, value, _ in m('key % ey'):
    ...     print("{}: {}".format(key, value))
    key: value
    key2: value3

    >>> for key, value, _ in m('key % ey or value = 44'):
    ...     print("{}: {}".format(key, value))
    key: value
    key2: value3
    number: 44

Queries also support to query with sub-dict elements:

.. code:: python

    >>> m["first"] = {"example": 44}
    >>> m["second"] = {"example": 45}
    >>> m["third"] = {"example": 46}

    >>> for key, value, _ in m('value.example > 44 and value.example < 46'):
    ...     print("{}: {}".format(key, value))
    second: 45

(TODO: Check the wiki page for more information about the query syntax)

Note that all the stores and removals are stored within a MongoDB. This means for each addition,edit and removal there is at least one connection to the MongoDB backend. In order to optimize it, a bulk operation can be used to wrap such amount of operations in a single connection:

.. code:: python

    >>> with m.bulk(buffer_size=100) as m:
    ...     for x in range(2000):
    ...         m["key{}".format(x)] = {"example": x}

Also, a mongo dict can be forked without the need to copy its content. This is specially useful if the target dict is extremely big and a copy is wanted. Note that a fork is an immediate process, and it allows to override or remove elements without modifying an original dictionary. It is achieved by applying a versioning technique with the dictionaries and it is still in an experimental state.

(TODO: More information about forking and versioning in the wiki page)

.. code:: python

    >>> m['foo'] = "bar"
    >>> fork = m.fork()
    >>> print(fork['foo'])
    bar
    >>> fork['foo'] = "foo"
    >>> print(fork['foo'], m['foo'])
    foo bar
