Files

Ian Cordasco 87a9c75ea3 Add Python API Reference documentation

This corrects some typos in earlier documentation patches, removes
outdated API reference documentation, and organizes all API reference
documentation under one chapter.

This also leaves room for future API versions and more specific API
reference documentation being broken out into sub-sections.

Change-Id: I5391a1acc7d1669207b3d10039a196d026216f40

2017-03-17 14:38:02 -05:00

3.2 KiB

Raw Blame History

Using the Projects API

Here we will assume that we already have a ~cratonclient.client.Client instance configured with the appropriate authentication method (as demonstrated in usage-auth).

Listing Projects

The Projects API implements pagination. This means that by default, it does not return all projects known to Craton. To ignore page limits and offsets, we can allow cratonclient to do handle pagination for us:

for project in craton.projects.list():
    print_project_info(project)

By default ~cratonclient.v1.projects.ProjectManager.list will handle pagination for you. If, instead, you want to handle it yourself you will want to do something akin to:

first_page_of_projects = list(craton.projects.list(autopaginate=False))
marker_id = first_page_of_projects[-1].id
second_page_of_projects = list(craton.projects.list(
    autopaginate=False,
    marker=marker_id,
))
marker_id = second_page_of_projects[-1].id
third_page_of_projects = list(craton.projects.list(
    autopaginate=False,
    marker=marker_id,
))
# etc.

A more realistic example, however, might look like this:

projects_list = None
marker = None
while projects_list and projects_list is not None:
    projects_list = list(craton.projects.list(
        marker=marker,
        autopaginate=False,
    ))
    # do something with projects_list
    if projects_list:
        marker = projects_list[-1].id

This will have the effect of stopping the while loop when you eventually receive an empty list from craton.projects.list(...).

Creating Projects

Projects are top-level items in Craton. To create a project, one needs:

A unique name
Permission to create new projects

project = craton.projects.create(
    name='my-project-0',
    variables={
        'some-var': 'some-var-value',
    },
)

Retrieving a Specific Project

Projects can be retrieved by id.

project = craton.projects.get(1)

Using a Project's Variables

Once we have a project we can introspect its variables like so:

project = craton.projects.get(project_id)
project_vars = project.variables.get()

To update them:

updated_vars = {
    'var-a': 'new-var-a',
    'var-b': 'new-var-b',
    'updated-var': 'updated value',
}
project.variables.update(**updated_vars)

To delete them:

project.variables.delete('var-a', 'var-b', 'updated-var')

Updating a Project

We can update a project's attributes (but not its variables) like so:

craton.projects.update(
    project_id,
    name='new name',
)

Most attributes that you can specify on creation can also be specified for updating the project as well.

Deleting a Project

We can delete with only its id:

craton.projects.delete(project_id)

3.2 KiB Raw Blame History