From 8a1b198e24c6702e0e0cc76de6151b2071761591 Mon Sep 17 00:00:00 2001 From: Thalian <39634976+fantasya-pbem@users.noreply.github.com> Date: Sun, 3 Nov 2019 14:09:33 +0100 Subject: [PATCH] [DOC] #4674 - Add more documentation for @api decorator. (#4801) docs: fix/improve documentation for @api decorator --- src/borg/remote.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/src/borg/remote.py b/src/borg/remote.py index ecf438367..4ebc135ce 100644 --- a/src/borg/remote.py +++ b/src/borg/remote.py @@ -422,18 +422,22 @@ class SleepingBandwidthLimiter: def api(*, since, **kwargs_decorator): """Check version requirements and use self.call to do the remote method call. - 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. + 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. + 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. + + 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)