+ All Categories
Home > Documents > Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions...

Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions...

Date post: 08-Oct-2020
Category:
Upload: others
View: 3 times
Download: 0 times
Share this document with a friend
30
Panoptes Client Documentation Release 1.1 Zooniverse Feb 08, 2019
Transcript
Page 1: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client DocumentationRelease 1.1

Zooniverse

Feb 08, 2019

Page 2: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types
Page 3: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Contents

1 User guide 31.1 User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.2.1 Uploading non-image media types . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.3 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.1.3.1 Tutorial: Creating a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.3.2 Other examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Module reference 92.1 panoptes_client package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1.1 panoptes_client.panoptes module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.1.2 panoptes_client.classification module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.1.3 panoptes_client.collection module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.1.4 panoptes_client.exportable module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.1.5 panoptes_client.project module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.1.6 panoptes_client.project_preferences module . . . . . . . . . . . . . . . . . . . . . . . . . . 152.1.7 panoptes_client.subject module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.1.8 panoptes_client.subject_set module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.1.9 panoptes_client.user module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.1.10 panoptes_client.workflow module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.1.11 panoptes_client.workflow_version module . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3 Indices and tables 21

Python Module Index 23

i

Page 4: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

ii

Page 5: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

This package is the Python SDK for Panoptes, the platform behind the Zooniverse. This module is intended to allowprogrammatic management of projects, providing high level access to the API for common project management tasks.

You can find the source code for this package on GitHub. We welcome bug reports, feature requests, and pull requests.

Contents 1

Page 6: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

2 Contents

Page 7: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

CHAPTER 1

User guide

1.1 User Guide

1.1.1 Introduction

The Panoptes Client provides high level access to the HTTP API for common project management tasks. The clientmodule provides a set of classes which act as an object-relational mapping (ORM) layer on top of the API, allowingyou to perform tasks such as creating/uploading subjects, retiring subjects, and downloading data exports withouthaving to concern yourself with the low level detail of how the API functions.

Most of the classes you’ll need can be imported directly from the panoptes_client package; see the modulereference for a complete list.

Of special note is the Panoptes class which provides the Panoptes.connect() method. This method must becalled to log into the API before you can perform any privileged, project owner-specific actions (though some things,such as listing public projects or available workflows, can be done anonymously, without logging in).

Most of the classes you’ll be using are subclasses of the abstract PanoptesObject class. Any references in thisdocumentation to “Panoptes object classes” or “model classes” refer to these subclasses. You should familiariseyourself with the methods that Panoptes object classes all have, in particular PanoptesObject.save() andPanoptesObject.where().

You might also want to refer to the Panoptes API documentation as this lists the full options and allowed values formany of the methods in this module – many method arguments are simply passed to the API as-is, with the APIperforming server-side validation. The API documentation also lists the full attributes for each class; these are notincluded in this documentation.

1.1.2 Installation

Install latest stable release:

$ pip install panoptes-client

3

Page 8: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

Or for development or testing, you can install the development version directly from GitHub:

$ pip install -U git+git://github.com/zooniverse/panoptes-python-client.git

Upgrade an existing installation:

$ pip install -U panoptes-client

The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards.

1.1.2.1 Uploading non-image media types

If you wish to upload subjects with non-image media (e.g. audio or video), you will need to make sure you havethe libmagic library installed. If you don’t already have libmagic, please see the dependency information forpython-magic for more details.

1.1.3 Usage Examples

1.1.3.1 Tutorial: Creating a new project

Once you have the client installed, you can import the modules you need from the panoptes_client package.For this tutorial, we’re going to log into the Panoptes API, create a project, create a subject set, and finally create somesubjects to go in the new set. Let’s start by importing all the classes we’ll need for that:

from panoptes_client import Panoptes, Project, SubjectSet, Subject

Now that we’ve imported all that, we can use the Panoptes.connect() method to log in:

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

Next we will create our new project. All we need to do is instantiate a new instance of Project, set some requiredattributes, and then save it, like so:

tutorial_project = Project()

tutorial_project.display_name = 'Tutorial Project'tutorial_project.description = 'My first project created in Python'tutorial_project.primary_language = 'en'tutorial_project.private = True

