Improved documentation.

RNS/Identity.py

@@ -177,6 +177,22 @@ class Identity:
         Identity.save_known_destinations()
 
 
+    @staticmethod
+    def from_bytes(prv_bytes):
+        """
+        Create a new :ref:`RNS.Identity<api-identity>` instance from *bytes* of private key.
+        Can be used to load previously created and saved identities into Reticulum.
+
+        :param prv_bytes: The *bytes* of private a saved private key. **HAZARD!** Never use this to generate a new key by feeding random data in prv_bytes.
+        :returns: A :ref:`RNS.Identity<api-identity>` instance, or *None* if the *bytes* data was invalid.
+        """
+        identity = Identity(create_keys=False)
+        if identity.load_private_key(prv_bytes):
+            return identity
+        else:
+            return None
+
+
     @staticmethod
     def from_file(path):
         """
@@ -210,22 +226,6 @@ class Identity:
             RNS.log("Error while saving identity to "+str(path), RNS.LOG_ERROR)
             RNS.log("The contained exception was: "+str(e))
 
-    @staticmethod
-    def from_bytes(prv_bytes):
-        """
-        Create a new :ref:`RNS.Identity<api-identity>` instance from *bytes* of private key.
-        Can be used to load previously created and saved identities into Reticulum.
-
-        :param prv_bytes: The *bytes* of private a saved private key. **HAZARD!** Never not use this to generate a new key by feeding random data in prv_bytes.
-        :returns: A :ref:`RNS.Identity<api-identity>` instance, or *None* if the *bytes* data was invalid.
-        """
-        identity = Identity(create_keys=False)
-        if identity.load_private_key(prv_bytes):
-            return identity
-        else:
-            return None
-
-
     def __init__(self,create_keys=True):
         # Initialize keys to none
         self.prv           = None

RNS/Link.py

@@ -27,14 +27,13 @@ class LinkCallbacks:
 
 class Link:
     """
-    This class.
+    This class is used to establish and manage links to other peers. When a
+    link instance is created, Reticulum will attempt to establish verified
+    connectivity with the specified destination.
 
     :param destination: A :ref:`RNS.Destination<api-destination>` instance which to establish a link to.
-    :param established_callback: A function or method with the signature *callback(link)* to be called when the link has been established.
-    :param closed_callback: A function or method with the signature *callback(link)* to be called when the link is closed.
-    :param owner: Internal use by :ref:`RNS.Transport<api-Transport>`, ignore this argument.
-    :param peer_pub_bytes: Internal use, ignore this argument.
-    :param peer_sig_pub_bytes: Internal use, ignore this argument.
+    :param established_callback: An optional function or method with the signature *callback(link)* to be called when the link has been established.
+    :param closed_callback: An optional function or method with the signature *callback(link)* to be called when the link is closed.
     """
     CURVE = RNS.Identity.CURVE
     """
@@ -870,6 +869,12 @@ class Link:
 
 
 class RequestReceipt():
+    """
+    An instance of this class is returned by the ``request`` method of ``RNS.Link``
+    instances. It should never be instantiated manually. It provides methods to
+    check status, response time and response data when the request concludes.
+    """
+
     FAILED    = 0x00
     SENT      = 0x01
     DELIVERED = 0x02
@@ -942,7 +947,7 @@ class RequestReceipt():
             self.callbacks.failed(self)
 
     def response_resource_progress(self, resource):
-        self.progress = resource.progress()
+        self.progress = resource.get_progress()
         self.__resource_response_timeout = time.time()+self.timeout
 
         if self.callbacks.progress != None:
@@ -979,9 +984,41 @@ class RequestReceipt():
         if self.callbacks.response != None:
             self.callbacks.response(self)
 
-    def response_time(self):
+    def get_request_id(self):
+        """
+        :returns: The request ID as *bytes*.
+        """
+        return self.request_id
+
+    def get_status(self):
+        """
+        :returns: The current status of the request, one of ``RNS.RequestReceipt.FAILED``, ``RNS.RequestReceipt.SENT``, ``RNS.RequestReceipt.DELIVERED``, ``RNS.RequestReceipt.READY``.
+        """
+        return self.status
+
+    def get_progress(self):
+        """
+        :returns: The progress of a response being received as a *float* between 0.0 and 1.0.
+        """
+        return self.progress
+
+    def get_response(self):
+        """
+        :returns: The response as *bytes* if it is ready, otherwise *None*.
+        """
+        if self.status == RequestReceipt.READY:
+            return self.response
+        else:
+            return None
+
+    def get_response_time(self):
+        """
+        :returns: The response time of the request in seconds.
+        """
         if self.status == RequestReceipt.READY:
             return self.response_concluded_at - self.started_at
