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 Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. 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 STOR command: "STOR 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-клієнтами для завантаження інформації про автентифікацію користувача перед запитом користувача.