Skip to content

Latest commit

 

History

History
77 lines (63 loc) · 2.74 KB

index.rst

File metadata and controls

77 lines (63 loc) · 2.74 KB
Raw

Welcome to Maestral's developer documentation

This documentation provides an API reference for the maestral daemon. It is built from the current dev branch and is intended for developers. For a user manual and an overview of Maestral's functionality, please refer to maestral.app.

.. toctree::
   :hidden:
   :caption: Background
   :maxdepth: 2

   background/sync_logic
   background/logging
   background/config_files
   background/state_files
   background/contributing


.. toctree::
   :hidden:
   :caption: Reference
   :maxdepth: 2

   autoapi/maestral/autostart/index
   autoapi/maestral/cli/index
   autoapi/maestral/client/index
   autoapi/maestral/config/index
   autoapi/maestral/constants/index
   autoapi/maestral/daemon/index
   autoapi/maestral/database/index
   autoapi/maestral/errorhandling/index
   autoapi/maestral/exceptions/index
   autoapi/maestral/fsevents/index
   autoapi/maestral/logging/index
   autoapi/maestral/main/index
   autoapi/maestral/manager/index
   autoapi/maestral/models/index
   autoapi/maestral/notify/index
   autoapi/maestral/keyring/index
   autoapi/maestral/sync/index
   autoapi/maestral/utils/index

Getting started

To use the Maestral API in a Python interpreter, import the main module first and initialize a Maestral instance with a configuration name. For this example, we use a new configuration "private" which is not yet linked to a Dropbox account:

>>> from maestral.main import Maestral
>>> m = Maestral(config_name="private")

Config files will be created on-demand for the new configuration, as described in :doc:`background/config_files` and :doc:`background/state_files`.

We now link the instance to an existing Dropbox account. This is done by generating a Dropbox URL for the user to visit and authorize Maestral. Using the :meth:`link` method, the resulting auth code is exchanged for an access token to make Dropbox API calls. See Dropbox's oauth-guide for details on the OAuth2 PKCE flow which we use. When the auth flow is successfully completed, the credentials will be saved in the system keyring (e.g., macOS Keychain or Gnome Keyring).

>>> url = m.get_auth_url()  # get token from Dropbox website
>>> print(f"Please go to {url} to retrieve a Dropbox authorization token.")
>>> token = input("Enter auth token: ")
>>> res = m.link(token)

The call to :meth:`link` will return 0 on success, 1 for an invalid code and 2 for connection errors. We verify that linking succeeded and proceed to create a local Dropbox folder and start syncing:

>>> if res == 0:
...     m.create_dropbox_directory("~/Dropbox (Private)")
...     m.start_sync()