# `ftplib` — FTP protocol client

Вихідний код: Lib/ftplib.py

Цей модуль визначає клас `FTP` і кілька пов’язаних елементів. Клас `FTP` реалізує клієнтську сторону протоколу FTP. Ви можете використовувати це для написання програм на Python, які виконують різноманітні автоматизовані завдання FTP, такі як віддзеркалення інших серверів FTP. Він також використовується модулем `urllib.request` для обробки URL-адрес, які використовують FTP. Додаткову інформацію про FTP (протокол передачі файлів) див. в Інтернеті RFC 959.

Стандартне кодування – UTF-8, наступне RFC 2640.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

Ось зразок сеансу з використанням модуля `ftplib`:

    >>> from ftplib import FTP
    >>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
    >>> ftp.login()                     # user anonymous, passwd anonymous@
    '230 Login successful.'
    >>> ftp.cwd('debian')               # change into "debian" directory
    '250 Directory successfully changed.'
    >>> ftp.retrlines('LIST')           # list directory contents
    -rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
    ...
    drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
    drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
    drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
    '226 Directory send OK.'
    >>> with open('README', 'wb') as fp:
    >>>     ftp.retrbinary('RETR README', fp.write)
    '226 Transfer complete.'
    >>> ftp.quit()
    '221 Goodbye.'

## Посилання

### FTP objects

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

  Return a new instance of the `FTP` class.

  Параметри:

    - host (str) – The hostname to connect to. If given, `connect(host)` is implicitly called by the constructor.

    - user (str) – The username to log in with (default: `'anonymous'`). If given, `login(host, passwd, acct)` is implicitly called by the constructor.

    - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

    - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

    - timeout (float | None) – A timeout in seconds for blocking operations like `connect()` (default: the global default timeout setting).

    - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    - encoding (str) – The encoding for directories and filenames (default: `'utf-8'`).

  Клас `FTP` підтримує оператор `with`, наприклад:

      >>> from ftplib import FTP
      >>> with FTP("ftp1.at.proftpd.org") as ftp:
      ...     ftp.login()
      ...     ftp.dir()
      ...
      '230 Anonymous login ok, restrictions apply.'
      dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
      dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
      dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
      dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
      >>>

  Змінено в версії 3.2: Додано підтримку оператора `with`.

  Змінено в версії 3.3: Додано параметр source_address.

  Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе `ValueError`, щоб запобігти створенню неблокуючого сокета. Параметр encoding було додано, а значення за замовчуванням змінено з Latin-1 на UTF-8 на RFC 2640.

  Several `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.

  Екземпляри `FTP` мають такі методи:

  set_debuglevel(level)

    Set the instance’s debugging level as an `int`. This controls the amount of debugging output printed. The debug levels are:

    - `0` (default): No debug output.

    - `1`: Produce a moderate amount of debug output, generally a single line per request.

    - `2` or higher: Produce the maximum amount of debugging output, logging each line sent and received on the control connection.

  connect(host='', port=0, timeout=None, source_address=None)

    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 `FTP` instance was created. All other `FTP` methods can only be called after a connection has successfully been made.

    Параметри:

      - host (str) – The host to connect to.

      - port (int) – 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.

      - timeout (float | None) – A timeout in seconds for the connection attempt (default: the global default timeout setting).

      - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    Викликає подію аудиту `ftplib.connect` з аргументами `self`, `host`, `port`.

    Змінено в версії 3.3: Додано параметр source_address.

  getwelcome()

    Повернути вітальне повідомлення, надіслане сервером у відповідь на початкове підключення. (Це повідомлення іноді містить застереження або довідкову інформацію, яка може бути актуальною для користувача.)

  login(user='anonymous', passwd='', acct='')

    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 `FTP` instance was created. Most FTP commands are only allowed after the client has logged in.

    Параметри:

      - user (str) – The username to log in with (default: `'anonymous'`).

      - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

      - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

  abort()

    Перервати передачу файлу, що триває. Використання цього не завжди працює, але варто спробувати.

  sendcmd(cmd)

    Надішліть простий рядок команди на сервер і поверніть рядок відповіді.

    Викликає подію аудиту `ftplib.sendcmd` з аргументами `self`, `cmd`.

  voidcmd(cmd)

    Send a simple command string to the server and handle the response. Return the response string if the response code corresponds to success (codes in the range 200–299). Raise `error_reply` otherwise.

    Викликає подію аудиту `ftplib.sendcmd` з аргументами `self`, `cmd`.

  retrbinary(cmd, callback, blocksize=8192, rest=None)

    Retrieve a file in binary transfer mode.

    Параметри:

      - cmd (str) – An appropriate `RETR` command: `"RETR filename"`.

      - callback (callable) – A single parameter callable that is called for each block of data received, with its single argument being the data as `bytes`.

      - blocksize (int) – The maximum chunk size to read on the low-level `socket` object created to do the actual transfer. This also corresponds to the largest size of data that will be passed to callback. Defaults to `8192`.

      - rest (int) – A `REST` command to be sent to the server. See the documentation for the rest parameter of the `transfercmd()` method.

  retrlines(cmd, callback=None)

    Retrieve a file or directory listing in the encoding specified by the encoding parameter at initialization. cmd should be an appropriate `RETR` command (see `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`.

  set_pasv(val)

    Увімкніть «пасивний» режим, якщо val має значення true, інакше вимкніть пасивний режим. Пасивний режим увімкнено за замовчуванням.

  storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

    Store a file in binary transfer mode.

    Параметри:

      - cmd (str) – An appropriate `STOR` command: `"STOR filename"`.

      - fp (file object) – A file object (opened in binary mode) which is read until EOF, using its `read()` method in blocks of size blocksize to provide the data to be stored.

      - blocksize (int) – The read block size. Defaults to `8192`.

      - callback (callable) – A single parameter callable that is called for each block of data sent, with its single argument being the data as `bytes`.

      - rest (int) – A `REST` command to be sent to the server. See the documentation for the rest parameter of the `transfercmd()` method.

    Змінено в версії 3.2: The rest parameter was added.

  storlines(cmd, fp, callback=None)

    Зберігайте файл у рядковому режимі. cmd має бути відповідною командою `STOR` (див. `storbinary()`). Рядки зчитуються до EOF з file object fp (відкритого у двійковому режимі) за допомогою його методу `readline()` для надання даних для збереження. callback — необов’язковий єдиний параметр, який викликається в кожному рядку після надсилання.

  transfercmd(cmd, rest=None)

    Ініціювати передачу через з’єднання даних. Якщо передача активна, надішліть команду `EPRT` або `PORT` і команду передачі, визначену cmd, і прийміть з’єднання. Якщо сервер пасивний, надішліть команду `EPSV` або `PASV`, підключіться до нього та запустіть команду передачі. У будь-якому випадку поверніть розетку для підключення.

    Якщо вказано необов’язковий rest, команда `REST` надсилається на сервер, передаючи rest як аргумент. rest зазвичай є зміщенням байтів у запитуваному файлі, повідомляючи серверу перезапустити надсилання байтів файлу із запитаним зміщенням, пропускаючи початкові байти. Однак зауважте, що метод `transfercmd()` перетворює rest на рядок із параметром encoding, указаним під час ініціалізації, але перевірка вмісту рядка не виконується. Якщо сервер не розпізнає команду `REST`, буде викликано виняток `error_reply`. Якщо це станеться, просто викличте `transfercmd()` без аргументу rest.

  ntransfercmd(cmd, rest=None)

    Подібно до `transfercmd()`, але повертає кортеж з’єднання даних і очікуваний розмір даних. Якщо очікуваний розмір не вдалося обчислити, як очікуваний розмір буде повернено «Немає». cmd і rest означають те саме, що й у `transfercmd()`.

  mlsd(path='', facts=[])

    Перерахуйте каталог у стандартизованому форматі за допомогою команди `MLSD` ( RFC 3659). Якщо шлях опущено, передбачається поточний каталог. факти — це список рядків, що представляють тип бажаної інформації (наприклад, `["тип", "розмір", "перм"]`). Повертає об’єкт-генератор, утворюючи кортеж із двох елементів для кожного файлу, знайденого на шляху. Перший елемент – ім’я файлу, другий – словник, що містить інформацію про ім’я файлу. Вміст цього словника може бути обмежений аргументом факти, але сервер не гарантує повернення всіх запитуваних фактів.

    Added in version 3.3.

  nlst(argument[, ...])

    Повертає список імен файлів, які повертає команда `NLST`. Необов’язковий аргумент — це каталог для переліку (за замовчуванням — це поточний каталог сервера). Для передачі нестандартних параметрів команді `NLST` можна використовувати кілька аргументів.

    Примітка

    Якщо ваш сервер підтримує команду, `mlsd()` пропонує кращий API.

  dir(argument[, ...])

    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 `retrlines()`; the default prints to `sys.stdout`. This method returns `None`.

    Примітка

    Якщо ваш сервер підтримує команду, `mlsd()` пропонує кращий API.

  rename(fromname, toname)

    Перейменуйте файл fromname на сервері на toname.

  delete(filename)

    Видаліть файл із назвою filename із сервера. У разі успіху повертає текст відповіді, інакше викликає `error_perm` у разі помилки дозволу або `error_reply` у випадку інших помилок.

  cwd(pathname)

    Встановити поточний каталог на сервері.

  mkd(pathname)

    Створіть новий каталог на сервері.

  pwd()

    Повертає шлях до поточного каталогу на сервері.

  rmd(dirname)

    Видаліть каталог із назвою dirname на сервері.

  size(filename)

    Запитати розмір файлу з назвою filename на сервері. У разі успіху розмір файлу повертається як ціле число, інакше повертається `None`. Зауважте, що команда `SIZE` не стандартизована, але підтримується багатьма поширеними серверними реалізаціями.

  quit()

    Надішліть команду `QUIT` на сервер і закрийте з’єднання. Це «ввічливий» спосіб закрити з’єднання, але він може спричинити виключення, якщо сервер відповість помилкою на команду `QUIT`. Це передбачає виклик методу `close()`, який робить екземпляр `FTP` марним для наступних викликів (див. нижче).

  close()

    Закрийте з’єднання в односторонньому порядку. Це не слід застосовувати до вже закритого з’єднання, наприклад після успішного виклику `quit()`. Після цього виклику екземпляр `FTP` більше не слід використовувати (після виклику `close()` або `quit()` ви не можете повторно відкрити з’єднання, виконавши інший спосіб `login()`).

### FTP_TLS objects

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')

  An `FTP` subclass which adds TLS support to FTP as described in RFC 4217. Connect to port 21 implicitly securing the FTP control connection before authenticating.

  Примітка

  The user must explicitly secure the data connection by calling the `prot_p()` method.

  Параметри:

    - host (str) – The hostname to connect to. If given, `connect(host)` is implicitly called by the constructor.

    - user (str) – The username to log in with (default: `'anonymous'`). If given, `login(host, passwd, acct)` is implicitly called by the constructor.

    - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

    - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

    - context (`ssl.SSLContext`) – An SSL context object which allows bundling SSL configuration options, certificates and private keys into a single, potentially long-lived, structure. Please read Міркування безпеки for best practices.

    - timeout (float | None) – A timeout in seconds for blocking operations like `connect()` (default: the global default timeout setting).

    - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    - encoding (str) – The encoding for directories and filenames (default: `'utf-8'`).

  Added in version 3.2.

  Змінено в версії 3.3: Added the source_address parameter.

  Змінено в версії 3.4: The class now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе `ValueError`, щоб запобігти створенню неблокуючого сокета. Параметр encoding було додано, а значення за замовчуванням змінено з Latin-1 на UTF-8 на RFC 2640.

  Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.

  Ось зразок сеансу з використанням класу `FTP_TLS`:

      >>> 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']

  `FTP_TLS` class inherits from `FTP`, defining these additional methods and attributes:

  ssl_version

    The SSL version to use (defaults to `ssl.PROTOCOL_SSLv23`).

  auth()

    Налаштуйте безпечне контрольне з’єднання за допомогою TLS або SSL, залежно від того, що вказано в атрибуті `ssl_version`.

    Змінено в версії 3.4: The method now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  ccc()

    Повернути канал керування назад до відкритого тексту. Це може бути корисним, щоб скористатися перевагами брандмауерів, які знають, як обробляти NAT із незахищеним FTP без відкриття фіксованих портів.

    Added in version 3.3.

  prot_p()

    Налаштуйте безпечне з’єднання даних.

  prot_c()

    Налаштуйте підключення для передачі даних у відкритому тексті.

### Module variables

exception ftplib.error_reply

  Виняток виникає, коли від сервера надходить неочікувана відповідь.

exception ftplib.error_temp

  Виняток виникає, коли отримано код помилки, що означає тимчасову помилку (коди відповіді в діапазоні 400–499).

exception ftplib.error_perm

  Виняток виникає, коли отримано код помилки, який означає постійну помилку (коди відповіді в діапазоні 500–599).

exception ftplib.error_proto

  Виняток виникає, коли відповідь, отримана від сервера, не відповідає специфікаціям відповіді протоколу передачі файлів, тобто починається з цифри в діапазоні 1–5.

ftplib.all_errors

  Набір усіх винятків (у вигляді кортежу), які методи екземплярів `FTP` можуть викликати в результаті проблем із з’єднанням FTP (на відміну від програмних помилок, зроблених абонентом). Цей набір включає чотири винятки, перелічені вище, а також `OSError` і `EOFError`.

Дивись також

Модуль `netrc`

  Парсер для формату файлу `.netrc`. Файл `.netrc` зазвичай використовується FTP-клієнтами для завантаження інформації про автентифікацію користувача перед запитом користувача.