.. dongo documentation master file, created by
   sphinx-quickstart on Sat May 12 11:21:53 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

dongo
=====

A Django-ORM inspired Mongo ODM.

Python 2.7 and 3.x compatible, and requires the database server running at least MongoDB 2.6, as PyMongo does.

Installation
------------

From PyPI::

    $ pip install dongo

From the project root directory::

    $ python setup.py install

Usage
-----

Dongo is a Django-ORM inspired ODM for mongodb.

Here are a few examples of the query and class syntax.

You will need to first connect to a database and host. By default, localhost
port 27017 will be selected, but you will still need to specify the default
database::

    from dongo import connect

    # For the mydatabase named database on localhost
    connect('mydatabase')

    # For your mongodb in the private network
    connect('mydatabase', host='192.168.1.200')

    # For multiple hosts in a replica set
    connect('mydatabase', hosts=['10.0.0.100', '10.0.0.101', '10.0.0.102:27018'], replica_set='myrepset0')

    # A uri can explicitly be specified as well
    connect('mydatabase', uri='mongodb://localhost:27017/')


You can separate collections into different databases, but those connections select
the default database that collections will use if database is unspecified.

Next you will need to declare some sort of collection classes::

    from dongo import DongoCollection
    from datetime import datetime

    class MusicArtist(DongoCollection):
        # if a specific database other than the default is desired, uncomment this:
        # database = 'myotherdatabase'
        collection = 'music_artists'

    # That is all you need to query and read records from the collection "music_artists",
    # and the following would create new records and insert them and query for them.

    queen = MusicArtist({
        'name': 'queen',
        'lead': 'freddie',
        'songs': ['we are the champions', 'we will rock you'],
        'fans': ['jack', 'jill'],
        'nested': {
            'field1': 1,
            'field2': 2,
        },
    })
    # insert must be called manually
    queen.insert()

    # you can use keywords and auto-insert with the "new" classmethod.
    queen_stoneage = MusicArtist.new(
        name='queens of the stone age',
        lead='josh',
        songs=['go with the flow', 'little sister'],
        start=datetime(year=1996, month=1, day=1),
        fans=['jack'],
        nested={
            'field1': 1,
            'field2': 222,
        },
    )

    # queries are simple
    for ma in MusicArtist.filter(fans='jack'):
        print('jack likes ' + ma['name'])

    # you can even do regex queries and bulk updates
    MusicArtist.filter(name__regex='^queen').update(new_field='this is a new field')

    # There are many operators, like __gt, __gte, __lt, __lte, __in, __nin, all corresponding to mongo's
    # operators like $gt.

    # you can do set logic as well with operators: |, &, ~
    # for example less than comparisons and checking field existence:
    for ma in (MusicArtist.filter(start__lt=datetime(2000, 1, 1)) | MusicArtist.filter(start__exists=0)):
        print('either this music artist started before the year 2000 or their startdate is unknown: ' + ma['name'])

    # And you can query inside nested dictionaries

    for ma in MusicArtist.filter(nested__field1=1):
        print(ma)

    # updating the database or fetching fields is as easy as dictionary access
    ma = MusicArtist.filter(name='queen').first()
    ma['new_field'] = 'new_value'
    print(ma['name'])
    ma.set(new_field_2='a', new_field_3='b', new_field_4={'foo': 'bar'})
    ma['nested.field1'] = 'new value in nested field'
    ma.set(nested__field1='reset that nested field to this value')


You will likely want methods associated with records, and to do that you just extend your
class definition::

    class Person(DongoCollection):
        collection = 'persons'

        def print_name(self):
            print(self.get('name', 'unknown'))

        def serialize(self):
            return {
                'name': self.get('name'),
                'age': self.get('age', 0),
                'birthday': self.get('start', datetime.min).isoformat(),
                'favorite_color': self.get('color'),
            }

        def change_color(self, new_color):
            # updates record in database as well
            self['color'] = new_color

        @classmethod
        def start_new_year(cls):
            # add 1 to all age values for every record with a field "age"
            cls.filter(age__exists=1).inc(age=1)
            # kill off those 110 and older
            cls.filter(age__gte=110).delete()

        @classmethod
        def startswith(cls, prefix):
            # find all persons with a name that starts with ``prefix``
            regex = '^{}'.format(prefix)
            return cls.filter(name__regex=regex)

        @classmethod
        def endswith(cls, suffix):
            # find all persons with a name that ends with ``suffix``
            regex = '{}$'.format(suffix)
            return cls.filter(name__regex=regex)

        @classmethod
        def first_10(cls):
            return cls.filter().iter(limit=10, sort='name')

        @classmethod
        def sort_by_oldest_first_then_alphabetically(cls):
            return cls.filter().iter(sort=[('age', -1), ('name', 1)])


.. toctree::
   :maxdepth: 2


Release Notes
-------------

:0.4.0:
    Added DongoBulk functionality, with lazy and bulk operations.
:0.3.0:
    Added Dongo references feature, with instance.ref() and deref
:0.2.3:
    Removed unnecessary dependency
:0.2.2:
    Released alpha with python 2.7 and 3.x compatibility
:0.2.1:
    Released alpha with python 3.x compatibility


Dongo API
---------

.. automodule:: dongo
   :members:


Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`