panoptes_client package

As a convenience, the following classes can be imported directly from the root of the panoptes_client package:

For example:

from panoptes_client import Panoptes, Project

Panoptes.connect(username='example', password='example')

new_project = Project()
new_project.display_name = 'My new project'
new_project.description = 'A great new project!'
new_project.primary_language = 'en'
new_project.private = True
new_project.save()

panoptes_client.panoptes module

class panoptes_client.panoptes.Panoptes(endpoint=None, client_id=None, client_secret=None, redirect_url=None, username=None, password=None, admin=False)[source]

Bases: object

The low-level Panoptes HTTP client class. You should never need to manually create an instance of this class, but you will need to import it to log in, etc.

classmethod connect(username=None, password=None, endpoint=None, admin=False)[source]

Configures the Panoptes client for use.

Note that there is no need to call this unless you need to pass one or more of the below arguments. By default, the client will connect to the public Zooniverse.org API as an anonymous user.

Also note that this method only stores the given values. It does not immediately perform any authentication or attempt to connect to the API. If the given credentials are incorrect, the client will raise a PanoptesAPIException the first time it makes a request to the API.

All arguments are optional:

  • username is your Zooniverse.org username.
  • password is your Zooniverse.org password.
  • endpoint is the HTTP API endpoint you’d like to connect to. Defaults to https://www.zooniverse.org. Should not include a trailing slash.
  • admin is a boolean, switching on admin mode if True. Has no effect if the given username is not a Zooniverse.org administrator.

Examples:

Panoptes.connect(username='example', password='example')
Panoptes.connect(endpoint='https://panoptes.example.com')
exception panoptes_client.panoptes.PanoptesAPIException[source]

Bases: Exception

Raised whenever the API returns an error. The exception will contain the raw error message from the API.

class panoptes_client.panoptes.PanoptesObject(raw={}, etag=None)[source]

Bases: object

The base class of all Panoptes model classes. You should never need to create instances of this class, but the methods defined here are common to all the model subclasses.

classmethod find(_id)[source]

Returns the individual instance with the given ID, if it exists. Raises PanoptesAPIException if the object with that ID is not found.

reload()[source]

Re-fetches the object from the API, discarding any local changes. Returns without doing anything if the object is new.

save()[source]

Saves the object. If the object has not been saved before (i.e. it’s new), then a new object is created. Otherwise, any changes are submitted to the API.

classmethod where(**kwargs)[source]

Returns a generator which yields instances matching the given query arguments.

For example, this would yield all :py:class:`Project`s:

Project.where()

And this would yield all launch approved :py:class:`Project`s:

Project.where(launch_approved=True)
exception panoptes_client.panoptes.ReadOnlyAttributeException[source]

Bases: Exception

Raised if an attempt is made to modify an attribute of a PanoptesObject which the API does not allow to be modified.

panoptes_client.classification module

