0
# OSFClient
1

2
A Python library and command-line interface for interacting with the Open Science Framework (OSF). OSFClient enables researchers and developers to programmatically upload, download, and manage large datasets and research files through both Python APIs and CLI commands, supporting scientific workflows and collaborative research projects.
3

4
## Package Information
5

6
- **Package Name**: osfclient
7
- **Language**: Python
8
- **Installation**: `pip install osfclient`
9
- **License**: BSD-3-Clause
10

11
## Core Imports
12

13
```python
14
from osfclient import OSF
15
```
16

17
For version information:
18
```python
19
from osfclient import __version__
20
```
21

22
## Basic Usage
23

24
```python
25
from osfclient import OSF
26

27
# Initialize with authentication
28
osf = OSF(username='your_username', password='your_password')
29
# Or use token authentication
30
osf = OSF(token='your_personal_access_token')
31

32
# Get a project
33
project = osf.project('project_id')
34
print(f"Project: {project.title}")
35

36
# Access default storage
37
storage = project.storage()
38

39
# List all files
40
for file in storage.files:
41
    print(f"File: {file.path}, Size: {file.size}")
42

43
# Download a file
44
with open('local_file.txt', 'wb') as f:
45
    remote_file = next(storage.files)  # Get first file
46
    remote_file.write_to(f)
47

48
# Upload a file
49
with open('local_upload.txt', 'rb') as f:
50
    storage.create_file('remote_path.txt', f)
51
```
52

53
Command-line usage:
54
```bash
55
# Set up project configuration
56
osf init
57

58
# List all files
59
osf ls
60

61
# Download all files
62
osf clone
63

64
# Download specific file
65
osf fetch remote/path.txt local/file.txt
66

67
# Upload file
68
osf upload local/file.txt remote/path.txt
69
```
70

71
## Architecture
72

73
OSFClient is built around a hierarchical model structure:
74

75
- **OSF**: Main client class for authentication and project access
76
- **Project**: Represents an OSF project containing multiple storage providers
77
- **Storage**: Individual storage provider (osfstorage, github, figshare, etc.)
78
- **File/Folder**: Individual files and folders within storage
79
- **OSFSession**: HTTP session management with rate limiting and authentication
80

81
This design mirrors the OSF platform's structure, providing intuitive navigation from projects down to individual files while supporting both programmatic access and command-line operations.
82

83
## Capabilities
84

85
### Python API
86

87
Core Python library functionality for programmatic access to OSF projects, including authentication, project management, and file operations.
88

89
```python { .api }
90
class OSF:
91
    def __init__(self, username=None, password=None, token=None): ...
92
    def login(self, username=None, password=None, token=None): ...
93
    def project(self, project_id): ...
94
    def guid(self, guid): ...
95
```
96

97
[Python API](./python-api.md)
98

99
### Project Management
100

101
Project, storage, file, and folder management classes for navigating and manipulating OSF project structures.
102

103
```python { .api }
104
class Project:
105
    def storage(self, provider='osfstorage'): ...
106
    @property
107
    def storages(self): ...
108

109
class Storage:
110
    def create_file(self, path, fp, force=False, update=False): ...
111
    def create_folder(self, name, exist_ok=False): ...
112
    @property
113
    def files(self): ...
114
```
115

116
[Project Management](./project-management.md)
117

118
### Command Line Interface
119

120
Full-featured CLI for OSF operations including project setup, file listing, downloading, uploading, and URL generation.
121

122
```bash { .api }
123
osf init                           # Set up project configuration
124
osf clone [output]                 # Download all files
125
osf fetch <remote> [local]         # Download specific file
126
osf list                          # List all files
127
osf upload <source> <destination>  # Upload file or directory
128
osf remove <target>               # Remove file
129
osf geturl <remote>               # Get download URL
130
```
131

132
[CLI Interface](./cli-interface.md)
133

134
### Utilities and Exceptions
135

136
Utility functions for path handling, file operations, and custom exception classes for error handling.
137

138
```python { .api }
139
def norm_remote_path(path): ...
140
def split_storage(path, default='osfstorage'): ...
141
def checksum(file_path, hash_type='md5', block_size=65536): ...
142

143
class OSFException(Exception): ...
144
class UnauthorizedException(OSFException): ...
145
```
146

147
[Utilities](./utilities.md)