+        else:
+            return None
 
 
 

RNS/Packet.py

@@ -20,11 +20,6 @@ class Packet:
     :param destination: A :ref:`RNS.Destination<api-destination>` instance to which the packet will be sent.
     :param data: The data payload to be included in the packet as *bytes*.
     :param create_receipt: Specifies whether a :ref:`RNS.PacketReceipt<api-packetreceipt>` should be created when instantiating the packet.
-    :param type: Internal use by :ref:`RNS.Transport<api-transport>`. Defaults to ``RNS.Packet.DATA``, and should not be specified.
-    :param context: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
-    :param transport_type: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
-    :param transport_id: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
-    :param attached_interface: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
     """
 
     # Packet types
@@ -309,8 +304,8 @@ class PacketReceipt:
     """
     The PacketReceipt class is used to receive notifications about
     :ref:`RNS.Packet<api-packet>` instances sent over the network. Instances
-    of this class should never be created manually, but always returned
-    from a the *send()* method of a :ref:`RNS.Packet<api-packet>` instance.
+    of this class are never created manually, but always returned from
+    the *send()* method of a :ref:`RNS.Packet<api-packet>` instance.
     """
     # Receipt status constants
     FAILED    = 0x00

RNS/Resource.py

@@ -15,14 +15,10 @@ class Resource:
 
     :param data: The data to be transferred. Can be *bytes* or an open *file handle*. See the :ref:`Filetransfer Example<example-filetransfer>` for details.
     :param link: The :ref:`RNS.Link<api-link>` instance on which to transfer the data.
-    :param advertise: Whether to automatically advertise the resource. Can be *True* or *False*.
-    :param auto_compress: Whether to auto-compress the resource. Can be *True* or *False*.
-    :param callback: A *callable* with the signature *callback(resource)*. Will be called when the resource transfer concludes.
-    :param progress_callback: A *callable* with the signature *callback(resource)*. Will be called whenever the resource transfer progress is updated.
-    :param segment_index: Internal use, ignore.
-    :param original_hash: Internal use, ignore.
-    :param is_request: Internal use, ignore.
-    :param is_response: Internal use, ignore.
+    :param advertise: Optional. Whether to automatically advertise the resource. Can be *True* or *False*.
+    :param auto_compress: Optional. Whether to auto-compress the resource. Can be *True* or *False*.
+    :param callback: An optional *callable* with the signature *callback(resource)*. Will be called when the resource transfer concludes.
+    :param progress_callback: An optional *callable* with the signature *callback(resource)*. Will be called whenever the resource transfer progress is updated.
     """
     WINDOW_FLEXIBILITY   = 4
     WINDOW_MIN           = 1
@@ -756,7 +752,7 @@ class Resource:
     def progress_callback(self, callback):
         self.__progress_callback = callback
 
-    def progress(self):
+    def get_progress(self):
         """
         :returns: The current progress of the resource transfer as a *float* between 0.0 and 1.0.
         """

RNS/Reticulum.py

@@ -36,6 +36,8 @@ class Reticulum:
     other programs to use on demand.
     """
 
+    # Future minimum will probably be locked in at 244 bytes to support
+    # networks with segments of different MTUs. Absolute minimum is 211.
     MTU            = 500
     """
     The MTU that Reticulum adheres to, and will expect other peers to
@@ -44,8 +46,8 @@ class Reticulum:
     completely break compatibility with all other RNS networks. An identical
     MTU is a prerequisite for peers to communicate in the same network.
 
-    The absolute minimum MTU that Reticulum will function with is 215 bytes,
-    but bandwidth efficiency will be significantly impacted.
+    Unless you really know what you are doing, the MTU should be left at
+    the default value.
     """
 
     # Length of truncated hashes in bits.

RNS/Transport.py

@@ -9,6 +9,10 @@ from time import sleep
 from .vendor import umsgpack as umsgpack
 
 class Transport:
+    """
+    Through static methods of this class you can interact with Reticulums
+    Transport system.
+    """
     # Constants
     BROADCAST    = 0x00;
     TRANSPORT    = 0x01;

RNS/__init__.py

@@ -9,7 +9,7 @@ from ._version import __version__
 
 from .Reticulum import Reticulum
 from .Identity import Identity
-from .Link import Link
+from .Link import Link, RequestReceipt
 from .Transport import Transport
 from .Destination import Destination
 from .Packet import Packet