Interacting with Projects¶
Coscine is a project-based data management platform. A project represents the central hub for all of the data resources and people involved in a scientific undertaking.
The Project object¶
The Coscine Python SDK abstracts Coscine projects with a
custom Project datatype. An instance of type coscine.Project
has the following properties:
Property |
Datatype |
Modifiable |
Description |
---|---|---|---|
created |
date |
❌ |
Timestamp when the project was created |
creator |
str |
❌ |
Coscine user ID of the project creator |
description |
str |
✔ |
Project description |
disciplines |
list[Discipline] |
✔ |
List of scientific disciplines |
display_name |
str |
✔ |
Short project name as displayed in the web interface |
end_date |
date |
✔ |
Project end date |
grant_id |
str |
✔ |
Project grant ID |
id |
str |
❌ |
Coscine Project ID |
keywords |
list[str] |
✔ |
List of related keywords |
name |
str |
✔ |
Full project name |
organizations |
list[Organization] |
✔ |
List of involved organizations |
pid |
str |
❌ |
Persistent Identifier for the project |
principal_investigators |
str |
✔ |
Project investigators |
slug |
str |
❌ |
Coscine project slug |
start_date |
date |
✔ |
Project start date |
url |
str |
❌ |
Project URL as in the web browser |
visibility |
Visibility |
✔ |
Project visibility setting |
Properties can be accessed via the usual dot notation
i. e. print(project.name)
.
Certain properties can be modified (✔) locally and updated remotely
by calling Project.update()
.
Accessing projects¶
The following snippet demonstrates how to get a list of
Coscine Projects and prints all returned projects by their
full name. By default, the call client.projects()
will only return
toplevel projects (i.e. only the projects at the root level).
To include subprojects in the results, the toplevel
parameter should be set to False
.
import coscine
client = coscine.ApiClient("My Coscine API Token")
projects = client.projects()
for project in projects:
print(project.name)
The list of projects can be filtered according to certain unique project properties. In the subsequent snippet, only one project is returned, saving us from manually going through the list if we want to access a speific project.
try:
project = client.project("My Project Display Name")
print(project.name)
except coscine.TooManyResults:
print("Found more than 1 project with the same property!")
except coscine.NotFoundError:
print("Failed to find a project via the property!")
We can filter projects according to these properties:
client.project(“Display Name”, Project.display_name)
client.project(“Full Name”, Project.name)
client.project(“Project ID”, Project.id)
client.project(“Persistent Identifier”, Project.pid)
client.project(“Web URL”, Project.url)
Other properties are rejected!
Creating a new project¶
Projects can be created via a simple function call. The new project object is returned immediately after the project has been created.
import coscine
from datetime import datetime
client = coscine.ApiClient("My Coscine API Token")
project = client.create_project(
"Full Name",
"Display Name",
"Project Description",
datetime.now().date(),
datetime.now().date(),
"Principal Investigator",
[client.discipline("Computer Science 409")],
[client.organization("https://ror.org/04xfq0f34")],
# -> RWTH Aachen University
client.visibility("Project Members")
)
print(project)
Deleting a project¶
If we create projects with the Coscine Python SDK we may also need to delete some projects.
import coscine
client = coscine.ApiClient("My Coscine API Token")
project = client.project("Some Project I don't like")
try:
project.delete()
except coscine.CoscineException:
print("Something went wrong. Maybe we are not authorized to delete that project. :(")
Be aware that this function may fail due to unsufficient privileges.
Only project owners can delete a project - members can not!
After calling delete()
we should also not use the project object in python anymore,
as it is invalid in Coscine (but can still be interacted with locally).
Downloading a project¶
Downloading a project and all of the resources inside of that project
is easy with the Project.download()
method. It accepts an optional
path where it should save the project to. If no path is specified, the
current local directory is chosen as path.
import coscine
client = coscine.ApiClient("My Coscine API Token")
project = client.project("Fancy project - please don't steal")
project.download(path="./") # This is my project now hehehe
Member management¶
Coscine Projects contain Project Members. We can get a list of the members
of a project by calling the Project.members()
method.
import coscine
client = coscine.ApiClient("My Coscine API Token")
project = client.project("My Project with Members")
members = project.members()
for member in members:
print(member.name)
print(member.email)
# Set project role for a member
member.role = client.role("Owner")
# Remove a member from the project
project.remove_member(member)
We can add Coscine users to our project:
import coscine
client = coscine.ApiClient("My Coscine API Token")
project = client.project("My Project with Members")
for user in client.users("*@institute.rwth-aachen.de"):
project.add_member(user, client.role("Member"))
Similarly we can invite new members via their E-Mail.
project.invite("john@example.com", "Member") # Or Owner / Guest