mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

[DOC] #4674 - Add more documentation for @api decorator. (#4801) 

docs: fix/improve documentation for @api decorator
This commit is contained in:
Thalian 2019-11-03 14:09:33 +01:00 committed by TW
parent 66d86b6280
commit 8a1b198e24
1 changed files with 12 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/borg/remote.py
View File

@ -422,18 +422,22 @@ class SleepingBandwidthLimiter:
def api(*, since, **kwargs_decorator):
"""Check version requirements and use self.call to do the remote method call.
<since> specifies the version in which borg introduced this method,
calling this method when connected to an older version will fail without transmiting
anything to the server.
<since> specifies the version in which borg introduced this method.
Calling this method when connected to an older version will fail without transmitting anything to the server.
Further kwargs can be used to encode version specific restrictions.
If a previous hardcoded behaviour is parameterized in a version, this allows calls that
use the previously hardcoded behaviour to pass through and generates an error if another
behaviour is requested by the client.
Further kwargs can be used to encode version specific restrictions:
e.g. when 'append_only' was introduced in 1.0.7 the previous behaviour was what now is append_only=False.
<previously> is the value resulting in the behaviour before introducing the new parameter.
If a previous hardcoded behaviour is parameterized in a version, this allows calls that use the previously
hardcoded behaviour to pass through and generates an error if another behaviour is requested by the client.
E.g. when 'append_only' was introduced in 1.0.7 the previous behaviour was what now is append_only=False.
Thus @api(..., append_only={'since': parse_version('1.0.7'), 'previously': False}) allows calls
with append_only=False for all version but rejects calls using append_only=True on versions older than 1.0.7.
<dontcare> is a flag to set the behaviour if an old version is called the new way.
If set to True, the method is called without the (not yet supported) parameter (this should be done if that is the
more desirable behaviour). If False, an exception is generated.
E.g. before 'threshold' was introduced in 1.2.0a8, a hardcoded threshold of 0.1 was used in commit().
"""
def decorator(f):
@functools.wraps(f)