[3.12] Docs: mark up FTP.connect() and FTP.login() with param lists (GH-114395) ...

Use rst substitutions to reduce raw text duplication.

(cherry picked from commit 01105c7c4f7f01a8b1077008e61d5c7df0ab832b)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index c7251db50a9371588272cdba1c62a2dded6f31c8..e93a1e85598e3a798e0275b2183a60ca7b70b863 100644 (file)
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -55,38 +55,56 @@ Reference
 FTP objects
 ^^^^^^^^^^^
 
+.. Use substitutions for some param docs so we don't need to repeat them
+   in multiple places.
+
+.. |param_doc_user| replace::
+   The username to log in with (default: ``'anonymous'``).
+
+.. |param_doc_passwd| replace::
+   The password to use when logging in.
+   If not given, and if *passwd* is the empty string or ``"-"``,
+   a password will be automatically generated.
+
+.. Ideally, we'd like to use the :rfc: directive, but Sphinx will not allow it.
+
+.. |param_doc_acct| replace::
+   Account information to be used for the ``ACCT`` FTP command.
+   Few systems implement this.
+   See `RFC-959 <https://datatracker.ietf.org/doc/html/rfc959.html>`__
+   for more details.
+
+.. |param_doc_source_address| replace::
+   A 2-tuple ``(host, port)`` for the socket to bind to as its
+   source address before connecting.
+
 .. class:: FTP(host='', user='', passwd='', acct='', timeout=None, \
                source_address=None, *, encoding='utf-8')
 
    Return a new instance of the :class:`FTP` class.
-   When *host* is given, the method call :meth:`connect(host) <connect>`
-   is made by the constructor.
-   When *user* is given, additionally the method call
-   :meth:`login(user, passwd, acct) <connect>` is made.
 
    :param str host:
       The hostname to connect to.
+      If given, :code:`connect(host)` is implicitly called by the constructor.
 
    :param str user:
-      The username to log in with.
-      If empty string, ``"anonymous"`` is used.
+      |param_doc_user|
+      If given, :code:`login(host, passwd, acct)` is implicitly called
+      by the constructor.
 
    :param str passwd:
-      The password to use when logging in.
-      If not given, and if *passwd* is the empty string or ``"-"``,
-      a password will be automatically generated.
+      |param_doc_passwd|
 
    :param str acct:
-      Account information; see the ACCT FTP command.
+      |param_doc_acct|
 
    :param timeout:
-      A timeout in seconds for blocking operations like :meth:`connect`.
-      If not specified, the global default timeout setting will be used.
+      A timeout in seconds for blocking operations like :meth:`connect`
+      (default: the global default timeout setting).
    :type timeout: int | None
 
    :param source_address:
-      *source_address* is a 2-tuple ``(host, port)`` for the socket
-      to bind to as its source address before connecting.
+      |param_doc_source_address|
    :type source_address: tuple | None
 
    :param str encoding:
@@ -140,17 +158,29 @@ FTP objects
 
    .. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
 
-      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.
+      Connect to the given host and port.
+      This function should be called only once for each instance;
+      it should not be called if a *host* argument was given
+      when the :class:`FTP` instance was created.
+      All other :class:`!FTP` methods can only be called
+      after a connection has successfully been made.
+
+      :param str host:
+         The host to connect to.
+
+      :param int port:
+         The TCP port to connect to (default: ``21``,
+         as specified by the FTP protocol specification).
+         It is rarely needed to specify a different port number.
+
+      :param timeout:
+         A timeout in seconds for the connection attempt
+         (default: the global default timeout setting).
+      :type timeout: int | None
+
+      :param source_address:
+         |param_doc_source_address|
+      :type source_address: tuple | None
 
       .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
 
@@ -167,14 +197,21 @@ FTP objects
 
    .. method:: FTP.login(user='anonymous', passwd='', acct='')
 
-      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.
+      Log on to the connected FTP server.
+      This function should be called only once for each instance,
+      after a connection has been established;
+      it should not be called if the *host* and *user* arguments were given
+      when the :class:`FTP` instance was created.
+      Most FTP commands are only allowed after the client has logged in.
+
+      :param str user:
+         |param_doc_user|
+
+      :param str passwd:
+         |param_doc_passwd|
+
+      :param str acct:
+         |param_doc_acct|
 
 
    .. method:: FTP.abort()