========
 Client
========

Connect to a xdserver server using a Python shell with
:program:`xdclient`.  Connect to a xdserver server in your own
code with :class:`xdserver.client.Client`.

In this section you'll learn how to connect using the command-line or
in your own code, and you'll see some basic examples of how to use
databases once connected.

For more complete information, see :doc:`api`.


Connect using the command-line
==============================

Run :program:`xdclient`, which connects to a xdserver server,
then provides a Python shell giving you access to useful objects:

.. code-block:: console

    $ xdclient
    xdserver shell
      Connection - xdserver.connection.Connection class
      client - xdserver.client.Client instance
    >>>

.. note::

   By default, :program:`xdclient` connects to 127.0.0.1 on port
   22972.  Connect to a different host and/or port by using
   :option:`--host` and :option:`--port`, as in this example:

   .. code-block:: console

      $ xdclient --host=11.22.33.44 --port=3333

.. note::

   If you have IPython_ installed, :program:`xdclient` will favor
   that over the default Python shell:

   .. code-block:: console

      $ xdclient
      xdserver shell
        Connection - xdserver.connection.Connection class
        client - xdserver.client.Client instance
      In [1]:

.. _IPython: http://ipython.scipy.org/

In the shell, use the :obj:`client` object's
:meth:`~xdserver.client.Client.storage` method to get a
:class:`durus.client.ClientStorage` instance for a named database.
Once you have that, create a :class:`~durus.connection.Connection`
instance::

    >>> conn = Connection(client.storage('userdata'))

With the :class:`~durus.connection.Connection` instance, use the
standard Durus API to operate on the database::

    >>> root = conn.get_root()
    >>> root['users'] = {}
    >>> root['groups'] = {}
    >>> conn.commit()


Connect in your own code
========================

Create a :class:`~xdserver.client.Client` instance, then perform
operations on it as above in `Connect using the command-line`_::

    from durus.connection import Connection
    from xdserver.client import Client

    # Connect to default server.
    client = Client()

    # Work with the "userdata" database.
    conn = Connection(client.storage('userdata'))

    # Create some objects and commit them in a transaction.
    root = conn.get_root()
    root['users'] = {}
    root['groups'] = {}
    conn.commit()
