Documentation fixes

docs/api/accessories.rst

@@ -2,3 +2,4 @@ accessories
 -----------
 
 .. automodule:: telnetlib3.accessories
+   :members:

docs/api/client.rst

@@ -2,3 +2,4 @@ client
 ------
 
 .. automodule:: telnetlib3.client
+   :members:

docs/api/client_base.rst

@@ -2,3 +2,4 @@ client_base
 -----------
 
 .. automodule:: telnetlib3.client_base
+   :members:

docs/api/client_shell.rst

@@ -2,3 +2,4 @@ client_shell
 ------------
 
 .. automodule:: telnetlib3.client_shell
+   :members:

docs/api/server.rst

@@ -2,3 +2,4 @@ server
 ------
 
 .. automodule:: telnetlib3.server
+   :members:

docs/api/server_base.rst

@@ -2,3 +2,4 @@ server_base
 -----------
 
 .. automodule:: telnetlib3.server_base
+   :members:

docs/api/server_shell.rst

@@ -2,3 +2,4 @@ server_shell
 ------------
 
 .. automodule:: telnetlib3.server_shell
+   :members:

docs/api/slc.rst

@@ -2,3 +2,4 @@ slc
 ---
 
 .. automodule:: telnetlib3.slc
+   :members:

docs/api/stream_reader.rst

@@ -2,3 +2,4 @@ stream_reader
 -------------
 
 .. automodule:: telnetlib3.stream_reader
+   :members:

docs/api/stream_writer.rst

@@ -2,3 +2,4 @@ stream_writer
 -------------
 
 .. automodule:: telnetlib3.stream_writer
+   :members:

docs/api/telopt.rst

@@ -2,3 +2,4 @@ telopt
 ------
 
 .. automodule:: telnetlib3.telopt
+   :members:

docs/conf.py

@@ -232,7 +232,8 @@
 
 # when linking to standard python library, use and prefer python 3
 # documentation.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted.

telnetlib3/client.py

@@ -15,7 +15,7 @@
 from . import accessories
 from . import client_base
 
-__all__ = ('TelnetClient', 'open_connection')
+__all__ = ('TelnetClient', 'TelnetTerminalClient', 'open_connection')
 
 
 class TelnetClient(client_base.BaseClient):
@@ -95,7 +95,7 @@ def send_env(self, keys):
         :returns: dictionary of environment values requested, or an
             empty string for keys not available. A return value must be
             given for each key requested.
-        :rtype: dict[(key, value), ..]
+        :rtype: dict
         """
         env = {
             'LANG': self._extra['lang'],
@@ -118,11 +118,11 @@ def send_charset(self, offered):
 
         The default implementation selects any matching encoding that
         python is capable of using, preferring any that matches
-        :py:attr:`self.encoding` if matched in the offered list.
+        :py:attr:`encoding` if matched in the offered list.
 
         :param list offered: list of CHARSET options offered by server.
         :returns: character encoding agreed to be used.
-        :rtype: str or None.
+        :rtype: Union[str, None]
         """
         selected = ''
         for offer in offered:
@@ -166,13 +166,6 @@ def encoding(self, outgoing=None, incoming=None):
             ``BINARY`` :rfc:`856` has been negotiated for the direction
             indicated or :attr`force_binary` is set ``True``.
         :rtype: str
-
-        Value resolution order (first-matching):
-
-        - value set by :meth:`set_encoding`.
-        - value of :meth:`get_extra_info` using key argument, ``lang``.
-        - value of :attr:`default_encoding`.
-        - ``US-ASCII`` when binary transmission not allowed.
         """
         if not (outgoing or incoming):
             raise TypeError("encoding arguments 'outgoing' and 'incoming' "
@@ -252,14 +245,14 @@ def open_connection(host=None, port=23, *, client_factory=None, loop=None,
     :param client_base.BaseClient client_factory: Client connection class
         factory.  When ``None``, :class:`TelnetTerminalClient` is used when
         *stdin* is attached to a terminal, :class:`TelnetClient` otherwise.
-    :param asyncio.base_events.BaseEventLoop loop: set the event loop to use.
+    :param asyncio.AbstractEventLoop loop: set the event loop to use.
         The return value of :func:`asyncio.get_event_loop` is used when unset.
     :param int family: Same meaning as
-        :meth:`asyncio.BaseEventLoop.create_connection`.
+        :meth:`asyncio.loop.create_connection`.
     :param int flags: Same meaning as
-        :meth:`asyncio.BaseEventLoop.create_connection`.
+        :meth:`asyncio.loop.create_connection`.
     :param tuple local_addr: Same meaning as
-        :meth:`asyncio.BaseEventLoop.create_connection`.
+        :meth:`asyncio.loop.create_connection`.
     :param logging.Logger log: target logger, if None is given, one is created
         using the namespace ``'telnetlib3.server'``.
     :param str encoding: The default assumed encoding, or ``False`` to disable
@@ -283,10 +276,10 @@ def open_connection(host=None, port=23, *, client_factory=None, loop=None,
         :rfc:`1079`.
     :param str xdisploc: String transmitted in response for request of
         XDISPLOC, :rfc:`1086` by server (X11).
-    :param asyncio.coroutine shell: A coroutine that is called after
+    :param Callable shell: A :func:`asyncio.coroutine` that is called after
         negotiation completes, receiving arguments ``(reader, writer)``.
-        The reader is a :class:`TelnetStreamReader` instance, the writer is
-        a :class:`TelnetStreamWriter` instance.
+        The reader is a :class:`~.TelnetReader` instance, the writer is
+        a :class:`~.TelnetWriter` instance.
     :param float connect_minwait: The client allows any additional telnet
         negotiations to be demanded by the server within this period of time
         before launching the shell.  Servers should assert desired negotiation
@@ -302,16 +295,16 @@ def open_connection(host=None, port=23, *, client_factory=None, loop=None,
     :param bool force_binary: When ``True``, the encoding specified is used for
         both directions even when failing ``BINARY`` negotiation, :rfc:`856`.
         This parameter has no effect when ``encoding=False``.
-    :param str encoding_errors: Same meaning as :class:`codecs.Codec`.
+    :param str encoding_errors: Same meaning as :meth:`codecs.Codec.encode`.
     :param float connect_minwait: XXX
     :param float connect_maxwait: If the remote end is not complaint, or
         otherwise confused by our demands, the shell continues anyway after the
         greater of this value has elapsed.  A client that is not answering
         option negotiation will delay the start of the shell by this amount.
 
     :param int limit: The buffer limit for reader stream.
-    :return (reader, writer): The reader is a :class:`TelnetStreamReader`
-        instance, the writer is a :class:`TelnetStreamWriter` instance.
+    :return (reader, writer): The reader is a :class:`~.TelnetReader`
+        instance, the writer is a :class:`~.TelnetWriter` instance.
 
     This function is a :func:`~asyncio.coroutine`.
     """

telnetlib3/client_base.py

@@ -3,6 +3,7 @@
 import datetime
 import traceback
 import asyncio
+import weakref
 import sys
 
 from .stream_writer import TelnetWriter, TelnetWriterUnicode
@@ -17,7 +18,6 @@ class BaseClient(asyncio.streams.FlowControlMixin, asyncio.Protocol):
     _when_connected = None
     _last_received = None
     _transport = None
-    _advanced = False
     _closing = False
     _reader_factory = TelnetReader
     _reader_factory_encoding = TelnetReaderUnicode
@@ -33,15 +33,19 @@ def __init__(self, shell=None, log=None, loop=None,
         super().__init__(loop=loop)
         self.log = log or logging.getLogger('telnetlib3.client')
         self._loop = loop or asyncio.get_event_loop()
+        #: encoding for new connections
         self.default_encoding = encoding
         self._encoding_errors = encoding_errors
         self.force_binary = force_binary
         self._extra = dict()
         self.waiter_closed = waiter_closed or asyncio.Future()
+        #: a future used for testing
         self._waiter_connected = _waiter_connected or asyncio.Future()
         self._tasks = []
         self.shell = shell
+        #: minimum duration for :meth:`check_negotiation`.
         self.connect_minwait = connect_minwait
+        #: maximum duration for :meth:`check_negotiation`.
         self.connect_maxwait = connect_maxwait
         self.reader = None
         self.writer = None
@@ -85,20 +89,21 @@ def connection_lost(self, exc):
             # we are disconnected before negotiation may be considered
             # complete.  We set waiter_closed, and any function consuming
             # the StreamReader will receive eof.
-            self._waiter_connected.set_result(self)
+            self._waiter_connected.set_result(weakref.proxy(self))
 
         if self.shell is None:
             # when a shell is defined, we allow the completion of the coroutine
             # to set the result of waiter_closed.
-            self.waiter_closed.set_result(self)
+            self.waiter_closed.set_result(weakref.proxy(self))
+
+        # break circular references.
+        self._transport = None
+        self.reader.fn_encoding = None
 
     def connection_made(self, transport):
         """
         Called when a connection is made.
 
-        Sets attributes :attr:`_transport`, :attr:`_when_connected`,
-        :attr:`_last_received`, :attr:`reader` and :attr:`writer`.
-
         Ensure ``super().connection_made(transport)`` is called when derived.
         """
         self._transport = transport
@@ -150,7 +155,7 @@ def begin_shell(self, result):
                 # future.
                 fut = self._loop.create_task(coro)
                 fut.add_done_callback(
-                    lambda fut_obj: self.waiter_closed.set_result(self))
+                    lambda fut_obj: self.waiter_closed.set_result(weakref.proxy(self)))
 
     def data_received(self, data):
         """Process bytes received by transport."""
@@ -220,8 +225,8 @@ def encoding(self, outgoing=False, incoming=False):
         """
         Encoding that should be used for the direction indicated.
 
-        The base implementation **always** returns :attr:`default_encoding`
-        or, when unspecified, ``US-ASCII``.
+        The base implementation **always** returns ``encoding`` argument
+        given to class initializer or, when unset (``None``), ``US-ASCII``.
         """
         # pylint: disable=unused-argument
         return self.default_encoding or 'US-ASCII'  # pragma: no cover
@@ -235,9 +240,9 @@ def check_negotiation(self, final=False):
         :returns: Whether negotiation is over (client end is satisfied).
         :rtype: bool
 
-        Method is called on each new command byte processed until negotiation
-        is considered final, or after :attr:`connect_maxwait` has elapsed,
-        setting :attr:`_waiter_connected` to value ``self`` when complete.
+        Method is called on each new command byte processed until negotiation is
+        considered final, or after :attr:`connect_maxwait` has elapsed, setting
+        the ``_waiter_connected`` attribute to value ``self`` when complete.
 
         This method returns False until :attr:`connect_minwait` has elapsed,
         ensuring the server may batch telnet negotiation demands without
@@ -269,7 +274,7 @@ def _check_negotiation_timer(self):
         if self.check_negotiation(final=final):
             self.log.debug('negotiation complete after {:1.2f}s.'
                            .format(self.duration))
-            self._waiter_connected.set_result(self)
+            self._waiter_connected.set_result(weakref.proxy(self))
         elif final:
             self.log.debug('negotiation failed after {:1.2f}s.'
                            .format(self.duration))
@@ -278,7 +283,7 @@ def _check_negotiation_timer(self):
                        self.writer.pending_option.items()
                        if pending]
             self.log.debug('failed-reply: {0!r}'.format(', '.join(_failed)))
-            self._waiter_connected.set_result(self)
+            self._waiter_connected.set_result(weakref.proxy(self))
         else:
             # keep re-queuing until complete.  Aggressively re-queue until
             # connect_minwait, or connect_maxwait, whichever occurs next

telnetlib3/server.py

@@ -1,7 +1,7 @@
 """
-The :func:`main` function here is wired to the command line tool by name
-telnetlib3-server.  If this server's PID receives the SIGTERM signal,
-it attempts to shutdown gracefully.
+The ``main`` function here is wired to the command line tool by name
+telnetlib3-server.  If this server's PID receives the SIGTERM signal, it
+attempts to shutdown gracefully.
 
 The :class:`TelnetServer` class negotiates a character-at-a-time (WILL-SGA,
 WILL-ECHO) session with support for negotiation about window size, environment
@@ -148,13 +148,6 @@ def encoding(self, outgoing=None, incoming=None):
             ``BINARY`` :rfc:`856` has been negotiated for the direction
             indicated or :attr`force_binary` is set ``True``.
         :rtype: str
-
-        Value resolution order (first-matching):
-
-        - value set by :meth:`set_encoding`.
-        - value of :meth:`get_extra_info` using key argument, ``LANG``.
-        - value of :attr:`default_encoding`.
-        - ``US-ASCII`` when binary transmission not allowed.
         """
         if not (outgoing or incoming):
             raise TypeError("encoding arguments 'outgoing' and 'incoming' "
@@ -187,10 +180,9 @@ def set_timeout(self, duration=-1):
         Restart or unset timeout for client.
 
         :param int duration: When specified as a positive integer,
-            schedules Future :attr:`self.waiter_timeout` with attached
-            instance callback :meth:`timeout`.  When ``-1``, the value
-            of :meth:`get_extra_info` for keyword ``timeout`` is used.
-            When non-True, :attr:`waiter_timeout` is cancelled.
+            schedules Future for callback of :meth:`on_timeout`.  When ``-1``,
+            the value of ``self.get_extra_info('timeout')`` is used.  When
+            non-True, it is canceled.
         """
         if duration == -1:
             duration = self.get_extra_info('timeout')
@@ -232,7 +224,7 @@ def on_request_environ(self):
         """
         Definition for NEW_ENVIRON request of client, :rfc:`1572`.
 
-        This method is a callback from :meth:`TelnetWriter.request_environ`,
+        This method is a callback from :meth:`~.TelnetWriter.request_environ`,
         first entered on receipt of (WILL, NEW_ENVIRON) by server.  The return
         value *defines the request made to the client* for environment values.
 
@@ -277,7 +269,7 @@ def on_request_charset(self):
         """
         Definition for CHARSET request by client, :rfc:`2066`.
 
-        This method is a callback from :meth:`TelnetWriter.request_charset`,
+        This method is a callback from :meth:`~.TelnetWriter.request_charset`,
         first entered on receipt of (WILL, CHARSET) by server.  The return
         value *defines the request made to the client* for encodings.
 
@@ -388,10 +380,10 @@ def create_server(host=None, port=23, protocol_factory=TelnetServer, **kwds):
     :param server_base.BaseServer protocol_factory: An alternate protocol
         factory for the server, when unspecified, :class:`TelnetServer` is
         used.
-    :param asyncio.coroutine shell: A coroutine that is called after
+    :param Callable shell: A :func:`asyncio.coroutine` that is called after
         negotiation completes, receiving arguments ``(reader, writer)``.
-        The reader is a :class:`TelnetStreamReader` instance, the writer is
-        a :class:`TelnetStreamWriter` instance.
+        The reader is a :class:`~.TelnetReader` instance, the writer is
+        a :class:`~.TelnetWriter` instance.
     :param logging.Logger log: target logger, if None is given, one is created
         using the namespace ``'telnetlib3.server'``.
     :param str encoding: The default assumed encoding, or ``False`` to disable
@@ -402,8 +394,8 @@ def create_server(host=None, port=23, protocol_factory=TelnetServer, **kwds):
         The server's attached ``reader, writer`` streams accept and return
         unicode, unless this value explicitly set ``False``.  In that case, the
         attached streams interfaces are bytes-only.
-    :param str encoding_errors: Same meaning as :class:`codecs.Codec`.  Default
-        value is ``strict``.
+    :param str encoding_errors: Same meaning as :meth:`codecs.Codec.encode`.
+        Default value is ``strict``.
     :param bool force_binary: When ``True``, the encoding specified is
         used for both directions even when BINARY mode, :rfc:`856`, is not
         negotiated for the direction specified.  This parameter has no effect
@@ -426,8 +418,8 @@ def create_server(host=None, port=23, protocol_factory=TelnetServer, **kwds):
     :param int limit: The buffer limit for the reader stream.
 
     :return asyncio.Server: The return value is the same as
-        :func:`loop.create_server`, An object which can be used to stop the
-        service.
+        :meth:`asyncio.loop.create_server`, An object which can be used
+        to stop the service.
 
     This function is a :func:`~asyncio.coroutine`.
     """