2018-12-08 22:34:34 +03:00
|
|
|
# Meastral
|
2019-06-15 22:57:17 +03:00
|
|
|
A light-weight and open-source Dropbox client for macOS and Linux.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2018-11-26 18:56:32 +03:00
|
|
|
## About
|
2019-06-15 22:57:17 +03:00
|
|
|
Meastral is an open-source Dropbox client written in Python. The project's main goal is to
|
|
|
|
provide a client for platforms and file systems that are not directly supported by
|
|
|
|
Dropbox. Meastral uses the Python SDK for the Dropbox API v2.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Installation
|
|
|
|
Download and install the Python package by running
|
|
|
|
```console
|
2019-06-23 22:53:08 +03:00
|
|
|
$ pip install --upgrade git+https://github.com/SamSchott/maestral
|
2019-06-15 22:57:17 +03:00
|
|
|
```
|
2019-06-25 21:29:01 +03:00
|
|
|
in the command line. If you intend to use the graphical user interface, you also need to
|
|
|
|
install PyQt5:
|
|
|
|
```console
|
|
|
|
$ pip install --upgrade PyQt5
|
|
|
|
```
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2018-12-08 20:05:55 +03:00
|
|
|
## Usage
|
2019-06-25 21:29:01 +03:00
|
|
|
Run `meastral gui` in the command line to start Meastral with a graphical user interface.
|
|
|
|
On its first run, Meastral will guide you through linking and configuring your Dropbox and
|
|
|
|
will then start syncing. The user interface is based on a status bar icon which shows the
|
2019-06-15 22:57:17 +03:00
|
|
|
current syncing status and a preference pane for configuration.
|
2018-12-08 15:50:42 +03:00
|
|
|
|
2019-06-27 01:21:25 +03:00
|
|
|
<img src="/screenshots/macOS.png" height="500" />
|
|
|
|
<img src="/screenshots/Fedora.png" height="500" />
|
2018-12-08 19:43:39 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Command line usage
|
|
|
|
After installation, Meastral will be available as a command line script by typing
|
|
|
|
`meastral` in the command prompt. Command line functionality resembles that of the
|
|
|
|
interactive client. Type `meastral --help` to get a full list of available commands.
|
|
|
|
Invoking `meastral sync` will configure Meastral on first run and then automatically start
|
|
|
|
syncing.
|
2018-12-08 15:50:42 +03:00
|
|
|
|
2018-12-02 03:26:41 +03:00
|
|
|
## Interactive usage (Python shell)
|
2018-11-28 00:29:49 +03:00
|
|
|
|
2018-11-28 00:34:35 +03:00
|
|
|
After installation, in a Python command prompt, run
|
2018-11-28 00:29:49 +03:00
|
|
|
```Python
|
2018-12-08 22:34:34 +03:00
|
|
|
>>> from meastral import Meastral
|
|
|
|
>>> m = Meastral()
|
2018-11-28 00:29:49 +03:00
|
|
|
```
|
2019-06-15 22:57:17 +03:00
|
|
|
On initial use, Meastral will ask you to link your Dropbox account, give the location of
|
|
|
|
your Dropbox folder on the local drive, and to specify excluded folders. It will then
|
|
|
|
start syncing. Supported commands are:
|
2018-11-28 00:29:49 +03:00
|
|
|
|
|
|
|
```Python
|
2018-12-08 22:34:34 +03:00
|
|
|
>>> m.pause_sync() # pause syncing
|
|
|
|
>>> m.resume_sync() # resume syncing
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2018-12-02 03:28:35 +03:00
|
|
|
>>> path = '/Folder/On/Dropbox' # path relative to Dropbox folder
|
2018-12-08 22:34:34 +03:00
|
|
|
>>> m.exclude_folder(path) # exclude Dropbox folder from sync, delete locally
|
2018-12-09 23:28:33 +03:00
|
|
|
>>> m.include_folder(path) # include Dropbox folder in sync, download its contents
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2018-12-09 23:28:33 +03:00
|
|
|
>>> m.set_dropbox_directory('~/Dropbox') # give path for local Dropbox folder
|
2018-12-08 22:34:34 +03:00
|
|
|
>>> m.unlink() # unlinks your Dropbox account but keeps are your files
|
2018-12-02 03:26:41 +03:00
|
|
|
```
|
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Structure
|
|
|
|
`client.MaestralClient` handles all the interaction with the Dropbox API such as
|
|
|
|
authentication, uploading and downloading files and folders, getting metadata and listing
|
|
|
|
folder contents. It also includes utilities to convert between local and Dropbox file
|
|
|
|
paths, to keep track of local revisions and to check for sync conflicts between local and
|
|
|
|
remote files.
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
`monitor.MaestralMonitor` handles the actual syncing. It monitors the local Dropbox
|
|
|
|
folders and the remote Dropbox for changes and applies them using the interface provided
|
|
|
|
by `MaestralClient`.
|
2018-11-28 00:29:49 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
`main.Maestral` provides the main programmatic user interface. It links your Dropbox
|
|
|
|
account and sets up your local, lets you select which folders to sync and can pause and
|
|
|
|
resume syncing.
|
2018-12-08 20:05:55 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
`gui` contains all user interfaces for `Maestral`.
|
|
|
|
|
|
|
|
## Contribute
|
2019-06-26 22:09:37 +03:00
|
|
|
The following tasks could need your help:
|
2019-06-15 22:57:17 +03:00
|
|
|
|
|
|
|
- [ ] Native Cocoa and GTK interfaces. Maestral currently uses PyQt.
|
|
|
|
- [ ] Better handling of network errors and API errors.
|
|
|
|
- [ ] Test robustness if internet connection is slow or lost, maestral process is killed
|
|
|
|
during sync, user is logged out during sync, etc.
|
2019-06-25 21:29:01 +03:00
|
|
|
- [ ] More efficient and robust tracking of local revisions. Possibly using xattr, even
|
|
|
|
though this would limit file system compatibility.
|
|
|
|
- [ ] Detect and warn in case of unsupported Dropbox folder locations (network drives,
|
|
|
|
external hard drives, etc) and when the Dropbox folder is deleted by the user.
|
|
|
|
- [ ] Speed up download of large folders and initial sync: Download zip files if possible.
|
|
|
|
|
2018-11-28 00:29:49 +03:00
|
|
|
|
2018-12-02 03:26:41 +03:00
|
|
|
## Warning:
|
2018-12-08 22:34:34 +03:00
|
|
|
- Meastral does not have production status yet, so only 500 accounts can use the API keys.
|
2019-06-25 21:29:01 +03:00
|
|
|
- Meastral is still in beta status and using it may potentially result in loss of data.
|
|
|
|
Only sync folders with non-essential files.
|
2019-03-13 22:01:58 +03:00
|
|
|
- Known issues:
|
2019-06-15 22:57:17 +03:00
|
|
|
- File and folder names with two periods are currently not supported. This prevents
|
|
|
|
syncing of temporary files which are created during the save process on some file
|
|
|
|
systems.
|
|
|
|
- Rare falsely detected sync conflicts may occur on startup.
|
|
|
|
- Network drives and some external hard drives are not supported as locations for the
|
|
|
|
Dropbox folder.
|
2018-11-28 00:23:00 +03:00
|
|
|
|
|
|
|
## Dependencies
|
|
|
|
*System:*
|
2018-12-08 19:52:24 +03:00
|
|
|
- Python 3.6 or higher
|
2018-11-28 00:23:00 +03:00
|
|
|
- macOS or Linux
|
2019-06-25 16:12:04 +03:00
|
|
|
- [gnome-shell-extension-appindicator](https://github.com/ubuntu/gnome-shell-extension-appindicator)
|
|
|
|
on Gnome 3.26 and higher
|
2018-11-28 00:23:00 +03:00
|
|
|
|
|
|
|
*Python:*
|
|
|
|
- dropbox
|
|
|
|
- watchdog
|
2018-12-06 00:11:47 +03:00
|
|
|
- blinker
|
2019-06-13 21:08:27 +03:00
|
|
|
- PyQt 5.9 or higher (for GUI only)
|