ftplib --- ứng dụng khách giao thức FTP

Source code: Lib/ftplib.py

Mô-đun này định nghĩa lớp FTP và một số mục liên quan. Lớp FTP triển khai phía máy khách của giao thức FTP. Bạn có thể sử dụng điều này để viết các chương trình Python thực hiện nhiều công việc FTP tự động khác nhau, chẳng hạn như sao chép các máy chủ FTP khác. Nó cũng được mô-đun urllib.request sử dụng để xử lý các URL sử dụng FTP. Để biết thêm thông tin về FTP (Giao thức truyền tệp), hãy xem internet RFC 959.

Mã hóa mặc định là UTF-8, theo sau RFC 2640.

sẵn có: not WASI.

Mô-đun này không hoạt động hoặc không có trên WebAssembly. Xem Nền tảng WebAssugging để biết thêm thông tin.

Đây là phiên mẫu sử dụng mô-đun ftplib:

>>> từ ftplib nhập FTP
>>> ftp = FTP('ftp.us.debian.org') # connect tới máy chủ, cổng mặc định
>>> ftp.login() # user ẩn danh, passwd ẩn danh@
'230 Đăng nhập thành công.'
>>> ftp.cwd('debian') # change vào thư mục "debian"
'Thư mục 250 đã được thay đổi thành công.'
>>> ftp.retrlines('LIST') nội dung thư mục # list
-rw-rw-r-- 1 1176 1176 1063 15 tháng 6 10:18 README
...
drwxr-sr-x 5 1176 1176 4096 Ngày 19 tháng 12 năm 2000 nhóm
dự án drwxr-sr-x 4 1176 1176 4096 17 tháng 11 năm 2008
drwxr-xr-x 3 1176 1176 4096 Ngày 10 tháng 10 năm 2012 công cụ
'226 Gửi thư mục OK.'
>>> với open('README', 'wb') là fp:
>>> ftp.retrbinary('RETR README', fp.write)
'226 Chuyển giao hoàn tất.'
>>> ftp.quit()
'221 Tạm biệt.'

Tài liệu tham khảo

đối tượng FTP

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

Trả về một phiên bản mới của lớp FTP.

Tham số:

  • host (str) -- Tên máy chủ để kết nối. Nếu được đưa ra, connect(host) được hàm tạo gọi ngầm.

  • user (str) -- The username to log in with (default: 'anonymous'). Nếu được cung cấp, login(host, passwd, acct) được hàm tạo ngầm gọi.

  • 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) -- Thời gian chờ tính bằng giây để chặn các hoạt động như connect() (mặc định: cài đặt thời gian chờ mặc định chung).

  • 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').

Lớp FTP hỗ trợ câu lệnh with, ví dụ:

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

Thay đổi trong phiên bản 3.2: Hỗ trợ cho câu lệnh with đã được thêm vào.

Thay đổi trong phiên bản 3.3: tham số source_address đã được thêm vào.

Thay đổi trong phiên bản 3.9: Nếu tham số timeout được đặt thành 0, nó sẽ tăng ValueError để ngăn việc tạo ổ cắm không chặn. Tham số encoding đã được thêm và mặc định đã được thay đổi từ Latin-1 thành UTF-8 để tuân theo RFC 2640.

Một số phương thức FTP có hai loại: một để xử lý tệp văn bản và một loại khác dành cho tệp nhị phân. Các phương thức được đặt tên theo lệnh được sử dụng, theo sau là lines cho phiên bản văn bản hoặc binary cho phiên bản nhị phân.

Các phiên bản FTP có các phương thức sau:

set_debuglevel(level)

Đặt mức gỡ lỗi của phiên bản là int. Điều này kiểm soát số lượng đầu ra gỡ lỗi được in. Các mức gỡ lỗi là:

  • 0 (mặc định): Không có đầu ra gỡ lỗi.

  • 1: Tạo ra lượng đầu ra gỡ lỗi vừa phải, thường là một dòng cho mỗi yêu cầu.

  • 2 trở lên: Tạo ra số lượng đầu ra gỡ lỗi tối đa, ghi lại từng dòng được gửi và nhận trên kết nối điều khiển.

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

