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
.
Contents
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]: