API Reference

Client library for the Open Science Framework

class osfclient.OSF(username=None, password=None, token=None)[source]

Interact with the Open Science Framework.

This is the main point of contact for interactions with the OSF. Use the methods of this class to find projects, login to the OSF, etc.

login(username, password=None, token=None)[source]

Login user for protected API calls.

password
project(project_id)[source]

Fetch project project_id.

username

osfclient.cli

Command line interface to the OSF

These functions implement the functionality of the command-line interface.

osfclient.cli.clone(args)[source]

Copy all files from all storages of a project.

The output directory defaults to the current directory.

If the project is private you need to specify a username.

osfclient.cli.config_from_env(config)[source]
osfclient.cli.config_from_file()[source]
osfclient.cli.fetch(args)[source]

Fetch an individual file from a project.

The first part of the remote path is interpreted as the name of the storage provider. If there is no match the default (osfstorage) is used.

The local path defaults to the name of the remote file.

If the project is private you need to specify a username.

osfclient.cli.init(args)[source]

Initialize or edit an existing .osfcli.config file.

osfclient.cli.list_(args)[source]

List all files from all storages for project.

If the project is private you need to specify a username.

osfclient.cli.might_need_auth(f)[source]

Decorate a CLI function that might require authentication.

Catches any UnauthorizedException raised, prints a helpful message and then exits.

osfclient.cli.remove(args)[source]

Remove a file from the project’s storage.

The first part of the remote path is interpreted as the name of the storage provider. If there is no match the default (osfstorage) is used.

osfclient.cli.upload(args)[source]

Upload a new file to an existing project.

The first part of the remote path is interpreted as the name of the storage provider. If there is no match the default (osfstorage) is used.

If the project is private you need to specify a username.

To upload a whole directory (and all its sub-directories) use the -r command-line option. If your source directory name ends in a / then files will be created directly in the remote directory. If it does not end in a slash an extra sub-directory with the name of the local directory will be created.

To place contents of local directory foo in remote directory bar/foo: $ osf upload -r foo bar To place contents of local directory foo in remote directory bar: $ osf upload -r foo/ bar

osfclient.utils

Utility functions

Helpers and other assorted functions.

osfclient.utils.file_empty(fp)[source]

Determine if a file is empty or not.

osfclient.utils.makedirs(path, mode=511, exist_ok=False)[source]
osfclient.utils.norm_remote_path(path)[source]

Normalize path.

All remote paths are absolute.

osfclient.utils.split_storage(path, default='osfstorage')[source]

Extract storage name from file path.

If a path begins with a known storage provider the name is removed from the path. Otherwise the default storage provider is returned and the path is not modified.

osfclient.models

Classes to model entities in the OSF API.

class osfclient.models.File(json, session=None)[source]
remove()[source]

Remove this file from the remote storage.

update(fp)[source]

Update the remote file from a local file.

Pass in a filepointer fp that has been opened for writing in binary mode.

write_to(fp)[source]

Write contents of this file to a local file.

Pass in a filepointer fp that has been opened for writing in binary mode.

class osfclient.models.Project(json, session=None)[source]
storage(provider='osfstorage')[source]

Return storage provider.

storages

Iterate over all storages for this projects.

class osfclient.models.Storage(json, session=None)[source]
create_file(path, fp, update=False)[source]

Store a new file at path in this storage.

The contents of the file descriptor fp (opened in ‘rb’ mode) will be uploaded to path which is the full path at which to store the file.

To update an existing file set update=True.

files

Iterate over all files in this storage.

Recursively lists all files in all subfolders.

Helpers and inner workings

These classes do not directly model entities in the OSF API. They are used to help with technical things in building the API.

class osfclient.models.core.OSFCore(json, session=None)[source]
class osfclient.models.OSFSession[source]
auth = None
basic_auth(username, password)[source]
build_url(*args)[source]
get(url, *args, **kwargs)[source]
put(url, *args, **kwargs)[source]