mirror of https://github.com/borgbackup/borg.git
docs: fix/improve documentation for @api decorator
This commit is contained in:
parent
66d86b6280
commit
8a1b198e24
|
@ -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)
|
||||
|
|
Loading…
Reference in New Issue