Sphinx docstrings for the funtions

Vedran · Vedran · commit 7a63c055aede · 2014-09-09T20:45:40.000+09:00
diff --git a/blockchain/blockchaindata.py b/blockchain/blockchaindata.py
@@ -1,7 +1,19 @@
+"""This module corresponds to functionality documented
+at https://blockchain.info/api/blockchain_api
+
+"""
+
 import util
 import json
 
 def get_block(block_id, api_code = None):
+    """Get a single block based on a block index or hash.
+    
+    :param str block_id: block hash or index to look up
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`Block` class
+    """
+    
     resource = 'rawblock/' + block_id
     if api_code is not None:
         resource += '?api_code=' + api_code
@@ -10,6 +22,13 @@ def get_block(block_id, api_code = None):
     return Block(json_response)
 
 def get_tx(tx, api_code = None):
+    """Get a single transaction based on a transaction index or hash.
+    
+    :param str block_id: transaction hash or index to look up
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`Transaction` class
+    """
+    
     resource = 'rawtx/' + tx
     if api_code is not None:
         resource += '?api_code=' + api_code
@@ -18,6 +37,13 @@ def get_tx(tx, api_code = None):
     return Transaction(json_response)
 
 def get_block_height(height, api_code = None):
+    """Get an array of blocks at the specified height.
+    
+    :param int height: block height to look up
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an array of :class:`Block` objects
+    """
+    
     resource = 'block-height/{0}?format=json'.format(height)
     if api_code is not None:
         resource += '&api_code=' + api_code
@@ -26,6 +52,13 @@ def get_block_height(height, api_code = None):
     return [Block(b) for b in json_response['blocks']]
 
 def get_address(address, api_code = None):
+    """Get data for a single address.
+    
+    :param str address: address to look up
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`Address` class
+    """
+    
     resource = 'rawaddr/' + address
     if api_code is not None:
         resource += '?api_code=' + api_code
@@ -34,6 +67,13 @@ def get_address(address, api_code = None):
     return Address(json_response)
     
 def get_unspent_outputs(address, api_code = None):
+    """Get unspent outputs for a single address.
+    
+    :param str address: address to look up
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an array of :class:`UnspentOutput` objects
+    """
+    
     resource = 'unspent?active=' + address
     if api_code is not None:
         resource += '&api_code=' + api_code
@@ -42,6 +82,12 @@ def get_unspent_outputs(address, api_code = None):
     return [UnspentOutput(o) for o in json_response['unspent_outputs']]
 
 def get_latest_block(api_code = None):
+    """Get the latest block on the main chain.
+    
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`LatestBlock` class
+    """
+    
     resource = 'latestblock'
     if api_code is not None:
         resource += '?api_code=' + api_code
@@ -50,6 +96,12 @@ def get_latest_block(api_code = None):
     return LatestBlock(json_response)
     
 def get_unconfirmed_tx(api_code = None):
+    """Get a list of currently unconfirmed transactions.
+    
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an array of :class:`Transaction` objects
+    """
+    
     resource = 'unconfirmed-transactions?format=json'
     if api_code is not None:
         resource += '&api_code=' + api_code
@@ -58,6 +110,15 @@ def get_unconfirmed_tx(api_code = None):
     return [Transaction(t) for t in json_response['txs']]
 
 def get_blocks(time = None, pool_name = None, api_code = None):
+    """Get a list of blocks for a specific day or mining pool.
+    Both parameters are optional but at least one is required.
+    
+    :param int time: time in milliseconds
+    :param str pool_name: name of the mining pool
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an array of :class:`SimpleBlock` objects
+    """
+    
     resource = 'blocks/{0}?format=json'
     if api_code is not None:
         resource += '&api_code=' + api_code
@@ -73,6 +134,12 @@ def get_blocks(time = None, pool_name = None, api_code = None):
     return [SimpleBlock(b) for b in json_response['blocks']]
 
 def get_inventory_data(hash, api_code = None):
+    """Get inventory data.
+    
+    :param str hash: tx or block hash
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`InventoryData` class
+    """
     resource = 'inv/{0}?format=json'.format(hash)
     if api_code is not None:
         resource += '&api_code=' + api_code
diff --git a/blockchain/createwallet.py b/blockchain/createwallet.py
@@ -1,10 +1,23 @@
+"""This module corresponds to functionality documented
+at https://blockchain.info/api/create_wallet
+
 """
