From 49b1c3e2cfb9b0224712e6891a12950f725c3b13 Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Tue, 7 Apr 2020 12:24:52 +0200 Subject: Improve README.md and docstrings for Sphinx --- otp2289/__main__.py | 12 ++++++------ otp2289/generator.py | 18 ++++++------------ otp2289/server.py | 27 +++++++++++++++------------ 3 files changed, 27 insertions(+), 30 deletions(-) (limited to 'otp2289') diff --git a/otp2289/__main__.py b/otp2289/__main__.py index 2962d29..7c71040 100644 --- a/otp2289/__main__.py +++ b/otp2289/__main__.py @@ -55,9 +55,9 @@ def generate_otp_response(args): :param args: The arguments assigned from argparse :type args: argparse.Namespace - :raises OTPChallengeException: In case of invalid challenge + :raises otp2289.OTPChallengeException: If the challenge is invalid - :raises OTPGeneratorException: In case of wrong generator parameters + :raises otp2289.OTPGeneratorException: If generator parameters are wrong :return: The response string :rtype: str @@ -89,9 +89,9 @@ def generate_otp_range(args): :param args: The arguments assigned from argparse :type args: argparse.Namespace - :raises OTPChallengeException: In case of invalid challenge + :raises otp2289.OTPChallengeException: If the challenge is invalid - :raises OTPGeneratorException: In case of wrong generator parameters + :raises otp2289.OTPGeneratorException: If generator parameters are wrong :return: The responses string :rtype: str @@ -137,9 +137,9 @@ def initiate_new_sequence(args): :param args: The arguments assigned from argparse :type args: argparse.Namespace - :raises OTPChallengeException: In case of invalid challenge + :raises otp2289.OTPChallengeException: If the challenge is invalid - :raises OTPGeneratorException: In case of wrong generator parameters + :raises otp2289.OTPGeneratorException: If generator parameters are wrong :return: The response string :rtype: str diff --git a/otp2289/generator.py b/otp2289/generator.py index ac3bb3c..4623dc0 100644 --- a/otp2289/generator.py +++ b/otp2289/generator.py @@ -310,7 +310,6 @@ class OTPGenerator: """ Constructs an OTPGenerator object with a given password and seed. - Keyword Arguments: :param password: The password string :type password: bytes @@ -320,7 +319,7 @@ class OTPGenerator: :param hash_algo: The hash algo, defaults to OTP_ALGO_MD5 :type hash_algo: int or str - :raises OTPGeneratorException: In case the input does not validate + :raises otp2289.OTPGeneratorException: If the input does not validate """ # enforce the rfc2289 constraints self._seed = seed @@ -389,7 +388,7 @@ class OTPGenerator: :param challenge: The challenge string described in RFC-2289 :type challenge: str - :raises OTPChallengeException: When the challenge string is invalid + :raises otp2289.OTPChallengeException: If the challenge is invalid :return: (seed, hash_algo, step) tuple. :rtype: tuple @@ -485,7 +484,7 @@ class OTPGenerator: :param tokens_str: String representing 6 words tokens :type tokens_str: str - :raises OTPGeneratorException: When the tokens_str is invalid + :raises otp2289.OTPGeneratorException: When the tokens_str is invalid :return: 6 words tokens :rtype: bytes @@ -529,7 +528,7 @@ class OTPGenerator: :param hash_algo: The hash algo, defaults to OTP_ALGO_MD5 :type hash_algo: int or str - :raises OTPGeneratorException: In case hash_algo does not validate + :raises otp2289.OTPGeneratorException: If hash_algo does not validate :return: The validated hash_algo in str-form :rtype: str @@ -556,7 +555,7 @@ class OTPGenerator: :param seed: The seed received from the challenge, defaults to '' :type seed: str - :raises OTPGeneratorException: In case seed does not validate + :raises otp2289.OTPGeneratorException: If seed does not validate :return: The validated (and very same) seed :rtype: str @@ -580,7 +579,7 @@ class OTPGenerator: :param seed: The step received from the challenge :type seed: int - :raises OTPGeneratorException: In case step does not validate + :raises otp2289.OTPGeneratorException: If step does not validate :return: The validated (and very same) step :rtype: int @@ -595,7 +594,6 @@ class OTPGenerator: """ Generates the OTP hexdigest for the given step. - Keyword Arguments: :param step: The step to generate OTP for :type step: int @@ -614,7 +612,6 @@ class OTPGenerator: extract these parameters. The syntax of the challenge is: otp- - Keyword Arguments: :param challenge: The challenge string :type challenge: str @@ -630,7 +627,6 @@ class OTPGenerator: """ Generates the OTP six words token for the given step. - Keyword Arguments: :param step: The step to generate OTP for :type step: int @@ -649,7 +645,6 @@ class OTPGenerator: extract these parameters. The syntax of the challenge is: otp- - Keyword Arguments: :param challenge: The challenge string :type challenge: str @@ -709,7 +704,6 @@ class OTPGenerator: """ Generates the OTP bytes for the given step. - Keyword Arguments: :param step: The step to generate OTP for :type step: int diff --git a/otp2289/server.py b/otp2289/server.py index fca3f06..119fbff 100644 --- a/otp2289/server.py +++ b/otp2289/server.py @@ -71,7 +71,7 @@ class OTPState: :param hash_algo: The hash algo, defaults to OTP_ALGO_MD5 :type hash_algo: int or str - :raises OTPStateException: In case the input does not validate + :raises otp2289.OTPStateException: If the input does not validate """ # enforce the rfc2289 constraints try: @@ -126,7 +126,7 @@ class OTPState: :type dict_obj: dict :return: A new OTPState object - :rtype: OTPStore + :rtype: otp2289.OTPStore """ return cls(**dict_obj) @@ -144,8 +144,9 @@ class OTPState: :param response: The response to this state (its challenge) :type response: str - :raises OTPInvalidResponse: If the response is corrupt / illegal, - but not if it simply does not validate + :raises otp2289.OTPInvalidResponse: If the response is corrupt/illegal, + but not if it simply does not + validate :return: The bytes representation of response (if any) :rtype: bytes @@ -168,7 +169,7 @@ class OTPState: :param ot_hex: The one-time hex to validate :type ot_hex: str - :raises OTPStateException: In case hex does not validate + :raises otp2289.OTPStateException: If hex does not validate :return: The validated hex (without leading 0x) converted to bytes :rtype: bytes @@ -194,7 +195,7 @@ class OTPState: where step -= 1 and ot_hex = self._new_digest_hex :return: The next OTPState if validated, None otherwise - :rtype: OTPState or None + :rtype: otp2289.OTPState or None """ if self._new_digest_hex is None: return None @@ -213,7 +214,8 @@ class OTPState: :param store_valid_response: Should a valid response be stored :type store_valid_response: bool - :raises OTPInvalidResponse: If the response does not match this state + :raises otp2289.OTPInvalidResponse: If the response does not match + this state :return: Returns True if response validates, False otherwise :rtype: bool @@ -328,9 +330,9 @@ class OTPStore: :type key: str :param state: The OTPState object - :type state: OTPState + :type state: otp2289.OTPState - :raises OTPStoreException: On failure + :raises otp2289.OTPStoreException: On failure """ if not isinstance(key, str): raise OTPStoreException('key must be a str') @@ -356,10 +358,10 @@ class OTPStore: :raises KeyError: If key does not exist - :raises OTPStoreException: On failure + :raises otp2289.OTPStoreException: On failure :return: The state corresponding to the key - :rtype: OTPState + :rtype: otp2289.OTPState """ if not isinstance(key, str): raise OTPStoreException('key must be a str') @@ -387,7 +389,8 @@ class OTPStore: :raises KeyError: If the key is not present - :raises OTPInvalidResponse: If the response does not match this state + :raises otp2289.OTPInvalidResponse: If the response does not match + this state :return: Returns True if response validates, False otherwise :rtype: bool -- cgit v1.3