materials_commons.api.client module

class materials_commons.api.client.Client(apikey, base_url='https://materialscommons.org/api', raise_exception=True)[source]

Bases: object

add_admin_to_project(project_id, user_id)[source]

Adds user as an admin to project :param int project_id: Id of project to add user to :param int user_id: Id of user to add to project :return: The updated project :rtype Project :raises MCAPIError

add_dataset_to_community(dataset_id, community_id)[source]

Add a dataset to a community. The dataset must have been published. :param int dataset_id: :param int community_id: :rtype Community :return: The community with the dataset :raises MCAPIError

add_user_to_project(project_id, user_id)[source]

Adds user to project :param int project_id: Id of project to add user to :param int user_id: Id of user to add to project :return: The updated project :rtype Project :raises MCAPIError

assign_doi_to_dataset(project_id, dataset_id)[source]

Assign DOI to existing dataset :param int project_id: The project to create the dataset in :param int dataset_id: The id of the dataset :return: The updated dataset with DOI :rtype Dataset :raises MCAPIError

change_dataset_file_selection(project_id, dataset_id, file_selection)[source]

Change the file selection for a dataset to match the passed in dataset :param int project_id: Project id containing dataset :param int dataset_id: Id of dataset :param file_selection: {

“include_files”: array, “exclude_files”: array, “include_dirs”: array, “exclude_dirs”: array,

} :return: The updated dataset :rtype Dataset :raises MCAPIError :param project_id: :param dataset_id: :param file_selection: :return:

check_file_by_path_in_dataset(project_id, dataset_id, file_path)[source]

Check if file path is in the dataset selection. Throws an error if the file_path isn’t in the project. :param int project_id: project dataset and file_path are in :param int dataset_id: data to check file_selection against :param str file_path: file_path to check against dataset file_selection :return: {‘in_dataset’: True} or {‘in_dataset’: False} :exception if file_path doesn’t exist in project :raises MCAPIError

check_file_in_dataset(project_id, dataset_id, file_id)[source]

Check if file is in the dataset selection :param int project_id: project dataset and file are in :param int dataset_id: dataset to check file_selection against :param int file_id: file to check :return: {‘in_dataset’: True} or {‘in_dataset’: False} :raises MCAPIError

close_globus_transfer(project_id)[source]

Closes an existing globus transfer. If there isn’t an open transfer for the user in project then does nothing and returns success :param int project_id: The id of the project to close globus transfer for the current user :return: None :raises MCAPIError

create_activity(project_id, name, attrs=None)[source]

Create a new activity in the project :param project_id: The project to create the activity int :param str name: Name of activity :param CreateActivityRequest attrs: Attributes on the activity :return: The activity to create :rtype Activity :raises MCAPIError

create_community(name, attrs={})[source]

Creates a new community owned by the user. :param str name: Name of community :param CreateCommunityRequest attrs: (optional) Additional attributes for the create request :return: The created community :rtype Community :raises MCAPIError

create_dataset(project_id, name, attrs=None)[source]

Create a new dataset in a project :param int project_id: The project to create the dataset in :param string name: The name of the dataset :param CreateDatasetRequest attrs: Attributes of the dataset :return: The created dataset :rtype Dataset :raises MCAPIError

create_directory(project_id, name, parent_id, attrs=None)[source]

Create a new directory in project in the given directory :param int project_id: The id of the project the directory will be created in :param str name: Name of directory :param int parent_id: Parent directory id - The directory that this directory will be in :param CreateDirectoryRequest attrs: Additional attributes on the directory :return: The created directory :rtype File :raises MCAPIError

create_entity(project_id, name, attrs=None)[source]

Creates a new entity in the project :param project_id: The id of the project to create entity in :param str name: The entity name :param CreateEntityRequest attrs: Attributes of the entity :return: The created entity :rtype Entity :raises MCAPIError

create_experiment(project_id, name, attrs=None)[source]

Create a new experiment in a project :param int project_id: The id of the project the experiment is in :param str name: Name of experiment :param CreateExperimentRequest attrs: Additional attributes on the experiment :return: The created experiment :rtype Experiment :raises MCAPIError

create_globus_download_request(project_id, name)[source]

Create a globus download request for a project :param int project_id: :param str name: The name of the download request :return: The globus download :rtype GlobusDownload :raises MCAPIError

create_globus_upload_request(project_id, name)[source]

Create a new globus request in the given project :param int project_id: The project id for the upload :param name: The name of the request :return: The globus request :rtype GlobusUpload :raises MCAPIError

Adds a link to a community :param int community_id: The community to add the link to :param str name: name to show for url :param str url: url to add :param CreateLinkRequest attrs: additional attrs :return: The community :rtype Community :raises MCAPIError

create_project(name, attrs=None)[source]

Creates a new project for the authenticated user. Project name must be unique :param str name: Name of project :param CreateProjectRequest attrs: (optional) Additional attributes for the create request :return: The created project :rtype Project :raises MCAPIError

delete(urlpart, params=None)[source]
delete_activity(project_id, activity_id)[source]

Deletes an activity :param project_id: The id of the project containing the activity :param activity_id: The id of the activity to delete :raises MCAPIError

delete_dataset(project_id, dataset_id)[source]

Delete an unpublished dataset :param int project_id: The project id containing the dataset :param int dataset_id: The id of the dataset :raises MCAPIError

delete_directory(project_id, directory_id)[source]

Should not be used yet: Delete a directory only if the directory is empty :param int project_id: The project id containing the directory to delete :param int directory_id: The id of the directory to delete :raises MCAPIError

delete_entity(project_id, entity_id)[source]

Delete an entity :param int project_id: The id of the project containing the entity :param int entity_id: The entity id :raises MCAPIError

delete_experiment(project_id, experiment_id)[source]

Delete experiment in project :param int project_id: The id of the project the experiment is in :param experiment_id: The experiment id :raises MCAPIError

delete_file(project_id, file_id, force=False)[source]

Delete a file in a project :param int project_id: The id of the project containing the file :param int file_id: The id of the file to delete :raises MCAPIError

delete_file_from_community(file_id, community_id)[source]

Deletes file from the community and deletes the file on the system. :param int file_id: The file to delete :param int community_id: The community to delete it from :raises MCAPIError

delete_globus_download_request(project_id, globus_download_id)[source]

Delete an existing globus download request :param int project_id: The id of the project containing the download request :param int globus_download_id: The id of the globus download to delete :raises MCAPIError

delete_globus_upload_request(project_id, globus_upload_id)[source]

Delete an existing globus upload request :param int project_id: :param int globus_upload_id: :raises MCAPIError

Delete a link from a community and remove it from the system. :param int link_id: The link to remove :param int community_id: The community to delete the link from :raises MCAPIError

delete_project(project_id)[source]

Deletes a project :param int project_id: id of project to delete :raises MCAPIError

delete_with_value(urlpart)[source]
download(urlpart, to)[source]
download_file(project_id, file_id, to)[source]

Download a file :param int project_id: The project id containing the file to download :param int file_id: The id of the file to download :param str to: path including file name to download file to :raises MCAPIError

download_file_by_path(project_id, path, to)[source]

Download a file by path :param int project_id: The project id containing the file to download :param str path: The path in the project of the file :param str to: path including file name to download file to :raises MCAPIError

download_published_dataset_file(dataset_id, file_id, to)[source]

Download file from a published dataset :param int dataset_id: The id of the published dataset :param int file_id: The id of the file in the dataset :param str to: The path including the file name to write the download to :raises MCAPIError

download_published_dataset_zipfile(dataset_id, to)[source]

Download the zipfile for a published dataset :param int dataset_id: The id of the published dataset :param str to: The path including the file name to write the download to :raises MCAPIError

finish_globus_upload_request(project_id, globus_upload_id)[source]

Mark a globus upload request as finished :param int project_id: The project id for the upload :param int globus_upload_id: The id of the globus upload :return: The globus upload :rtype GlobusUpload :raises MCAPIError

get(urlpart, params={}, other_params={})[source]
get_activity(project_id, activity_id, params=None)[source]

Get an activity :param int project_id: The id of the project containing the activity :param int activity_id: The id of the activity :param params: :return: The activity :rtype Activity :raises MCAPIError

get_all_activities(project_id, params=None)[source]

Get all activities in a project :param int project_id: The id of the project :param params: :return: List of activities :rtype Activity[] :raises MCAPIError

get_all_datasets(project_id, params=None)[source]

Get all datasets in a project :param int project_id: The project id :param params: :return: The list of datasets :rtype Dataset[] :raises MCAPIError

get_all_entities(project_id, params=None)[source]

Get all entities in a project :param int project_id: The id of the project :param params: :return: The list of entities :rtype Entity[] :raises MCAPIError

get_all_experiments(project_id, params=None)[source]

Get all experiments for a given project :param int project_id: The project id :param params: :return: A list of experiments :rtype Experiment[] :raises MCAPIError

get_all_globus_download_requests(project_id, params=None)[source]

Get all globus download requests for a project :param int project_id: The project :return: List of all globus downloads :rtype GlobusDownload[] :raises MCAPIError

get_all_globus_upload_requests(project_id, params=None)[source]

Get all globus uploads in a project :param int project_id: The project id :return: List of globus uploads :rtype GlobusUpload[] :raises MCAPIError

get_all_my_communities(params=None)[source]

Get all communities owned by user :rtype Community[] :return: List of communities :raises MCAPIError

get_all_projects(params=None)[source]

Returns a list of all the projects a user has access to :param params: :return: List of projects :rtype Project[] :raises MCAPIError

get_all_public_communities(params=None)[source]

Get all public communities :rtype Community[] :return: List of public communities :raises MCAPIError

get_all_published_datasets(params=None)[source]

Get all published datasets :param params: :return: The list of published datasets :rtype Dataset[] :raises MCAPIError

static get_apikey(email, password, base_url='https://materialscommons.org/api')[source]
get_community(community_id, params=None)[source]

Get a commmunity :param int community_id: The id of the community to get :param params: Query specific parameters :rtype Community :return: The Community :raises MCAPIError

get_dataset(project_id, dataset_id, params=None)[source]

Get dataset in a project :param int project_id: The project id containing the dataset :param int dataset_id: The dataset id :param params: :return: The dataset :rtype Dataset :raises MCAPIError

get_dataset_activities(project_id, dataset_id, params=None)[source]

Get activities for a dataset :param int project_id: The project id containing the dataset :param int dataset_id: The dataset id :param params: :rtype: Activity[] :return: The activities :raises MCAPIError

get_dataset_entities(project_id, dataset_id, params=None)[source]

Get entities for a dataset :param int project_id: The project id containing the dataset :param int dataset_id: The dataset id :param params: :rtype: Entity[] :return: The entities :raises MCAPIError

get_dataset_files(project_id, dataset_id, params=None)[source]

Get files for a dataset :param int project_id: The project id containing the dataset :param int dataset_id: The dataset id :param params: :rtype: File[] :return: The files :raises MCAPIError

get_directory(project_id, directory_id, params=None)[source]

Get a directory in the project :param int project_id: The id of the project the directory is in :param int directory_id: The directory id :param params: :return: The directory :rtype File :raises MCAPIError

get_entity(project_id, entity_id, params=None)[source]

Get an entity :param int project_id: The id of the project containing the entity :param int entity_id: The id of the entity :param params: :return: The entity :rtype Entity :raises MCAPIError

get_experiment(experiment_id, params=None)[source]

Get an experiment :param int experiment_id: The experiment id :param params: :return: The experiment :rtype Experiment :raises MCAPIError

get_file(project_id, file_id, params=None)[source]

Get file in project :param int project_id: The id of the project containing the file :param int file_id: The id of the file :param params: :return: The file :rtype File :raises MCAPIError

get_file_by_path(project_id, file_path)[source]

Get file by path in project :param int project_id: The id of the project containing the file :param file_path: The path to the file :return: The file :rtype File :raises MCAPIError

get_file_versions(project_id, file_id, params=None)[source]

Get versions for file in project (does not include file given) :param int project_id: The id of the project containing the file :param int file_id: The id of the file :param params: :return: File versions :rtype File[] :raises MCAPIError

get_globus_download_request(project_id, globus_download_id, params=None)[source]

Get a globus download :param int project_id: The id of the project containing the globus download :param int globus_download_id: The globus download id :return: The globus download :rtype GlobusDownload :raises MCAPIError

get_no_value(urlpart)[source]
get_project(project_id, params=None)[source]

Get a project by its id :param int project_id: Project id for project :param params: :return: The project :rtype Project :raises MCAPIError

get_published_dataset(dataset_id, params=None)[source]

Get published dataset :param int dataset_id: The dataset id :param params: :return: The dataset :rtype Dataset :raises MCAPIError

get_published_dataset_activities(dataset_id, params=None)[source]

Get activities for a published dataset :param int dataset_id: The dataset id :param params: :rtype: Activity[] :return: The activities :raises MCAPIError

get_published_dataset_entities(dataset_id, params=None)[source]

Get entities for a published dataset :param int dataset_id: The dataset id :param params: :rtype: Entity[] :return: The entities :raises MCAPIError

get_published_dataset_files(dataset_id, params=None)[source]

Get files for a published dataset :param int dataset_id: The dataset id :param params: :rtype: File[] :return: The files :raises MCAPIError

get_published_datasets_for_author(author)[source]

Get all published datasets for an author :param str author: Author name string :return: List of datasets author is on :rtype Dataset[] :raises MCAPIError

get_published_datasets_for_tag(tag)[source]

Get all published datasets tagged with tag :param str tag: tag to use :return: List of datasets tagged with tag :rtype Dataset[] :raises MCAPIError

get_server_info()[source]

Gets information about the materials commons server :return: server information :rtype Server

get_user_by_email(email, params=None)[source]

Get a user by their email :param string email: email address of user to lookup :return: The user :rtype User :raises MCAPIError

import_dataset(dataset_id, project_id, directory_name)[source]

Launches a job to import a dataset into a project. The import will complete at some point in the future. There isn’t currently a way to query the import status. :param int dataset_id: The dataset id to import :param int project_id: A project id the user has access to :param string directory_name: The top level directory to import the dataset into (will be created) :raises MCAPIError

list_authors_in_community(community_id)[source]

List all unique authors across all the published datasets in a community :param int community_id: The community to list the authors for :return: The list of authors :rtype string[] :raises MCAPIError

list_directory(project_id, directory_id, params=None)[source]

Return a list of all the files and directories in a given directory :param int project_id: The id of the project the directory is in :param int directory_id: The directory id :param params: :return: A list of the files and directories in the given directory :rtype File[] :raises MCAPIError

list_directory_by_path(project_id, path, params=None)[source]

Return a list of all the files and directories at given path :param int project_id: The id of the project the path is in :param str path: :param params: :return: A list of th efiles and directories in the given path :rtype File[] :raises MCAPIError

list_published_authors()[source]

List all published authors :return: List of authors :rtype User[] :raises MCAPIError

list_tags_for_published_datasets()[source]

List all tags used in published datasets :return: List of tags :rtype Tag[] :raises MCAPIError

list_tags_in_community(community_id)[source]

List all the unique tags across all the published datasets in a community :param int community_id: The community to list the tags for :return: The list of tags :rtype Tag[] :raises MCAPIError

list_users(params=None)[source]

List users of Materials Commons :return: List of users :rtype User[] :raises MCAPIError

static login(email, password, base_url='https://materialscommons.org/api')[source]
move_directory(project_id, directory_id, to_directory_id)[source]

Moves a directory into another directory :param int project_id: The project id that target and destination directories are in :param int directory_id: Id of directory to move :param int to_directory_id: Id of the destination directory :return: The directory that was moved :rtype File :raises MCAPIError

move_file(project_id, file_id, to_directory_id)[source]

Move file into a different directory :param int project_id: The project id of the file and the destination directory :param int file_id: The id of the file to move :param int to_directory_id: The id of the destination directory :return: The moved file :rtype File :raises MCAPIError

open_globus_transfer(project_id, params=None)[source]

Open a globus transfer request for current user in project. If one is already active then it returns the already active request. :param int project_id: The id of the project associated with this globus transfer :return: The globus transfer :rtype GlobusTransfer :raises MCAPIError

post(urlpart, data)[source]
publish_dataset(project_id, dataset_id)[source]

Publish a dataset :param int project_id: The id of the project containing the dataset :param int dataset_id: The dataset id :return: The dataset :rtype Dataset :raises MCAPIError

put(urlpart, data)[source]
remove_admin_from_project(project_id, user_id)[source]

Removes admin user from project :param int project_id: Id of project to add user to :param int user_id: Id of user to remove from project :return: The updated project :rtype Project :raises MCAPIError

remove_dataset_from_community(dataset_id, community_id)[source]

Remove a dataset from a community. :param int dataset_id: :param int community_id: :raises MCAPIError

remove_user_from_project(project_id, user_id)[source]

Remove user from project :param int project_id: Id of project to add user to :param int user_id: Id of user to add to project :return: The updated project :rtype Project :raises MCAPIError

rename_directory(project_id, directory_id, name)[source]

Rename a given directory :param int project_id: The project id that the directory is in :param int directory_id: The id of the directory being renamed :param name: The new name of the directory :return: The directory that was renamed :rtype File :raises MCAPIError

rename_file(project_id, file_id, name)[source]

Rename a file :param int project_id: The project id of the file to rename :param int file_id: The id of the file to rename :param str name: The files new name :return: The rename file :rtype File :raises MCAPIError