tutorial_project.save()

Now if you log into the Zooniverse project builder you should see the new project listed there. Next we will create asubject set in the same way:

subject_set = SubjectSet()

subject_set.links.project = tutorial_projectsubject_set.display_name = 'Tutorial subject set'

subject_set.save()

Here you’ll notice we set the subject_set.links.project attribute. links is a special attribute that handlesconnecting related Panoptes objects to each other. You can directly assign a Panoptes object instance, as above, or youcan assign an object’s ID number if you have it. As well as assigning objects, you can use links to access related

4 Chapter 1. User guide

Page 9: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

objects. Now that we’ve created our new subject set, we will also see a link to it on tutorial_project if wereload it:

tutorial_project.reload()print(tutorial_project.links.subject_sets)

This would output something like this:

[<SubjectSet 1234>]

Showing a list of the linked subject sets (containing only our new set in this case). Here 1234 is the internal ID numberof the subject set (also accessible as subject_set.id), so the exact result you get will be slightly different.

Now that we have a subject set, let’s create some subjects and add them to it. For this tutorial, we’ll assume you have adict containing filenames and subject metadata. In reality you might load this from a CSV file, or query a database,or generate it in any number of different ways, but this would be outside the scope of this tutorial:

subject_metadata = {'/Users/me/file1.png': {

'subject_reference': 1,'date': '2017-01-01',

},'/Users/me/file2.png': {

'subject_reference': 2,'date': '2017-01-02',

},'/Users/me/file3.png': {

'subject_reference': 3,'date': '2017-01-03',

},}

Now we create a Subject instance for each one:

new_subjects = []

for filename, metadata in subject_metadata.items():subject = Subject()

subject.links.project = tutorial_projectsubject.add_location(filename)

subject.metadata.update(metadata)

subject.save()new_subjects.append(subject)

Saving the subject will create the subject in Panoptes and then upload the image file. The Subject.add_location() method prepares files to be uploaded. You can give it a string, as above, to point to a pathon the local filesystem, or you can give it an open file object, or a dict for remote URLs. See the Subject.add_location() documentation for examples.

Note that by default the metadata attribute is an empty dict, so in this example we just call dict.update() tomerge it with our existing metadata. You can also set individual keys as normal:

subject.metadata['my_metadata'] = 'abcd'

Or you can leave it empty if you don’t need to set anything.

1.1. User Guide 5

Page 10: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

All that’s left to do now is to link our new subjects to our new subject set. That can be done with the SubjectSet.add() method:

subject_set.add(new_subjects)

That takes the list of subjects and links them all in one go. This is the preferred way of doing it if you have severalsubjects to link (because it’s faster than making several separate calls), but you can also link subjects one at a time ifyou need to:

subject_set.add(subject1)subject_set.add(subject2)

And that’s all there is to it! Your new subjects are now linked to the new subject set.

1.1.3.2 Other examples

Print all project titles:

for project in Project.where():print(project.title)

Find a project by slug and print all its workflow names:

project = Project.find(slug='zooniverse/example')for workflow in project.links.workflows:

print(workflow.display_name)

List the subjects in a subject_set:

subject_set = SubjectSet.find(1234)for subject in subject_set.subjects:

print(subject.id)

Add subject set to first workflow in project:

workflow = project.links.workflows[0]workflow.links.subject_sets.add(subject_set)

Project owners with client credentials can update their users’ project settings (workflow_id only):

Panoptes.connect(client_id="example", client_secret="example")

user = User.find("1234")project = Project.find("1234")new_settings = {"workflow_id": "1234"}

ProjectPreferences.save_settings(project=project,user=user,settings=new_settings,

)

Alternatively, the project ID and user ID can be passed in directly if they are already known:

ProjectPreferences.save_settings(project=project_id,

(continues on next page)

6 Chapter 1. User guide

Page 11: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

(continued from previous page)

user=user_id,settings=new_settings,

)

1.1. User Guide 7

Page 12: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

8 Chapter 1. User guide

Page 13: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

CHAPTER 2

Module reference

