Docs: structure the ftplib reference (#114317)

Introduce the following headings and subheadings:

- Reference
  * FTP objects
  * FTP_TLS objects
  * Module variables

1 files changed, 250 insertions, 244 deletions

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index d1fe641..6c44b8d 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -45,7 +45,15 @@ Here's a sample session using the :mod:`ftplib` module::
    '221 Goodbye.'
 
 
-The module defines the following items:
+.. _ftplib-reference:
+
+Reference
+---------
+
+.. _ftp-objects:
+
+FTP objects
+^^^^^^^^^^^
 
 .. class:: FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')
 
@@ -85,376 +93,374 @@ The module defines the following items:
       The *encoding* parameter was added, and the default was changed from
       Latin-1 to UTF-8 to follow :rfc:`2640`.
 
-.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None,
-                   timeout=None, source_address=None, encoding='utf-8')
+   Several :class:`!FTP` methods are available in two flavors:
+   one for handling text files and another for binary files.
+   The methods are named for the command which is used followed by
+   ``lines`` for the text version or ``binary`` for the binary version.
 
-   A :class:`FTP` subclass which adds TLS support to FTP as described in
-   :rfc:`4217`.
-   Connect as usual to port 21 implicitly securing the FTP control connection
-   before authenticating. Securing the data connection requires the user to
-   explicitly ask for it by calling the :meth:`prot_p` method.  *context*
-   is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
-   options, certificates and private keys into a single (potentially
-   long-lived) structure.  Please read :ref:`ssl-security` for best practices.
+   :class:`FTP` instances have the following methods:
 
-   .. versionadded:: 3.2
+   .. method:: FTP.set_debuglevel(level)
 
-   .. versionchanged:: 3.3
-      *source_address* parameter was added.
+      Set the instance's debugging level.  This controls the amount of debugging
+      output printed.  The default, ``0``, produces no debugging output.  A value of
+      ``1`` produces a moderate amount of debugging output, generally a single line
+      per request.  A value of ``2`` or higher produces the maximum amount of
+      debugging output, logging each line sent and received on the control connection.
 
-   .. versionchanged:: 3.4
-      The class now supports hostname check with
-      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
-      :const:`ssl.HAS_SNI`).
 
-   .. versionchanged:: 3.9
-      If the *timeout* parameter is set to be zero, it will raise a
-      :class:`ValueError` to prevent the creation of a non-blocking socket.
-      The *encoding* parameter was added, and the default was changed from
-      Latin-1 to UTF-8 to follow :rfc:`2640`.
+   .. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
 
-   .. versionchanged:: 3.12
-      The deprecated *keyfile* and *certfile* parameters have been removed.
+      Connect to the given host and port.  The default port number is ``21``, as
+      specified by the FTP protocol specification.  It is rarely needed to specify a
+      different port number.  This function should be called only once for each
+      instance; it should not be called at all if a host was given when the instance
+      was created.  All other methods can only be used after a connection has been
+      made.
+      The optional *timeout* parameter specifies a timeout in seconds for the
+      connection attempt. If no *timeout* is passed, the global default timeout
+      setting will be used.
+      *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
+      its source address before connecting.
 
-   Here's a sample session using the :class:`FTP_TLS` class::
+      .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
 
-      >>> ftps = FTP_TLS('ftp.pureftpd.org')
-      >>> ftps.login()
-      '230 Anonymous user logged in'
-      >>> ftps.prot_p()
-      '200 Data protection level set to "private"'
-      >>> ftps.nlst()
-      ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
+      .. versionchanged:: 3.3
+         *source_address* parameter was added.
 
 
-.. exception:: error_reply
+   .. method:: FTP.getwelcome()
 
-   Exception raised when an unexpected reply is received from the server.
+      Return the welcome message sent by the server in reply to the initial
+      connection.  (This message sometimes contains disclaimers or help information
+      that may be relevant to the user.)
 
 
-.. exception:: error_temp
+   .. method:: FTP.login(user='anonymous', passwd='', acct='')
 
-   Exception raised when an error code signifying a temporary error (response
-   codes in the range 400--499) is received.
-
-
-.. exception:: error_perm
-
-   Exception raised when an error code signifying a permanent error (response
-   codes in the range 500--599) is received.
+      Log in as the given *user*.  The *passwd* and *acct* parameters are optional and
+      default to the empty string.  If no *user* is specified, it defaults to
+      ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is
+      ``'anonymous@'``.  This function should be called only once for each instance,
+      after a connection has been established; it should not be called at all if a
+      host and user were given when the instance was created.  Most FTP commands are
+      only allowed after the client has logged in.  The *acct* parameter supplies
+      "accounting information"; few systems implement this.
 
 
-.. exception:: error_proto
+   .. method:: FTP.abort()
 
-   Exception raised when a reply is received from the server that does not fit
-   the response specifications of the File Transfer Protocol, i.e. begin with a
-   digit in the range 1--5.
+      Abort a file transfer that is in progress.  Using this does not always work, but
+      it's worth a try.
 
 
-.. data:: all_errors
+   .. method:: FTP.sendcmd(cmd)
 
-   The set of all exceptions (as a tuple) that methods of :class:`FTP`
-   instances may raise as a result of problems with the FTP connection (as
-   opposed to programming errors made by the caller).  This set includes the
-   four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`.
+      Send a simple command string to the server and return the response string.
 
+      .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
 
-.. seealso::
 
-   Module :mod:`netrc`
-      Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is
-      typically used by FTP clients to load user authentication information
-      before prompting the user.
+   .. method:: FTP.voidcmd(cmd)
 
+      Send a simple command string to the server and handle the response.  Return
+      nothing if a response code corresponding to success (codes in the range
+      200--299) is received.  Raise :exc:`error_reply` otherwise.
 
-.. _ftp-objects:
+      .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
 
-FTP Objects
------------
 
-Several methods are available in two flavors: one for handling text files and
-another for binary files.  These are named for the command which is used
-followed by ``lines`` for the text version or ``binary`` for the binary version.
+   .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
 
-:class:`FTP` instances have the following methods:
+      Retrieve a file in binary transfer mode.  *cmd* should be an appropriate
+      ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
+      each block of data received, with a single bytes argument giving the data
+      block. The optional *blocksize* argument specifies the maximum chunk size to
+      read on the low-level socket object created to do the actual transfer (which
+      will also be the largest size of the data blocks passed to *callback*).  A
+      reasonable default is chosen. *rest* means the same thing as in the
+      :meth:`transfercmd` method.
 
 
-.. method:: FTP.set_debuglevel(level)
+   .. method:: FTP.retrlines(cmd, callback=None)
 
-   Set the instance's debugging level.  This controls the amount of debugging
-   output printed.  The default, ``0``, produces no debugging output.  A value of
-   ``1`` produces a moderate amount of debugging output, generally a single line
-   per request.  A value of ``2`` or higher produces the maximum amount of
-   debugging output, logging each line sent and received on the control connection.
+      Retrieve a file or directory listing in the encoding specified by the
+      *encoding* parameter at initialization.
+      *cmd* should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or
+      a command such as ``LIST`` or ``NLST`` (usually just the string ``'LIST'``).
+      ``LIST`` retrieves a list of files and information about those files.
+      ``NLST`` retrieves a list of file names.
+      The *callback* function is called for each line with a string argument
+      containing the line with the trailing CRLF stripped.  The default *callback*
+      prints the line to ``sys.stdout``.
 
 
-.. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
+   .. method:: FTP.set_pasv(val)
 
-   Connect to the given host and port.  The default port number is ``21``, as
-   specified by the FTP protocol specification.  It is rarely needed to specify a
-   different port number.  This function should be called only once for each
-   instance; it should not be called at all if a host was given when the instance
-   was created.  All other methods can only be used after a connection has been
-   made.
-   The optional *timeout* parameter specifies a timeout in seconds for the
-   connection attempt. If no *timeout* is passed, the global default timeout
-   setting will be used.
-   *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
-   its source address before connecting.
+      Enable "passive" mode if *val* is true, otherwise disable passive mode.
+      Passive mode is on by default.
 
-   .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
 
-   .. versionchanged:: 3.3
-      *source_address* parameter was added.
+   .. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
 
+      Store a file in binary transfer mode.  *cmd* should be an appropriate
+      ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object`
+      (opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read`
+      method in blocks of size *blocksize* to provide the data to be stored.
+      The *blocksize* argument defaults to 8192.  *callback* is an optional single
+      parameter callable that is called on each block of data after it is sent.
+      *rest* means the same thing as in the :meth:`transfercmd` method.
 
-.. method:: FTP.getwelcome()
+      .. versionchanged:: 3.2
+         *rest* parameter added.
 
-   Return the welcome message sent by the server in reply to the initial
-   connection.  (This message sometimes contains disclaimers or help information
-   that may be relevant to the user.)
 
+   .. method:: FTP.storlines(cmd, fp, callback=None)
 
-.. method:: FTP.login(user='anonymous', passwd='', acct='')
+      Store a file in line mode.  *cmd* should be an appropriate
+      ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
+      :term:`file object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline`
+      method to provide the data to be stored.  *callback* is an optional single
+      parameter callable that is called on each line after it is sent.
 
-   Log in as the given *user*.  The *passwd* and *acct* parameters are optional and
-   default to the empty string.  If no *user* is specified, it defaults to
-   ``'anonymous'``.  If *user* is ``'anonymous'``, the default *passwd* is
-   ``'anonymous@'``.  This function should be called only once for each instance,
-   after a connection has been established; it should not be called at all if a
-   host and user were given when the instance was created.  Most FTP commands are
-   only allowed after the client has logged in.  The *acct* parameter supplies
-   "accounting information"; few systems implement this.
 
+   .. method:: FTP.transfercmd(cmd, rest=None)
 
-.. method:: FTP.abort()
+      Initiate a transfer over the data connection.  If the transfer is active, send an
+      ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
+      accept the connection.  If the server is passive, send an ``EPSV`` or ``PASV``
+      command, connect to it, and start the transfer command.  Either way, return the
+      socket for the connection.
 
-   Abort a file transfer that is in progress.  Using this does not always work, but
-   it's worth a try.
+      If optional *rest* is given, a ``REST`` command is sent to the server, passing
+      *rest* as an argument.  *rest* is usually a byte offset into the requested file,
+      telling the server to restart sending the file's bytes at the requested offset,
+      skipping over the initial bytes.  Note however that the :meth:`transfercmd`
+      method converts *rest* to a string with the *encoding* parameter specified
+      at initialization, but no check is performed on the string's contents.  If the
+      server does not recognize the ``REST`` command, an :exc:`error_reply` exception
+      will be raised.  If this happens, simply call :meth:`transfercmd` without a
+      *rest* argument.
 
 
-.. method:: FTP.sendcmd(cmd)
+   .. method:: FTP.ntransfercmd(cmd, rest=None)
 
-   Send a simple command string to the server and return the response string.
+      Like :meth:`transfercmd`, but returns a tuple of the data connection and the
+      expected size of the data.  If the expected size could not be computed, ``None``
+      will be returned as the expected size.  *cmd* and *rest* means the same thing as
+      in :meth:`transfercmd`.
 
-   .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
 
+   .. method:: FTP.mlsd(path="", facts=[])
 
-.. method:: FTP.voidcmd(cmd)
+      List a directory in a standardized format by using ``MLSD`` command
+      (:rfc:`3659`).  If *path* is omitted the current directory is assumed.
+      *facts* is a list of strings representing the type of information desired
+      (e.g. ``["type", "size", "perm"]``).  Return a generator object yielding a
+      tuple of two elements for every file found in path.  First element is the
+      file name, the second one is a dictionary containing facts about the file
+      name.  Content of this dictionary might be limited by the *facts* argument
+      but server is not guaranteed to return all requested facts.
 
-   Send a simple command string to the server and handle the response.  Return
-   nothing if a response code corresponding to success (codes in the range
-   200--299) is received.  Raise :exc:`error_reply` otherwise.
+      .. versionadded:: 3.3
 
-   .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
 
+   .. method:: FTP.nlst(argument[, ...])
 
-.. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
+      Return a list of file names as returned by the ``NLST`` command.  The
+      optional *argument* is a directory to list (default is the current server
+      directory).  Multiple arguments can be used to pass non-standard options to
+      the ``NLST`` command.
 
-   Retrieve a file in binary transfer mode.  *cmd* should be an appropriate
-   ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
-   each block of data received, with a single bytes argument giving the data
-   block. The optional *blocksize* argument specifies the maximum chunk size to
-   read on the low-level socket object created to do the actual transfer (which
-   will also be the largest size of the data blocks passed to *callback*).  A
-   reasonable default is chosen. *rest* means the same thing as in the
-   :meth:`transfercmd` method.
+      .. note:: If your server supports the command, :meth:`mlsd` offers a better API.
 
 
-.. method:: FTP.retrlines(cmd, callback=None)
+   .. method:: FTP.dir(argument[, ...])
 
-   Retrieve a file or directory listing in the encoding specified by the
-   *encoding* parameter at initialization.
-   *cmd* should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or
-   a command such as ``LIST`` or ``NLST`` (usually just the string ``'LIST'``).
-   ``LIST`` retrieves a list of files and information about those files.
-   ``NLST`` retrieves a list of file names.
-   The *callback* function is called for each line with a string argument
-   containing the line with the trailing CRLF stripped.  The default *callback*
-   prints the line to ``sys.stdout``.
+      Produce a directory listing as returned by the ``LIST`` command, printing it to
+      standard output.  The optional *argument* is a directory to list (default is the
+      current server directory).  Multiple arguments can be used to pass non-standard
+      options to the ``LIST`` command.  If the last argument is a function, it is used
+      as a *callback* function as for :meth:`retrlines`; the default prints to
+      ``sys.stdout``.  This method returns ``None``.
 
+      .. note:: If your server supports the command, :meth:`mlsd` offers a better API.
 
-.. method:: FTP.set_pasv(val)
 
-   Enable "passive" mode if *val* is true, otherwise disable passive mode.
-   Passive mode is on by default.
+   .. method:: FTP.rename(fromname, toname)
 
+      Rename file *fromname* on the server to *toname*.
 
-.. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
 
-   Store a file in binary transfer mode.  *cmd* should be an appropriate
-   ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object`
-   (opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read`
-   method in blocks of size *blocksize* to provide the data to be stored.
-   The *blocksize* argument defaults to 8192.  *callback* is an optional single
-   parameter callable that is called on each block of data after it is sent.
-   *rest* means the same thing as in the :meth:`transfercmd` method.
+   .. method:: FTP.delete(filename)
 
-   .. versionchanged:: 3.2
-      *rest* parameter added.
+      Remove the file named *filename* from the server.  If successful, returns the
+      text of the response, otherwise raises :exc:`error_perm` on permission errors or
+      :exc:`error_reply` on other errors.
 
 
-.. method:: FTP.storlines(cmd, fp, callback=None)
+   .. method:: FTP.cwd(pathname)
 
-   Store a file in line mode.  *cmd* should be an appropriate
-   ``STOR`` command (see :meth:`storbinary`).  Lines are read until EOF from the
-   :term:`file object` *fp* (opened in binary mode) using its :meth:`~io.IOBase.readline`
-   method to provide the data to be stored.  *callback* is an optional single
-   parameter callable that is called on each line after it is sent.
+      Set the current directory on the server.
 
 
-.. method:: FTP.transfercmd(cmd, rest=None)
+   .. method:: FTP.mkd(pathname)
 
-   Initiate a transfer over the data connection.  If the transfer is active, send an
-   ``EPRT`` or  ``PORT`` command and the transfer command specified by *cmd*, and
-   accept the connection.  If the server is passive, send an ``EPSV`` or ``PASV``
-   command, connect to it, and start the transfer command.  Either way, return the
-   socket for the connection.
+      Create a new directory on the server.
 
-   If optional *rest* is given, a ``REST`` command is sent to the server, passing
-   *rest* as an argument.  *rest* is usually a byte offset into the requested file,
-   telling the server to restart sending the file's bytes at the requested offset,
-   skipping over the initial bytes.  Note however that the :meth:`transfercmd`
-   method converts *rest* to a string with the *encoding* parameter specified
-   at initialization, but no check is performed on the string's contents.  If the
-   server does not recognize the ``REST`` command, an :exc:`error_reply` exception
-   will be raised.  If this happens, simply call :meth:`transfercmd` without a
-   *rest* argument.
 
+   .. method:: FTP.pwd()
 
-.. method:: FTP.ntransfercmd(cmd, rest=None)
+      Return the pathname of the current directory on the server.
 
-   Like :meth:`transfercmd`, but returns a tuple of the data connection and the
-   expected size of the data.  If the expected size could not be computed, ``None``
-   will be returned as the expected size.  *cmd* and *rest* means the same thing as
-   in :meth:`transfercmd`.
 
+   .. method:: FTP.rmd(dirname)
 
-.. method:: FTP.mlsd(path="", facts=[])
+      Remove the directory named *dirname* on the server.
 
-   List a directory in a standardized format by using ``MLSD`` command
-   (:rfc:`3659`).  If *path* is omitted the current directory is assumed.
-   *facts* is a list of strings representing the type of information desired
-   (e.g. ``["type", "size", "perm"]``).  Return a generator object yielding a
-   tuple of two elements for every file found in path.  First element is the
-   file name, the second one is a dictionary containing facts about the file
-   name.  Content of this dictionary might be limited by the *facts* argument
-   but server is not guaranteed to return all requested facts.
 
-   .. versionadded:: 3.3
+   .. method:: FTP.size(filename)
 
+      Request the size of the file named *filename* on the server.  On success, the
+      size of the file is returned as an integer, otherwise ``None`` is returned.
+      Note that the ``SIZE`` command is not  standardized, but is supported by many
+      common server implementations.
 
-.. method:: FTP.nlst(argument[, ...])
 
-   Return a list of file names as returned by the ``NLST`` command.  The
-   optional *argument* is a directory to list (default is the current server
-   directory).  Multiple arguments can be used to pass non-standard options to
-   the ``NLST`` command.
+   .. method:: FTP.quit()
 
-   .. note:: If your server supports the command, :meth:`mlsd` offers a better API.
+      Send a ``QUIT`` command to the server and close the connection. This is the
+      "polite" way to close a connection, but it may raise an exception if the server
+      responds with an error to the ``QUIT`` command.  This implies a call to the
+      :meth:`close` method which renders the :class:`FTP` instance useless for
+      subsequent calls (see below).
 
 
-.. method:: FTP.dir(argument[, ...])
+   .. method:: FTP.close()
 
-   Produce a directory listing as returned by the ``LIST`` command, printing it to
-   standard output.  The optional *argument* is a directory to list (default is the
-   current server directory).  Multiple arguments can be used to pass non-standard
-   options to the ``LIST`` command.  If the last argument is a function, it is used
-   as a *callback* function as for :meth:`retrlines`; the default prints to
-   ``sys.stdout``.  This method returns ``None``.
+      Close the connection unilaterally.  This should not be applied to an already
+      closed connection such as after a successful call to :meth:`~FTP.quit`.
+      After this call the :class:`FTP` instance should not be used any more (after
+      a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
+      connection by issuing another :meth:`login` method).
 
-   .. note:: If your server supports the command, :meth:`mlsd` offers a better API.
 
+FTP_TLS objects
+^^^^^^^^^^^^^^^
 
-.. method:: FTP.rename(fromname, toname)
+.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None,
+                   timeout=None, source_address=None, encoding='utf-8')
 
-   Rename file *fromname* on the server to *toname*.
+   A :class:`FTP` subclass which adds TLS support to FTP as described in
+   :rfc:`4217`.
+   Connect as usual to port 21 implicitly securing the FTP control connection
+   before authenticating. Securing the data connection requires the user to
+   explicitly ask for it by calling the :meth:`prot_p` method.  *context*
+   is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
+   options, certificates and private keys into a single (potentially
+   long-lived) structure.  Please read :ref:`ssl-security` for best practices.
 
+   .. versionadded:: 3.2
 
-.. method:: FTP.delete(filename)
+   .. versionchanged:: 3.3
+      *source_address* parameter was added.
 
-   Remove the file named *filename* from the server.  If successful, returns the
-   text of the response, otherwise raises :exc:`error_perm` on permission errors or
-   :exc:`error_reply` on other errors.
+   .. versionchanged:: 3.4
+      The class now supports hostname check with
+      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
+      :const:`ssl.HAS_SNI`).
 
+   .. versionchanged:: 3.9
+      If the *timeout* parameter is set to be zero, it will raise a
+      :class:`ValueError` to prevent the creation of a non-blocking socket.
+      The *encoding* parameter was added, and the default was changed from
+      Latin-1 to UTF-8 to follow :rfc:`2640`.
 
-.. method:: FTP.cwd(pathname)
+   .. versionchanged:: 3.12
+      The deprecated *keyfile* and *certfile* parameters have been removed.
 
-   Set the current directory on the server.
+   Here's a sample session using the :class:`FTP_TLS` class::
 
+      >>> ftps = FTP_TLS('ftp.pureftpd.org')
+      >>> ftps.login()
+      '230 Anonymous user logged in'
+      >>> ftps.prot_p()
+      '200 Data protection level set to "private"'
+      >>> ftps.nlst()
+      ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
 
-.. method:: FTP.mkd(pathname)
+   :class:`!FTP_TLS` class inherits from :class:`FTP`,
+   defining these additional methods and attributes:
 
-   Create a new directory on the server.
+   .. attribute:: FTP_TLS.ssl_version
 
+      The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
 
-.. method:: FTP.pwd()
+   .. method:: FTP_TLS.auth()
 
-   Return the pathname of the current directory on the server.
+      Set up a secure control connection by using TLS or SSL, depending on what
+      is specified in the :attr:`ssl_version` attribute.
 
+      .. versionchanged:: 3.4
+         The method now supports hostname check with
+         :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
+         :const:`ssl.HAS_SNI`).
 
-.. method:: FTP.rmd(dirname)
+   .. method:: FTP_TLS.ccc()
 
-   Remove the directory named *dirname* on the server.
+      Revert control channel back to plaintext.  This can be useful to take
+      advantage of firewalls that know how to handle NAT with non-secure FTP
+      without opening fixed ports.
 
+      .. versionadded:: 3.3
 
-.. method:: FTP.size(filename)
+   .. method:: FTP_TLS.prot_p()
 
-   Request the size of the file named *filename* on the server.  On success, the
-   size of the file is returned as an integer, otherwise ``None`` is returned.
-   Note that the ``SIZE`` command is not  standardized, but is supported by many
-   common server implementations.
+      Set up secure data connection.
 
+   .. method:: FTP_TLS.prot_c()
 
-.. method:: FTP.quit()
+      Set up clear text data connection.
 
-   Send a ``QUIT`` command to the server and close the connection. This is the
-   "polite" way to close a connection, but it may raise an exception if the server
-   responds with an error to the ``QUIT`` command.  This implies a call to the
-   :meth:`close` method which renders the :class:`FTP` instance useless for
-   subsequent calls (see below).
 
+Module variables
+^^^^^^^^^^^^^^^^
 
-.. method:: FTP.close()
+.. exception:: error_reply
 
-   Close the connection unilaterally.  This should not be applied to an already
-   closed connection such as after a successful call to :meth:`~FTP.quit`.
-   After this call the :class:`FTP` instance should not be used any more (after
-   a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
-   connection by issuing another :meth:`login` method).
+   Exception raised when an unexpected reply is received from the server.
 
 
-FTP_TLS Objects
----------------
+.. exception:: error_temp
 
-:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects:
+   Exception raised when an error code signifying a temporary error (response
+   codes in the range 400--499) is received.
 
-.. attribute:: FTP_TLS.ssl_version
 
-   The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
+.. exception:: error_perm
 
-.. method:: FTP_TLS.auth()
+   Exception raised when an error code signifying a permanent error (response
+   codes in the range 500--599) is received.
 
-   Set up a secure control connection by using TLS or SSL, depending on what
-   is specified in the :attr:`ssl_version` attribute.
 
-   .. versionchanged:: 3.4
-      The method now supports hostname check with
-      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
-      :const:`ssl.HAS_SNI`).
+.. exception:: error_proto
 
-.. method:: FTP_TLS.ccc()
+   Exception raised when a reply is received from the server that does not fit
+   the response specifications of the File Transfer Protocol, i.e. begin with a
+   digit in the range 1--5.
 
-   Revert control channel back to plaintext.  This can be useful to take
-   advantage of firewalls that know how to handle NAT with non-secure FTP
-   without opening fixed ports.
 
-   .. versionadded:: 3.3
+.. data:: all_errors
 
-.. method:: FTP_TLS.prot_p()
+   The set of all exceptions (as a tuple) that methods of :class:`FTP`
+   instances may raise as a result of problems with the FTP connection (as
+   opposed to programming errors made by the caller).  This set includes the
+   four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`.
 
-   Set up secure data connection.
 
-.. method:: FTP_TLS.prot_c()
+.. seealso::
 
-   Set up clear text data connection.
+   Module :mod:`netrc`
+      Parser for the :file:`.netrc` file format.  The file :file:`.netrc` is
+      typically used by FTP clients to load user authentication information
+      before prompting the user.