https://github.com/python/cpython/commit/d492b19856e6cd05d33ce6264d2733cb926b02f4 commit: d492b19856e6cd05d33ce6264d2733cb926b02f4 branch: 3.12 author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com> committer: erlend-aasland <erlend.aasl...@protonmail.com> date: 2024-01-23T14:04:01Z summary:
[3.12] Docs: mark up FTP.connect() and FTP.login() with param lists (GH-114395) (#114485) Use rst substitutions to reduce raw text duplication. (cherry picked from commit 01105c7c4f7f01a8b1077008e61d5c7df0ab832b) Co-authored-by: Erlend E. Aasland <erl...@python.org> Co-authored-by: Ezio Melotti <ezio.melo...@gmail.com> Co-authored-by: Hugo van Kemenade <1324225+hug...@users.noreply.github.com> files: M Doc/library/ftplib.rst diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index c7251db50a9371..e93a1e85598e3a 100644 --- 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() _______________________________________________ Python-checkins mailing list -- python-checkins@python.org To unsubscribe send an email to python-checkins-le...@python.org https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: arch...@mail-archive.com
