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 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 Organization objects in the Brood server, etc.

The Organization API provides access to Teams, Users and Repositories.

Creating the BroodClient

When using the Hatcher Python API, the entry-point should always be via the 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 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 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]: