More complete narrative and reference documentation. (#63)

Co-authored-by: Robert Smallshire <[email protected]>

Author: rob-smallshire

documentation/api.rst

@@ -2,55 +2,88 @@
  pySerial-asyncio API
 ======================
 
-asyncio
-=======
-
 .. module:: serial_asyncio
 
-.. warning:: This implementation is currently in an experimental state. Use
-    at your own risk.
 
-Experimental asyncio support is available for Python 3.4 and newer. The module
-:mod:`serial_asyncio` provides a :class:`asyncio.Transport`:
-``SerialTransport``.
+The following high-level functions are provided for initiating a serial connection:
+
+.. function:: create_serial_connection(loop, protocol_factory, *args, **kwargs)
+    :async:
+
+    Open a streaming connection to the specified serial port.
+
+    :param loop: The *asyncio* event loop
+    :param protocol_factory: A callable which when invoked without arguments and which should
+        return a :class:`asyncio.Protocol` subclass. Most commonly the protocol *class*
+        (*e.g.* ``MyProtocol``) can be passed as this argument. If it is required to use an
+        existing protocol *instance*, pass a zero-argument lambda which evaluates to the instance,
+        such as ``lambda: my_protocol``
+    :param args: Forwarded to the :class:`serial.Serial` constructor
+    :param kwargs: Forwarded to the :class:`serial.Serial` constructor
+    :returns: A coroutine for managing a serial port connection, which when
+        awaited returns transport and protocol instances.
+    :platform: Posix
+
+    Use this function to associate an asynchronous call-back based protocol with an
+    new :class:`serial.Serial` instance that will be created on your behalf.
+
+    The chronological order of the operation is:
+
+    1. ``protocol_factory`` is called without arguments and must return
+       a :class:`asyncio.Protocol` subclass instance.
+
+    2. The protocol instance is tied to a :class:`~serial_asyncio.SerialTransport`.
 
+    3. This coroutine returns successfully with a ``(transport, protocol)`` pair.
 
-A factory function (`asyncio.coroutine`) is provided:
+    4. The :meth:`~serial_asyncio.SerialTransport.connection_made()` method of the protocol
+       will be called at some point by the event loop.
 
-.. function:: create_serial_connection(loop, protocol_factory, \*args, \*\*kwargs)
 
-    :param loop: The event handler
-    :param protocol_factory: Factory function for a :class:`asyncio.Protocol`
-    :param args: Passed to the :class:`serial.Serial` init function
-    :param kwargs: Passed to the :class:`serial.Serial` init function
+
+.. function:: connection_for_serial(loop, protocol_factory, serial_instance)
+    :async:
+
+    Open a streaming connection to an existing serial port instance.
+
+    :param loop: The *asyncio* event loop
+    :param protocol_factory: A callable which when invoked without arguments and which should
+        return a :class:`asyncio.Protocol` subclass. Most commonly the protocol *class*
+        (*e.g.* ``MyProtocol``) can be passed as this argument. If it is required to use an
+        existing protocol *instance*, pass a zero-argument lambda which evaluates to the instance,
+        such as ``lambda: my_protocol``
+    :param serial_instance: A :class:`serial.Serial` instance.
+    :returns: A coroutine for managing a serial port connection, which when
+        awaited returns transport and protocol instances.
     :platform: Posix
 
-    Get a connection making coroutine.
+    Use this function to associate an asynchronous call-back based protocol with an
+    existing :class:`serial.Serial` instance.
+
+    The chronological order of the operation is:
 
-Example::
+    1. ``protocol_factory`` is called without arguments and must return
+       a :class:`asyncio.Protocol` subclass instance.
 
-    import asyncio
-    import serial_asyncio
-    
-    
-    class Output(asyncio.Protocol):
-        def connection_made(self, transport):
-            self.transport = transport
-            print('port opened', transport)
-            transport.serial.rts = False
-            transport.write(b'hello world\n')
+    2. The protocol instance is tied to a :class:`~serial_asyncio.SerialTransport`.
 
-        def data_received(self, data):
-            print('data received', repr(data))
-            self.transport.close()
+    3. This coroutine returns successfully with a ``(transport, protocol)`` pair.
 
-        def connection_lost(self, exc):
-            print('port closed')
-            asyncio.get_event_loop().stop()
+    4. The :meth:`~serial_asyncio.SerialTransport.connection_made()` method of the protocol
+       will be called at some point by the event loop.
 
-    loop = asyncio.get_event_loop()
-    coro = serial_asyncio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
-    loop.run_until_complete(coro)
-    loop.run_forever()
-    loop.close()
 
+.. function:: open_serial_connection(*, loop=None, limit=None, **kwargs)
+    :async:
+
+    Open a streaming connection to an existing serial port instance.
+
+    :param loop: The *asyncio* event loop
+    :param limit: A optional buffer limit in bytes for the :class:`asyncio.StreamReader`
+    :param kwargs: Forwarded to the :class:`serial.Serial` constructor
+    :returns: A coroutine for managing a serial port connection, which when
+        awaited returns an :class:`asyncio.StreamReader` and a :class:`asyncio.StreamWriter`.
+    :platform: Posix
+
+    Use this function to open connections where serial traffic is handled by
+    an asynchronous coroutine interacting with :class:`asyncio.StreamReader` and a :class:`asyncio.StreamWriter` objects.

documentation/conf.py

@@ -22,7 +22,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx']
+extensions = [
+    'sphinx.ext.intersphinx',
+    'sphinx_rtd_theme',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -38,7 +41,7 @@
 
 # General information about the project.
 project = u'pySerial-asyncio'
-copyright = u'2015-2017, pySerial-team'
+copyright = u'2015-2020, pySerial-team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -81,7 +84,7 @@
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+#pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -91,7 +94,7 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-#html_theme = 'default'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -195,6 +198,6 @@
 
 # for external links to standard library
 intersphinx_mapping = {
-        #~ 'python': ('http://docs.python.org', None),
-        'py': ('http://docs.python.org', None),
-        }
+    'python': ('https://docs.python.org/3', None),
+    'pyserial': ('https://pyserial.readthedocs.io/en/latest', None),
+}

documentation/index.rst

@@ -5,9 +5,9 @@ Welcome to pySerial-asyncio's documentation
 
 `Async I/O`_ extension for the `Python Serial Port`_ package for OSX, Linux, BSD
 
-It depends on pySerial and is compatible with Python 3.4 and later.
+It depends on pySerial and is compatible with Python 3.5 and later.
 
-.. _`Async I/O`: https://www.python.org/dev/peps/pep-3156/
+.. _`Async I/O`: https://docs.python.org/3/library/asyncio.html
 .. _`Python Serial Port`: https://pypi.python.org/pypi/pyserial
 
 

documentation/shortintro.rst

@@ -1,13 +1,63 @@
-==================
-Short introduction
-==================
+========
+Overview
+========
+
+Serial transports, protocols and streams
+----------------------------------------
+
+This module layers `asyncio <https://docs.python.org/3/library/asyncio.html>`_ support onto
+`pySerial <http://pyserial.readthedocs.io/>`_. It provides support for working with serial
+ports through *asyncio*
+`Transports <https://docs.python.org/3/library/asyncio-protocol.html#transports>`_,
+`Protocols <https://docs.python.org/3/library/asyncio-protocol.html#protocols>`_, and
+`Streams <https://docs.python.org/3/library/asyncio-stream.html>`_.
+
+Transports are a low-level abstraction, provided by this package in the form of an
+:class:`asyncio.Transport` implementation called :class:`SerialTransport`, which manages the
+asynchronous transmission of data through an underlying *pySerial* :class:`~serial.Serial`
+instance. Transports are concerned with *how* bytes are transmitted through the serial port.
+
+Protocols are a callback-based abstraction which determine *which* bytes are transmitted
+through an underlying transport. You can implement a subclass of :class:`asyncio.Protocol` which
+reads from, and/or writes to, a :class:`~serial_asyncio.SerialTransport`. When a serial connection
+is established your protocol will be handed a transport, to which your protocol
+implementation can write data as necessary. Incoming data and other serial connection lifecycle
+events cause callbacks on your protocol to be invoked, so it can take action as necessary.
+
+Usually, you will not create a :class:`~serial_asyncio.SerialTransport` directly. Rather, you will
+define a ``Protocol`` class and pass that protocol to a function such as
+:func:`~serial_asyncio.create_serial_connection()` which will instantiate your ``Protocol`` and
+connect it to a :class:`~serial_asyncio.SerialTransport`.
+
+Streams are a coroutine-based alternative to callback-based protocols. This package provides a
+function :func:`~serial_asyncio.open_serial_connection` which returns :class:`asyncio.StreamReader`
+and :class:`asyncio.StreamWriter` objects for interacting with underlying protocol and transport
+objects, which this library will create for you.
+
+
+Protocol Example
+----------------
+
+This example defines a very simple Protocol which sends a greeting message through the serial port
+and displays to the console any data received through the serial port, until a newline byte is
+received.
+
+A call is made to :func:`create_serial_connection()`, to which the protocol *class* (not an
+instance) is passed, together with arguments destined for the :class:`~serial.Serial` constructor.
+This call returns a coroutine object. When passed to :func:`~asyncio.run_until_complete` the
+coroutine is scheduled to run as an :class:`asyncio.Task` by the *asyncio* library, and the result
+of the coroutine, which is a tuple containing the transport and protocol instances, return to the
+caller.
+
+While the event loop is running (:meth:`~asyncio.AbstractEventLoop.loop.run_forever`), or until
+the protocol closes the transport itself, the protocol will process data received through the serial
+port asynchronously::
 
-Example::
 
     import asyncio
     import serial_asyncio
 
-    class Output(asyncio.Protocol):
+    class OutputProtocol(asyncio.Protocol):
         def connection_made(self, transport):
             self.transport = transport
             print('port opened', transport)
@@ -32,8 +82,8 @@ Example::
             print('resume writing')
 
     loop = asyncio.get_event_loop()
-    coro = serial_asyncio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
-    loop.run_until_complete(coro)
+    coro = serial_asyncio.create_serial_connection(loop, OutputProtocol, '/dev/ttyUSB0', baudrate=115200)
+    transport, protocol = loop.run_until_complete(coro)
     loop.run_forever()
     loop.close()
 

serial_asyncio/__init__.py

@@ -465,7 +465,7 @@ async def connection_for_serial(loop, protocol_factory, serial_instance):
 
 async def open_serial_connection(*,
                            loop=None,
-                           limit=asyncio.streams._DEFAULT_LIMIT,
+                           limit=None,
                            **kwargs):
     """A wrapper for create_serial_connection() returning a (reader,
     writer) pair.
@@ -482,6 +482,8 @@ async def open_serial_connection(*,
     """
     if loop is None:
         loop = asyncio.get_event_loop()
+    if limit is None:
+        limit = asyncio.streams._DEFAULT_LIMIT
     reader = asyncio.StreamReader(limit=limit, loop=loop)
     protocol = asyncio.StreamReaderProtocol(reader, loop=loop)
     transport, _ = await create_serial_connection(
@@ -526,6 +528,6 @@ def resume_writing(self):
 
     loop = asyncio.get_event_loop()
     coro = create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
-    loop.run_until_complete(coro)
+    transport, protocol = loop.run_until_complete(coro)
     loop.run_forever()
     loop.close()