Skip to content

Commit 8816e1a

Browse files
erlend-aaslandaisk
authored andcommitted
Docs: mark up the FTP_TLS() docs with param list (python#114510)
Also turn sentence about prot_p() into a note.
1 parent efdd16a commit 8816e1a

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

@@ -447,19 +449,53 @@ FTP_TLS objects
447449
.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None, \
448450
timeout=None, source_address=None, encoding='utf-8')
449451

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

459495
.. versionadded:: 3.2
460496

461497
.. versionchanged:: 3.3
462-
*source_address* parameter was added.
498+
Added the *source_address* parameter.
463499

464500
.. versionchanged:: 3.4
465501
The class now supports hostname check with

0 commit comments

Comments
 (0)