Merge #9577: Fix docstrings in qa tests

3f95a80 Fix docstrings in qa tests (John Newbery)

15 files changed, 96 insertions, 133 deletions

diff --git a/qa/rpc-tests/test_framework/address.py b/qa/rpc-tests/test_framework/address.py
index 50b999be61..96bebe1ea1 100644
--- a/qa/rpc-tests/test_framework/address.py
+++ b/qa/rpc-tests/test_framework/address.py
@@ -2,12 +2,7 @@
 # Copyright (c) 2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-
-#
-# address.py
-#
-# This file encodes and decodes BASE58 P2PKH and P2SH addresses
-#
+"""Encode and decode BASE58, P2PKH and P2SH addresses."""
 
 from .script import hash256, hash160, sha256, CScript, OP_0
 from .util import bytes_to_hex_str, hex_str_to_bytes
diff --git a/qa/rpc-tests/test_framework/authproxy.py b/qa/rpc-tests/test_framework/authproxy.py
index 09ed611299..9ab3094b06 100644
--- a/qa/rpc-tests/test_framework/authproxy.py
+++ b/qa/rpc-tests/test_framework/authproxy.py
@@ -1,37 +1,36 @@
-
-"""
-  Copyright (c) 2011 Jeff Garzik
-
-  AuthServiceProxy has the following improvements over python-jsonrpc's
-  ServiceProxy class:
-
-  - HTTP connections persist for the life of the AuthServiceProxy object
-    (if server supports HTTP/1.1)
-  - sends protocol 'version', per JSON-RPC 1.1
-  - sends proper, incrementing 'id'
-  - sends Basic HTTP authentication headers
-  - parses all JSON numbers that look like floats as Decimal
-  - uses standard Python json lib
-
-  Previous copyright, from python-jsonrpc/jsonrpc/proxy.py:
-
-  Copyright (c) 2007 Jan-Klaas Kollhof
-
-  This file is part of jsonrpc.
-
-  jsonrpc is free software; you can redistribute it and/or modify
-  it under the terms of the GNU Lesser General Public License as published by
-  the Free Software Foundation; either version 2.1 of the License, or
-  (at your option) any later version.
-
-  This software is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU Lesser General Public License for more details.
-
-  You should have received a copy of the GNU Lesser General Public License
-  along with this software; if not, write to the Free Software
-  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# Copyright (c) 2011 Jeff Garzik
+#
+# Previous copyright, from python-jsonrpc/jsonrpc/proxy.py:
+#
+# Copyright (c) 2007 Jan-Klaas Kollhof
+#
+# This file is part of jsonrpc.
+#
+# jsonrpc is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2.1 of the License, or
+# (at your option) any later version.
+#
+# This software is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this software; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+"""HTTP proxy for opening RPC connection to bitcoind.
+
+AuthServiceProxy has the following improvements over python-jsonrpc's
+ServiceProxy class:
+
+- HTTP connections persist for the life of the AuthServiceProxy object
+  (if server supports HTTP/1.1)
+- sends protocol 'version', per JSON-RPC 1.1
+- sends proper, incrementing 'id'
+- sends Basic HTTP authentication headers
+- parses all JSON numbers that look like floats as Decimal
+- uses standard Python json lib
 """
 
 try:
diff --git a/qa/rpc-tests/test_framework/bignum.py b/qa/rpc-tests/test_framework/bignum.py
index ef800e4d57..024611da6e 100644
--- a/qa/rpc-tests/test_framework/bignum.py
+++ b/qa/rpc-tests/test_framework/bignum.py
@@ -1,15 +1,11 @@
 #!/usr/bin/env python3
 #
-# bignum.py
-#
-# This file is copied from python-bitcoinlib.
-#
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-#
-
-"""Bignum routines"""
+"""Big number routines.
 
