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')
-
classmethod
-
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.
-
classmethod
-
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.- scope can be any of the values given in the Classification Collection API documentation without the leading slash.
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, )
-
classmethod
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 singleSubject
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)])
- subjects can be a list of
-
remove
(subjects)[source]¶ Unlinks the given subjects from this collection.
- subjects can be a list of
Subject
instances, a list of subject IDs, a singleSubject
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 can be a list of
-
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
isTrue
. - wait_timeout is the number of seconds to wait if
wait
isTrue
. Has no effect ifwait
isFalse
or ifgenerate
isTrue
.
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 singleSubjectSet
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)])
- subject_sets can be a list of
-
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 singleWorkflow
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)])
- workflows can be a list of
-
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 aProject
.-
classmethod
find
(id='', user=None, project=None)[source]¶ Like
PanoptesObject.find()
but can also query by user and project.
-
classmethod
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 adict
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'})
- location can be an open
-
save
()[source]¶ Like
PanoptesObject.save()
, but also uploads any local files which have previosly been added to the subject withadd_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 singleSubject
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)])
- subjects can be a list of
-
remove
(subjects)[source]¶ Unlinks the given subjects from this set.
- subjects can be a list of
Subject
instances, a list of subject IDs, a singleSubject
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 can be a list of
-
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.- workflow must be a
Workflow
instance.
- workflow must be a
-
classmethod