samschott/maestral
1
1
Fork 0
mirror of https://github.com/samschott/maestral.git synced 2024-10-06 10:28:07 +03:00
Code Issues Projects Releases Wiki Activity

improved type annotations in doc strings

Browse Source
This commit is contained in:
Sam Schott 2020-04-05 01:24:04 +01:00
parent 04d5887fd0
commit 66ac9c419a
7 changed files with 57 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
maestral/cli.py
View File

@ -146,9 +146,9 @@ def format_table(rows=None, columns=None, headers=None, padding_right=2):
"""
Prints given data as a pretty table. Either rows or columns must be given.s
:param list rows: List of strings for table rows.
:param list columns: List of strings for table columns.
:param list headers: List of strings for column titles.
:param Optional[list] rows: List of strings for table rows.
:param Optional[list] columns: List of strings for table columns.
:param Optional[list] headers: List of strings for column titles.
:param int padding_right: Padding between columns.
:return: Formatted multiline string.
:rtype: str

26
maestral/errors.py
View File

@ -22,16 +22,16 @@ class MaestralApiError(Exception):
"""
Base class for errors originating from the Dropbox API or the 'local API'.
:ivar str title: A short description of the error type. This can be used in a CLI or
:param str title: A short description of the error type. This can be used in a CLI or
GUI to give a short error summary.
:ivar str message: A more verbose description which can include instructions on how to
proceed to fix the error.
:ivar str dbx_path: Dropbox path of the file that caused the error.
:ivar str dbx_path_dst: Dropbox destination path of the file that caused the error.
This should be set for instance when error occurs when moving a file / folder.
:ivar str local_path: Local path of the file that caused the error.
:ivar str local_path_dst: Local destination path of the file that caused the error.
This should be set for instance when error occurs when moving a file / folder.
:param str message: A more verbose description which can include instructions on how
to proceed to fix the error.
:param Optional[str] dbx_path: Dropbox path of the file that caused the error.
:param Optional[str] dbx_path_dst: Dropbox destination path of the file that caused
the error. This should be set for instance when error occurs when moving an item.
:param Optional[str] local_path: Local path of the file that caused the error.
:param Optional[str] local_path_dst: Local destination path of the file that caused
the error. This should be set for instance when error occurs when moving an item.
"""
def __init__(self, title, message, dbx_path=None, dbx_path_dst=None,
@ -175,8 +175,8 @@ def os_to_maestral_error(exc, dbx_path=None, local_path=None):
IsADirectoryError: If raised, this likely is a Maestral bug.
:param OSError exc: Python Exception.
:param str dbx_path: Dropbox path of file which triggered the error.
:param str local_path: Local path of file which triggered the error.
:param Optional[str] dbx_path: Dropbox path of file which triggered the error.
:param Optional[str] local_path: Local path of file which triggered the error.
:returns: :class:`MaestralApiError` instance or :class:`OSError` instance.
"""
@ -225,8 +225,8 @@ def dropbox_to_maestral_error(exc, dbx_path=None, local_path=None):
informative error title and message.
:param exc: :class:`dropbox.exceptions.DropboxException` instance.
:param str dbx_path: Dropbox path of file which triggered the error.
:param str local_path: Local path of file which triggered the error.
:param Optional[str] dbx_path: Dropbox path of file which triggered the error.
:param Optional[str] local_path: Local path of file which triggered the error.
:returns: :class:`MaestralApiError` instance.
:rtype: :class:`MaestralApiError`
"""

14
maestral/main.py
View File

@ -89,8 +89,8 @@ class CachedHandler(logging.Handler):
error interfaces.
:param int level: Initial log level. Defaults to NOTSET.
:param int maxlen: Maximum number of records to store. If ``None``, all records will
be stored.
:param Optional[int] maxlen: Maximum number of records to store. If ``None``, all
records will be stored. Defaults to ``None``.
"""
def __init__(self, level=logging.NOTSET, maxlen=None):
@ -855,7 +855,7 @@ class Maestral:
On initial sync, this does not trigger any downloads.
:param list items: If given, list of excluded files or folders to set.
:param Optional[list] items: If given, list of excluded files or folders to set.
:raises: :class:`errors.MaestralApiError`
"""
@ -921,8 +921,8 @@ class Maestral:
Sets the local Dropbox directory. This moves all local files to the new location
and resumes syncing afterwards.
:param str new_path: Full path to local Dropbox folder. If not given, the user
will be prompted to input the path.
:param Optional[str] new_path: Full path to local Dropbox folder. If not given,
the user will be prompted to input the path.
:raises: :class:`OSError` if moving the directory fails.
"""
@ -954,8 +954,8 @@ class Maestral:
"""
Creates a new Dropbox directory. Only call this during setup.
:param str path: Full path to local Dropbox folder. If not given, the user will be
prompted to input the path.
:param Optional[str] path: Full path to local Dropbox folder. If not given, the
user will be prompted to input the path.
:raises: :class:`OSError` if creation fails
"""
path = path or select_dbx_path_dialog(self._config_name, allow_merge=True)

27
maestral/sync.py
View File

@ -910,8 +910,8 @@ class UpDownSync:
"""
Clears all sync errors for ``local_path`` or ``dbx_path``.
:param str local_path: Absolute path on local drive.
:param str dbx_path: Path relative to Dropbox folder.
:param Optional[str] local_path: Absolute path on local drive.
:param Optional[str] dbx_path: Path relative to Dropbox folder.
:raises: :class:`ValueError` if no path is given.
"""
if not (local_path or dbx_path):
@ -3052,22 +3052,19 @@ def entries_to_str(entries):
def cpu_usage_percent(interval=0.1):
"""Returns a float representing the current process CPU
utilization as a percentage. This copies the similar
method from psutil.
"""Returns a float representing the current process CPU utilization as a percentage.
This copies the similar method from psutil.
Compares process times to system CPU times elapsed before
and after the interval (blocking). It is recommended for
accuracy that this function be called with an interval of
at least 0.1 sec.
Compares process times to system CPU times elapsed before and after the interval
(blocking). It is recommended for accuracy that this function be called with an
interval of at least 0.1 sec.
A value > 100.0 can be returned in case of processes running
multiple threads on different CPU cores.
A value > 100.0 can be returned in case of processes running multiple threads on
different CPU cores.
The returned value is explicitly NOT split evenly between
all available logical CPUs. This means that a busy loop process
running on a system with 2 logical CPUs will be reported as
having 100% CPU utilization instead of 50%.
The returned value is explicitly NOT split evenly between all available logical CPUs.
This means that a busy loop process running on a system with 2 logical CPUs will be
reported as having 100% CPU utilization instead of 50%.
"""
if not interval > 0:

18
maestral/utils/appdirs.py
View File

@ -33,8 +33,8 @@ def get_cache_path(subfolder=None, filename=None, create=True):
- Linux: '$XDG_CACHE_HOME/SUBFOLDER/FILENAME'
- fallback: '$HOME/.cache/SUBFOLDER/FILENAME'
:param str subfolder: The subfolder for the app.
:param str filename: The filename to append for the app.
:param Optional[str] subfolder: The subfolder for the app.
:param Optional[str] filename: The filename to append for the app.
:param bool create: If ``True``, the folder '<subfolder>' will be created on-demand.
"""
if platform.system() == 'Darwin':
@ -54,8 +54,8 @@ def get_log_path(subfolder=None, filename=None, create=True):
- Linux: '$XDG_CACHE_HOME/SUBFOLDER/FILENAME'
- fallback: '$HOME/.cache/SUBFOLDER/FILENAME'
:param str subfolder: The subfolder for the app.
:param str filename: The filename to append for the app.
:param Optional[str] subfolder: The subfolder for the app.
:param Optional[str] filename: The filename to append for the app.
:param bool create: If ``True``, the folder '<subfolder>' will be created on-demand.
"""
@ -75,7 +75,7 @@ def get_autostart_path(filename=None, create=True):
- Linux: '$XDG_CONFIG_HOME/autostart/FILENAME'
- fallback: '$HOME/.config/autostart/FILENAME'
:param str filename: The filename to append for the app.
:param Optional[str] filename: The filename to append for the app.
:param bool create: If ``True``, the folder '<subfolder>' will be created on-demand.
"""
if platform.system() == 'Darwin':
@ -97,8 +97,8 @@ def get_runtime_path(subfolder=None, filename=None, create=True):
- Linux: '$XDG_RUNTIME_DIR/SUBFOLDER/FILENAME'
- fallback: '$HOME/.cache/SUBFOLDER/FILENAME'
:param str subfolder: The subfolder for the app.
:param str filename: The filename to append for the app.
:param Optional[str] subfolder: The subfolder for the app.
:param Optional[str] filename: The filename to append for the app.
:param bool create: If ``True``, the folder '<subfolder>' will be created on-demand.
"""
@ -119,8 +119,8 @@ def get_old_runtime_path(subfolder=None, filename=None, create=True):
- Linux: '$XDG_RUNTIME_DIR/SUBFOLDER/FILENAME'
- fallback: '$HOME/.cache/SUBFOLDER/FILENAME'
:param str subfolder: The subfolder for the app.
:param str filename: The filename to append for the app.
:param Optional[str] subfolder: The subfolder for the app.
:param Optional[str] filename: The filename to append for the app.
:param bool create: If ``True``, the folder '<subfolder>' will be created on-demand.
"""

4
maestral/utils/notify.py
View File

@ -291,8 +291,8 @@ class DesktopNotifier:
:param str message: Notification message.
:param str urgency: Notification urgency. Some backends use this to determine how
the notification is displayed.
:param str icon: Path to an icon. Some backends support displaying an (app) icon
together with the notification.
:param Optional[str] icon: Path to an icon. Some backends support displaying an
(app) icon together with the notification.
"""
self._impl.send(title, message, urgency, icon)

21
maestral/utils/oauth_implicit.py
View File

@ -32,7 +32,7 @@ class DropboxOAuth2FlowImplicitBase:
Class to perform an OAuth implicit grant flow.
:param str consumer_key: Consumer key / API key.
:param str locale: Locale to use.
:param Optional[str] locale: Locale to use.
"""
def __init__(self, consumer_key, locale=None):
@ -57,7 +57,7 @@ class DropboxOAuth2FlowImplicitBase:
and puts a marker for the API version in front.
:param str target: A target url (e.g. '/files') to build upon.
:param dict params: Optional dictionary of parameters.
:param Optional[dict] params: Optional dictionary of parameters.
:returns: The path and parameters components of an API URL.
:rtype: str
"""
@ -82,7 +82,7 @@ class DropboxOAuth2FlowImplicitBase:
This method adds scheme and hostname to the path returned from build_path.
:param str target: A target url (e.g. '/files') to build upon.
:param dict params: Optional dictionary of parameters (name to value).
:param Optional[dict] params: Optional dictionary of parameters (name to value).
:param str host: The host url.
:returns: The full API URL.
:rtype: str
@ -101,13 +101,14 @@ class DropboxOAuth2FlowImplicit(DropboxOAuth2FlowImplicitBase):
after the user finishes authorizing your app. This URI must be HTTPS-based and
pre-registered with the Dropbox servers, though localhost URIs are allowed without
pre-registration and can be either HTTP or HTTPS.
:param dict session: A dict-like object that represents the current user's web session
(will be used to save the CSRF token).
:param Optional[dict] session: A dict-like object that represents the current user's
web session (will be used to save the CSRF token).
:param str csrf_token_session_key: The key to use when storing the CSRF token in the
session (for example: 'dropbox-auth-csrf-token').
:param str locale: The locale of the user of your application. For example 'en' or
'en_US'. Some API calls return localized data and error messages; this setting
tells the server which locale to use. If not given, the server uses 'en_US'.
:param Optional[str] locale: The locale of the user of your application. For example
'en' or 'en_US'. Some API calls return localized data and error messages; this
setting tells the server which locale to use. If not given, the Dropbox server
uses 'en_US'.
"""
REDIRECT_URI = 'https://www.dropbox.com/1/oauth2/display_token'
@ -135,8 +136,8 @@ class DropboxOAuth2FlowImplicit(DropboxOAuth2FlowImplicitBase):
(as provided to the constructor). This CSRF token will be checked on
:meth:`finish` to prevent request forgery.
:param str url_state: Any data that you would like to keep in the URL through the
authorization process.
:param Optional[str] url_state: Any data that you would like to keep in the URL
through the authorization process.
:returns: The URL for a page on Dropbox's website. This page will let the user
'approve' your app, which gives your app permission to access the user's
Dropbox account. Tell the user to visit this URL and approve your app.