=================
 Getting Started
=================

The Hatcher Python API is a hierarchical API representing the logical
hierarchy of components in a Brood server.

The top-level entry point into the Hatcher Python API is the
:class:`~hatcher.core.brood_client.BroodClient`, which provides access
to the most top-level API of the Brood server.  This includes actions
such as manipulating API tokens for authentication, creating
:class:`~hatcher.core.organization.Organization` objects in the Brood
server, etc.

The :class:`~hatcher.core.organization.Organization` API provides access
to :class:`Teams <hatcher.core.team.Team>`, :class:`Users
<hatcher.core.user.User>` and :class:`Repositories
<hatcher.core.repository.Repository>`.


.. contents::

Creating the ``BroodClient``
============================

When using the Hatcher Python API, the entry-point should always be via
the :meth:`BroodClient.from_url()
<hatcher.core.brood_client.BroodClient.from_url>` method.  This ensures
that the full API is correctly initialized::

    from hatcher.api import BroodClient

    # Create a BroodClient instance from a Brood URL
    # and username/password pair.
    brood_client = BroodClient.from_url(
        'https://brood.enthought.com',
        auth=('username', 'password'))


Token Authentication
====================

Brood servers always require authentication.  There are two methods of
authentication available via Hatcher: password authentication and bearer
token authentication.  The example above shows authentication with a
username and password.  In order to authenticate with a bearer token,
first a token needs to be created, following the guide in
:ref:`token-authentication`.  Once a token has been created, it can be
used here::


    from hatcher.api import BroodBearerTokenAuth, BroodClient

    # Create a BroodClient instance from a Brood URL
    # and a bearer token
    token_auth = BroodBearerTokenAuth('<token-data>')
    brood_client = BroodClient.from_url(
        'https://brood.enthought.com',
        auth=token_auth)


The Hatcher Python API is Lazy
==============================

The Hatcher Python API will only issue requests to the Brood server once
a full interaction has been specified.  A full interaction is a command
such as creating a repository, uploading an egg or downloading an index.
For other commands, which just build up the Hatcher API hierarchy, no
requests will be sent::


    from hatcher.api import BroodClient

    # None of the following will issue any requests.  These just build
    # up the required context for a request.
    brood_client = BroodClient.from_url('https://brood.enthought.com')
    enthought = brood_client.organization('enthought')
    dev = enthought.repository('dev')
    rh5_64 = dev.platform('rh5-x86_64')

    # This is when Hatcher will issue a request to Brood
    rh5_64.upload_egg('nose-1.3.0-1.egg')


Exploring the API
=================

Once the :class:`~hatcher.core.brood_client.BroodClient` instance has
been created, the Hatcher Python API can easily be explored
interactively from ``IPython``.  This is a good way to learn what is
possible using the Hatcher Python API::

    In [1]: from hatcher.api import BroodClient

    In [2]: brood_client = BroodClient.from_url('https://brood.enthought.com')

    In [3]: brood_client.
    brood_client.create_api_token     brood_client.list_api_tokens
    brood_client.create_organization  brood_client.list_organizations
    brood_client.delete_api_token     brood_client.list_platforms
    brood_client.from_url             brood_client.organization

    In [3]: brood_client.

    In [3]: brood_client.organization?
    Type:        method
    String form: <bound method BroodClient.organization of <hatcher.core.brood_client.BroodClient object at 0x7fc219a65da0>>
    File:        /home/simon/workspace/enthought/source/hatcher/hatcher/core/brood_client.py
    Definition:  brood_client.organization(self, name)
    Docstring:
    Get an existing organization.

    Parameters
    ----------
    name : str
        The name of the organization.

    Returns :class:`~hatcher.core.organization.Organization`

    In [4]: enthought = brood_client.organization('enthought')

    In [5]: enthought.
    enthought.create_repository  enthought.list_repositories  enthought.name
    enthought.create_team        enthought.list_teams         enthought.repository
    enthought.create_user        enthought.list_users         enthought.team
    enthought.delete             enthought.metadata           enthought.user

    In [5]: dev = enthought.repository('dev')

    In [6]: dev.
    dev.delete             dev.metadata           dev.organization_name  dev.upload_app
    dev.list_platforms     dev.name               dev.platform           dev.upload_runtime

    In [6]: rh5_64 = dev.platform('rh5-x86_64')

    In [7]: rh5_64.
    rh5_64.app_index              rh5_64.iter_download_egg      rh5_64.organization_name
    rh5_64.app_metadata           rh5_64.iter_download_runtime  rh5_64.repository_name
    rh5_64.delete_egg             rh5_64.list_apps              rh5_64.runtime_index
    rh5_64.download_egg           rh5_64.list_eggs              rh5_64.runtime_metadata
    rh5_64.download_runtime       rh5_64.list_runtimes          rh5_64.upload_egg
    rh5_64.egg_index              rh5_64.name

    In [7]: rh5_64.upload_egg?
    Type:        method
    String form: <bound method SinglePlatformRepository.upload_egg of <SinglePlatformRepository organization='enthought', repository='dev', platform='rh5-x86_64'>>
    File:        /home/simon/workspace/enthought/source/hatcher/hatcher/core/repository.py
    Definition:  rh5_64.upload_egg(self, filename, overwrite=False)
    Docstring:
    Upload an egg to the repository.

    In [8]: