autofixed documentation (#90)

Author: fametrano

.pre-commit-config.yaml

@@ -45,6 +45,8 @@ repos:
       - id: pyupgrade
         args: [--py37-plus]
         # exclude: *fixtures
+        language: python
+        types: [python]
   - repo: https://github.com/PyCQA/autoflake
     rev: v2.0.0
     hooks:
@@ -57,20 +59,43 @@ repos:
           - --remove-duplicate-keys
           - --remove-unused-variables
           - --remove-rhs-for-unused-variables
+        language: python
+        types: [python]
   - repo: https://github.com/pycqa/isort
     rev: 5.11.4
     hooks:
       - id: isort
         name: isort (black profile, in place fixes)
         args: ["--profile", "black", "--filter-files"]
+        language: python
+        types: [python]
+  - repo: https://github.com/myint/docformatter
+    rev: v1.5.0
+    hooks:
+      - id: docformatter
+        description: "Formats docstrings to follow PEP 257."
+        language: python
+        types: [python]
+        args: ["--in-place"]
   - repo: https://github.com/DanielNoord/pydocstringformatter
     rev: v0.7.3
     hooks:
       - id: pydocstringformatter
+        language: python
+        types: [python]
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.2.3
+    hooks:
+      - id: pydocstyle
+        additional_dependencies: [tomli]
+        language: python
+        types: [python]
   - repo: https://github.com/asottile/yesqa
     rev: v1.4.0
     hooks:
       - id: yesqa
+        language: python
+        types: [python]
   - repo: https://github.com/psf/black
     rev: 22.12.0
     hooks:
@@ -82,17 +107,23 @@ repos:
         # pre-commit's default_language_version, see
         # https://pre-commit.com/#top_level-default_language_version
         # language_version: python3.11
+        language: python
+        types: [python]
   - repo: https://github.com/PyCQA/flake8
     rev: 6.0.0
     hooks:
       - id: flake8
+        language: python
+        types: [python]
   - repo: https://github.com/PyCQA/bandit
     rev: 1.7.4
     hooks:
       - id: bandit
         name: bandit (btclib)
         args: []
         exclude: test_*
+        language: python
+        types: [python]
   - repo: https://github.com/PyCQA/bandit
     rev: 1.7.4
     hooks:
@@ -101,6 +132,8 @@ repos:
         # disable B101 (Test for use of assert) for the tests folder
         args: ["--skip", "B101"]
         exclude: btclib
+        language: python
+        types: [python]
   - repo: https://github.com/pycqa/pylint
     rev: v2.15.9
     hooks:
@@ -109,10 +142,14 @@ repos:
             "--score=false",
             "--disable=E0401", # import-error
           ]
+        language: python
+        types: [python]
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v0.991
     hooks:
       - id: mypy
+        language: python
+        types: [python]
   - repo: https://github.com/mgedmin/check-manifest
     rev: "0.49"
     hooks:

README.md

@@ -5,10 +5,11 @@
 | | |
 | --- | --- |
 | Package | [![python](https://img.shields.io/pypi/pyversions/btclib.svg?logo=python)](https://pypi.python.org/pypi/btclib/) [![calver: yyy.m.d](https://img.shields.io/badge/cal_ver-yyyy.m.d-1674b1.svg?logo=calver)](https://calver.org/) [![pypi](https://img.shields.io/pypi/v/btclib.svg?logo=pypi)](https://pypi.python.org/pypi/btclib/) [![downloads](https://static.pepy.tech/badge/btclib)](https://pepy.tech/project/btclib) [![status](https://img.shields.io/pypi/status/btclib.svg)](https://pypi.python.org/pypi/btclib/) [![license](https://img.shields.io/github/license/btclib-org/btclib.svg)](https://github.com/btclib-org/btclib/blob/master/LICENSE) |
-| Coding standards | [![lint: pydocstringformatter](https://img.shields.io/badge/lint-pydocstringformatter-yellowgreen.svg?logo=pydocstringformatter)](https://github.com/DanielNoord/pydocstringformatter) [![lint: pyupgrade](https://img.shields.io/badge/lint-pyupgrade-yellowgreen.svg?logo=pyupgrade)](https://github.com/asottile/pyupgrade) [![lint: isort](https://img.shields.io/badge/lint-isort-yellowgreen.svg?logo=isort)](https://github.com/PyCQA/isort) [![lint: black](https://img.shields.io/badge/lint-black-yellowgreen.svg?logo=black)](https://github.com/psf/black) [![lint: autoflake](https://img.shields.io/badge/lint-autoflake-yellowgreen.svg?logo=autoflake)](https://github.com/PyCQA/autoflake) [![lint: flake8](https://img.shields.io/badge/lint-flake8-yellowgreen.svg?logo=flake8)](<https://github.com/PyCQA/flake8>) [![lint: yesqa](https://img.shields.io/badge/lint-yesqa-yellowgreen.svg?logo=yesqa)](<https://github.com/asottile/yesqa>) [![lint: pylint](https://img.shields.io/badge/lint-pylint-yellowgreen.svg?logo=pylint)](https://github.com/PyCQA/pylint) [![type check: mypy](https://img.shields.io/badge/type_check-mypy-yellowgreen.svg?logo=mypy)](http://mypy-lang.org/) [![type check: pyright](https://img.shields.io/badge/type_check-pyright-yellowgreen.svg)](https://github.com/microsoft/pyright) [![lint: sourcery](https://img.shields.io/badge/lint-sourcery-yellowgreen.svg?logo=sourcery)](https://sourcery.ai) [![security: bandit](https://img.shields.io/badge/security-bandit-yellowgreen.svg?logo=bandit)](https://github.com/PyCQA/bandit) [![lint: markdownlint-cli2](https://img.shields.io/badge/lint-markdownlint--cli2-yellowgreen.svg?logo=sourcery)](https://github.com/DavidAnson/markdownlint-cli2) |
+| Formatting standards | [![lint: isort](https://img.shields.io/badge/lint-isort-yellowgreen.svg?logo=isort)](https://github.com/PyCQA/isort) [![lint: black](https://img.shields.io/badge/lint-black-yellowgreen.svg?logo=black)](https://github.com/psf/black) [![lint: flake8](https://img.shields.io/badge/lint-flake8-yellowgreen.svg?logo=flake8)](<https://github.com/PyCQA/flake8>) [![lint: yesqa](https://img.shields.io/badge/lint-yesqa-yellowgreen.svg?logo=yesqa)](<https://github.com/asottile/yesqa>) [![lint: markdownlint-cli2](https://img.shields.io/badge/lint-markdownlint--cli2-yellowgreen.svg?logo=sourcery)](https://github.com/DavidAnson/markdownlint-cli2) |
+| Coding standards | [![type check: mypy](https://img.shields.io/badge/type_check-mypy-yellowgreen.svg?logo=mypy)](http://mypy-lang.org/) [![type check: pyright](https://img.shields.io/badge/type_check-pyright-yellowgreen.svg)](https://github.com/microsoft/pyright) [![lint: pylint](https://img.shields.io/badge/lint-pylint-yellowgreen.svg?logo=pylint)](https://github.com/PyCQA/pylint) [![lint: autoflake](https://img.shields.io/badge/lint-autoflake-yellowgreen.svg?logo=autoflake)](https://github.com/PyCQA/autoflake) [![lint: pyupgrade](https://img.shields.io/badge/lint-pyupgrade-yellowgreen.svg?logo=pyupgrade)](https://github.com/asottile/pyupgrade)  [![lint: sourcery](https://img.shields.io/badge/lint-sourcery-yellowgreen.svg?logo=sourcery)](https://sourcery.ai) [![security: bandit](https://img.shields.io/badge/security-bandit-yellowgreen.svg?logo=bandit)](https://github.com/PyCQA/bandit) |
+| Docs | [![lint: docformatter](https://img.shields.io/badge/lint-docformatter-yellowgreen.svg?logo=docformatter)](https://github.com/PyCQA/docformatter) [![lint: pydocstringformatter](https://img.shields.io/badge/lint-pydocstringformatter-yellowgreen.svg?logo=pydocstringformatter)](https://github.com/DanielNoord/pydocstringformatter) [![lint: pydocstyle](https://img.shields.io/badge/lint-pydocstyle-yellowgreen.svg?logo=pydocstyle)](https://github.com/PyCQA/pydocstyle)|
 | CI/CD | [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/btclib-org/btclib/master.svg)](https://results.pre-commit.ci/latest/github/btclib-org/btclib/master) [![lint](https://github.com/btclib-org/btclib/actions/workflows/lint.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/lint.yml) [![test](https://github.com/btclib-org/btclib/actions/workflows/test.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test.yml) [![test-py312](https://github.com/btclib-org/btclib/actions/workflows/test-py312.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test-py312.yml) [![coverage](https://coveralls.io/repos/github/btclib-org/btclib/badge.svg?logo=coveralls)](https://coveralls.io/github/btclib-org/btclib) | [![docs](https://img.shields.io/readthedocs/btclib.svg?logo=readthedocs)](https://btclib.readthedocs.io) |
 | Conversations | [![slack](https://img.shields.io/badge/slack-btclib_dev-white.svg?logo=slack)](https://bbt-training.slack.com/messages/C01CCJ85AES) [![Follow on Twitter](https://img.shields.io/twitter/follow/btclib?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=btclib)|
-|
 
 [Browse GitHub Code Repository](https://github.com/btclib-org/btclib/)
 

btclib/b32.py

@@ -59,7 +59,6 @@
 
 
 def has_segwit_prefix(addr: String) -> bool:
-
     str_addr = addr.strip().lower() if isinstance(addr, str) else addr.decode("ascii")
     return any(str_addr.startswith(f"{net.hrp}1") for net in NETWORKS.values())
 
@@ -97,7 +96,6 @@ def power_of_2_base_conversion(
 
 
 def check_witness(wit_ver: int, wit_prg: Octets) -> bytes:
-
     if not 0 <= wit_ver < 17:
         err_msg = "invalid witness version: "
         err_msg += f"{wit_ver} not in 0..16"
@@ -126,7 +124,6 @@ def address_from_witness(
     wit_ver: int, wit_prg: Octets, network: str = "mainnet"
 ) -> str:
     """Encode a bech32 native SegWit address from the witness."""
-
     hrp = NETWORKS[network].hrp
     return _address_from_witness(wit_ver, wit_prg, hrp)
 
@@ -136,7 +133,6 @@ def witness_from_address(b32addr: String) -> tuple[int, bytes, str]:
 
     The returned data structure is: version, program, network.
     """
-
     if isinstance(b32addr, str):
         b32addr = b32addr.strip()
 

btclib/b58.py

@@ -10,8 +10,8 @@
 
 """Base58 address and WIF functions.
 
-Base58 encoding of public keys and scripts as addresses,
-private keys as WIFs
+Base58 encoding of public keys and scripts as addresses, private keys as
+WIFs
 """
 from __future__ import annotations
 
@@ -31,7 +31,6 @@ def wif_from_prv_key(
     prv_key: PrvKey, network: str | None = None, compressed: bool | None = None
 ) -> str:
     """Return the WIF encoding of a private key."""
-
     q, net, compr = prv_keyinfo_from_prv_key(prv_key)
 
     # the private key might provide network and compressed informations
@@ -58,7 +57,6 @@ def wif_from_prv_key(
 
 def address_from_h160(script_type: str, h160: Octets, network: str = "mainnet") -> str:
     """Return a base58 address from the payload."""
-
     if script_type == "p2sh":
         prefix = NETWORKS[network].p2sh
     elif script_type == "p2pkh":
@@ -72,7 +70,6 @@ def address_from_h160(script_type: str, h160: Octets, network: str = "mainnet")
 
 def h160_from_address(b58addr: String) -> tuple[str, bytes, str]:
     """Return the payload from a base58 address."""
-
     if isinstance(b58addr, str):
         b58addr = b58addr.strip()
     payload = b58decode(b58addr, 21)
@@ -110,7 +107,6 @@ def p2sh(script_pub_key: Octets, network: str = "mainnet") -> str:
 
 def _address_from_v0_witness(wit_prg: Octets, network: str = "mainnet") -> str:
     """Return the legacy base58 p2sh-wrapped SegWit v0 address."""
-
     # check witness program
     wit_prg = b32.check_witness(0, wit_prg)
     redeem_script = serialize(["OP_0", wit_prg])
@@ -121,13 +117,13 @@ def _address_from_v0_witness(wit_prg: Octets, network: str = "mainnet") -> str:
 
 
 def p2wpkh_p2sh(key: Key, network: str | None = None) -> str:
-    """Return the p2wpkh-p2sh base58 address corresponding to a public key."""
+    """Return the base58 p2sh-wrapped address of a p2wpkh."""
     pub_key, network = pub_keyinfo_from_key(key, network, compressed=True)
     witness_program = hash160(pub_key)
     return _address_from_v0_witness(witness_program, network)
 
 
 def p2wsh_p2sh(redeem_script: Octets, network: str = "mainnet") -> str:
-    """Return the p2wsh-p2sh base58 address corresponding to a reedem script."""
+    """Return the base58 p2sh-wrapped address of a p2wsh."""
     witness_program = sha256(redeem_script)
     return _address_from_v0_witness(witness_program, network)

btclib/base58.py

@@ -47,7 +47,6 @@
 
 
 def _b58encode_from_int(i: int) -> bytes:
-
     result = b""
     while i or not result:
         i, idx = divmod(i, __BASE)
@@ -57,7 +56,6 @@ def _b58encode_from_int(i: int) -> bytes:
 
 
 def _b58encode(v: bytes) -> bytes:
-
     # preserve leading-0s
     # leading-0s become base58 leading-1s
     n_pad = len(v)
@@ -75,14 +73,12 @@ def _b58encode(v: bytes) -> bytes:
 
 def b58encode(v: Octets, in_size: int | None = None) -> bytes:
     """Encode a bytes-like object using Base58Check."""
-
     v = bytes_from_octets(v, in_size)
     h256 = hash256(v)
     return _b58encode(v + h256[:4])
 
 
 def _b58decode_to_int(v: bytes) -> int:
-
     i = 0
     for char in v:
         i *= __BASE
@@ -91,7 +87,6 @@ def _b58decode_to_int(v: bytes) -> int:
 
 
 def _b58decode(v: bytes) -> bytes:
-
     if any(x not in _ALPHABET for x in v):
         msg = "Base58 string contains invalid characters"
         raise BTClibValueError(msg)
@@ -117,7 +112,6 @@ def b58decode(v: String, out_size: int | None = None) -> bytes:
 
     Optionally, it also ensures required output size.
     """
-
     if isinstance(v, str):
         # do not trim spaces
         v = v.encode("ascii")

btclib/bech32.py

@@ -59,7 +59,7 @@
 
 
 def _polymod(values: Iterable[int]) -> int:
-    """Internal function that computes the bech32 checksum."""
+    """Return the bech32 checksum."""
     generator = [0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3]
     chk = 1
     for value in values:
@@ -96,7 +96,6 @@ def _verify_checksum(hrp: str, data: list[int], m: int) -> bool:
 
 def _decode(bech: String) -> tuple[str, list[int], list[int]]:
     """Determine a bech32 string HRP, data and checksum."""
-
     if isinstance(bech, bytes):
         bech = bech.decode("ascii")
 

btclib/bip32/bip32.py

@@ -95,7 +95,6 @@ def __init__(
         key: Octets,
         check_validity: bool = True,
     ) -> None:
-
         self.version = bytes_from_octets(version)
         self.depth = depth
         self.parent_fingerprint = bytes_from_octets(parent_fingerprint)
@@ -107,7 +106,6 @@ def __init__(
             self.assert_valid()
 
     def assert_valid(self) -> None:
-
         for key, size in _KEY_SIZE:
             value = bytes(getattr(self, key))
             setattr(self, key, value)
@@ -155,7 +153,6 @@ def assert_valid(self) -> None:
             )
 
     def serialize(self, check_validity: bool = True) -> bytes:
-
         if check_validity:
             self.assert_valid()
 
@@ -179,7 +176,6 @@ def parse(
         cls: type[BIP32KeyData], xkey_bin: BinaryData, check_validity: bool = True
     ) -> BIP32KeyData:
         """Return a BIP32KeyData by parsing 73 bytes from binary data."""
-
         stream = bytesio_from_binarydata(xkey_bin)
         xkey_bin = stream.read(_REQUIRED_LENGHT)
 
@@ -202,7 +198,6 @@ def parse(
     def b58decode(
         cls: type[BIP32KeyData], address: String, check_validity: bool = True
     ) -> BIP32KeyData:
-
         if isinstance(address, str):
             address = address.strip()
 
@@ -214,7 +209,6 @@ def _rootxprv_from_seed(
     seed: Octets, version: Octets = NETWORKS["mainnet"].bip32_prv
 ) -> BIP32KeyData:
     """Return BIP32 root master extended private key from seed."""
-
     seed = bytes_from_octets(seed)
     bitlenght = len(seed) * 8
     if bitlenght < 128:
@@ -254,9 +248,9 @@ def _xpub_from_xprv(xprv: BIP32Key) -> BIP32KeyData:
     """Neutered Derivation (ND).
 
     Derivation of the extended public key corresponding to an extended
-    private key (“neutered” as it removes the ability to sign transactions).
+    private key (“neutered” as it removes the ability to sign
+    transactions).
     """
-
     if isinstance(xprv, BIP32KeyData):
         xkey = copy.copy(xprv)
     else:
@@ -280,7 +274,8 @@ def xpub_from_xprv(xprv: BIP32Key) -> str:
     """Neutered Derivation (ND).
 
     Derivation of the extended public key corresponding to an extended
-    private key (“neutered” as it removes the ability to sign transactions).
+    private key (“neutered” as it removes the ability to sign
+    transactions).
     """
     xkey = _xpub_from_xprv(xprv)
     return xkey.b58encode()
@@ -290,6 +285,7 @@ def xpub_from_xprv(xprv: BIP32Key) -> str:
 class _ExtendedBIP32KeyData(BIP32KeyData):
     # extensions used to cache intermediate results
     # in multi-level derivation: do not rely on them elsewhere
+
     prv_key_int: int  # non-zero for private key only
     pub_key_point: Point  # non-Infinity for public key only
 
@@ -320,7 +316,6 @@ def __init__(
 
 
 def __child_key_derivation(xkey: _ExtendedBIP32KeyData, index: int) -> None:
-
     xkey.depth += 1
     xkey.index = index
     if xkey.is_private:
@@ -371,7 +366,6 @@ def __public_key_derivation(xkey: _ExtendedBIP32KeyData, index: int) -> None:
 def _derive(
     xkey: BIP32Key, der_path: BIP32DerPath, forced_version: Octets | None = None
 ) -> BIP32KeyData:
-
     if not isinstance(xkey, BIP32KeyData):
         xkey = BIP32KeyData.b58decode(xkey)
 
@@ -434,7 +428,6 @@ def _derive_from_account(
     branches_0_1_only: bool = True,
     max_index: int = 0xFFFF,
 ) -> BIP32KeyData:
-
     if not isinstance(mxkey, BIP32KeyData):
         mxkey = BIP32KeyData.b58decode(mxkey)
 
@@ -465,18 +458,16 @@ def derive_from_account(
 ) -> str:
     """Derive a key with public derivation at the given branch and index.
 
-    It also ensures that the master key is hardened,
-    that the branch is a standard receive or change,
-    and that the index is not arbitrarily high.
+    It also ensures that the master key is hardened, that the branch is
+    a standard receive or change, and that the index is not arbitrarily
+    high.
     """
-
     return _derive_from_account(
         mxkey, branch, address_index, branches_0_1_only, max_index
     ).b58encode()
 
 
 def crack_prv_key(parent_xpub: BIP32Key, child_xprv: BIP32Key) -> str:
-
     if isinstance(parent_xpub, BIP32KeyData):
         p = copy.copy(parent_xpub)
     else: