https://github.com/python/cpython/commit/b1ad5a5d446f944a45c43a3e865d1d8f47611071
commit: b1ad5a5d446f944a45c43a3e865d1d8f47611071
branch: main
author: Erlend E. Aasland <[email protected]>
committer: erlend-aasland <[email protected]>
date: 2024-01-20T16:06:52+01:00
summary:
Docs: structure the ftplib reference (#114317)
Introduce the following headings and subheadings:
- Reference
* FTP objects
* FTP_TLS objects
* Module variables
files:
M Doc/library/ftplib.rst
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index d1fe6414ea020c..6c44b8d65c3293 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -45,7 +45,15 @@ Here's a sample session using the :mod:`ftplib` module::
'221 Goodbye.'
-The module defines the following items:
+.. _ftplib-reference:
+
+Reference
+---------
+
+.. _ftp-objects:
+
+FTP objects
+^^^^^^^^^^^
.. class:: FTP(host='', user='', passwd='', acct='', timeout=None,
source_address=None, *, encoding='utf-8')
@@ -85,376 +93,374 @@ The module defines the following items:
The *encoding* parameter was added, and the default was changed from
Latin-1 to UTF-8 to follow :rfc:`2640`.
-.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None,
- timeout=None, source_address=None, encoding='utf-8')
+ Several :class:`!FTP` methods are available in two flavors:
+ one for handling text files and another for binary files.
+ The methods are named for the command which is used followed by
+ ``lines`` for the text version or ``binary`` for the binary version.
- A :class:`FTP` subclass which adds TLS support to FTP as described in
- :rfc:`4217`.
- Connect as usual to port 21 implicitly securing the FTP control connection
- before authenticating. Securing the data connection requires the user to
- explicitly ask for it by calling the :meth:`prot_p` method. *context*
- is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
- options, certificates and private keys into a single (potentially
- long-lived) structure. Please read :ref:`ssl-security` for best practices.
+ :class:`FTP` instances have the following methods:
- .. versionadded:: 3.2
+ .. method:: FTP.set_debuglevel(level)
- .. versionchanged:: 3.3
- *source_address* parameter was added.
+ Set the instance's debugging level. This controls the amount of
debugging
+ output printed. The default, ``0``, produces no debugging output. A
value of
+ ``1`` produces a moderate amount of debugging output, generally a single
line
+ per request. A value of ``2`` or higher produces the maximum amount of
+ debugging output, logging each line sent and received on the control
connection.
- .. versionchanged:: 3.4
- The class now supports hostname check with
- :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
- :const:`ssl.HAS_SNI`).
- .. versionchanged:: 3.9
- If the *timeout* parameter is set to be zero, it will raise a
- :class:`ValueError` to prevent the creation of a non-blocking socket.
- The *encoding* parameter was added, and the default was changed from
- Latin-1 to UTF-8 to follow :rfc:`2640`.
+ .. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
- .. versionchanged:: 3.12
- The deprecated *keyfile* and *certfile* parameters have been removed.
+ 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.
- Here's a sample session using the :class:`FTP_TLS` class::
+ .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
- >>> ftps = FTP_TLS('ftp.pureftpd.org')
- >>> ftps.login()
- '230 Anonymous user logged in'
- >>> ftps.prot_p()
- '200 Data protection level set to "private"'
- >>> ftps.nlst()
- ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed',
'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone',
'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc',
'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash',
'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub',
'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache',
'sound', 'tmp', 'ucarp']
+ .. versionchanged:: 3.3
+ *source_address* parameter was added.
-.. exception:: error_reply
+ .. method:: FTP.getwelcome()
- Exception raised when an unexpected reply is received from the server.
+ Return the welcome message sent by the server in reply to the initial
+ connection. (This message sometimes contains disclaimers or help
information
+ that may be relevant to the user.)
-.. exception:: error_temp
+ .. method:: FTP.login(user='anonymous', passwd='', acct='')
- Exception raised when an error code signifying a temporary error (response
- codes in the range 400--499) is received.
-
-
-.. exception:: error_perm
-
- Exception raised when an error code signifying a permanent error (response
- codes in the range 500--599) is received.
+ 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.
-.. exception:: error_proto
+ .. method:: FTP.abort()
- Exception raised when a reply is received from the server that does not fit
- the response specifications of the File Transfer Protocol, i.e. begin with a
- digit in the range 1--5.
+ Abort a file transfer that is in progress. Using this does not always
work, but
+ it's worth a try.
-.. data:: all_errors
+ .. method:: FTP.sendcmd(cmd)
- The set of all exceptions (as a tuple) that methods of :class:`FTP`
- instances may raise as a result of problems with the FTP connection (as
- opposed to programming errors made by the caller). This set includes the
- four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`.
+ Send a simple command string to the server and return the response
string.
+ .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
-.. seealso::
- Module :mod:`netrc`
- Parser for the :file:`.netrc` file format. The file :file:`.netrc` is
- typically used by FTP clients to load user authentication information
- before prompting the user.
+ .. method:: FTP.voidcmd(cmd)
+ Send a simple command string to the server and handle the response.
Return
+ nothing if a response code corresponding to success (codes in the range
+ 200--299) is received. Raise :exc:`error_reply` otherwise.
-.. _ftp-objects:
+ .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
-FTP Objects
------------
-Several methods are available in two flavors: one for handling text files and
-another for binary files. These are named for the command which is used
-followed by ``lines`` for the text version or ``binary`` for the binary
version.
+ .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
-:class:`FTP` instances have the following methods:
+ Retrieve a file in binary transfer mode. *cmd* should be an appropriate
+ ``RETR`` command: ``'RETR filename'``. The *callback* function is called
for
+ each block of data received, with a single bytes argument giving the data
+ block. The optional *blocksize* argument specifies the maximum chunk
size to
+ read on the low-level socket object created to do the actual transfer
(which
+ will also be the largest size of the data blocks passed to *callback*).
A
+ reasonable default is chosen. *rest* means the same thing as in the
+ :meth:`transfercmd` method.
-.. method:: FTP.set_debuglevel(level)
+ .. method:: FTP.retrlines(cmd, callback=None)
- Set the instance's debugging level. This controls the amount of debugging
- output printed. The default, ``0``, produces no debugging output. A value
of
- ``1`` produces a moderate amount of debugging output, generally a single
line
- per request. A value of ``2`` or higher produces the maximum amount of
- debugging output, logging each line sent and received on the control
connection.
+ Retrieve a file or directory listing in the encoding specified by the
+ *encoding* parameter at initialization.
+ *cmd* should be an appropriate ``RETR`` command (see :meth:`retrbinary`)
or
+ a command such as ``LIST`` or ``NLST`` (usually just the string
``'LIST'``).
+ ``LIST`` retrieves a list of files and information about those files.
+ ``NLST`` retrieves a list of file names.
+ The *callback* function is called for each line with a string argument
+ containing the line with the trailing CRLF stripped. The default
*callback*
+ prints the line to ``sys.stdout``.
-.. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
+ .. method:: FTP.set_pasv(val)
- 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.
+ Enable "passive" mode if *val* is true, otherwise disable passive mode.
+ Passive mode is on by default.
- .. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
- .. versionchanged:: 3.3
- *source_address* parameter was added.
+ .. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None,
rest=None)
+ Store a file in binary transfer mode. *cmd* should be an appropriate
+ ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object`
+ (opened in binary mode) which is read until EOF using its
:meth:`~io.IOBase.read`
+ method in blocks of size *blocksize* to provide the data to be stored.
+ The *blocksize* argument defaults to 8192. *callback* is an optional
single
+ parameter callable that is called on each block of data after it is sent.
+ *rest* means the same thing as in the :meth:`transfercmd` method.
-.. method:: FTP.getwelcome()
+ .. versionchanged:: 3.2
+ *rest* parameter added.
- Return the welcome message sent by the server in reply to the initial
- connection. (This message sometimes contains disclaimers or help
information
- that may be relevant to the user.)
+ .. method:: FTP.storlines(cmd, fp, callback=None)
-.. method:: FTP.login(user='anonymous', passwd='', acct='')
+ Store a file in line mode. *cmd* should be an appropriate
+ ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF
from the
+ :term:`file object` *fp* (opened in binary mode) using its
:meth:`~io.IOBase.readline`
+ method to provide the data to be stored. *callback* is an optional
single
+ parameter callable that is called on each line after it is sent.
- 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.
+ .. method:: FTP.transfercmd(cmd, rest=None)
-.. method:: FTP.abort()
+ Initiate a transfer over the data connection. If the transfer is
active, send an
+ ``EPRT`` or ``PORT`` command and the transfer command specified by
*cmd*, and
+ accept the connection. If the server is passive, send an ``EPSV`` or
``PASV``
+ command, connect to it, and start the transfer command. Either way,
return the
+ socket for the connection.
- Abort a file transfer that is in progress. Using this does not always
work, but
- it's worth a try.
+ If optional *rest* is given, a ``REST`` command is sent to the server,
passing
+ *rest* as an argument. *rest* is usually a byte offset into the
requested file,
+ telling the server to restart sending the file's bytes at the requested
offset,
+ skipping over the initial bytes. Note however that the
:meth:`transfercmd`
+ method converts *rest* to a string with the *encoding* parameter
specified
+ at initialization, but no check is performed on the string's contents.
If the
+ server does not recognize the ``REST`` command, an :exc:`error_reply`
exception
+ will be raised. If this happens, simply call :meth:`transfercmd`
without a
+ *rest* argument.
-.. method:: FTP.sendcmd(cmd)
+ .. method:: FTP.ntransfercmd(cmd, rest=None)
- Send a simple command string to the server and return the response string.
+ Like :meth:`transfercmd`, but returns a tuple of the data connection and
the
+ expected size of the data. If the expected size could not be computed,
``None``
+ will be returned as the expected size. *cmd* and *rest* means the same
thing as
+ in :meth:`transfercmd`.
- .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
+ .. method:: FTP.mlsd(path="", facts=[])
-.. method:: FTP.voidcmd(cmd)
+ List a directory in a standardized format by using ``MLSD`` command
+ (:rfc:`3659`). If *path* is omitted the current directory is assumed.
+ *facts* is a list of strings representing the type of information desired
+ (e.g. ``["type", "size", "perm"]``). Return a generator object yielding
a
+ tuple of two elements for every file found in path. First element is the
+ file name, the second one is a dictionary containing facts about the file
+ name. Content of this dictionary might be limited by the *facts*
argument
+ but server is not guaranteed to return all requested facts.
- Send a simple command string to the server and handle the response. Return
- nothing if a response code corresponding to success (codes in the range
- 200--299) is received. Raise :exc:`error_reply` otherwise.
+ .. versionadded:: 3.3
- .. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
+ .. method:: FTP.nlst(argument[, ...])
-.. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
+ Return a list of file names as returned by the ``NLST`` command. The
+ optional *argument* is a directory to list (default is the current server
+ directory). Multiple arguments can be used to pass non-standard options
to
+ the ``NLST`` command.
- Retrieve a file in binary transfer mode. *cmd* should be an appropriate
- ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
- each block of data received, with a single bytes argument giving the data
- block. The optional *blocksize* argument specifies the maximum chunk size to
- read on the low-level socket object created to do the actual transfer (which
- will also be the largest size of the data blocks passed to *callback*). A
- reasonable default is chosen. *rest* means the same thing as in the
- :meth:`transfercmd` method.
+ .. note:: If your server supports the command, :meth:`mlsd` offers a
better API.
-.. method:: FTP.retrlines(cmd, callback=None)
+ .. method:: FTP.dir(argument[, ...])
- Retrieve a file or directory listing in the encoding specified by the
- *encoding* parameter at initialization.
- *cmd* should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or
- a command such as ``LIST`` or ``NLST`` (usually just the string ``'LIST'``).
- ``LIST`` retrieves a list of files and information about those files.
- ``NLST`` retrieves a list of file names.
- The *callback* function is called for each line with a string argument
- containing the line with the trailing CRLF stripped. The default *callback*
- prints the line to ``sys.stdout``.
+ Produce a directory listing as returned by the ``LIST`` command,
printing it to
+ standard output. The optional *argument* is a directory to list
(default is the
+ current server directory). Multiple arguments can be used to pass
non-standard
+ options to the ``LIST`` command. If the last argument is a function, it
is used
+ as a *callback* function as for :meth:`retrlines`; the default prints to
+ ``sys.stdout``. This method returns ``None``.
+ .. note:: If your server supports the command, :meth:`mlsd` offers a
better API.
-.. method:: FTP.set_pasv(val)
- Enable "passive" mode if *val* is true, otherwise disable passive mode.
- Passive mode is on by default.
+ .. method:: FTP.rename(fromname, toname)
+ Rename file *fromname* on the server to *toname*.
-.. method:: FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
- Store a file in binary transfer mode. *cmd* should be an appropriate
- ``STOR`` command: ``"STOR filename"``. *fp* is a :term:`file object`
- (opened in binary mode) which is read until EOF using its
:meth:`~io.IOBase.read`
- method in blocks of size *blocksize* to provide the data to be stored.
- The *blocksize* argument defaults to 8192. *callback* is an optional single
- parameter callable that is called on each block of data after it is sent.
- *rest* means the same thing as in the :meth:`transfercmd` method.
+ .. method:: FTP.delete(filename)
- .. versionchanged:: 3.2
- *rest* parameter added.
+ Remove the file named *filename* from the server. If successful,
returns the
+ text of the response, otherwise raises :exc:`error_perm` on permission
errors or
+ :exc:`error_reply` on other errors.
-.. method:: FTP.storlines(cmd, fp, callback=None)
+ .. method:: FTP.cwd(pathname)
- Store a file in line mode. *cmd* should be an appropriate
- ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from
the
- :term:`file object` *fp* (opened in binary mode) using its
:meth:`~io.IOBase.readline`
- method to provide the data to be stored. *callback* is an optional single
- parameter callable that is called on each line after it is sent.
+ Set the current directory on the server.
-.. method:: FTP.transfercmd(cmd, rest=None)
+ .. method:: FTP.mkd(pathname)
- Initiate a transfer over the data connection. If the transfer is active,
send an
- ``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*,
and
- accept the connection. If the server is passive, send an ``EPSV`` or
``PASV``
- command, connect to it, and start the transfer command. Either way, return
the
- socket for the connection.
+ Create a new directory on the server.
- If optional *rest* is given, a ``REST`` command is sent to the server,
passing
- *rest* as an argument. *rest* is usually a byte offset into the requested
file,
- telling the server to restart sending the file's bytes at the requested
offset,
- skipping over the initial bytes. Note however that the :meth:`transfercmd`
- method converts *rest* to a string with the *encoding* parameter specified
- at initialization, but no check is performed on the string's contents. If
the
- server does not recognize the ``REST`` command, an :exc:`error_reply`
exception
- will be raised. If this happens, simply call :meth:`transfercmd` without a
- *rest* argument.
+ .. method:: FTP.pwd()
-.. method:: FTP.ntransfercmd(cmd, rest=None)
+ Return the pathname of the current directory on the server.
- Like :meth:`transfercmd`, but returns a tuple of the data connection and the
- expected size of the data. If the expected size could not be computed,
``None``
- will be returned as the expected size. *cmd* and *rest* means the same
thing as
- in :meth:`transfercmd`.
+ .. method:: FTP.rmd(dirname)
-.. method:: FTP.mlsd(path="", facts=[])
+ Remove the directory named *dirname* on the server.
- List a directory in a standardized format by using ``MLSD`` command
- (:rfc:`3659`). If *path* is omitted the current directory is assumed.
- *facts* is a list of strings representing the type of information desired
- (e.g. ``["type", "size", "perm"]``). Return a generator object yielding a
- tuple of two elements for every file found in path. First element is the
- file name, the second one is a dictionary containing facts about the file
- name. Content of this dictionary might be limited by the *facts* argument
- but server is not guaranteed to return all requested facts.
- .. versionadded:: 3.3
+ .. method:: FTP.size(filename)
+ Request the size of the file named *filename* on the server. On
success, the
+ size of the file is returned as an integer, otherwise ``None`` is
returned.
+ Note that the ``SIZE`` command is not standardized, but is supported by
many
+ common server implementations.
-.. method:: FTP.nlst(argument[, ...])
- Return a list of file names as returned by the ``NLST`` command. The
- optional *argument* is a directory to list (default is the current server
- directory). Multiple arguments can be used to pass non-standard options to
- the ``NLST`` command.
+ .. method:: FTP.quit()
- .. note:: If your server supports the command, :meth:`mlsd` offers a better
API.
+ Send a ``QUIT`` command to the server and close the connection. This is
the
+ "polite" way to close a connection, but it may raise an exception if the
server
+ responds with an error to the ``QUIT`` command. This implies a call to
the
+ :meth:`close` method which renders the :class:`FTP` instance useless for
+ subsequent calls (see below).
-.. method:: FTP.dir(argument[, ...])
+ .. method:: FTP.close()
- Produce a directory listing as returned by the ``LIST`` command, printing
it to
- standard output. The optional *argument* is a directory to list (default
is the
- current server directory). Multiple arguments can be used to pass
non-standard
- options to the ``LIST`` command. If the last argument is a function, it is
used
- as a *callback* function as for :meth:`retrlines`; the default prints to
- ``sys.stdout``. This method returns ``None``.
+ Close the connection unilaterally. This should not be applied to an
already
+ closed connection such as after a successful call to :meth:`~FTP.quit`.
+ After this call the :class:`FTP` instance should not be used any more
(after
+ a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
+ connection by issuing another :meth:`login` method).
- .. note:: If your server supports the command, :meth:`mlsd` offers a better
API.
+FTP_TLS objects
+^^^^^^^^^^^^^^^
-.. method:: FTP.rename(fromname, toname)
+.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None,
+ timeout=None, source_address=None, encoding='utf-8')
- Rename file *fromname* on the server to *toname*.
+ A :class:`FTP` subclass which adds TLS support to FTP as described in
+ :rfc:`4217`.
+ Connect as usual to port 21 implicitly securing the FTP control connection
+ before authenticating. Securing the data connection requires the user to
+ explicitly ask for it by calling the :meth:`prot_p` method. *context*
+ is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
+ options, certificates and private keys into a single (potentially
+ long-lived) structure. Please read :ref:`ssl-security` for best practices.
+ .. versionadded:: 3.2
-.. method:: FTP.delete(filename)
+ .. versionchanged:: 3.3
+ *source_address* parameter was added.
- Remove the file named *filename* from the server. If successful, returns
the
- text of the response, otherwise raises :exc:`error_perm` on permission
errors or
- :exc:`error_reply` on other errors.
+ .. versionchanged:: 3.4
+ The class now supports hostname check with
+ :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
+ :const:`ssl.HAS_SNI`).
+ .. versionchanged:: 3.9
+ If the *timeout* parameter is set to be zero, it will raise a
+ :class:`ValueError` to prevent the creation of a non-blocking socket.
+ The *encoding* parameter was added, and the default was changed from
+ Latin-1 to UTF-8 to follow :rfc:`2640`.
-.. method:: FTP.cwd(pathname)
+ .. versionchanged:: 3.12
+ The deprecated *keyfile* and *certfile* parameters have been removed.
- Set the current directory on the server.
+ Here's a sample session using the :class:`FTP_TLS` class::
+ >>> ftps = FTP_TLS('ftp.pureftpd.org')
+ >>> ftps.login()
+ '230 Anonymous user logged in'
+ >>> ftps.prot_p()
+ '200 Data protection level set to "private"'
+ >>> ftps.nlst()
+ ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed',
'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone',
'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc',
'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash',
'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub',
'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache',
'sound', 'tmp', 'ucarp']
-.. method:: FTP.mkd(pathname)
+ :class:`!FTP_TLS` class inherits from :class:`FTP`,
+ defining these additional methods and attributes:
- Create a new directory on the server.
+ .. attribute:: FTP_TLS.ssl_version
+ The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
-.. method:: FTP.pwd()
+ .. method:: FTP_TLS.auth()
- Return the pathname of the current directory on the server.
+ Set up a secure control connection by using TLS or SSL, depending on what
+ is specified in the :attr:`ssl_version` attribute.
+ .. versionchanged:: 3.4
+ The method now supports hostname check with
+ :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication*
(see
+ :const:`ssl.HAS_SNI`).
-.. method:: FTP.rmd(dirname)
+ .. method:: FTP_TLS.ccc()
- Remove the directory named *dirname* on the server.
+ Revert control channel back to plaintext. This can be useful to take
+ advantage of firewalls that know how to handle NAT with non-secure FTP
+ without opening fixed ports.
+ .. versionadded:: 3.3
-.. method:: FTP.size(filename)
+ .. method:: FTP_TLS.prot_p()
- Request the size of the file named *filename* on the server. On success,
the
- size of the file is returned as an integer, otherwise ``None`` is returned.
- Note that the ``SIZE`` command is not standardized, but is supported by
many
- common server implementations.
+ Set up secure data connection.
+ .. method:: FTP_TLS.prot_c()
-.. method:: FTP.quit()
+ Set up clear text data connection.
- Send a ``QUIT`` command to the server and close the connection. This is the
- "polite" way to close a connection, but it may raise an exception if the
server
- responds with an error to the ``QUIT`` command. This implies a call to the
- :meth:`close` method which renders the :class:`FTP` instance useless for
- subsequent calls (see below).
+Module variables
+^^^^^^^^^^^^^^^^
-.. method:: FTP.close()
+.. exception:: error_reply
- Close the connection unilaterally. This should not be applied to an already
- closed connection such as after a successful call to :meth:`~FTP.quit`.
- After this call the :class:`FTP` instance should not be used any more (after
- a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
- connection by issuing another :meth:`login` method).
+ Exception raised when an unexpected reply is received from the server.
-FTP_TLS Objects
----------------
+.. exception:: error_temp
-:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional
objects:
+ Exception raised when an error code signifying a temporary error (response
+ codes in the range 400--499) is received.
-.. attribute:: FTP_TLS.ssl_version
- The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
+.. exception:: error_perm
-.. method:: FTP_TLS.auth()
+ Exception raised when an error code signifying a permanent error (response
+ codes in the range 500--599) is received.
- Set up a secure control connection by using TLS or SSL, depending on what
- is specified in the :attr:`ssl_version` attribute.
- .. versionchanged:: 3.4
- The method now supports hostname check with
- :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
- :const:`ssl.HAS_SNI`).
+.. exception:: error_proto
-.. method:: FTP_TLS.ccc()
+ Exception raised when a reply is received from the server that does not fit
+ the response specifications of the File Transfer Protocol, i.e. begin with a
+ digit in the range 1--5.
- Revert control channel back to plaintext. This can be useful to take
- advantage of firewalls that know how to handle NAT with non-secure FTP
- without opening fixed ports.
- .. versionadded:: 3.3
+.. data:: all_errors
-.. method:: FTP_TLS.prot_p()
+ The set of all exceptions (as a tuple) that methods of :class:`FTP`
+ instances may raise as a result of problems with the FTP connection (as
+ opposed to programming errors made by the caller). This set includes the
+ four exceptions listed above as well as :exc:`OSError` and :exc:`EOFError`.
- Set up secure data connection.
-.. method:: FTP_TLS.prot_c()
+.. seealso::
- Set up clear text data connection.
+ Module :mod:`netrc`
+ Parser for the :file:`.netrc` file format. The file :file:`.netrc` is
+ typically used by FTP clients to load user authentication information
+ before prompting the user.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