class panoptes_client.classification.Classification(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

classmethod where(scope=None, **kwargs)[source]

Like PanoptesObject.where(), but also allows setting the query scope.

Examples:

my_classifications = Classifiction.where()
my_proj_123_classifications = Classification.where(project_id=123)

all_proj_123_classifications = Classification.where(
    scope='project',
    project_id=123,
)

panoptes_client.collection module

class panoptes_client.collection.Collection(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

add(subjects)[source]

Links the given subjects to this collection.

  • subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.

Examples:

collection.add(1234)
collection.add([1,2,3,4])
collection.add(Subject(1234))
collection.add([Subject(12), Subject(34)])
remove(subjects)[source]

Unlinks the given subjects from this collection.

  • subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.

Examples:

collection.remove(1234)
collection.remove([1,2,3,4])
collection.remove(Subject(1234))
collection.remove([Subject(12), Subject(34)])
subjects

A generator which yields each Subject in this collection.

panoptes_client.exportable module

class panoptes_client.exportable.Exportable[source]

Bases: object

Abstract class containing methods for generating and downloading data exports.

describe_export(export_type)[source]

Fetch metadata for an export.

  • export_type is a string specifying which type of export to look up.

Returns a dict containing metadata for the export.

generate_export(export_type)[source]

Start a new export.

  • export_type is a string specifying which type of export to start.

Returns a dict containing metadata for the new export.

get_export(export_type, generate=False, wait=False, wait_timeout=None)[source]

Downloads a data export over HTTP. Returns a file-like object containing the content of the export.

  • export_type is a string specifying which type of export should be downloaded.
  • generate is a boolean specifying whether to generate a new export and wait for it to be ready, or to just download the latest export.
  • wait is a boolean specifying whether to wait for an in-progress export to finish, if there is one. Has no effect if generate is True.
  • wait_timeout is the number of seconds to wait if wait is True. Has no effect if wait is False or if generate is True.

Example:

classification_export = Project(1234).get_export('classifications')
for row in csv.DictReader(classification_export):
    print(row)
wait_export(export_type, timeout=None)[source]

Blocks until an in-progress export is ready.

  • export_type is a string specifying which type of export to wait for.
  • timeout is the maximum number of seconds to wait.

If timeout is given and the export is not ready by the time limit, PanoptesAPIException is raised.

panoptes_client.project module

class panoptes_client.project.Project(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_subject_sets(subject_sets)[source]

Links the given subject sets to this project. New subject sets are created as copies of the given sets.

  • subject_sets can be a list of SubjectSet instances, a list of subject set IDs, a single SubjectSet instance, or a single subject set ID.

Examples:

project.add_subject_sets(1234)
project.add_subject_sets([1,2,3,4])
project.add_subject_sets(SubjectSet(1234))
project.add_subject_sets([SubjectSet(12), SubjectSet(34)])
add_workflows(workflows)[source]

Links the given workflows to this project. New workflows are created as copies of the given workflows.

  • workflows can be a list of Workflow instances, a list of workflow IDs, a single Workflow instance, or a single workflow ID.

Examples:

project.add_workflows(1234)
project.add_workflows([1,2,3,4])
project.add_workflows(Workflow(1234))
project.add_workflows([Workflow(12), Workflow(34)])
collaborators(*roles)[source]

Returns a list of User who are collaborators on this project.

Zero or more role arguments can be passed as strings to narrow down the results. If any roles are given, users who possess at least one of the given roles are returned.

Examples:

all_collabs = project.collaborators()
moderators = project.collaborators("moderators")
moderators_and_translators = project.collaborators(
    "moderators",
    "translators",
)
classmethod find(id='', slug=None)[source]

Similar to PanoptesObject.find(), but allows lookup by slug as well as ID.

Examples:

project_1234 = Project.find(1234)
galaxy_zoo = Project.find(slug="zooniverse/galaxy-zoo")

panoptes_client.project_preferences module

class panoptes_client.project_preferences.ProjectPreferences(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

Contains the settings for a User on a Project.

classmethod find(id='', user=None, project=None)[source]

Like PanoptesObject.find() but can also query by user and project.

  • user and project can be either a User and Project instance respectively, or they can be given as IDs. If either argument is given, the other is also required.
classmethod save_settings(project=None, user=None, settings=None)[source]

Save settings for a user without first fetching their preferences.

  • user and project can be either a User and Project instance respectively, or they can be given as IDs. If either argument is given, the other is also required.
  • settings is a dict containing the settings to be saved.

panoptes_client.subject module

class panoptes_client.subject.Subject(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

add_location(location)[source]

Add a media location to this subject.

  • location can be an open file object, a path to a local file, or a dict containing MIME types and URLs for remote media.

Examples:

subject.add_location(my_file)
subject.add_location('/data/image.jpg')
subject.add_location({'image/png': 'https://example.com/image.png'})
save()[source]

Like PanoptesObject.save(), but also uploads any local files which have previosly been added to the subject with add_location(). Automatically retries uploads on error.

panoptes_client.subject_set module

class panoptes_client.subject_set.SubjectSet(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

add(subjects)[source]

Links the given subjects to this set.

  • subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.

Examples:

subject_set.add(1234)
subject_set.add([1,2,3,4])
subject_set.add(Subject(1234))
subject_set.add([Subject(12), Subject(34)])
remove(subjects)[source]

Unlinks the given subjects from this set.

  • subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.

Examples:

subject_set.remove(1234)
subject_set.remove([1,2,3,4])
subject_set.remove(Subject(1234))
subject_set.remove([Subject(12), Subject(34)])
subjects

A generator which yields Subject objects which are in this subject set.

Examples:

for subject in subject_set.subjects:
    print(subject.id)

panoptes_client.user module

class panoptes_client.user.User(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

avatar

A dict containing metadata about the user’s avatar.

panoptes_client.workflow module

class panoptes_client.workflow.Workflow(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_subject_sets(subject_sets)[source]

Links the given subject sets to this workflow.

  • subject_sets can be a list of SubjectSet instances, a list of subject set IDs, a single SubjectSet instance, or a single subject set ID.

Examples:

workflow.add_subject_sets(1234)
workflow.add_subject_sets([1,2,3,4])
workflow.add_subject_sets(SubjectSet(1234))
workflow.add_subject_sets([SubjectSet(12), SubjectSet(34)])
remove_subject_sets(subject_sets)[source]

Unlinks the given subject sets from this workflow.

  • subject_sets can be a list of SubjectSet instances, a list of subject set IDs, a single SubjectSet instance, or a single subject set ID.

Examples:

workflow.remove_subject_sets(1234)
workflow.remove_subject_sets([1,2,3,4])
workflow.remove_subject_sets(SubjectSet(1234))
workflow.remove_subject_sets([SubjectSet(12), SubjectSet(34)])
retire_subjects(subjects, reason='other')[source]

Retires subjects in this workflow.

  • subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.
  • reason gives the reason the subject has been retired. Defaults to other.

Examples:

workflow.retire_subjects(1234)
workflow.retire_subjects([1,2,3,4])
workflow.retire_subjects(Subject(1234))
workflow.retire_subjects([Subject(12), Subject(34)])
versions

A generator which yields all WorkflowVersion instances for this workflow.

panoptes_client.workflow_version module

class panoptes_client.workflow_version.WorkflowVersion(raw={}, etag=None)[source]

Bases: panoptes_client.panoptes.PanoptesObject

classmethod find(_id, workflow)[source]

Like PanoptesObject.find() but also allows lookup by workflow.

save()[source]

Not implemented for this class. It is not possible to modify workflow versions once they are created.

workflow

The Workflow to which this version refers.