Fix Ruff lint errors related to docstrings

generalmimon · generalmimon · commit a071175c18d4 · 2025-12-28T21:41:57.000+01:00
See the relevant rules in the Ruff documentation: * [D205](https://docs.astral.sh/ruff/rules/missing-blank-line-after-summary/) * [D401](https://docs.astral.sh/ruff/rules/non-imperative-mood/) This commit fixes the following lint errors: ```console $ ruff --version ruff 0.14.10 $ ruff check --statistics --ignore E501 $(git ls-files '*.py') 16 D205 missing-blank-line-after-summary 3 D401 non-imperative-mood Found 19 errors. $ ruff check --ignore E501 $(git ls-files '*.py') D205 1 blank line required between summary line and description --> kaitaistruct.py:341:9 | 340 | def read_bits_int(self, n): 341 | / """Deprecated and no longer used as of KSC 0.9. It is only available 342 | | for backwards compatibility and will be removed in the future. 343 | | 344 | | KSC 0.9 and later uses `read_bits_int_be()` instead. 345 | | """ | |___________^ 346 | warnings.warn( 347 | "read_bits_int() is deprecated since 0.9, use read_bits_int_be() instead", | help: Insert single blank line D401 First line of docstring should be in imperative mood: "Deprecated and no longer used as of KSC 0.9. It is only available" --> kaitaistruct.py:341:9 | 340 | def read_bits_int(self, n): 341 | / """Deprecated and no longer used as of KSC 0.9. It is only available 342 | | for backwards compatibility and will be removed in the future. 343 | | 344 | | KSC 0.9 and later uses `read_bits_int_be()` instead. 345 | | """ | |___________^ 346 | warnings.warn( 347 | "read_bits_int() is deprecated since 0.9, use read_bits_int_be() instead", | D205 1 blank line required between summary line and description --> kaitaistruct.py:470:9 | 469 | def ensure_fixed_contents(self, expected): 470 | / """Deprecated and no longer used as of KSC 0.9. It is only available 471 | | for backwards compatibility and will be removed in the future. 472 | | 473 | | KSC 0.9 and later explicitly raises `ValidationNotEqualError` from an 474 | | `if` statement instead. 475 | | """ | |___________^ 476 | warnings.warn( 477 | "ensure_fixed_contents() is deprecated since 0.9, explicitly raise " | help: Insert single blank line D401 First line of docstring should be in imperative mood: "Deprecated and no longer used as of KSC 0.9. It is only available" --> kaitaistruct.py:470:9 | 469 | def ensure_fixed_contents(self, expected): 470 | / """Deprecated and no longer used as of KSC 0.9. It is only available 471 | | for backwards compatibility and will be removed in the future. 472 | | 473 | | KSC 0.9 and later explicitly raises `ValidationNotEqualError` from an 474 | | `if` statement instead. 475 | | """ | |___________^ 476 | warnings.warn( 477 | "ensure_fixed_contents() is deprecated since 0.9, explicitly raise " | D205 1 blank line required between summary line and description --> kaitaistruct.py:829:9 | 827 | @staticmethod 828 | def resolve_enum(enum_obj, value): 829 | / """Resolves value using enum: if the value is not found in the map, 830 | | we'll just use literal value per se. Works around problem with Python 831 | | enums throwing an exception when encountering unknown value. 832 | | """ | |___________^ 833 | try: 834 | return enum_obj(value) | help: Insert single blank line D401 First line of docstring should be in imperative mood: "Resolves value using enum: if the value is not found in the map," --> kaitaistruct.py:829:9 | 827 | @staticmethod 828 | def resolve_enum(enum_obj, value): 829 | / """Resolves value using enum: if the value is not found in the map, 830 | | we'll just use literal value per se. Works around problem with Python 831 | | enums throwing an exception when encountering unknown value. 832 | | """ | |___________^ 833 | try: 834 | return enum_obj(value) | D205 1 blank line required between summary line and description --> kaitaistruct.py:874:5 | 873 | class KaitaiStructError(Exception): 874 | / """Common ancestor for all errors originating from correct Kaitai Struct 875 | | usage (i.e. errors that indicate a problem with user input, not errors 876 | | indicating incorrect usage that are not meant to be caught but fixed in the 877 | | application code). Use this exception type in the `except` clause if you 878 | | want to handle all parse errors and serialization errors. 879 | | 880 | | If available, the `src_path` attribute will contain the KSY source path 881 | | pointing to the element where the error occurred. If it is not available, 882 | | `src_path` will be `None`. 883 | | """ | |_______^ 884 | 885 | def __init__(self, msg, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:891:5 | 890 | class InvalidArgumentError(KaitaiStructError, ValueError): 891 | / """Indicates that an invalid argument value was received (like `ValueError`), 892 | | but used in places where this might indicate invalid user input and 893 | | therefore represents a parse error or serialization error. 894 | | """ | |_______^ 895 | 896 | def __init__(self, msg): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:901:5 | 900 | class EndOfStreamError(KaitaiStructError, EOFError): 901 | / """Read or write beyond end of stream. Provides the `bytes_needed` (number 902 | | of bytes requested to read or write) and `bytes_available` (number of bytes 903 | | remaining in the stream) attributes. 904 | | """ | |_______^ 905 | 906 | def __init__(self, msg, bytes_needed, bytes_available): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:913:5 | 912 | class NoTerminatorFoundError(EndOfStreamError): 913 | / """Special type of `EndOfStreamError` that occurs when end of stream is 914 | | reached before the required terminator is found. If you want to tolerate a 915 | | missing terminator, you can specify `eos-error: false` in the KSY 916 | | specification, in which case the end of stream will be considered a valid 917 | | end of field and this error will no longer be raised. 918 | | 919 | | The `term` attribute contains a `bytes` object with the searched terminator. 920 | | """ | |_______^ 921 | 922 | def __init__(self, term, bytes_available): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:932:5 | 931 | class UndecidedEndiannessError(KaitaiStructError): 932 | / """Error that occurs when default endianness should be decided with 933 | | switch, but nothing matches (although using endianness expression 934 | | implies that there should be some positive result). 935 | | """ | |_______^ 936 | 937 | def __init__(self, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:942:5 | 941 | class ValidationFailedError(KaitaiStructError): 942 | / """Common ancestor for all validation failures. Stores pointer to 943 | | KaitaiStream IO object which was involved in an error. 944 | | """ | |_______^ 945 | 946 | def __init__(self, msg, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:957:5 | 956 | class ValidationNotEqualError(ValidationFailedError): 957 | / """Signals validation failure: we required "actual" value to be equal to 958 | | "expected", but it turned out that it's not. 959 | | """ | |_______^ 960 | 961 | def __init__(self, expected, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:970:5 | 969 | class ValidationLessThanError(ValidationFailedError): 970 | / """Signals validation failure: we required "actual" value to be 971 | | greater than or equal to "min", but it turned out that it's not. 972 | | """ | |_______^ 973 | 974 | def __init__(self, min_bound, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:983:5 | 982 | class ValidationGreaterThanError(ValidationFailedError): 983 | / """Signals validation failure: we required "actual" value to be 984 | | less than or equal to "max", but it turned out that it's not. 985 | | """ | |_______^ 986 | 987 | def __init__(self, max_bound, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:996:5 | 995 | class ValidationNotAnyOfError(ValidationFailedError): 996 | / """Signals validation failure: we required "actual" value to be 997 | | from the list, but it turned out that it's not. 998 | | """ | |_______^ 999 | 1000 | def __init__(self, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:1006:5 | 1005 | class ValidationNotInEnumError(ValidationFailedError): 1006 | / """Signals validation failure: we required "actual" value to be in 1007 | | the enum, but it turned out that it's not. 1008 | | """ | |_______^ 1009 | 1010 | def __init__(self, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:1016:5 | 1015 | class ValidationExprError(ValidationFailedError): 1016 | / """Signals validation failure: we required "actual" value to match 1017 | | the expression, but it turned out that it doesn't. 1018 | | """ | |_______^ 1019 | 1020 | def __init__(self, actual, io, src_path): | help: Insert single blank line D205 1 blank line required between summary line and description --> kaitaistruct.py:1036:5 | 1035 | class ConsistencyNotCheckedError(Exception): 1036 | / """Thrown when attempting to write an object whose consistency hasn't been 1037 | | checked since the last modification. 1038 | | """ | |_______^ 1039 | 1040 | def __init__(self): | help: Insert single blank line Found 19 errors. ```
diff --git a/kaitaistruct.py b/kaitaistruct.py
@@ -310,6 +310,7 @@ def align_to_byte(self):
         self.bits = 0
 
     def read_bits_int_be(self, n):
+        """Read an unsigned `n`-bit integer in big-endian parsing direction."""
         self.bits_write_mode = False
 
         res = 0
@@ -338,7 +339,9 @@ def read_bits_int_be(self, n):
         return res
 
     def read_bits_int(self, n):
-        """Deprecated and no longer used as of KSC 0.9. It is only available
+        """Read an unsigned `n`-bit integer in big-endian parsing direction.
+
+        Deprecated and no longer used as of KSC 0.9. It is only available
         for backwards compatibility and will be removed in the future.
 
         KSC 0.9 and later uses `read_bits_int_be()` instead.
@@ -351,6 +354,7 @@ def read_bits_int(self, n):
         return self.read_bits_int_be(n)
 
     def read_bits_int_le(self, n):
+        """Read an unsigned `n`-bit integer in little-endian parsing direction."""
         self.bits_write_mode = False
 
         res = 0
@@ -467,7 +471,9 @@ def read_bytes_term_multi(self, term, include_term, consume_term, eos_error):
             r += c
 
     def ensure_fixed_contents(self, expected):
-        """Deprecated and no longer used as of KSC 0.9. It is only available
+        """Check that the `expected` bytes follow in the stream.
+
+        Deprecated and no longer used as of KSC 0.9. It is only available
         for backwards compatibility and will be removed in the future.
 
         KSC 0.9 and later explicitly raises `ValidationNotEqualError` from an
@@ -826,9 +832,16 @@ def byte_array_index_of(data, b):
 
     @staticmethod
     def resolve_enum(enum_obj, value):
-        """Resolves value using enum: if the value is not found in the map,
-        we'll just use literal value per se. Works around problem with Python
-        enums throwing an exception when encountering unknown value.
+        """Convert an integer to the given enum if possible, otherwise return it back.
+
+        Enums in Python raise a `ValueError` exception when they encounter an unknown
+        value. This method works around this issue so that attempting to convert an
+        unknown integer value to an enum does not stop parsing by default.
+
+        If it is desired to stop parsing on unknown enum values, `valid/in-enum: true`
+        can be used in the .ksy specification on a specific `seq` or `instances` enum
+        field. This adds validation that the field contains one of the known (defined)
+        enum values, otherwise a `ValidationNotInEnumError` exception is raised.
         """
         try:
             return enum_obj(value)
@@ -871,11 +884,14 @@ def _write_back(self, parent):
 
 
 class KaitaiStructError(Exception):
-    """Common ancestor for all errors originating from correct Kaitai Struct
-    usage (i.e. errors that indicate a problem with user input, not errors
-    indicating incorrect usage that are not meant to be caught but fixed in the
-    application code). Use this exception type in the `except` clause if you
-    want to handle all parse errors and serialization errors.
+    """Common ancestor for all errors originating from correct Kaitai Struct usage.
+
+    Use this exception class in the `except` clause if you want to handle all
+    parse errors and serialization errors.
+
+    "Correct usage" refers to errors that indicate a problem with user input,
+    not errors indicating incorrect usage, which are not meant to be caught but
+    fixed in the application code.
 
     If available, the `src_path` attribute will contain the KSY source path
     pointing to the element where the error occurred. If it is not available,
@@ -888,19 +904,23 @@ def __init__(self, msg, src_path):
 
 
 class InvalidArgumentError(KaitaiStructError, ValueError):
-    """Indicates that an invalid argument value was received (like `ValueError`),
-    but used in places where this might indicate invalid user input and
-    therefore represents a parse error or serialization error.
+    """Raised when an invalid argument is encountered during parsing or serialization.
+
+    This is a subclass of `ValueError`, which is the standard built-in exception
+    class for invalid arguments in Python. It is also a subclass of
+    `KaitaiStructError`, as it indicates invalid user input and therefore
+    represents a parsing or serialization error.
     """
 
     def __init__(self, msg):
         super().__init__(msg, None)
 
 
 class EndOfStreamError(KaitaiStructError, EOFError):
-    """Read or write beyond end of stream. Provides the `bytes_needed` (number
-    of bytes requested to read or write) and `bytes_available` (number of bytes
-    remaining in the stream) attributes.
+    """Raised when attempting to read or write beyond end of stream.
+
+    Provides the `bytes_needed` (number of bytes requested to read or write) and
+    `bytes_available` (number of bytes remaining in the stream) attributes.
     """
 
     def __init__(self, msg, bytes_needed, bytes_available):
@@ -910,11 +930,17 @@ def __init__(self, msg, bytes_needed, bytes_available):
 
 
 class NoTerminatorFoundError(EndOfStreamError):
-    """Special type of `EndOfStreamError` that occurs when end of stream is
-    reached before the required terminator is found. If you want to tolerate a
-    missing terminator, you can specify `eos-error: false` in the KSY
-    specification, in which case the end of stream will be considered a valid
-    end of field and this error will no longer be raised.
+    """Raised when end of stream is reached before the required terminator is found.
+
+    This is a subclass of `EndOfStreamError` because it is a special type of
+    reaching the end of the stream prematurely - see
+    https://github.com/kaitai-io/kaitai_struct_python_runtime/issues/41 for an
+    explanation.
+
+    If you want to tolerate a missing terminator, you can specify `eos-error: false`
+    in the .ksy specification. Reaching the end of the stream will then be
+    considered a valid end of the field, and this error will no longer be
+    raised.
 
     The `term` attribute contains a `bytes` object with the searched terminator.
     """
@@ -929,18 +955,24 @@ def __init__(self, term, bytes_available):
 
 
 class UndecidedEndiannessError(KaitaiStructError):
-    """Error that occurs when default endianness should be decided with
-    switch, but nothing matches (although using endianness expression
-    implies that there should be some positive result).
+    """Raised when the calculated default endianness cannot be determined.
+
+    The default endianness should have been decided with a switch, but no case
+    matches (although the endianness switch suggests that the result should be
+    positive).
     """
 
     def __init__(self, src_path):
         super().__init__("unable to decide on endianness for a type", src_path)
 
 
 class ValidationFailedError(KaitaiStructError):
-    """Common ancestor for all validation failures. Stores pointer to
-    KaitaiStream IO object which was involved in an error.
+    """Common ancestor for all validation failures.
+
+    The `io` attribute stores the `KaitaiStream` object representing the I/O
+    stream associated with the error. Validation exceptions raised from
+    `_check()` methods do not have an I/O stream available, so their `io` will
+    be `None`.
     """
 
     def __init__(self, msg, io, src_path):
@@ -954,8 +986,16 @@ def __init__(self, msg, io, src_path):
 
 
 class ValidationNotEqualError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to be equal to
-    "expected", but it turned out that it's not.
+    """Raised when validation specified using the `contents` or `valid/eq` keys fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    been equal to `expected`, but it was not.
+
+    The `expected` attribute contains the expected value specified in the
+    `contents` or `valid/eq` key in .ksy specifications. Note that the syntax
+    `valid/eq: <expression>` has a shorthand form `valid: <expression>`.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, expected, actual, io, src_path):
@@ -967,8 +1007,15 @@ def __init__(self, expected, actual, io, src_path):
 
 
 class ValidationLessThanError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to be
-    greater than or equal to "min", but it turned out that it's not.
+    """Raised when validation specified using the `valid/min` key fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    been greater than or equal to `min`, but it was not.
+
+    The `min` attribute contains the minimum value specified in the `valid/min`
+    key in .ksy specifications.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, min_bound, actual, io, src_path):
@@ -980,8 +1027,15 @@ def __init__(self, min_bound, actual, io, src_path):
 
 
 class ValidationGreaterThanError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to be
-    less than or equal to "max", but it turned out that it's not.
+    """Raised when validation specified using the `valid/max` key fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    been less than or equal to `max`, but it was not.
+
+    The `max` attribute contains the maximum value specified in the `valid/max`
+    key in .ksy specifications.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, max_bound, actual, io, src_path):
@@ -993,8 +1047,12 @@ def __init__(self, max_bound, actual, io, src_path):
 
 
 class ValidationNotAnyOfError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to be
-    from the list, but it turned out that it's not.
+    """Raised when validation specified using the `valid/any-of` key fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    been any of the values listed in the `valid/any-of` key, but it was not.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, actual, io, src_path):
@@ -1003,8 +1061,12 @@ def __init__(self, actual, io, src_path):
 
 
 class ValidationNotInEnumError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to be in
-    the enum, but it turned out that it's not.
+    """Raised when validation specified using the `valid/in-enum` key fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    been a known value defined in the enum, but it was not.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, actual, io, src_path):
@@ -1013,8 +1075,12 @@ def __init__(self, actual, io, src_path):
 
 
 class ValidationExprError(ValidationFailedError):
-    """Signals validation failure: we required "actual" value to match
-    the expression, but it turned out that it doesn't.
+    """Raised when validation specified using the `valid/expr` key fails.
+
+    This exception is the result of a validation failure: `actual` should have
+    satisfied the validation expression in the `valid/expr` key, but it did not.
+
+    The `actual` attribute contains the actual value parsed from the stream.
     """
 
     def __init__(self, actual, io, src_path):
@@ -1033,9 +1099,7 @@ def __init__(self, attr_id, expected, actual):
 
 
 class ConsistencyNotCheckedError(Exception):
-    """Thrown when attempting to write an object whose consistency hasn't been
-    checked since the last modification.
-    """
+    """Raised when attempting to write an object with unchecked consistency."""
 
     def __init__(self):
         super().__init__(