Kết nối với máy chủ và cổng nhất định. Hàm này chỉ được gọi một lần cho mỗi phiên bản; nó không nên được gọi nếu đối số host được đưa ra khi phiên bản FTP được tạo. Tất cả các phương thức FTP khác chỉ có thể được gọi sau khi thực hiện kết nối thành công.

Tham số:

  • host (str) -- Máy chủ để kết nối.

  • port (int) -- Cổng TCP để kết nối (mặc định: 21, như được chỉ định bởi đặc tả giao thức FTP). Hiếm khi cần chỉ định số cổng khác.

  • timeout (float | None) -- Thời gian chờ tính bằng giây cho lần thử kết nối (mặc định: cài đặt thời gian chờ mặc định chung).

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

Tăng một auditing event ftplib.connect với các đối số self, host, port.

Thay đổi trong phiên bản 3.3: tham số source_address đã được thêm vào.

getwelcome()

Trả lại tin nhắn chào mừng được gửi bởi máy chủ để trả lời kết nối ban đầu. (Thông báo này đôi khi chứa tuyên bố từ chối trách nhiệm hoặc thông tin trợ giúp có thể liên quan đến người dùng.)

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

Đăng nhập vào máy chủ FTP được kết nối. Hàm này chỉ được gọi một lần cho mỗi phiên bản sau khi kết nối được thiết lập; nó không nên được gọi nếu các đối số host và user được đưa ra khi phiên bản FTP được tạo. Hầu hết các lệnh FTP chỉ được phép sau khi máy khách đã đăng nhập.

Tham số:

  • 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()

Hủy bỏ quá trình truyền tập tin đang diễn ra. Việc sử dụng cách này không phải lúc nào cũng hiệu quả nhưng đáng để thử.

sendcmd(cmd)

Gửi một chuỗi lệnh đơn giản đến máy chủ và trả về chuỗi phản hồi.

Tăng một auditing event ftplib.sendcmd với các đối số self, cmd.

voidcmd(cmd)

Gửi một chuỗi lệnh đơn giản đến máy chủ và xử lý phản hồi. Trả về chuỗi phản hồi nếu mã phản hồi tương ứng với thành công (mã trong phạm vi 200--299). Nếu không thì hãy tăng error_reply.

Tăng một auditing event ftplib.sendcmd với các đối số self, cmd.

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

Truy xuất tệp ở chế độ truyền nhị phân.

Tham số:

  • cmd (str) -- Lệnh RETR thích hợp: "RETR filename".

  • callback (callable) -- Một tham số duy nhất có thể gọi được, được gọi cho mỗi khối dữ liệu nhận được, với đối số duy nhất của nó là dữ liệu dưới dạng bytes.

  • blocksize (int) -- Kích thước đoạn tối đa để đọc trên đối tượng socket cấp thấp được tạo để thực hiện quá trình truyền thực tế. Điều này cũng tương ứng với kích thước lớn nhất của dữ liệu sẽ được chuyển tới callback. Mặc định là 8192.

  • rest (int) -- Lệnh REST sẽ được gửi đến máy chủ. Xem tài liệu về tham số rest của phương thức transfercmd().

retrlines(cmd, callback=None)

Truy xuất danh sách tệp hoặc thư mục trong mã hóa được chỉ định bởi tham số encoding khi khởi tạo. cmd phải là lệnh RETR thích hợp (xem retrbinary()) hoặc một lệnh như LIST hoặc NLST (thường chỉ là chuỗi 'LIST'). LIST lấy danh sách các file và thông tin về các file đó. NLST lấy danh sách tên tệp. Hàm callback được gọi cho mỗi dòng có đối số chuỗi chứa dòng bị loại bỏ CRLF ở cuối. Zz011zz mặc định in dòng thành sys.stdout.

set_pasv(val)

Bật chế độ "thụ động" nếu val đúng, nếu không thì tắt chế độ thụ động. Chế độ thụ động được bật theo mặc định.

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

Lưu trữ một tập tin ở chế độ truyền nhị phân.

Tham số:

  • cmd (str) -- Lệnh STOR thích hợp: "STOR filename".

  • fp (file object) -- Một đối tượng tệp (được mở ở chế độ nhị phân) được đọc cho đến EOF, sử dụng phương thức read() của nó trong các khối có kích thước blocksize để cung cấp dữ liệu được lưu trữ.

  • blocksize (int) -- Kích thước khối đọc. Mặc định là 8192.

  • callback (callable) -- Một tham số duy nhất có thể gọi được, được gọi cho mỗi khối dữ liệu được gửi, với đối số duy nhất của nó là dữ liệu dưới dạng bytes.

  • rest (int) -- Lệnh REST sẽ được gửi đến máy chủ. Xem tài liệu về tham số rest của phương thức transfercmd().

Thay đổi trong phiên bản 3.2: Tham số rest đã được thêm vào.

storlines(cmd, fp, callback=None)

Lưu trữ một tập tin ở chế độ dòng. cmd phải là lệnh STOR thích hợp (xem storbinary()). Các dòng được đọc cho đến EOF từ file object fp (mở ở chế độ nhị phân) bằng phương pháp readline() để cung cấp dữ liệu được lưu trữ. callback là một tham số đơn tùy chọn có thể gọi được trên mỗi dòng sau khi nó được gửi.

transfercmd(cmd, rest=None)

Bắt đầu chuyển qua kết nối dữ liệu. Nếu quá trình truyền đang hoạt động, hãy gửi lệnh EPRT hoặc PORT và lệnh truyền do cmd chỉ định rồi chấp nhận kết nối. Nếu máy chủ thụ động, hãy gửi lệnh EPSV hoặc PASV, kết nối với nó và bắt đầu lệnh truyền. Dù bằng cách nào, hãy trả lại ổ cắm để kết nối.

Nếu rest tùy chọn được cung cấp, lệnh REST sẽ được gửi đến máy chủ, chuyển rest làm đối số. rest thường là phần bù byte vào tệp được yêu cầu, yêu cầu máy chủ khởi động lại việc gửi byte của tệp ở phần bù được yêu cầu, bỏ qua các byte ban đầu. Tuy nhiên, xin lưu ý rằng phương thức transfercmd() chuyển đổi rest thành một chuỗi có tham số encoding được chỉ định khi khởi tạo nhưng không thực hiện kiểm tra nào đối với nội dung của chuỗi. Nếu máy chủ không nhận ra lệnh REST, ngoại lệ error_reply sẽ xuất hiện. Nếu điều này xảy ra, chỉ cần gọi transfercmd() mà không có đối số rest.

ntransfercmd(cmd, rest=None)

Giống như transfercmd(), nhưng trả về một bộ kết nối dữ liệu và kích thước dự kiến của dữ liệu. Nếu không thể tính được kích thước dự kiến, None sẽ được trả về như kích thước dự kiến. cmd và rest có nghĩa tương tự như trong transfercmd().

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

Liệt kê một thư mục ở định dạng chuẩn hóa bằng cách sử dụng lệnh MLSD (RFC 3659). Nếu path bị bỏ qua thì thư mục hiện tại sẽ được giả định. facts là danh sách các chuỗi đại diện cho loại thông tin mong muốn (ví dụ: ["type", "size", "perm"]). Trả về một đối tượng trình tạo mang lại một bộ gồm hai phần tử cho mỗi tệp được tìm thấy trong đường dẫn. Phần tử đầu tiên là tên tệp, phần tử thứ hai là từ điển chứa thông tin về tên tệp. Nội dung của từ điển này có thể bị giới hạn bởi đối số facts nhưng máy chủ không đảm bảo trả về tất cả thông tin được yêu cầu.

Added in version 3.3.

nlst(argument[, ...])

Trả về danh sách tên tệp được trả về bởi lệnh NLST. Zz002zz tùy chọn là một thư mục để liệt kê (mặc định là thư mục máy chủ hiện tại). Nhiều đối số có thể được sử dụng để chuyển các tùy chọn không chuẩn cho lệnh NLST.

Ghi chú

Nếu máy chủ của bạn hỗ trợ lệnh, mlsd() sẽ cung cấp API tốt hơn.

dir(argument[, ...])

Tạo danh sách thư mục được trả về bởi lệnh LIST, in nó ra đầu ra tiêu chuẩn. Zz005zz tùy chọn là một thư mục để liệt kê (mặc định là thư mục máy chủ hiện tại). Nhiều đối số có thể được sử dụng để chuyển các tùy chọn không chuẩn cho lệnh LIST. Nếu đối số cuối cùng là một hàm thì nó được sử dụng làm hàm callback như đối với retrlines(); mặc định in ra sys.stdout. Phương thức này trả về None.

Ghi chú

Nếu máy chủ của bạn hỗ trợ lệnh, mlsd() sẽ cung cấp API tốt hơn.

rename(fromname, toname)

Đổi tên file fromname trên máy chủ thành toname.

delete(filename)

Xóa tệp có tên filename khỏi máy chủ. Nếu thành công, trả về văn bản phản hồi, nếu không sẽ tăng error_perm đối với các lỗi về quyền hoặc error_reply đối với các lỗi khác.

cwd(pathname)

Đặt thư mục hiện tại trên máy chủ.

mkd(pathname)

Tạo một thư mục mới trên máy chủ.

pwd()

Trả về tên đường dẫn của thư mục hiện tại trên máy chủ.

rmd(dirname)

Xóa thư mục có tên dirname trên máy chủ.

size(filename)

Yêu cầu kích thước của tệp có tên filename trên máy chủ. Nếu thành công, kích thước của tệp được trả về dưới dạng số nguyên, nếu không thì trả về None. Lưu ý rằng lệnh SIZE không được chuẩn hóa nhưng được hỗ trợ bởi nhiều triển khai máy chủ phổ biến.

quit()

Gửi lệnh QUIT đến máy chủ và đóng kết nối. Đây là cách "lịch sự" để đóng kết nối, nhưng nó có thể gây ra ngoại lệ nếu máy chủ phản hồi với lỗi với lệnh QUIT. Điều này hàm ý một lệnh gọi đến phương thức close() khiến phiên bản FTP trở nên vô dụng đối với các lệnh gọi tiếp theo (xem bên dưới).

close()

Đóng kết nối đơn phương. Không nên áp dụng điều này cho kết nối đã đóng, chẳng hạn như sau khi gọi thành công tới quit(). Sau lệnh gọi này, phiên bản FTP sẽ không được sử dụng nữa (sau lệnh gọi tới close() hoặc quit(), bạn không thể mở lại kết nối bằng cách đưa ra một phương thức login() khác).

đối tượng FTP_TLS

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

Một lớp con FTP bổ sung hỗ trợ TLS cho FTP như được mô tả trong RFC 4217. Kết nối với cổng 21 ngầm đảm bảo kết nối điều khiển FTP trước khi xác thực.

Ghi chú

Người dùng phải bảo mật rõ ràng kết nối dữ liệu bằng cách gọi phương thức prot_p().

Tham số:

  • host (str) -- Tên máy chủ để kết nối. Nếu được đưa ra, connect(host) được hàm tạo gọi ngầm.

  • user (str) -- The username to log in with (default: 'anonymous'). Nếu được cung cấp, login(host, passwd, acct) được hàm tạo ngầm gọi.

  • 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) -- Một đối tượng ngữ cảnh SSL cho phép gộp các tùy chọn cấu hình, chứng chỉ và khóa riêng của SSL vào một cấu trúc duy nhất, có khả năng tồn tại lâu dài. Vui lòng đọc Cân nhắc về bảo mật để biết các phương pháp hay nhất.

  • timeout (float | None) -- Thời gian chờ tính bằng giây để chặn các hoạt động như connect() (mặc định: cài đặt thời gian chờ mặc định chung).

  • 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.

Thay đổi trong phiên bản 3.3: Đã thêm tham số source_address.

Thay đổi trong phiên bản 3.4: Lớp hiện hỗ trợ kiểm tra tên máy chủ bằng ssl.SSLContext.check_hostname và Server Name Indication (xem ssl.HAS_SNI).

Thay đổi trong phiên bản 3.9: Nếu tham số timeout được đặt thành 0, nó sẽ tăng ValueError để ngăn việc tạo ổ cắm không chặn. Tham số encoding đã được thêm và mặc định đã được thay đổi từ Latin-1 thành UTF-8 để tuân theo RFC 2640.

Thay đổi trong phiên bản 3.12: Các tham số keyfile và certfile không được dùng nữa đã bị xóa.

Đây là phiên mẫu sử dụng lớp FTP_TLS:

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Người dùng ẩn danh đã đăng nhập'
>>> ftps.prot_p()
'200 Mức độ bảo vệ dữ liệu được đặt thành "riêng tư"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'bỏ qua', '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', 'âm thanh', 'tmp', 'ucarp']

Lớp FTP_TLS kế thừa từ FTP, xác định các phương thức và thuộc tính bổ sung sau:

ssl_version

Phiên bản SSL sẽ sử dụng (mặc định là ssl.PROTOCOL_SSLv23).

auth()

Thiết lập kết nối điều khiển an toàn bằng cách sử dụng TLS hoặc SSL, tùy thuộc vào nội dung được chỉ định trong thuộc tính ssl_version.

Thay đổi trong phiên bản 3.4: Phương pháp này hiện hỗ trợ kiểm tra tên máy chủ bằng ssl.SSLContext.check_hostname và Server Name Indication (xem ssl.HAS_SNI).

ccc()

Hoàn nguyên kênh điều khiển về dạng bản rõ. Điều này có thể hữu ích để tận dụng tường lửa biết cách xử lý NAT với FTP không an toàn mà không cần mở các cổng cố định.

Added in version 3.3.

prot_p()

Thiết lập kết nối dữ liệu an toàn.

prot_c()

Thiết lập kết nối dữ liệu văn bản rõ ràng.

Biến mô-đun

exception ftplib.error_reply

Ngoại lệ nảy sinh khi nhận được phản hồi không mong muốn từ máy chủ.

exception ftplib.error_temp

Ngoại lệ nảy sinh khi nhận được mã lỗi biểu thị lỗi tạm thời (mã phản hồi trong phạm vi 400--499).

exception ftplib.error_perm

Ngoại lệ nảy sinh khi nhận được mã lỗi biểu thị lỗi vĩnh viễn (mã phản hồi trong phạm vi 500--599).

exception ftplib.error_proto

Ngoại lệ nảy sinh khi nhận được phản hồi từ máy chủ không phù hợp với thông số kỹ thuật phản hồi của Giao thức truyền tệp, tức là bắt đầu bằng một chữ số trong phạm vi 1--5.

ftplib.all_errors

Tập hợp tất cả các ngoại lệ (dưới dạng một bộ) mà các phương thức của phiên bản FTP có thể phát sinh do sự cố với kết nối FTP (trái ngược với lỗi lập trình do người gọi gây ra). Bộ này bao gồm bốn trường hợp ngoại lệ được liệt kê ở trên cũng như OSError và EOFError.

Xem thêm

Mô-đun netrc

Trình phân tích cú pháp cho định dạng tệp .netrc. Tệp .netrc thường được máy khách FTP sử dụng để tải thông tin xác thực người dùng trước khi nhắc người dùng.