Better documentation and utils

README.rst

@@ -132,13 +132,26 @@ More examples
 You can see more demo applications in `docs/examples` directory of the source repository.
 
 
-External links
---------------
+Resources
+---------
 
+* `i2plib online documentation`_
 * `Invisible Internet Project`_
 * `SAM API documentation`_
 * `Python asyncio documentation`_
 
+.. _i2plib online documentation: https://i2plib.readthedocs.io/en/latest/
 .. _Invisible Internet Project: https://geti2p.net/en/
 .. _SAM API documentation: https://geti2p.net/en/docs/api/samv3
 .. _Python asyncio documentation: https://docs.python.org/3/library/asyncio.html
+
+Aknowledgments
+--------------
+
+* `i2p.socket, drop in python socket module that uses i2p`_
+* `txi2p, I2P bindings for Twisted`_
+* `leaflet, Dead simple I2P SAM library, written in Python 3`_
+
+.. _i2p.socket, drop in python socket module that uses i2p: https://github.com/majestrate/i2p.socket
+.. _txi2p, I2P bindings for Twisted: https://github.com/str4d/txi2p
+.. _leaflet, Dead simple I2P SAM library, written in Python 3: https://github.com/MuxZeroNet/leaflet

docs/api.rst

@@ -14,8 +14,8 @@ These 4 *coroutines* provide everything you need for making connections inside
 I2P network. All of them return a tuple of transports *(reader, writer)* to 
 deal with.
 
-The *reader* returned is an asyncio.StreamReader instance; the *writer* is 
-an asyncio.StreamWriter instance.
+The *reader* returned is an :class:`asyncio.StreamReader` instance; the *writer* is 
+an :class:`asyncio.StreamWriter` instance.
 
 
 .. autofunction:: create_session
@@ -40,8 +40,10 @@ Server tunnel exposes a local address to the I2P network.
 .. autoclass:: i2plib.tunnel.I2PTunnel
    :members:
 .. autoclass:: i2plib.ClientTunnel
+   :members:
    :inherited-members:
 .. autoclass:: i2plib.ServerTunnel
+   :members:
    :inherited-members:
 
 Data structures

docs/conf.py

@@ -17,6 +17,8 @@ import sys
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('.'))
 
+import i2plib
+
 
 # -- Project information -----------------------------------------------------
 
@@ -25,9 +27,9 @@ copyright = '2018, Viktor Villainov'
 author = 'Viktor Villainov'
 
 # The short X.Y version
-version = ''
+version = i2plib.__version__
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
+release = i2plib.__version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -41,6 +43,8 @@ release = '0.0.1'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -158,3 +162,6 @@ texinfo_documents = [
 
 
 # -- Extension configuration -------------------------------------------------
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+}

docs/index.rst

@@ -18,13 +18,15 @@ Contents
    api
 
 
-External links
---------------
+Resources
+---------
 
+* `i2plib online documentation`_
 * `Invisible Internet Project`_
 * `SAM API documentation`_
 * `Python asyncio documentation`_
 
+.. _i2plib online documentation: https://i2plib.readthedocs.io/en/latest/
 .. _Invisible Internet Project: https://geti2p.net/en/
 .. _SAM API documentation: https://geti2p.net/en/docs/api/samv3
 .. _Python asyncio documentation: https://docs.python.org/3/library/asyncio.html

i2plib/__version__.py

@@ -1,7 +1,7 @@
 __title__ = 'i2plib'
 __description__ = 'A modern asynchronous library for building I2P applications.'
 __url__ = 'https://github.com/l-n-s/i2plib'
-__version__ = '0.0.8'
+__version__ = '0.0.9'
 __author__ = 'Viktor Villainov'
 __author_email__ = 'supervillain@riseup.net'
 __license__ = 'MIT'

i2plib/aiosam.py

@@ -34,7 +34,7 @@ async def dest_lookup(domain, sam_address=i2plib.sam.DEFAULT_ADDRESS,
                    address.
     :param sam_address: (optional) SAM API address
     :param loop: (optional) Event loop instance
-    :return: An instance of i2plib.Destination
+    :return: An instance of :class:`i2plib.Destination`
     """
     reader, writer = await get_sam_socket(sam_address, loop)
     writer.write(i2plib.sam.naming_lookup(domain))
@@ -53,7 +53,7 @@ async def new_destination(sam_address=i2plib.sam.DEFAULT_ADDRESS, loop=None,
     :param sam_address: (optional) SAM API address
     :param loop: (optional) Event loop instance
     :param sig_type: (optional) Signature type
-    :return: An instance of i2plib.Destination
+    :return: An instance of :class:`i2plib.Destination`
     """
     reader, writer = await get_sam_socket(sam_address, loop)
     writer.write(i2plib.sam.dest_generate(sig_type))
@@ -77,8 +77,9 @@ async def create_session(session_name, sam_address=i2plib.sam.DEFAULT_ADDRESS,
     :param signature_type: (optional) If the destination is TRANSIENT, this 
                         signature type is used
     :param destination: (optional) Destination to use in this session. Can be 
-                        a base64 encoded string, i2plib.sam.Destination instance
-                        or None. TRANSIENT destination is used when it is None.
+                        a base64 encoded string, :class:`i2plib.Destination` 
+                        instance or None. TRANSIENT destination is used when it
+                        is None.
     :param options: (optional) A dict object with i2cp options
     :param session_created: (optional) A coroutine to be executed after the 
                         session is created. Executed with arguments

i2plib/sam.py

@@ -139,7 +139,7 @@ class Destination(object):
         self.data = bytes() 
         #: Base64 encoded destination
         self.base64 = ""    
-        #: i2plib.PrivateKey instance or None
+        #: :class:`i2plib.PrivateKey` instance or None
         self.private_key = None    
         
         if path:

i2plib/tunnel.py

@@ -30,9 +30,10 @@ class I2PTunnel(object):
 
     :param local_address: A local address to use for a tunnel. 
                           E.g. ("127.0.0.1", 6668)
-    :param destination: (optional) Destination to use in this session. Can be 
-                        a base64 encoded string, i2plib.sam.Destination instance
-                        or None. A new destination is created when it is None.
+    :param destination: (optional) Destination to use for this tunnel. Can be 
+                        a base64 encoded string, :class:`i2plib.Destination`
+                        instance or None. A new destination is created when it
+                        is None.
     :param session_name: (optional) Session nick name. A new session nickname is
                         generated if not specified.
     :param options: (optional) A dict object with i2cp options
@@ -72,7 +73,7 @@ class ClientTunnel(I2PTunnel):
 
     :param remote_destination: Remote I2P destination, can be either .i2p 
                         domain, .b32.i2p address, base64 destination or 
-                        i2plib.Destination instance
+                        :class:`i2plib.Destination` instance
     """
 
     def __init__(self, remote_destination, *args, **kwargs):

i2plib/utils.py

@@ -3,6 +3,7 @@ import os
 import i2plib.sam
 
 def get_free_port():
+    """Get a free port on your local host"""
     s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
     s.bind(('', 0))
@@ -10,6 +11,12 @@ def get_free_port():
     s.close()
     return free_port
 
+def is_address_accessible(address):
+    """Check if address is accessible or down"""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    is_accessible = s.connect_ex(address) == 0
+    s.close()
+    return is_accessible
 
 def address_from_string(address_string):
     """Address tuple from host:port string"""
@@ -17,12 +24,12 @@ def address_from_string(address_string):
     return (address[0], int(address[1]))
 
 def get_sam_address():
-    """Get SAM address from environment variable SAM_ADDRESS, or use a default 
-       value"""
-    if os.getenv("SAM_ADDRESS"):
-        return address_from_string(os.getenv("SAM_ADDRESS"))
-    else:
-        return i2plib.sam.DEFAULT_ADDRESS
+    """
+    Get SAM address from environment variable I2P_SAM_ADDRESS, or use a default
+    value
+    """
+    value = os.getenv("I2P_SAM_ADDRESS")
+    return address_from_string(value) if value else i2plib.sam.DEFAULT_ADDRESS
 
 def get_new_destination(sam_address=i2plib.sam.DEFAULT_ADDRESS, 
                         sig_type=i2plib.sam.Destination.default_sig_type):