Skip to content

Commit 94c5567

Browse files
[3.11] Docs: mark up the FTP_TLS() docs with param list (GH-114510) (#114533)
Also turn sentence about prot_p() into a note. (cherry picked from commit 6fadd68) Co-authored-by: Erlend E. Aasland <[email protected]>
1 parent aa17d91 commit 94c5567

File tree

1 file changed

+46
-10
lines changed

1 file changed

+46
-10
lines changed

Doc/library/ftplib.rst

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,9 @@ FTP objects
7878
A 2-tuple ``(host, port)`` for the socket to bind to as its
7979
source address before connecting.
8080

81+
.. |param_doc_encoding| replace::
82+
The encoding for directories and filenames (default: ``'utf-8'``).
83+
8184
.. class:: FTP(host='', user='', passwd='', acct='', timeout=None, \
8285
source_address=None, *, encoding='utf-8')
8386
@@ -108,8 +111,7 @@ FTP objects
108111
:type source_address: tuple | None
109112

110113
:param str encoding:
111-
The *encoding* parameter specifies the encoding
112-
for directories and filenames.
114+
|param_doc_encoding|
113115

114116
The :class:`FTP` class supports the :keyword:`with` statement, e.g.:
115117

@@ -448,14 +450,48 @@ FTP_TLS objects
448450
certfile=None, context=None, timeout=None, \
449451
source_address=None, *, encoding='utf-8')
450452
451-
A :class:`FTP` subclass which adds TLS support to FTP as described in
453+
An :class:`FTP` subclass which adds TLS support to FTP as described in
452454
:rfc:`4217`.
453-
Connect as usual to port 21 implicitly securing the FTP control connection
454-
before authenticating. Securing the data connection requires the user to
455-
explicitly ask for it by calling the :meth:`prot_p` method. *context*
456-
is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
457-
options, certificates and private keys into a single (potentially
458-
long-lived) structure. Please read :ref:`ssl-security` for best practices.
455+
Connect to port 21 implicitly securing the FTP control connection
456+
before authenticating.
457+
458+
.. note::
459+
The user must explicitly secure the data connection
460+
by calling the :meth:`prot_p` method.
461+
462+
:param str host:
463+
The hostname to connect to.
464+
If given, :code:`connect(host)` is implicitly called by the constructor.
465+
466+
:param str user:
467+
|param_doc_user|
468+
If given, :code:`login(host, passwd, acct)` is implicitly called
469+
by the constructor.
470+
471+
:param str passwd:
472+
|param_doc_passwd|
473+
474+
:param str acct:
475+
|param_doc_acct|
476+
477+
:param context:
478+
An SSL context object which allows bundling SSL configuration options,
479+
certificates and private keys into a single, potentially long-lived,
480+
structure.
481+
Please read :ref:`ssl-security` for best practices.
482+
:type context: :class:`ssl.SSLContext`
483+
484+
:param timeout:
485+
A timeout in seconds for blocking operations like :meth:`~FTP.connect`
486+
(default: the global default timeout setting).
487+
:type timeout: int | None
488+
489+
:param source_address:
490+
|param_doc_source_address|
491+
:type source_address: tuple | None
492+
493+
:param str encoding:
494+
|param_doc_encoding|
459495

460496
*keyfile* and *certfile* are a legacy alternative to *context* -- they
461497
can point to PEM-formatted private key and certificate chain files
@@ -464,7 +500,7 @@ FTP_TLS objects
464500
.. versionadded:: 3.2
465501

466502
.. versionchanged:: 3.3
467-
*source_address* parameter was added.
503+
Added the *source_address* parameter.
468504

469505
.. versionchanged:: 3.4
470506
The class now supports hostname check with

0 commit comments

Comments
 (0)