maestral/CONTRIBUTING.md

Code

To start, install maestral with the dev extra to get all dependencies required for development:

pip3 install maestral[dev]

This will install packages to check and enforce the code style, use pre-commit hooks and bump the current version.

Code is formatted with black. Coding style is checked with flake8. Type hints, PEP484, are checked with mypy.

You can check the format, coding style, and type hints at the same time by running the provided pre-commit hook from the git directory:

pre-commit run -a

You can also install the provided pre-commit hook to run checks on every commit. This will however significantly slow down commits. An introduction to pre-commit commit hooks is given at https://pre-commit.com.

Documentation

The documentation is built using sphinx and a few of its extensions. It is built from the develop and master branches and hosted on Read The Docs. If you want to build the documentation locally, install maestral with the docs extra to get all required dependencies:

pip3 install maestral[docs]

The API documentation is mostly based on doc strings. Inline comments should be used whenever code may be difficult to understand for others.

Tests

The test suite uses pytest to define and run all tests.

Test are grouped into those which require a linked Dropbox account ("linked") and those who can run by themselves ("offline"). The former tend to be integration test while the latter are mostly unit tests. The focus currently lies on integration tests, especially for the sync engine, as they are easier to maintain when the implementation and internal APIs change. Exceptions are made for performance tests, for instance for indexing and cleaning up sync events, and for particularly complex functions that are prone to regressions.

Important: The entire content of the Dropbox folder is deleted before and after running each test case. You should therefore use a dedicated account to run tests.

The current test suite uses a Dropbox access token provided by the environment variable DROPBOX_ACCESS_TOKEN or a refresh token provided by DROPBOX_REFRESH_TOKEN to connect to a real account. The GitHub action which is running the tests will set the DROPBOX_ACCESS_TOKEN environment variable for you with a temporary access token that expires after 4 hours. Tests are run on ubuntu-latest and macos-latest in parallel on different accounts.

When you create a new test case, you should acquire a "lock" on the account before running tests to prevent them from interfering which each other by creating a folder test.lock in the root of the Dropbox folder. This folder should have a client_modified time set in the future, to the expiry time of the lock. Fixtures to create and clean up a test config and to acquire a lock are provided in the tests/linked/conftest.py.

If you run the tests locally, you will need to provide a refresh or access token for your own Dropbox account. If your account is already linked with Maestral, it will have saved a long-lived "refresh token" in your system keyring. You can access it manually or through the Python API:

from maestral.main import Maestral

m = Maestral()
print(m.cred_storage.token)

You can then store the retrieved refresh token in the environment variable DROPBOX_REFRESH_TOKEN to be automatically picked up by the tests.