-TODO
-"""
+
 import util
 import json
- 
+
 def create_wallet(password, api_code, priv = None, label = None, email = None):
+        """Create a new Blockchain.info wallet. It can be created containing a 
+        pre-generated private key or will otherwise generate a new private key. 
+
+        :param str password: password for the new wallet. At least 10 characters.
+        :param str api_code: API code with create wallets permission
+        :param str priv: private key to add to the wallet (optional)
+        :param str label: label for the first address in the wallet (optional)
+        :param str email: email to associate with the new wallet (optional)
+        :return: an instance of :class:`WalletResponse` class
+        """
+        
         params = { 'password': password, 'api_code': api_code }
         if priv is not None:
             params['priv'] = priv
diff --git a/blockchain/exceptions.py b/blockchain/exceptions.py
@@ -1,6 +1,3 @@
-class ValidationException(Exception):
-    pass
-    
 class APIException(Exception):
     def __init__(self, message, code):
         Exception.__init__(self, message)
diff --git a/blockchain/exchangerates.py b/blockchain/exchangerates.py
@@ -1,16 +1,19 @@
+"""This module corresponds to functionality documented at 
+https://blockchain.info/api/exchange_rates_api
+"""
+
 import urllib2
 import util
 import json
 
-class Currency:
-    def __init__(self, last, buy, sell, symbol, p15min):
-        self.last = last
-        self.buy = buy
-        self.sell = sell
-        self.symbol = symbol
-        self.p15min = p15min
-
-def ticker(api_code = None):
+def get_ticker(api_code = None):
+    """Call the 'ticker' method and return a dictionary
+    of :class:`Currency` objects.
+    
+    :param str api_code: Blockchain.info API code (optional)
+    :return: a dictionary in the format of ccy_symbol(str):currency(:class:`Currency`)
+    """
+    
     response = util.call_api('ticker' if api_code is None else 'ticker?api_code=' + api_code)
     json_response = json.loads(response)
     ticker = {}
@@ -25,7 +28,23 @@ def ticker(api_code = None):
     return ticker
 
 def to_btc(ccy, value, api_code = None):
+    """Call the 'tobtc' method and convert x value in the provided currency to BTC.
+    
+    :param str ccy: currency code
+    :param int value: value to convert
+    :param str api_code: Blockchain.info API code
+    :return: the value in BTC
+    """
+    
     res = 'tobtc?currency={0}&value={1}'.format(ccy, value)
     if api_code is not None:
         res += '&api_code=' + api_code
-    return util.call_api(res)
+    return util.call_api(res)
+    
+class Currency:
+    def __init__(self, last, buy, sell, symbol, p15min):
+        self.last = last
+        self.buy = buy
+        self.sell = sell
+        self.symbol = symbol
+        self.p15min = p15min
diff --git a/blockchain/receive.py b/blockchain/receive.py
@@ -1,15 +1,28 @@
+"""This module corresponds to functionality documented
+at https://blockchain.info/api/api_receive
+"""
+
 import urllib2
 import util
 import json
 
 class PaymentResponse:
+
     def __init__(self, fee, dest, input, callback):
         self.fee = fee
         self.destination_address = dest
         self.input_address = input
         self.callback_url = callback
 
 def receive(dest_addr, callback, api_code = None):
+    """Call the 'api/receive' endpoint and create a forwarding address.
+    
+    :param str dest_addr: destination address where the payment should be sent
+    :param str callback: callback URI that will be called upon payment
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`PaymentResponse` class
+    """
+    
     params = { 'method': 'create', 'address': dest_addr, 'callback': callback }
     if api_code is not None:
         params['api_code'] = api_code
diff --git a/blockchain/statistics.py b/blockchain/statistics.py
@@ -1,7 +1,18 @@
+"""This module corresponds to functionality documented
+at https://blockchain.info/api/charts_api
+
+"""
+
 import util
 import json
 
 def get(api_code = None):
+    """Get network statistics.
+    
+    :param str api_code: Blockchain.info API code (optional)
+    :return: an instance of :class:`Stats` class
+    """
+    
     resource = 'stats?format=json'
     if api_code is not None:
         resource += '&api_code=' + api_code
diff --git a/blockchain/util.py b/blockchain/util.py
@@ -1,6 +1,5 @@
 import urllib
 import urllib2
-import re
 
 from .exceptions import *
 from validation import validate
@@ -10,24 +9,7 @@
 
 def call_api(resource, data = None):
     try:
-        #print urllib.urlencode(data)
         return urllib2.urlopen(BASE_URL + resource,
                                 None if data is None else urllib.urlencode(data)).read()
     except urllib2.HTTPError as e:
-        raise APIException(e.read(), e.code)
-    
-def validate_address(address):
-    if not validate(address):
-        raise ValidationException("Invalid bitcoin address")
-        
-def validate_url(url):
-    regex = re.compile(
-        r'^(?:[a-z0-9\.\-]*)://' # scheme is validated separately
-        r'(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+(?:[A-Z]{2,6}\.?|[A-Z0-9-]{2,}(?<!-)\.?)|' # domain...
-        r'localhost|' # localhost...
-        r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}|' # ...or ipv4
-        r'\[?[A-F0-9]*:[A-F0-9:]+\]?)' # ...or ipv6
-        r'(?::\d+)?' # optional port
-        r'(?:/?|[/?]\S+)$', re.IGNORECASE)
-    if url is None or not regex.search(url):
-        raise ValidationException("Invalid URL")
+        raise APIException(e.read(), e.code)
diff --git a/blockchain/validation.py b/blockchain/validation.py
diff --git a/blockchain/wallet.py b/blockchain/wallet.py