2.1 panoptes_client package

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

• Panoptes

• Classification

• Collection

• Project

• ProjectPreferences

• Subject

• SubjectSet

• User

• Workflow

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 = Truenew_project.save()

9

Page 14: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

2.1.1 panoptes_client.panoptes module

class panoptes_client.panoptes.LinkCollection(cls, slug, parent, linked_objects)Bases: object

A collection of PanoptesObject of one class which are linked to a parent PanoptesObject.

Allows indexing, iteration, and membership testing:

project = Project(1234)

print(project.links.workflows[2].display_name)

for workflow in project.links.workflows:print(workflow.id)

if Workflow(5678) in project.links.workflows:print('Workflow found')

# Integers, strings, and PanoptesObjects are all OKif 9012 not in project.links.workflows:

print('Workflow not found')

add(objs)Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObjectinstance, or a single object ID.

Examples:

organization.links.projects.add(1234)organization.links.projects.add(Project(1234))workflow.links.subject_sets.add([1,2,3,4])workflow.links.subject_sets.add([Project(12), Project(34)])

remove(objs)Removes the given objs from this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObjectinstance, or a single object ID.

Examples:

organization.links.projects.remove(1234)organization.links.projects.remove(Project(1234))workflow.links.subject_sets.remove([1,2,3,4])workflow.links.subject_sets.remove([Project(12), Project(34)])

exception panoptes_client.panoptes.ObjectNotSavedExceptionBases: Exception

Raised if an attempt is made to perform an operation on an unsaved PanoptesObject which requires theobject to be saved first.

class panoptes_client.panoptes.Panoptes(endpoint=None, client_id=None,client_secret=None, redirect_url=None, user-name=None, password=None, login=None,admin=False)

Bases: object

10 Chapter 2. Module reference

Page 15: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

The low-level Panoptes HTTP client class. Use this class to log into the API. In most cases you can just callPanoptes.connect() once and all subsequent API requests will be authenticated.

If you want to configure multiple clients, e.g. to perform operations as multiple users, you should initialisethe client as a context manager, using the with statement instead of using Panoptes.connect(). In thisexample, we modify a project by authenticating as the project owner, then log in as a regular user to add asubject to a collection, then switch back to the project owner’s account to retire some subjects:

owner_client = Panoptes(username='example-project-owner', password='')

with owner_client:project = Project(1234)project.display_name = 'New name'project.save()

with Panoptes(username='example-user', password=''):Collection(1234).add(Subject(1234))

with owner_client:Workflow(1234).retire_subjects([1234, 5678, 9012])

Using the with statement in this way ensures it is clear which user will be used for each action.

classmethod connect(username=None, password=None, endpoint=None, admin=False)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. Bydefault, the client will connect to the public Zooniverse.org API as an anonymous user.

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 tohttps://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 aZooniverse.org administrator.

Examples:

Panoptes.connect(username='example', password='example')Panoptes.connect(endpoint='https://panoptes.example.com')

exception panoptes_client.panoptes.PanoptesAPIExceptionBases: 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)Bases: object

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

‘PanoptesObject‘s support lazy loading of attributes, where data is loaded from the API only when it is firstaccessed. You can do this by passing an object ID to the contructor:

project = Project(1234)print(project.display_name)

2.1. panoptes_client package 11

Page 16: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

This will not make any HTTP requests until the print statement.

delete()Deletes the object. Returns without doing anything if the object is new.

classmethod find(_id)Returns the individual instance with the given ID, if it exists. Raises PanoptesAPIException if theobject with that ID is not found.

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

save()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)Returns a generator which yields instances matching the given query arguments.

For example, this would yield all Project:

Project.where()

And this would yield all launch approved Project:

Project.where(launch_approved=True)

exception panoptes_client.panoptes.ReadOnlyAttributeExceptionBases: Exception

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

2.1.2 panoptes_client.classification module

class panoptes_client.classification.Classification(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

classmethod where(scope=None, **kwargs)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 theleading slash.

Examples:

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

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

)

12 Chapter 2. Module reference

Page 17: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

2.1.3 panoptes_client.collection module

class panoptes_client.collection.Collection(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

add(subjects)A wrapper around LinkCollection.add(). Equivalent to:

collection.links.add(subjects)

classmethod find(id=”, slug=None)Similar to PanoptesObject.find(), but allows lookup by slug as well as ID.

Examples:

collection_1234 = Collection.find(1234)my_collection = Collection.find(slug="example/my-collection")

remove(subjects)A wrapper around LinkCollection.remove(). Equivalent to:

collection.links.remove(subjects)

set_default_subject(subject)Sets the subject’s location media URL as a link. It displays as the default subject on PFE.

• subject can be a single Subject instance or a single subject ID.

Examples:

collection.set_default_subject(1234)collection.set_default_subject(Subject(1234))

subjectsA generator which yields each Subject in this collection.

2.1.4 panoptes_client.exportable module

class panoptes_client.exportable.ExportableBases: object

Abstract class containing methods for generating and downloading data exports.

describe_export(export_type)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)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)Downloads a data export over HTTP. Returns a Requests Response object containing the content of theexport.

2.1. panoptes_client package 13

Page 18: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

• 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 tojust download the latest export.

• wait is a boolean specifying whether to wait for an in-progress export to finish, if there is one. Has noeffect if generate is True.

• wait_timeout is the number of seconds to wait if wait is True. Has no effect if wait is False orif generate is True.

The returned Response object has two additional attributes as a convenience for working with theCSV content; csv_reader and csv_dictreader, which are wrappers for csv.reader() and csv.DictReader respectively. These wrappers take care of correctly decoding the export content for theCSV parser.

Example:

classification_export = Project(1234).get_export('classifications')for row in classification_export.csv_reader():

print(row)

classification_export = Project(1234).get_export('classifications')for row in classification_export.csv_dictreader():

print(row)

wait_export(export_type, timeout=None)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.

2.1.5 panoptes_client.project module

class panoptes_client.project.Project(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_subject_sets(subject_sets)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 SubjectSetinstance, 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)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:

14 Chapter 2. Module reference

Page 19: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

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

avatarA dict containing metadata about the project’s avatar.

collaborators(*roles)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)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")

class panoptes_client.project.ProjectLinkCollection(cls, slug, parent, linked_objects)Bases: panoptes_client.panoptes.LinkCollection

add(objs)Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObjectinstance, or a single object ID.

Examples:

organization.links.projects.add(1234)organization.links.projects.add(Project(1234))workflow.links.subject_sets.add([1,2,3,4])workflow.links.subject_sets.add([Project(12), Project(34)])

2.1.6 panoptes_client.project_preferences module

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

Bases: panoptes_client.panoptes.PanoptesObject

Contains the settings for a User on a Project.

classmethod find(id=”, user=None, project=None)Like PanoptesObject.find() but can also query by user and project.

2.1. panoptes_client package 15

Page 20: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

• user and project can be either a User and Project instance respectively, or they can be given asIDs. If either argument is given, the other is also required.

classmethod save_settings(project=None, user=None, settings=None)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 asIDs. If either argument is given, the other is also required.

• settings is a dict containing the settings to be saved.

2.1.7 panoptes_client.subject module

class panoptes_client.subject.Subject(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

add_location(location)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 andURLs 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'})

async_save_resultRetrieves the result of this subject’s asynchronous save.

• Returns True if the subject was saved successfully.

• Raises concurrent.futures.CancelledError if the save was cancelled.

• If the save failed, raises the relevant exception.

• Returns False if the subject hasn’t finished saving or if the subject has not been queued for asyn-chronous save.

classmethod async_saves()Returns a context manager to allow asynchronously creating subjects. Using this context manager will cre-ate a pool of threads which will create multiple subjects at once and upload any local files simultaneously.

The recommended way to use this is with the with statement:

with Subject.async_saves():local_files = [...]for filename in local_files:

s = Subject()s.links.project = 1234s.add_location(filename)s.save()

Alternatively, you can manually shut down the thread pool:

pool = Subject.async_saves()local_files = [...]try:

for filename in local_files:

(continues on next page)

16 Chapter 2. Module reference

Page 21: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

(continued from previous page)

s = Subject()s.links.project = 1234s.add_location(filename)s.save()

finally:pool.shutdown()

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

If multiple local files are to be uploaded, several files will be uploaded simultaneously to save time.

set_raw(raw, etag=None, loaded=True)

exception panoptes_client.subject.UnknownMediaExceptionBases: Exception

2.1.8 panoptes_client.subject_set module

class panoptes_client.subject_set.SubjectSet(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

add(subjects)A wrapper around LinkCollection.add(). Equivalent to:

subject_set.links.add(subjects)

remove(subjects)A wrapper around LinkCollection.remove(). Equivalent to:

subject_set.links.remove(subjects)

set_raw(raw, etag=None, loaded=True)

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

Examples:

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

class panoptes_client.subject_set.SubjectSetLinkCollection(cls, slug, parent,linked_objects)

Bases: panoptes_client.panoptes.LinkCollection

add(objs)Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObjectinstance, or a single object ID.

Examples:

organization.links.projects.add(1234)organization.links.projects.add(Project(1234))

(continues on next page)

2.1. panoptes_client package 17

Page 22: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

(continued from previous page)

workflow.links.subject_sets.add([1,2,3,4])workflow.links.subject_sets.add([Project(12), Project(34)])

remove(objs)Removes the given objs from this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObjectinstance, or a single object ID.

Examples:

organization.links.projects.remove(1234)organization.links.projects.remove(Project(1234))workflow.links.subject_sets.remove([1,2,3,4])workflow.links.subject_sets.remove([Project(12), Project(34)])

2.1.9 panoptes_client.user module

class panoptes_client.user.User(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

avatarA dict containing metadata about the user’s avatar.

classmethod where(**kwargs)Returns a generator which yields instances matching the given query arguments.

For example, this would yield all Project:

Project.where()

And this would yield all launch approved Project:

Project.where(launch_approved=True)

2.1.10 panoptes_client.workflow module

class panoptes_client.workflow.Workflow(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_subject_sets(subject_sets)A wrapper around LinkCollection.add(). Equivalent to:

workflow.links.subject_sets.add(subject_sets)

remove_subject_sets(subject_sets)A wrapper around LinkCollection.remove(). Equivalent to:

workflow.links.subject_sets.remove(subject_sets)

retire_subjects(subjects, reason=’other’)Retires subjects in this workflow.

18 Chapter 2. Module reference

Page 23: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

• subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or asingle 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)])

versionsA generator which yields all WorkflowVersion instances for this workflow.

2.1.11 panoptes_client.workflow_version module

class panoptes_client.workflow_version.WorkflowVersion(raw={}, etag=None)Bases: panoptes_client.panoptes.PanoptesObject

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

• workflow must be a Workflow instance.

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

workflowThe Workflow to which this version refers.

2.1. panoptes_client package 19

Page 24: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

20 Chapter 2. Module reference

Page 25: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

CHAPTER 3

Indices and tables

• genindex

• modindex

• search

21

Page 26: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

22 Chapter 3. Indices and tables

Page 27: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Python Module Index

ppanoptes_client.classification, 12panoptes_client.collection, 13panoptes_client.exportable, 13panoptes_client.panoptes, 10panoptes_client.project, 14panoptes_client.project_preferences, 15panoptes_client.subject, 16panoptes_client.subject_set, 17panoptes_client.user, 18panoptes_client.workflow, 18panoptes_client.workflow_version, 19

23

Page 28: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

24 Python Module Index

Page 29: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Index

Aadd() (panoptes_client.collection.Collection method), 13add() (panoptes_client.panoptes.LinkCollection method),

10add() (panoptes_client.project.ProjectLinkCollection

method), 15add() (panoptes_client.subject_set.SubjectSet method),

17add() (panoptes_client.subject_set.SubjectSetLinkCollection

method), 17add_location() (panoptes_client.subject.Subject method),

16add_subject_sets() (panoptes_client.project.Project

method), 14add_subject_sets() (panoptes_client.workflow.Workflow

method), 18add_workflows() (panoptes_client.project.Project

method), 14async_save_result (panoptes_client.subject.Subject at-

tribute), 16async_saves() (panoptes_client.subject.Subject class

method), 16avatar (panoptes_client.project.Project attribute), 15avatar (panoptes_client.user.User attribute), 18

CClassification (class in panoptes_client.classification), 12collaborators() (panoptes_client.project.Project method),

15Collection (class in panoptes_client.collection), 13connect() (panoptes_client.panoptes.Panoptes class

method), 11

Ddelete() (panoptes_client.panoptes.PanoptesObject

method), 12describe_export() (panoptes_client.exportable.Exportable

method), 13

EExportable (class in panoptes_client.exportable), 13

Ffind() (panoptes_client.collection.Collection class

method), 13find() (panoptes_client.panoptes.PanoptesObject class

method), 12find() (panoptes_client.project.Project class method), 15find() (panoptes_client.project_preferences.ProjectPreferences

class method), 15find() (panoptes_client.workflow_version.WorkflowVersion

class method), 19

Ggenerate_export() (panoptes_client.exportable.Exportable

method), 13get_export() (panoptes_client.exportable.Exportable

method), 13

LLinkCollection (class in panoptes_client.panoptes), 10

OObjectNotSavedException, 10

PPanoptes (class in panoptes_client.panoptes), 10panoptes_client.classification (module), 12panoptes_client.collection (module), 13panoptes_client.exportable (module), 13panoptes_client.panoptes (module), 10panoptes_client.project (module), 14panoptes_client.project_preferences (module), 15panoptes_client.subject (module), 16panoptes_client.subject_set (module), 17panoptes_client.user (module), 18panoptes_client.workflow (module), 18panoptes_client.workflow_version (module), 19

25

Page 30: Panoptes Client Documentation - Read the Docs · The Panoptes Client is supported on all versions of Python 2 and 3, from Python 2.7 onwards. 1.1.2.1Uploading non-image media types

Panoptes Client Documentation, Release 1.1

PanoptesAPIException, 11PanoptesObject (class in panoptes_client.panoptes), 11Project (class in panoptes_client.project), 14ProjectLinkCollection (class in panoptes_client.project),

15ProjectPreferences (class in

panoptes_client.project_preferences), 15

RReadOnlyAttributeException, 12reload() (panoptes_client.panoptes.PanoptesObject

method), 12remove() (panoptes_client.collection.Collection method),

13remove() (panoptes_client.panoptes.LinkCollection

method), 10remove() (panoptes_client.subject_set.SubjectSet

method), 17remove() (panoptes_client.subject_set.SubjectSetLinkCollection

method), 18remove_subject_sets() (panoptes_client.workflow.Workflow

method), 18retire_subjects() (panoptes_client.workflow.Workflow

method), 18

Ssave() (panoptes_client.panoptes.PanoptesObject

method), 12save() (panoptes_client.subject.Subject method), 17save() (panoptes_client.workflow_version.WorkflowVersion

method), 19save_settings() (panoptes_client.project_preferences.ProjectPreferences

class method), 16set_default_subject() (panoptes_client.collection.Collection

method), 13set_raw() (panoptes_client.subject.Subject method), 17set_raw() (panoptes_client.subject_set.SubjectSet

method), 17Subject (class in panoptes_client.subject), 16subjects (panoptes_client.collection.Collection attribute),

13subjects (panoptes_client.subject_set.SubjectSet at-

tribute), 17SubjectSet (class in panoptes_client.subject_set), 17SubjectSetLinkCollection (class in

panoptes_client.subject_set), 17

UUnknownMediaException, 17User (class in panoptes_client.user), 18

Vversions (panoptes_client.workflow.Workflow attribute),

19

Wwait_export() (panoptes_client.exportable.Exportable

method), 14where() (panoptes_client.classification.Classification

class method), 12where() (panoptes_client.panoptes.PanoptesObject class

method), 12where() (panoptes_client.user.User class method), 18Workflow (class in panoptes_client.workflow), 18workflow (panoptes_client.workflow_version.WorkflowVersion

attribute), 19WorkflowVersion (class in

panoptes_client.workflow_version), 19

26 Index


Recommended