https://github.com/psychopy/pyosf
A pure python library for simple sync with Open Science Framework
https://github.com/psychopy/pyosf
Last synced: 5 months ago
JSON representation
A pure python library for simple sync with Open Science Framework
- Host: GitHub
- URL: https://github.com/psychopy/pyosf
- Owner: psychopy
- Created: 2016-01-25T21:47:18.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-12-04T10:44:04.000Z (over 7 years ago)
- Last Synced: 2025-11-24T06:35:11.986Z (8 months ago)
- Language: Python
- Size: 155 KB
- Stars: 9
- Watchers: 5
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
`pyosf` is a pure Python library for simple file sync with Open Science
Framework
This package is for simple synchronisation of files from the local file space
to the Open Science Framework (OSF). There is a more complex fully-featured
sync package by the Center for Open Science, who created OSF, called [osf-sync](https://github.com/CenterForOpenScience/osf-sync)
The OSF official package is designed for continuous automated synchronisation
of many projects (a la Dropbox). We needed something simpler (for combination
with PsychoPy). The `pyosf` package aims to perform basic search/login/sync
operations with single projects on OSF but only when instructed to do so (no
continuous sync).
In implementation `pyosf` differs from osf-sync in the following ways:
- fewer dependencies
- support for Python2.x
- no GUI included (yet)
- local database of files saved as flat json format (no database)
- simpler handling of sync resolution rules(?)
It can be distributed freely under the MIT license.
[](https://travis-ci.org/psychopy/pyosf)
[](https://codecov.io/github/psychopy/pyosf?branch=master)
Installation
------------
`pyosf` is compatible with Linux, OS X and Windows, and with Python 2.7 and
Python 3.4 (upwards)
Install it with:
pip install pyosf
Usage
-----
When you first create a `Project`, or to perform searches for projects, you
need to create a `Session`::
import pyosf
session = pyosf.Session(username='name@gmail.com', password='xxyxyayxy')
The `Session` allows you to conduct searches::
```python
users = session.find_users('Peirce') # a list of user ids
print(users)
jon_id = users[0]['id'] # we're just using the first one
projs = session.find_user_projects(user_id=jon_id) # id=None to find your own projects
for proj in projs:
print('{}: {}'.format(proj.id, proj.title))
osf_proj = session.open_project(proj_id) # or this if you know the project id
```
Then you can create a `Project` object to track the remote and local files. A
`Project` consists of:
- `project_file`: your project info
- `root_path`: the location where your osf project is permanently stored
locally
- `osf`: an OSF project object from a `Session`
OR
- simply a project file location, on subsequent repeats (provided you did not
change the `root_path`.)
If initially, you do not have a `project_file`, just specify the location where
you want to save it later. `pyosf` will give you a warning that it did not find
a `project_file`, which is ok because we are going to create it.
```python
# Make a project object
proj = pyosf.Project(project_file='/Home/myUserName/pyosfProjects/first.proj',
root_path='/Home/myUserName/experiments/firstExperiment',
osf=osf_proj)
# get the difference between local and remote project
changes = proj.get_changes()
# inspect the changes
print(changes)
# do the sync
changes.apply()
# If you did not have a project file initially, the following will create one
# and save it under the path that you have given when calling `pyosf.Project`
proj.save()
```
The project file saves your username (but not password) and, if the username
has previously been used to authenticate a `Session` with OSF then an
authentication token will have been saved to `~/.pyosf/tokens.json` and that
will allow the project to create a new session. i.e. on subsequent logins you
can do just:
```python
import pyosf
# no need to create a session second time around
proj = pyosf.Project(project_file='/Home/myUserName/pyosfProjects/first.proj')
changes = proj.get_changes()
changes.apply()
```
Security and passwords
----------------------
When you first create a `Session` you need to provide a username (email
address) and your OSF password. These will be sent securely (over https) and an
auth token will be retrieved. That auth token will be stored in readable text
in the current user space of your computer (in ~/.pyosf/tokens.json). When a
`Session` is subsequently created the username is used to check for a previous
auth token and if one is found a password will not be needed.
The second step is from the `Project`. The `Project` stores in its .proj file
(json format) the username that was being used for this sync (as supplied on
first access). That username will be used to create a `Session` which will then
fetch the appropriate token as described above.