search_published_data(search_str)[source]

Search published datasets for matching string :param str search_str: string to search on :return: List of matches :rtype: Searchable[] :raises MCAPIError

set_as_active_file(project_id, file_id)[source]

Set file as active version, changing current active file version to inactive :param int project_id: The id of the project containing the file :param int file_id: The id of the file :return: File :rtype File :raises MCAPIError

static set_debug_off()[source]
static set_debug_on()[source]
unpublish_dataset(project_id, dataset_id)[source]

Unpublish an published dataset :param int project_id: The id of the project containing the dataset :param int dataset_id: The dataset id :return: The dataset :rtype Dataset :raises MCAPIError

update_dataset(project_id, dataset_id, name, attrs=None)[source]

Update an existing dataset :param int project_id: The project to create the dataset in :param int dataset_id: The id of the dataset :param str name: The name of the dataset (doesn’t need to be different) :param UpdateDatasetRequest attrs: The attributes to update :return: The updated dataset :rtype Dataset :raises MCAPIError

update_dataset_activities(project_id, dataset_id, activity_id)[source]

Toggle whether an activity is in a dataset :param int project_id: Project id containing dataset and activity :param int dataset_id: Id of dataset :param int activity_id: Id of activity :return: The updated dataset :rtype Dataset :raises MCAPIError

update_dataset_entities(project_id, dataset_id, entity_id)[source]

Toggle whether an entity is in a dataset :param int project_id: Project id containing dataset and entity :param int dataset_id: Id of dataset :param int entity_id: Id of entity :return: The updated dataset :rtype Dataset :raises MCAPIError

update_dataset_file_selection(project_id, dataset_id, file_selection)[source]

Update the file selection for a dataset :param int project_id: Project id containing dataset :param int dataset_id: Id of dataset :param file_selection: {

“include_file”: str, “remove_include_file”: str, “exclude_file”: str, “remove_exclude_file”: str, “include_dir”: str, “remove_include_dir”: str, “exclude_dir”: str, “remove_exclude_dir”: str

} :return: The updated dataset :rtype Dataset :raises MCAPIError

update_dataset_workflows(project_id, dataset_id, workflow_id)[source]

Toggle whether an workflow is in a dataset :param int project_id: Project id containing dataset and workflow :param int dataset_id: Id of dataset :param int workflow_id: Id of workflow :return: The updated dataset :rtype Dataset :raises MCAPIError

update_directory(project_id, directory_id, attrs)[source]

Update attributes on a directory :param int project_id: The project id containing the directory :param int directory_id: The id of the directory to update :param attrs: Attributes to update :return: The updated directory :rtype File :raises MCAPIError

update_experiment(experiment_id, attrs)[source]

Update attributes of an experiment :param int experiment_id: The experiment id :param UpdateExperimentRequest attrs: Attributes to update :return: The updated experiment :rtype Experiment :raises MCAPIError

update_experiment_workflows(project_id, experiment_id, workflow_id)[source]

Toggle whether an workflow is in the experiment :param int project_id: Id of project containing the experiment and workflow :param experiment_id: Id of experiment :param workflow_id: Id of workflow :return: The updated experiment :rtype Experiment :raises MCAPIError

update_file(project_id, file_id, attrs)[source]

Update attributes of a file :param project_id: :param file_id: :param UpdateFileRequest attrs: Attributes to update :return: The updated file :rtype File :raises MCAPIError

update_project(project_id, attrs)[source]

Updates the given project :param int project_id: Id of project to update :param UpdateProjectRequest attrs: The attributes to update on the project :return: The updated project :rtype Project :raises MCAPIError

upload(urlpart, file_path)[source]
upload_bytes(project_id, directory_id, name, f)[source]
upload_file(project_id, directory_id, file_path)[source]

Uploads a file to a project :param int project_id: The project to upload file to :param int directory_id: The directory in the project to upload the file into :param str file_path: path of file to upload :return: The created file :rtype File :raises MCAPIError

upload_file_to_community(file_path, community_id)[source]

TODO: A file has other attributes such as description and summary Uploads a file to a community :param str file_path: path of file to upload :param int community_id: The community to upload the file to :return: The community :rtype Community :raises MCAPIError

upload_raw(urlpart, f)[source]
exception materials_commons.api.client.MCAPIError(message, response)[source]

Bases: Exception

materials_commons.api.client.merge_dicts(dict1, dict2)[source]