.. highlight:: python

.. currentmodule:: mango

Tutorial
========

Zeroth, read the `pymongo tutorial <https://api.mongodb.com/python/current/tutorial.html>`_.
Many of Mango's objects are drop-in replacements for their equivalent pymongo objects, and can be used in exactly the same way.

First, install Mango::

   >>> pip install mango

Once Mango is installed, import it and create a client.
The client represents a connection to a MongoDB database.
The syntax for creating databases and collections is identical to pymongo's::

   import mango

   client = mango.Client()
   database = client.db_name
   collection = database.coll_name

The above code creates a Mango :class:`Client` with default host options (same as pymongo's), a :class:`Database` named ``db_name``, and a :class:`Collection` named ``coll_name``.
Although we created these manually, Mango can also manage them for us::

   import mango

   client = mango.Client()

   @mango.assign(client.db_blog)
   class Post(mango.Document):
       def __init__(self, author = 'me', title = 'Are mangos tasty?', text = 'Mangos are delicious!'):
           super().__init__(author = author, title = title, text = text)

The :func:`assign` decorator automatically creates a collection for ``Post``, which is a subclass of :class:`Document`, which is itself a subclass of :class:`dict`.
Shortcut functions such as :func:`utils.filter_dict` are available to make the above example less verbose in practice.