In each example I'll be assuming that you have configured connection to `syncano`::

All models are defined in :mod:`syncano.models.base` but ``syncano`` simplifies access to them

by attaching all of them directly to ``connection``. Thus::

and::

are equivalent.

Creating objects

A model class represents a single ``Syncano API`` endpoint,

and an instance of that class represents a particular record in this endpoint.

To create an object, instantiate it using **keyword arguments** to the model class,

then call :meth:`~syncano.models.base.Model.save` to save it to the ``Syncano API``.

Here’s an example::

This performs a **POST** request to ``Syncano API`` behind the scenes.

Syncano doesn’t hit the API until you explicitly call :meth:`~syncano.models.base.Model.save`.

.. note::

To create and save **an object** in a single step, use the :meth:`~syncano.models.manager.Manager.create` method.

To create and save **multiple objects** in a single step, use the :meth:`~syncano.models.manager.Manager.bulk_create` method.

Saving changes to objects

To save changes to an object that’s already in the ``Syncano API``, use :meth:`~syncano.models.base.Model.save`.

Regarding our **instance** from previous example,

this example changes its description and updates its record in the ``Syncano API``::

>>> instance.description = 'new description'

>>> instance.save()

This performs a **PUT** request to ``Syncano API`` behind the scenes.

Syncano doesn’t hit the API until you explicitly call :meth:`~syncano.models.base.Model.save`.

.. note::

To change and save **an object** in a single step, use the :meth:`~syncano.models.manager.Manager.update` method.

Retrieving objects

To retrieve objects from ``Syncano API``, construct a query via a :class:`~syncano.models.manager.Manager` on your model class.

Each model has only one :class:`~syncano.models.manager.Manager`, and it’s called **please** by default.

Access it directly via the model class, like so::

.. note::

**Managers** are accessible only via model classes, rather than from model instances,

to enforce a separation between “table-level” operations and “record-level” operations.

Retrieving all objects

The simplest way to retrieve objects from a ``Syncano API`` is to get all of them.

To do this, use the :meth:`~syncano.models.manager.Manager.all` or :meth:`~syncano.models.manager.Manager.list`

method on a :class:`~syncano.models.manager.Manager`::

>>> Instance.please

>>> Instance.please.all()

>>> Instance.please.list()

This performs a **GET** request to ``Syncano API`` list endpoint behind the scenes.

Manager is lazy

:class:`~syncano.models.manager.Manager` is lazy – the act of creating a **Manager** doesn’t involve any API activity.

You can stack filters Manager methods all day long, and Syncano won’t actually run the API call until the **Manager** is evaluated.

Take a look at this example::

>>> query = Class.please.list('test-instance')

>>> query = query.limit(10)

>>> print(query)

Though this looks like two API calls, in fact it hits API only once, at the last line (``print(query)``).

In general, the results of a :class:`~syncano.models.manager.Manager` aren’t fetched from API until you “ask” for them.

Retrieving a single object

If you know there is only one object that matches your API call,

you can use the :meth:`~syncano.models.manager.Manager.get` method on a :class:`~syncano.models.manager.Manager`

which returns the object directly::

>>> instance = Instance.please.get('instance-name')

This performs a **GET** request to ``Syncano API`` details endpoint behind the scenes.

If there are no results that match the API call, :meth:`~syncano.models.manager.Manager.get`

will raise a :class:`~syncano.exceptions.SyncanoDoesNotExist` exception.

This exception is an attribute of the model class that the API call is being performed on - so in the code above,

if there is no **Instance** object with a name equal "instance-name", Syncano will raise **Instance.DoesNotExist**.

.. note::

To have more RESTful like method names there is :meth:`~syncano.models.manager.Manager.detail`

alias for :meth:`~syncano.models.manager.Manager.get` method.

Removing a single object

The delete method, conveniently, is named :meth:`~syncano.models.base.Model.delete`.

This method immediately deletes the object and has no return value.

Example::

>>> instance = Instance.please.get('test-one')

>>> instance.delete()

This performs a **DELETE** request to ``Syncano API`` details endpoint behind the scenes.

Limiting returned objects

Use a subset of Python’s array-slicing syntax to limit your

:class:`~syncano.models.manager.Manager` to a certain number of results.

For example, this returns the first 5 objects::

>>> Instance.please[:5]

This returns the sixth through tenth objects::

>>> Instance.please[5:10]

Negative indexing (i.e. **Instance.please.all()[-1]**) is not supported.

.. note::

If you don't want to use array-slicing syntax there

is a special manager method called :meth:`~syncano.models.manager.Manager.limit`.

.. warning::

Python’s array-slicing syntax is a expensive operation in context of API calls so using

:meth:`~syncano.models.manager.Manager.limit` is a recommended way.

Lookups that span relationships

Related objects

Falling back to raw JSON

If you find yourself needing to work on raw JSON data instead of Python objects just use

:meth:`~syncano.models.manager.Manager.raw` method::

Some settings can be overwritten via environmental variables e.g:

.. code-block:: bash

.. warning::

**DEBUG** loglevel will **disbale** SSL cert check.

parent = Instance

return self.manager.all()