+This file is copied from python-bitcoinlib.
+"""
 
 import struct
 
diff --git a/qa/rpc-tests/test_framework/blockstore.py b/qa/rpc-tests/test_framework/blockstore.py
index 28a6b92b81..5280d18cdc 100644
--- a/qa/rpc-tests/test_framework/blockstore.py
+++ b/qa/rpc-tests/test_framework/blockstore.py
@@ -2,16 +2,20 @@
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-# BlockStore: a helper class that keeps a map of blocks and implements
-#             helper functions for responding to getheaders and getdata,
-#             and for constructing a getheaders message
-#
+"""BlockStore and TxStore helper classes."""
 
 from .mininode import *
 from io import BytesIO
 import dbm.dumb as dbmd
 
 class BlockStore(object):
+    """BlockStore helper class.
+
+    BlockStore keeps a map of blocks and implements helper functions for
+    responding to getheaders and getdata, and for constructing a getheaders
+    message.
+    """
+
     def __init__(self, datadir):
         self.blockDB = dbmd.open(datadir + "/blocks", 'c')
         self.currentBlock = 0
diff --git a/qa/rpc-tests/test_framework/blocktools.py b/qa/rpc-tests/test_framework/blocktools.py
index f69958823c..2c9a0857df 100644
--- a/qa/rpc-tests/test_framework/blocktools.py
+++ b/qa/rpc-tests/test_framework/blocktools.py
@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
-# blocktools.py - utilities for manipulating blocks and transactions
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Utilities for manipulating blocks and transactions."""
 
 from .mininode import *
 from .script import CScript, OP_TRUE, OP_CHECKSIG, OP_RETURN
diff --git a/qa/rpc-tests/test_framework/comptool.py b/qa/rpc-tests/test_framework/comptool.py
index 17679fc7e1..b617895cac 100755
--- a/qa/rpc-tests/test_framework/comptool.py
+++ b/qa/rpc-tests/test_framework/comptool.py
@@ -2,34 +2,29 @@
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-
-from .mininode import *
-from .blockstore import BlockStore, TxStore
-from .util import p2p_port
-
-'''
-This is a tool for comparing two or more bitcoinds to each other
-using a script provided.
+"""Compare two or more bitcoinds to each other.
 
 To use, create a class that implements get_tests(), and pass it in
 as the test generator to TestManager.  get_tests() should be a python
 generator that returns TestInstance objects.  See below for definition.
-'''
 
-# TestNode behaves as follows:
-# Configure with a BlockStore and TxStore
-# on_inv: log the message but don't request
-# on_headers: log the chain tip
-# on_pong: update ping response map (for synchronization)
-# on_getheaders: provide headers via BlockStore
-# on_getdata: provide blocks via BlockStore
+TestNode behaves as follows:
+    Configure with a BlockStore and TxStore
+    on_inv: log the message but don't request
+    on_headers: log the chain tip
+    on_pong: update ping response map (for synchronization)
+    on_getheaders: provide headers via BlockStore
+    on_getdata: provide blocks via BlockStore
+"""
+
+from .mininode import *
+from .blockstore import BlockStore, TxStore
+from .util import p2p_port
 
 global mininode_lock
 
 class RejectResult(object):
-    '''
-    Outcome that expects rejection of a transaction or block.
-    '''
+    """Outcome that expects rejection of a transaction or block."""
     def __init__(self, code, reason=b''):
         self.code = code
         self.reason = reason
diff --git a/qa/rpc-tests/test_framework/coverage.py b/qa/rpc-tests/test_framework/coverage.py
index 13b33869f5..3f87ef91f6 100644
--- a/qa/rpc-tests/test_framework/coverage.py
+++ b/qa/rpc-tests/test_framework/coverage.py
@@ -2,15 +2,12 @@
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Utilities for doing coverage analysis on the RPC interface.
 
-"""
-This module contains utilities for doing coverage analysis on the RPC
-interface.
-
-It provides a way to track which RPC commands are exercised during
+Provides a way to track which RPC commands are exercised during
 testing.
-
 """
+
 import os
 
 
diff --git a/qa/rpc-tests/test_framework/key.py b/qa/rpc-tests/test_framework/key.py
index c63a15c1e0..85a6158a2f 100644
--- a/qa/rpc-tests/test_framework/key.py
+++ b/qa/rpc-tests/test_framework/key.py
@@ -1,14 +1,10 @@
 # Copyright (c) 2011 Sam Rushing
-#
-# key.py - OpenSSL wrapper
-#
-# This file is modified from python-bitcoinlib.
-#
-
-"""ECC secp256k1 crypto routines
+"""ECC secp256k1 OpenSSL wrapper.
 
 WARNING: This module does not mlock() secrets; your private keys may end up on
 disk in swap! Use with caution!
+
+This file is modified from python-bitcoinlib.
 """
 
 import ctypes
diff --git a/qa/rpc-tests/test_framework/mininode.py b/qa/rpc-tests/test_framework/mininode.py
index 5b563c58ae..b2292f6477 100755
--- a/qa/rpc-tests/test_framework/mininode.py
+++ b/qa/rpc-tests/test_framework/mininode.py
@@ -4,23 +4,21 @@
 # Copyright (c) 2010-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-
-#
-# mininode.py - Bitcoin P2P network half-a-node
-#
-# This python code was modified from ArtForz' public domain  half-a-node, as
-# found in the mini-node branch of http://github.com/jgarzik/pynode.
-#
-# NodeConn: an object which manages p2p connectivity to a bitcoin node
-# NodeConnCB: a base class that describes the interface for receiving
-#             callbacks with network messages from a NodeConn
-# CBlock, CTransaction, CBlockHeader, CTxIn, CTxOut, etc....:
-#     data structures that should map to corresponding structures in
-#     bitcoin/primitives
-# msg_block, msg_tx, msg_headers, etc.:
-#     data structures that represent network messages
-# ser_*, deser_*: functions that handle serialization/deserialization
-
+"""Bitcoin P2P network half-a-node.
+
+This python code was modified from ArtForz' public domain  half-a-node, as
+found in the mini-node branch of http://github.com/jgarzik/pynode.
+
+NodeConn: an object which manages p2p connectivity to a bitcoin node
+NodeConnCB: a base class that describes the interface for receiving
+            callbacks with network messages from a NodeConn
+CBlock, CTransaction, CBlockHeader, CTxIn, CTxOut, etc....:
+    data structures that should map to corresponding structures in
+    bitcoin/primitives
+msg_block, msg_tx, msg_headers, etc.:
+    data structures that represent network messages
+ser_*, deser_*: functions that handle serialization/deserialization
+"""
 
 import struct
 import socket
diff --git a/qa/rpc-tests/test_framework/netutil.py b/qa/rpc-tests/test_framework/netutil.py
index b92a9f6e1c..45d8e22d22 100644
--- a/qa/rpc-tests/test_framework/netutil.py
+++ b/qa/rpc-tests/test_framework/netutil.py
@@ -2,8 +2,10 @@
 # Copyright (c) 2014-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Linux network utilities.
 
