Projects

Methods for drawing down, editing and uploading data about DocumentCloud projects. A project is a group of documents.

Retrieval

client.projects.get(id=None, title=None)

Return the project with the provided DocumentCloud identifer. You can retrieve projects using either the id or title.

>>> from documentcloud import DocumentCloud
>>> client = DocumentCloud(USERNAME, PASSWORD)
>>> # Fetch using the id
>>> obj = client.projects.get(id='816')
>>> obj
<Project: The Ruben Salazar Files>
>>> # Fetch using the title
>>> obj = client.projects.get(title='The Ruben Salazar Files')
>>> obj
<Project: The Ruben Salazar Files>

client.projects.get_by_id(id)

Return the project with the provided id. Operates the same as client.projects.get.

client.projects.get_by_title(title)

Return the project with the provided title. Operates the same as client.projects.get.

client.projects.all()

Return all projects for the authorized DocumentCloud account

>>> from documentcloud import DocumentCloud
>>> client = DocumentCloud(USERNAME, PASSWORD)
>>> obj_list = client.projects.all()
>>> obj_list[0]
<Project: Ruben Salazar>

Editing

project_obj.put()

Save changes to a project back to DocumentCloud. You must be authorized to make these changes. Only the title, source, document_list attributes may be edited.

>>> obj = client.projects.get('816')
>>> obj.title = "Brand new title"
>>> obj.put()

project_obj.delete()

Delete a project from DocumentCloud. You must be authorized to make these changes.

>>> obj = client.projects.get('816')
>>> obj.delete()

project_obj.save()

An alias for put that saves changes back to DocumentCloud.

Creation

client.projects.create(title=None, description=None, document_ids=None)

Create a new project on DocumentCloud. You must be authorized to do this. Returns the object representing the new record you’ve created.

>>> from documentcloud import DocumentCloud
>>> client = DocumentCloud(USERNAME, PASSWORD)
>>> obj = client.projects.create("New project")
>>> obj
<Project: New project>

client.projects.get_or_create_by_title(title=None)

Fetch the project with provided name, or create it if it does not exist. You must be authorized to do this. Returns a tuple. An object representing the record comes first. A boolean that reports whether or not the objects was created fresh comes second. It is true when the record was created, false when it was found on the site already.

>>> from documentcloud import DocumentCloud
>>> client = DocumentCloud(USERNAME, PASSWORD)
>>> # The first time it will be created and added to documentcloud.org
>>> obj, created = client.projects.get_or_create_by_title("New project")
>>> obj, created
<Project: New project>, True
>>> # The second time it will be fetched from documentcloud.org
>>> obj, created = client.projects.get_or_create_by_title("New project")
>>> obj, created
<Project: New project>, False

Metadata

project_obj.description

A summary of the project. Can be edited and saved with a put command.

project_obj.document_ids

A list that contains the unique identifier of the documents assigned to this project. Cannot be edited. Edit the document_list instead.

>>> obj = client.projects.get('816')
>>> obj.document_ids
[u'19419-times-columnist-ruben-salazar-killed-by-bullet', u'19420-usps-american-journalists-stamp', u'19280-fbi-file-on-el-paso-investigations', u'19281-letter-from-the-lapd-chief', ...

project_obj.document_list

A list that documents assigned to this project. Can be expanded by appending new documents to the list or cleared by reassigning it as an empty list and then issuing the put command.

>>> obj = client.projects.get('816')
>>> obj.document_list
[<Document: Times Columnist Ruben Salazar Slain by Tear-gas Missile>, <Document: Salazar's Legacy Lives On>, <Document: Cub Reporter Catches Attention of El Paso FBI>, ...

project_obj.get_document(id)

Retrieves a particular document from the project using the provided DocumentCloud identifer.

project_obj.id

The unique identifer of the project in DocumentCloud’s system. Typically this is a number.

project_obj.title

The name of the project. Can be edited and saved with a put command.