Projects
Methods for drawing down, editing and uploading data about DocumentCloud projects. A project is a group of documents.
ProjectClient
- class documentcloud.projects.ProjectClient
The project client gives access to retrieval and creation of projects. It is generally accessed as
client.projects
.- all(**params)
Return all projects for the authorized DocumentCloud account. Please see the full API documentation for available parameters.
>>> from documentcloud import DocumentCloud >>> client = DocumentCloud(USERNAME, PASSWORD) >>> obj_list = client.projects.all() >>> obj_list[0] <Project: Ruben Salazar>
- create(title, description='', private=True, 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>
- 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>
- get_or_create_by_title(title)
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
- get_by_id(id)
Return the project with the provided id. Operates the same as client.projects.get.
- get_by_title(title)
Return the project with the provided title. Operates the same as client.projects.get.
- list(**params)
List all projects. Please see the full API documentation for available parameters.
Project
- class documentcloud.projects.Project
An individual project, as obtained by the
documentcloud.projects.ProjectClient
.- put()
Save changes to a project back to DocumentCloud. You must be authorized to make these changes. Only the
description
,document_list
,private
, andtitle
, attributes may be edited.>>> obj = client.projects.get('816') >>> obj.title = "Brand new title" >>> obj.put()
- delete()
Delete a project from DocumentCloud. You must be authorized to make these changes.
>>> obj = client.projects.get('816') >>> obj.delete()
- clear_documents()
Removes all documents from a project.
>>> obj = client.projects.get('816') >>> obj.clear_documents()
- add_documents()
Efficiently adds a lot of documents to a project. Adds the documents 25 at a time using bulk API calls.
>>> documents_to_add = [client.documents.get('23745990'), client.documents.get('23745988')] >>> obj = client.projects.get('816') >>> obj.add_documents(documents_to_add) >>> obj.put()
- created_at
The date and time when this project was created
- description
A summary of the project. Can be edited and saved with a put command.
- 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 [19419, 19420, 19280, 19281, ...
- 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>, ...
- documents
Alias for
document_list
.
- edit_access
A boolean indicating whether or not you have the ability to save this project.
- get_document(id)
Retrieves a particular document from the project using the provided DocumentCloud identifer.
- id
The unique identifer of the project in DocumentCloud’s system. Typically this is a number.
- private
Whether or not this project is private. Private documents in public projects will not be viewable, but setting a project to private will protect its existence from being publically viewable.
- slug
The slug for the project. A slug is a URL friendly version of the title.
- title
The name of the project. Can be edited and saved with a put command.
- updated_at
The date and time of the last time this project was updated.
- user
The ID of the
documentcloud.users.User
who created this project.