From e0470f681cdf8965ec2d7334b8b01c586033db77 Mon Sep 17 00:00:00 2001 From: james Date: Tue, 11 Jan 2022 17:08:25 +0800 Subject: [PATCH] Specify units in docstrings for all lifetime fields/parameters. Signed-off-by: james --- gssapi/creds.py | 19 ++++++++++--------- gssapi/raw/creds.pyx | 16 +++++++++------- gssapi/raw/ext_cred_store.pyx | 8 ++++---- gssapi/raw/ext_password.pyx | 4 ++-- gssapi/raw/ext_password_add.pyx | 4 ++-- gssapi/raw/ext_s4u.pyx | 8 ++++---- gssapi/raw/named_tuples.py | 10 +++++----- gssapi/raw/sec_contexts.pyx | 10 +++++----- gssapi/sec_contexts.py | 3 ++- 9 files changed, 43 insertions(+), 39 deletions(-) diff --git a/gssapi/creds.py b/gssapi/creds.py index 888fea50..b42adb69 100644 --- a/gssapi/creds.py +++ b/gssapi/creds.py @@ -74,7 +74,7 @@ def name(self): @property def lifetime(self): - """Get the remaining lifetime of these credentials""" + """Get the remaining lifetime of these credentials, in seconds""" return self.inquire(name=False, lifetime=True, usage=False, mechs=False).lifetime @@ -110,8 +110,8 @@ def acquire(cls, name=None, lifetime=None, mechs=None, usage='both', Args: name (~gssapi.names.Name): the name associated with the credentials, or None for the default name - lifetime (int): the desired lifetime of the credentials, or None - for indefinite + lifetime (int): the desired lifetime of the credentials in seconds, + or None for indefinite mechs (list): the desired :class:`MechType` OIDs to be used with the credentials, or None for the default set usage (str): the usage for the credentials -- either 'both', @@ -213,8 +213,8 @@ def impersonate(self, name=None, lifetime=None, mechs=None, Args: name (~gssapi.names.Name): the name to impersonate - lifetime (int): the desired lifetime of the new credentials, - or None for indefinite + lifetime (int): the desired lifetime of the new credentials + in seconds, or None for indefinite mechs (list): the desired :class:`MechType` OIDs for the new credentials usage (str): the desired usage for the new credentials -- either @@ -243,6 +243,7 @@ def inquire(self, name=True, lifetime=True, usage=True, mechs=True): Args: name (bool): get the name associated with the credentials lifetime (bool): get the remaining lifetime for the credentials + in seconds usage (bool): get the usage for the credentials mechs (bool): get the mechanisms associated with the credentials @@ -278,9 +279,9 @@ def inquire_by_mech(self, mech, name=True, init_lifetime=True, information name (bool): get the name associated with the credentials init_lifetime (bool): get the remaining initiate lifetime for - the credentials + the credentials in seconds accept_lifetime (bool): get the remaining accept lifetime for - the credentials + the credentials in seconds usage (bool): get the usage for the credentials Returns: @@ -335,9 +336,9 @@ def add(self, name, mech, usage='both', usage (str): the usage for the credentials -- either 'both', 'initiate', or 'accept' init_lifetime (int): the desired initiate lifetime of the - credentials, or None for indefinite + credentials in seconds, or None for indefinite accept_lifetime (int): the desired accept lifetime of the - credentials, or None for indefinite + credentialsin seconds , or None for indefinite impersonator (Credentials): the credentials to use to impersonate the given name, or None to not acquire normally (:requires-ext:`s4u`) diff --git a/gssapi/raw/creds.pyx b/gssapi/raw/creds.pyx index caac3ea6..9412e886 100644 --- a/gssapi/raw/creds.pyx +++ b/gssapi/raw/creds.pyx @@ -92,8 +92,8 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'): Args: name (~gssapi.raw.names.Name): the name for which to acquire the credentials (or None for the "no name" functionality) - lifetime (int): the lifetime for the credentials (or None for - indefinite) + lifetime (int): the lifetime in seconds for the credentials + (or None for indefinite) mechs (~gssapi.MechType): the desired mechanisms for which the credentials should work, or None for the default set usage (str): the usage type for the credentials: may be @@ -101,8 +101,8 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'): Returns: AcquireCredResult: the resulting credentials, the actual mechanisms - with which they may be used, and their actual lifetime (or None for - indefinite or not supported) + with which they may be used, and their actual lifetime in seconds + (or None for indefinite or not supported) Raises: ~gssapi.exceptions.BadMechanismError @@ -206,9 +206,9 @@ accept_lifetime=None, mutate_input=False) usage (str): usage type for credentials. Possible values: 'initiate' (default), 'accept', 'both' (failsafe). init_lifetime (int): lifetime of credentials for use in initiating - security contexts (None for indefinite) + security contexts in seconds (None for indefinite) accept_lifetime (int): lifetime of credentials for use in accepting - security contexts (None for indefinite) + security contexts in seconds (None for indefinite) mutate_input (bool): whether to mutate the input credentials (True) or produce a new set of credentials (False). Defaults to False @@ -289,7 +289,7 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True, Args: creds (Creds): the credentials to inspect name (bool): get the Name associated with the credentials - lifetime (bool): get the TTL for the credentials + lifetime (bool): get the TTL for the credentials (in seconds) usage (bool): get the usage type of the credentials mechs (bool): the mechanims used with the credentials @@ -375,7 +375,9 @@ accept_lifetime=True, usage=True) mech (~gssapi.OID): the desired mechanism name (bool): get the Name associated with the credentials init_lifetime (bool): get the initiator TTL for the credentials + (in seconds) accept_lifetime (bool): get the acceptor TTL for the credentials + (in seconds) usage (bool): get the usage type of the credentials Returns: diff --git a/gssapi/raw/ext_cred_store.pyx b/gssapi/raw/ext_cred_store.pyx index 5edd5e65..0e6dd87c 100644 --- a/gssapi/raw/ext_cred_store.pyx +++ b/gssapi/raw/ext_cred_store.pyx @@ -122,8 +122,8 @@ usage='both') See :doc:`credstore` for valid values name (~gssapi.raw.names.Name): the name associated with the credentials, or None for the default name - lifetime (int): the desired lifetime of the credentials, or None - for indefinite + lifetime (int): the desired lifetime of the credentials in seconds, + or None for indefinite mechs (list): the desired mechanisms to be used with these credentials, or None for the default set usage (str): the usage for these credentials -- either 'both', @@ -224,9 +224,9 @@ init_lifetime=None, accept_lifetime=None) usage (str): the usage for these credentials -- either 'both', 'initiate', or 'accept' init_lifetime (int): the desired initiate lifetime of the - credentials, or None for indefinite + credentials in seconds, or None for indefinite accept_lifetime (int): the desired accept lifetime of the - credentials, or None for indefinite + credentials in seconds, or None for indefinite Returns: AcquireCredResult: the new credentials set and information about diff --git a/gssapi/raw/ext_password.pyx b/gssapi/raw/ext_password.pyx index 4f1ed81e..937d61b4 100644 --- a/gssapi/raw/ext_password.pyx +++ b/gssapi/raw/ext_password.pyx @@ -43,7 +43,7 @@ usage="initiate") name (~gssapi.raw.names.Name): the name to acquire credentials for password (bytes): the password used to acquire credentialss with lifetime (int): the lifetime for the credentials (or None for - indefinite) + indefinite), in seconds mechs (~gssapi.MechType): the desired mechanisms for which the credentials should work (or None for the default set) usage (str): usage type for credentials. Possible values: @@ -52,7 +52,7 @@ usage="initiate") Returns: AcquireCredResult: the resulting credentials, the actual mechanisms with which they may be used, and their actual lifetime (or None for - indefinite or not supported) + indefinite or not supported), in seconds Raises: ~gssapi.exceptions.GSSError diff --git a/gssapi/raw/ext_password_add.pyx b/gssapi/raw/ext_password_add.pyx index 5a142e76..5dbb8655 100644 --- a/gssapi/raw/ext_password_add.pyx +++ b/gssapi/raw/ext_password_add.pyx @@ -56,10 +56,10 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) 'initiate', 'accept', or 'both' init_lifetime (int): the lifetime for the credentials to remain valid when using them to initiate security contexts (or None for - indefinite) + indefinite), in seconds accept_lifetime (int): the lifetime for the credentials to remain valid when using them to accept security contexts (or None for - indefinite) + indefinite), in seconds Returns: AddCredResult: the actual mechanisms with which the credentials may be diff --git a/gssapi/raw/ext_s4u.pyx b/gssapi/raw/ext_s4u.pyx index 177b02e3..bc413d7b 100644 --- a/gssapi/raw/ext_s4u.pyx +++ b/gssapi/raw/ext_s4u.pyx @@ -55,7 +55,7 @@ mechs=None, usage='initiate') impersonate the target name name (~gssapi.raw.names.Name): the name to impersonate lifetime (int): the lifetime for the credentials (or None for - indefinite) + indefinite), in seconds mechs (~gssapi.MechType): the desired mechanisms for which the credentials should work (or None for the default set) usage (str): the usage type for the credentials: may be @@ -64,7 +64,7 @@ mechs=None, usage='initiate') Returns: AcquireCredResult: the resulting credentials, the actual mechanisms with which they may be used, and their actual lifetime (or None for - indefinite or not support) + indefinite or not support), in seconds Raises: ~gssapi.exceptions.GSSError @@ -142,10 +142,10 @@ usage='initiate', init_lifetime=None, accept_lifetime=None) 'initiate', 'accept', or 'both' init_lifetime (int): the lifetime for the credentials to remain valid when using them to initiate security contexts (or None for - indefinite) + indefinite), in seconds accept_lifetime (int): the lifetime for the credentials to remain valid when using them to accept security contexts (or None for - indefinite) + indefinite), in seconds Returns: AddCredResult: the actual mechanisms with which the credentials may be diff --git a/gssapi/raw/named_tuples.py b/gssapi/raw/named_tuples.py index 03501316..3a2596a5 100644 --- a/gssapi/raw/named_tuples.py +++ b/gssapi/raw/named_tuples.py @@ -26,8 +26,8 @@ class InquireCredResult(NamedTuple): class InquireCredByMechResult(NamedTuple): """Information about the credential for a specific mechanism.""" name: Optional["Name"] #: The principal associated with the credential - init_lifetime: Optional[int] #: Time valid for initiation - accept_lifetime: Optional[int] #: Time valid for accepting + init_lifetime: Optional[int] #: Time valid for initiation, in seconds + accept_lifetime: Optional[int] #: Time valid for accepting, in seconds usage: Optional[str] #: How the credential can be used @@ -35,8 +35,8 @@ class AddCredResult(NamedTuple): """Result of adding to a GSSAPI credential.""" creds: Optional["Creds"] #: The credential that was generated mechs: Set["OID"] #: Set of mechs the cred is for - init_lifetime: int #: Time valid for initiation - accept_lifetime: int #: Time valid for accepting + init_lifetime: int #: Time valid for initiation, in seconds + accept_lifetime: int #: Time valid for accepting, in seconds class DisplayNameResult(NamedTuple): @@ -84,7 +84,7 @@ class InquireContextResult(NamedTuple): """Information about the security context.""" initiator_name: Optional["Name"] #: Name of the initiator target_name: Optional["Name"] #: Name of the acceptor - lifetime: Optional[int] #: Time valid for the security context + lifetime: Optional[int] #: Time valid for the security context, in seconds mech: Optional["OID"] #: Mech used to create the security context flags: Optional["RequirementFlag"] #: Services available for the context locally_init: Optional[bool] #: Context was initiated locally diff --git a/gssapi/raw/sec_contexts.pyx b/gssapi/raw/sec_contexts.pyx index 5ed9b3c2..7b7d069a 100644 --- a/gssapi/raw/sec_contexts.pyx +++ b/gssapi/raw/sec_contexts.pyx @@ -142,7 +142,7 @@ flags=None, lifetime=None, channel_bindings=None, input_token=None) out_of_sequence_detection. This may also be an :class:`IntEnumFlagSet` lifetime (int): the request lifetime of the security context (a value - of 0 or None means indefinite) + of 0 or None means indefinite), in seconds channel_bindings (ChannelBindings): The channel bindings (or None for no channel bindings) input_token (bytes): the token to use to update the security context, @@ -152,8 +152,8 @@ flags=None, lifetime=None, channel_bindings=None, input_token=None) InitSecContextResult: the output security context, the actual mech type, the actual flags used, the output token to send to the acceptor, the actual lifetime of the context (or None if not supported or - indefinite), and whether or not more calls are needed to finish the - initiation. + indefinite) in seconds, and whether or not more calls are needed to + finish the initiation. Raises: ~gssapi.exceptions.InvalidTokenError @@ -274,8 +274,8 @@ channel_bindings=None) Returns: AcceptSecContextResult: the resulting security context, the initiator name, the mechanism being used, the output token, the flags in use, - the lifetime of the context (or None for indefinite or not - supported), the delegated credentials (valid only if the + the lifetime (in seconds) of the context (or None for indefinite + or not supported), the delegated credentials (valid only if the delegate_to_peer flag is set), and whether or not further token exchanges are needed to finalize the security context. diff --git a/gssapi/sec_contexts.py b/gssapi/sec_contexts.py index 80787ac4..4ab621fc 100644 --- a/gssapi/sec_contexts.py +++ b/gssapi/sec_contexts.py @@ -373,7 +373,8 @@ def _inquire(self, **kwargs): Args: initiator_name (bool): get the initiator name for this context target_name (bool): get the target name for this context - lifetime (bool): get the remaining lifetime for this context + lifetime (bool): get the remaining lifetime (in seconds) for this + context mech (bool): get the :class:`MechType` used by this context flags (bool): get the flags set on this context locally_init (bool): get whether this context was locally initiated