Improve many things about the documentation

  * Better signature for the `connect` function (fixes ipfs-shipyard#150)
  * Document the `stream` parameter
  * Return values are now *documented*, not *commented* on (syntactial change)
  * Document the JSON object keys of several methods separately

Author: ntninja

docs/conf.py

@@ -64,7 +64,7 @@
 
 # General information about the project.
 project = 'Python IPFS HTTP Client'
-copyright = '2016, py-ipfs-http-client team'
+copyright = '2019, py-ipfs-http-client team'
 author = 'py-ipfs-http-client team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -313,7 +313,8 @@
 
 # External documentation link mapping
 intersphinx_mapping = {
-	'python': ('https://docs.python.org/3', None)
+	'python': ('https://docs.python.org/3', None),
+	'cid': ('https://py-cid.readthedocs.io/en/master/', None)
 }
 
 # -- Napoleon settings ----------------------------------------------------

docs/http_client_ref.md

@@ -11,19 +11,52 @@ All commands are accessed through the ``ipfshttpclient.Client`` class.
 ```
 
 
+### Utility Functions
 
-### The HTTP Client
+```eval_rst
+.. data:: ipfshttpclient.DEFAULT_HOST
 
-All methods accept the following parameters in their ``kwargs``:
+    The default hostname that the client library will attempt to connect to.
+    This may be overwritten on a per-client-instance basis using the ``host``
+    parameter of the :func:`~ipfshttpclient.connect` function.
 
- * **opts** (*dict*) – A dictionary of custom parameters to be sent with the
-                       HTTP request
+.. data:: ipfshttpclient.DEFAULT_PORT
 
-```eval_rst
-.. autofunction:: ipfshttpclient.connect
+    The default port number that the client library will attempt to connect to.
+    This may be overwritten on a per-client-instance basis using the ``port``
+    parameter of the :func:`~ipfshttpclient.connect` function.
+
+.. data:: ipfshttpclient.DEFAULT_BASE
+
+    The default HTTP URL prefix (or “base”) that the client library will use.
+    This may be overwritten on a per-client-instance basis using the ``base``
+    parameter of the :func:`~ipfshttpclient.connect` function.
+
+.. autofunction:: ipfshttpclient.connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE)
 
 .. autofunction:: ipfshttpclient.assert_version
 
+```
+
+### The API Client
+
+All methods accept the following parameters in their `kwargs`:
+
+ * **opts** (*dict*) – A mapping of custom IPFS API parameters to be sent along
+                       with the regular parameters generated by the client
+                       library
+    * Values specified here will always override their respective counterparts
+      of the client library itself.
+ * **stream** (*bool*) – Return results incrementally as they arrive?
+    * Each method called with `stream=True` will return a generator instead
+      of the documented value. If the return type is of type `list` then each
+      item of the given list will be yielded separately; if it is of type
+      `bytes` then arbitrary bags of bytes will be yielded that together form
+      a stream; finally, if it is of type `dict` then the single dictonary item
+      will be yielded once.
+
+```eval_rst
+
 .. autoclientclass:: ipfshttpclient.Client
 	:members:
 	:inherited-members:

ipfshttpclient/client/__init__.py

@@ -49,11 +49,11 @@ def assert_version(version, minimum=VERSION_MINIMUM, maximum=VERSION_MAXIMUM):
 	Parameters
 	----------
 	version : str
-		The version of an IPFS daemon.
+		The actual version of an IPFS daemon
 	minimum : str
-		The minimal IPFS version to allow.
+		The minimal IPFS daemon version to allowed
 	maximum : str
-		The maximum IPFS version to allow.
+		The maximum IPFS daemon version to allowed
 	"""
 	# Convert version strings to integer tuples
 	version = list(map(int, version.split('-', 1)[0].split('.')))
@@ -84,7 +84,7 @@ def connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE,
 
 	Returns
 	-------
-		~ipfshttpclient.Client
+		:class:`~ipfshttpclient.Client`
 	"""
 	# Create client instance
 	client = Client(host, port, base, chunk_size, **defaults)
@@ -96,6 +96,16 @@ def connect(host=DEFAULT_HOST, port=DEFAULT_PORT, base=DEFAULT_BASE,
 
 
 class Client(files.Base, miscellaneous.Base):
+	"""The main IPFS HTTP client class
+	
+	Allows access to an IPFS daemon instance using its HTTP API by exposing an
+	`IPFS Interface Core <https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC>`__
+	compatible set of methods.
+	
+	It is possible to instantiate this class directly, using the same parameters
+	as :func:`connect`, to prevent the client from checking for an active and
+	compatible version of the daemon.
+	"""
 	bitswap   = base.SectionProperty(bitswap.Section)
 	block     = base.SectionProperty(block.Section)
 	bootstrap = base.SectionProperty(bootstrap.Section)
@@ -134,7 +144,8 @@ def add_bytes(self, data, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		body, headers = multipart.stream_bytes(data, self.chunk_size)
 		return self._client.request('/add', decoder='json',
@@ -159,7 +170,8 @@ def add_str(self, string, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		body, headers = multipart.stream_text(string, self.chunk_size)
 		return self._client.request('/add', decoder='json',
@@ -180,7 +192,8 @@ def add_json(self, json_obj, **kwargs):
 
 		Returns
 		-------
-			str : Hash of the added IPFS object
+			str
+				Hash of the added IPFS object
 		"""
 		return self.add_bytes(encoding.Json().encode(json_obj), **kwargs)
 
@@ -196,11 +209,12 @@ def get_json(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
 		   CID of the IPFS object to load
 
 		Returns
 		-------
-			object : Deserialized IPFS JSON object value
+			object
+				Deserialized IPFS JSON object value
 		"""
 		return self.cat(cid, decoder='json', **kwargs)

ipfshttpclient/client/bitswap.py

@@ -25,7 +25,11 @@ def wantlist(self, peer=None, **kwargs):
 		
 		Returns
 		-------
-			dict : List of wanted blocks
+			dict
+		
+		+------+----------------------------------------------------+
+		| Keys | List of blocks the connected daemon is looking for |
+		+------+----------------------------------------------------+
 		"""
 		args = (peer,)
 		return self._client.request('/bitswap/wantlist', args, decoder='json', **kwargs)
@@ -57,6 +61,7 @@ def stat(self, **kwargs):
 		
 		Returns
 		-------
-			dict : Statistics, peers and wanted blocks
+			dict
+				Statistics, peers and wanted blocks
 		"""
 		return self._client.request('/bitswap/stat', decoder='json', **kwargs)

ipfshttpclient/client/block.py

@@ -21,12 +21,13 @@ def get(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
-			The base58 CID of an existing block to get
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
+			The CID of an existing block to get
 
 		Returns
 		-------
-			bytes : Value of the requested block
+			bytes
+				Contents of the requested block
 		"""
 		args = (str(cid),)
 		return self._client.request('/block/get', args, **kwargs)
@@ -49,9 +50,10 @@ def put(self, file, **kwargs):
 
 		Returns
 		-------
-			dict : Information about the new block
-
-				   See :meth:`~ipfshttpclient.Client.block.stat`
+			dict
+				Information about the new block
+				
+				See :meth:`~ipfshttpclient.Client.block.stat`
 		"""
 		body, headers = multipart.stream_files(file, self.chunk_size)
 		return self._client.request('/block/put', decoder='json', data=body,
@@ -70,12 +72,13 @@ def stat(self, cid, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
-			The base58 CID of an existing block to stat
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
+			The CID of an existing block to stat
 
 		Returns
 		-------
-			dict : Information about the requested block
+			dict
+				Information about the requested block
 		"""
 		args = (str(cid),)
 		return self._client.request('/block/stat', args, decoder='json', **kwargs)

ipfshttpclient/client/bootstrap.py

@@ -37,11 +37,16 @@ def list(self, **kwargs):
 				'/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRa … ca9z',
 				'/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKD … KrGM',
 				…
-				'/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3p … QBU3']}
+				'/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3p … QBU3'
+			]}
 
 		Returns
 		-------
-			dict : List of known bootstrap peers
+			dict
+		
+		+-------+-------------------------------+
+		| Peers | List of known bootstrap peers |
+		+-------+-------------------------------+
 		"""
 		return self._client.request('/bootstrap', decoder='json', **kwargs)
 

ipfshttpclient/client/config.py

@@ -10,11 +10,6 @@ def get(self, **kwargs):
 		#TODO: Support the optional `key` parameter
 		"""Returns the current used server configuration.
 
-		.. warning::
-
-			The configuration file contains private key data that must be
-			handled with care.
-
 		.. code-block:: python
 
 			>>> config = client.config.get()
@@ -27,30 +22,31 @@ def get(self, **kwargs):
 
 		Returns
 		-------
-			dict : The entire IPFS daemon configuration
+			dict
+				The entire IPFS daemon configuration
 		"""
 		return self._client.request('/config/show', decoder='json', **kwargs)
 
 
 	@base.returns_single_item
 	def replace(self, config, **kwargs):
-		"""Replaces the existing config with a user-defined config.
+		"""Replaces the existing configuration with a new configuration tree.
 
 		Make sure to back up the config file first if neccessary, as this
-		operation can't be undone.
+		operation can not be undone.
 		"""
 		return self._client.request('/config/replace', (config,), decoder='json', **kwargs)
 
 
 	@base.returns_single_item
 	def set(self, key, value=None, **kwargs):
-		"""Add or replace a configuration value.
+		"""Add or replace a single configuration value.
 
 		.. code-block:: python
 
-			>>> client.config("Addresses.Gateway")
+			>>> client.config.set("Addresses.Gateway")
 			{'Key': 'Addresses.Gateway', 'Value': '/ip4/127.0.0.1/tcp/8080'}
-			>>> client.config("Addresses.Gateway", "/ip4/127.0.0.1/tcp/8081")
+			>>> client.config.set("Addresses.Gateway", "/ip4/127.0.0.1/tcp/8081")
 			{'Key': 'Addresses.Gateway', 'Value': '/ip4/127.0.0.1/tcp/8081'}
 
 		Parameters
@@ -62,7 +58,13 @@ def set(self, key, value=None, **kwargs):
 
 		Returns
 		-------
-			dict : Requested/updated key and its (new) value
+			dict
+		
+		+-------+---------------------------------------------+
+		| Key   | The requested configuration key             |
+		+-------+---------------------------------------------+
+		| Value | The new value of the this configuration key |
+		+-------+---------------------------------------------+
 		"""
 		args = (key, value)
 		return self._client.request('/config', args, decoder='json', **kwargs)

ipfshttpclient/client/dht.py

@@ -13,7 +13,7 @@ def findpeer(self, peer_id, *peer_ids, **kwargs):
 
 		.. code-block:: python
 
-			>>> client.dht_findpeer("QmaxqKpiYNr62uSFBhxJAMmEMkT6dvc3oHkrZN … MTLZ")
+			>>> client.dht.findpeer("QmaxqKpiYNr62uSFBhxJAMmEMkT6dvc3oHkrZN … MTLZ")
 			[{'ID': 'QmfVGMFrwW6AV6fTWmD6eocaTybffqAvkVLXQEFrYdk6yc',
 			  'Extra': '', 'Type': 6, 'Responses': None},
 			 {'ID': 'QmTKiUdjbRjeN9yPhNhG1X38YNuBdjeiV9JXYWzCAJ4mj5',
@@ -38,7 +38,8 @@ def findpeer(self, peer_id, *peer_ids, **kwargs):
 
 		Returns
 		-------
-			dict : List of multiaddrs
+			dict
+				List of multiaddrs
 		"""
 		args = (peer_id,) + peer_ids
 		return self._client.request('/dht/findpeer', args, decoder='json', **kwargs)
@@ -49,7 +50,7 @@ def findprovs(self, cid, *cids, **kwargs):
 
 		.. code-block:: python
 
-			>>> client.dht_findprovs("QmNPXDC6wTXVmZ9Uoc8X1oqxRRJr4f1sDuyQu … mpW2")
+			>>> client.dht.findprovs("QmNPXDC6wTXVmZ9Uoc8X1oqxRRJr4f1sDuyQu … mpW2")
 			[{'ID': 'QmaxqKpiYNr62uSFBhxJAMmEMkT6dvc3oHkrZNpH2VMTLZ',
 			  'Extra': '', 'Type': 6, 'Responses': None},
 			 {'ID': 'QmaK6Aj5WXkfnWGoWq7V8pGUYzcHPZp4jKQ5JtmRvSzQGk',
@@ -72,12 +73,13 @@ def findprovs(self, cid, *cids, **kwargs):
 
 		Parameters
 		----------
-		cid : Union[str, cid.BaseCID]
+		cid : Union[str, cid.CIDv0, cid.CIDv1]
 			The DHT key to find providers for
 
 		Returns
 		-------
-			dict : List of provider Peer IDs
+			dict
+				List of provider Peer IDs
 		"""
 		args = (str(cid),) + tuple(str(c) for c in cids)
 		return self._client.request('/dht/findprovs', args, decoder='json', **kwargs)
@@ -138,7 +140,7 @@ def put(self, key, value, **kwargs):
 
 		.. code-block:: python
 
-			>>> client.dht_put("QmVgNoP89mzpgEAAqK8owYoDEyB97Mkc … E9Uc", "test123")
+			>>> client.dht.put("QmVgNoP89mzpgEAAqK8owYoDEyB97Mkc … E9Uc", "test123")
 			[{'ID': 'QmfLy2aqbhU1RqZnGQyqHSovV8tDufLUaPfN1LNtg5CvDZ',
 			  'Extra': '', 'Type': 5, 'Responses': None},
 			 {'ID': 'QmZ5qTkNvvZ5eFq9T4dcCEK7kX8L7iysYEpvQmij9vokGE',
@@ -169,7 +171,7 @@ def query(self, peer_id, *peer_ids, **kwargs):
 
 		.. code-block:: python
 
-			>>> client.dht_query("/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDM … uvuJ")
+			>>> client.dht.query("/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDM … uvuJ")
 			[{'ID': 'QmPkFbxAQ7DeKD5VGSh9HQrdS574pyNzDmxJeGrRJxoucF',
 			  'Extra': '', 'Type': 2, 'Responses': None},
 			 {'ID': 'QmR1MhHVLJSLt9ZthsNNhudb1ny1WdhY4FPW21ZYFWec4f',
@@ -187,7 +189,8 @@ def query(self, peer_id, *peer_ids, **kwargs):
 
 		Returns
 		-------
-			dict : List of peers IDs
+			dict
+				List of peers IDs
 		"""
 		args = (peer_id,) + peer_ids
 		return self._client.request('/dht/query', args, decoder='json', **kwargs)