-# Linux network utilities
+Roughly based on http://voorloopnul.com/blog/a-python-netstat-in-less-than-100-lines-of-code/ by Ricardo Pascal
+"""
 
 import sys
 import socket
@@ -13,7 +15,6 @@ import array
 import os
 from binascii import unhexlify, hexlify
 
-# Roughly based on http://voorloopnul.com/blog/a-python-netstat-in-less-than-100-lines-of-code/ by Ricardo Pascal
 STATE_ESTABLISHED = '01'
 STATE_SYN_SENT  = '02'
 STATE_SYN_RECV = '03'
diff --git a/qa/rpc-tests/test_framework/script.py b/qa/rpc-tests/test_framework/script.py
index 83bbf20479..3d9572788e 100644
--- a/qa/rpc-tests/test_framework/script.py
+++ b/qa/rpc-tests/test_framework/script.py
@@ -2,19 +2,11 @@
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Functionality to build scripts, as well as SignatureHash().
 
-#
-# script.py
-#
-# This file is modified from python-bitcoinlib.
-#
-
-"""Scripts
-
-Functionality to build scripts, as well as SignatureHash().
+This file is modified from python-bitcoinlib.
 """
 
-
 from .mininode import CTransaction, CTxOut, sha256, hash256, uint256_from_str, ser_uint256, ser_string
 from binascii import hexlify
 import hashlib
diff --git a/qa/rpc-tests/test_framework/siphash.py b/qa/rpc-tests/test_framework/siphash.py
index 9c0574bd93..f68ecad36b 100644
--- a/qa/rpc-tests/test_framework/siphash.py
+++ b/qa/rpc-tests/test_framework/siphash.py
@@ -2,11 +2,10 @@
 # Copyright (c) 2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Specialized SipHash-2-4 implementations.
 
-#
-# siphash.py - Specialized SipHash-2-4 implementations
-#
-# This implements SipHash-2-4 for 256-bit integers.
+This implements SipHash-2-4 for 256-bit integers.
+"""
 
 def rotl64(n, b):
     return n >> (64 - b) | (n & ((1 << (64 - b)) - 1)) << b
diff --git a/qa/rpc-tests/test_framework/socks5.py b/qa/rpc-tests/test_framework/socks5.py
index 372f5ed605..450bf3775e 100644
--- a/qa/rpc-tests/test_framework/socks5.py
+++ b/qa/rpc-tests/test_framework/socks5.py
@@ -2,9 +2,7 @@
 # Copyright (c) 2015-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-'''
-Dummy Socks5 server for testing.
-'''
+"""Dummy Socks5 server for testing."""
 
 import socket, threading, queue
 import traceback, sys
@@ -20,7 +18,7 @@ class AddressType:
 
 ### Utility functions
 def recvall(s, n):
-    '''Receive n bytes from a socket, or fail'''
+    """Receive n bytes from a socket, or fail."""
     rv = bytearray()
     while n > 0:
         d = s.recv(n)
@@ -32,7 +30,7 @@ def recvall(s, n):
 
 ### Implementation classes
 class Socks5Configuration(object):
-    '''Proxy configuration'''
+    """Proxy configuration."""
     def __init__(self):
         self.addr = None # Bind address (must be set)
         self.af = socket.AF_INET # Bind address family
@@ -40,7 +38,7 @@ class Socks5Configuration(object):
         self.auth = False  # Support authentication
 
 class Socks5Command(object):
-    '''Information about an incoming socks5 command'''
+    """Information about an incoming socks5 command."""
     def __init__(self, cmd, atyp, addr, port, username, password):
         self.cmd = cmd # Command (one of Command.*)
         self.atyp = atyp # Address type (one of AddressType.*)
@@ -58,9 +56,7 @@ class Socks5Connection(object):
         self.peer = peer
 
     def handle(self):
-        '''
-        Handle socks5 request according to RFC1928
-        '''
+        """Handle socks5 request according to RFC192."""
         try:
             # Verify socks version
             ver = recvall(self.conn, 1)[0]
diff --git a/qa/rpc-tests/test_framework/test_framework.py b/qa/rpc-tests/test_framework/test_framework.py
index 98c4f6070b..c5e9c6a658 100755
--- a/qa/rpc-tests/test_framework/test_framework.py
+++ b/qa/rpc-tests/test_framework/test_framework.py
@@ -2,8 +2,7 @@
 # Copyright (c) 2014-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-
-# Base class for RPC testing
+"""Base class for RPC testing."""
 
 import logging
 import optparse
diff --git a/qa/rpc-tests/test_framework/util.py b/qa/rpc-tests/test_framework/util.py
index ec151c2a65..e838a40582 100644
--- a/qa/rpc-tests/test_framework/util.py
+++ b/qa/rpc-tests/test_framework/util.py
@@ -2,11 +2,7 @@
 # Copyright (c) 2014-2016 The Bitcoin Core developers
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
-
-
-#
-# Helpful routines for regression testing
-#
+"""Helpful routines for regression testing."""
 
 import os
 import sys