From e086f84f0a6a049c1480358191132ec9f0d283bf Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 21 Jan 2024 18:19:26 +0100 Subject: [PATCH 1/7] Docs: mark up FTP.connect() and FTP.login() with param lists --- Doc/library/ftplib.rst | 80 ++++++++++++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index c4c5beb7b49525..14c318e571df42 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -59,25 +59,25 @@ FTP objects 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) ` - is made by the constructor. - When *user* is given, additionally the method call - :meth:`login(user, passwd, acct) ` is made. :param str host: The hostname to connect to. + If given, :code:`connect(host)` is implicitly called by the constructor. + See the corresponding parameter to :meth:`connect` for more details. :param str user: The username to log in with. - If empty string, ``"anonymous"`` is used. + If given, :code:`login(host, passwd, acct)` is implicitly called + by the constructor. + See the corresponding parameter to :meth:`login` for more details. :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. + See the corresponding parameter to :meth:`login` for more details. :param str acct: - Account information; see the ACCT FTP command. + Account information to be used for the ``ACCT`` FTP command. + See the corresponding parameter to :meth:`login` for more details. :param timeout: A timeout in seconds for blocking operations like :meth:`connect`. @@ -140,17 +140,31 @@ 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. + If no port number is provided, port ``21`` is used, + 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. + If not specified, the global default timeout setting will be used. + :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. + :type source_address: tuple | None .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect @@ -167,14 +181,26 @@ 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: + The username to log in with. + If no *user* is specified, ``'anonymous'`` will be used. + + :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 str acct: + Account information to be used for the ``ACCT`` FTP command. + See :rfc:`959` for more details. + Few systems implement this. .. method:: FTP.abort() From cc571255d6f8f3d0401b1f2e97b63346cbab43ca Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 22 Jan 2024 15:10:05 +0100 Subject: [PATCH 2/7] Use rst substitutions to reduce duplicated raw text --- Doc/library/ftplib.rst | 60 ++++++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 5e98ce31b2bc84..cfbff5d999cca8 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -55,6 +55,33 @@ Reference FTP objects ^^^^^^^^^^^ +.. Use substitutions for some param docs so we don't need to repeat them + multiple places. + +.. |param_doc_user| replace:: + The username to log in with. + If no *user* is specified, ``'anonymous'`` will be used. + +.. |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 :ref: 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 for more details. + +.. |param_doc_timeout| replace:: + A timeout in seconds for blocking operations like :meth:`connect`. + If not specified, the global default timeout setting will be used. + +.. |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') @@ -63,30 +90,24 @@ FTP objects :param str host: The hostname to connect to. If given, :code:`connect(host)` is implicitly called by the constructor. - See the corresponding parameter to :meth:`connect` for more details. :param str user: - The username to log in with. + |param_doc_user| If given, :code:`login(host, passwd, acct)` is implicitly called by the constructor. - See the corresponding parameter to :meth:`login` for more details. :param str passwd: - The password to use when logging in. - See the corresponding parameter to :meth:`login` for more details. + |param_doc_passwd| :param str acct: - Account information to be used for the ``ACCT`` FTP command. - See the corresponding parameter to :meth:`login` for more details. + |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. + |param_doc_timeout| :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: @@ -157,13 +178,11 @@ FTP objects It is rarely needed to specify a different port number. :param timeout: - A timeout in seconds for the connection attempt. - If not specified, the global default timeout setting will be used. + |param_doc_timeout| :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 .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect @@ -189,18 +208,13 @@ FTP objects Most FTP commands are only allowed after the client has logged in. :param str user: - The username to log in with. - If no *user* is specified, ``'anonymous'`` will be used. + |param_doc_user| :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 to be used for the ``ACCT`` FTP command. - See :rfc:`959` for more details. - Few systems implement this. + |param_doc_acct| .. method:: FTP.abort() From c5390a8b42e82fb30b64ddbe8f48fe2d145c9cdb Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 22 Jan 2024 15:16:57 +0100 Subject: [PATCH 3/7] Revert subst for timeout --- Doc/library/ftplib.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index cfbff5d999cca8..0de22a5db835a1 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -74,10 +74,6 @@ FTP objects Few systems implement this. See RFC-959 for more details. -.. |param_doc_timeout| replace:: - A timeout in seconds for blocking operations like :meth:`connect`. - If not specified, the global default timeout setting will be used. - .. |param_doc_source_address| replace:: A 2-tuple ``(host, port)`` for the socket to bind to as its source address before connecting. @@ -103,7 +99,8 @@ FTP objects |param_doc_acct| :param timeout: - |param_doc_timeout| + A timeout in seconds for blocking operations like :meth:`connect`. + If not specified, the global default timeout setting will be used. :type timeout: int | None :param source_address: @@ -178,7 +175,8 @@ FTP objects It is rarely needed to specify a different port number. :param timeout: - |param_doc_timeout| + A timeout in seconds for the connection attempt. + If not specified, the global default timeout setting will be used. :type timeout: int | None :param source_address: From 77cae6312df292d38024697b8c07df08ec2a7902 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 22 Jan 2024 15:18:04 +0100 Subject: [PATCH 4/7] Indent --- Doc/library/ftplib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 0de22a5db835a1..5000a7908584ac 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -99,8 +99,8 @@ FTP objects |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`. + If not specified, the global default timeout setting will be used. :type timeout: int | None :param source_address: From 0316e9180c5e4f3f241f02735cf90c3c8ba84d8e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 22 Jan 2024 23:46:43 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Ezio Melotti --- Doc/library/ftplib.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 5000a7908584ac..d996399dea62ae 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -56,7 +56,7 @@ FTP objects ^^^^^^^^^^^ .. Use substitutions for some param docs so we don't need to repeat them - multiple places. + in multiple places. .. |param_doc_user| replace:: The username to log in with. @@ -67,12 +67,13 @@ FTP objects If not given, and if *passwd* is the empty string or ``"-"``, a password will be automatically generated. -.. Ideally, we'd like to use the :ref: directive, but Sphinx will not allow it. +.. 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 for more details. + See `RFC-959 `__ + for more details. .. |param_doc_source_address| replace:: A 2-tuple ``(host, port)`` for the socket to bind to as its From 3477916d97e2cfe63432113b02e4ca649ab9e83b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 14:49:43 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/ftplib.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index d996399dea62ae..3ccdaa751c087d 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -59,8 +59,7 @@ FTP objects in multiple places. .. |param_doc_user| replace:: - The username to log in with. - If no *user* is specified, ``'anonymous'`` will be used. + The username to log in with (default: ``'anonymous'``). .. |param_doc_passwd| replace:: The password to use when logging in. @@ -170,14 +169,13 @@ FTP objects The host to connect to. :param int port: - The TCP port to connect to. - If no port number is provided, port ``21`` is used, - as specified by the FTP protocol specification. + 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. - If not specified, the global default timeout setting will be used. + A timeout in seconds for the connection attempt + (default: the global default timeout setting). :type timeout: int | None :param source_address: From 745978e322854a8973b36788dc17d1609fb2f4a6 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 14:50:32 +0100 Subject: [PATCH 7/7] Also change line 104 --- Doc/library/ftplib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 3ccdaa751c087d..5bc74c156f7a0f 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -99,8 +99,8 @@ FTP objects |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: