`urllib.request` --- Thư viện mở rộng để mở URL¶

Source code: Lib/urllib/request.py

Mô-đun urllib.request xác định các hàm và lớp giúp mở URL (chủ yếu là HTTP) trong một thế giới phức tạp --- xác thực cơ bản và tóm tắt, chuyển hướng, cookie, v.v.

Xem thêm

Zz000zz được khuyên dùng cho giao diện máy khách HTTP cấp cao hơn.

Cảnh báo

Trên macOS, việc sử dụng mô-đun này trong các chương trình sử dụng os.fork() là không an toàn vì việc triển khai getproxies() cho macOS sử dụng hệ thống cấp cao hơn API. Đặt biến môi trường no_proxy thành * để tránh sự cố này (ví dụ: os.environ["no_proxy"] = "*").

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.

Mô-đun urllib.request xác định các chức năng sau:

urllib.request.urlopen(url, data=None, [timeout, ]*, context=None)¶

Mở url, có thể là một chuỗi chứa URL được mã hóa hợp lệ hoặc một đối tượng Request.

data phải là một đối tượng chỉ định dữ liệu bổ sung sẽ được gửi đến máy chủ hoặc None nếu không cần dữ liệu đó. Xem Request để biết chi tiết.

mô-đun urllib.request sử dụng HTTP/1.1 và bao gồm tiêu đề Connection:close trong các yêu cầu HTTP của nó.

Tham số timeout tùy chọn chỉ định thời gian chờ tính bằng giây cho các hoạt động chặn như nỗ lực kết nối (nếu không được chỉ định, cài đặt thời gian chờ mặc định chung sẽ được sử dụng). Điều này thực sự chỉ hoạt động đối với các kết nối HTTP, HTTPS và FTP.

Nếu context được chỉ định, thì đó phải là phiên bản ssl.SSLContext mô tả các tùy chọn SSL khác nhau. Xem HTTPSConnection để biết thêm chi tiết.

Hàm này luôn trả về một đối tượng có thể hoạt động như một context manager và có các thuộc tính url, headers và status. Xem urllib.response.addinfourl để biết thêm chi tiết về các thuộc tính này.

Đối với URL HTTP và HTTPS, hàm này trả về một đối tượng http.client.HTTPResponse được sửa đổi một chút. Ngoài ba phương thức mới ở trên, thuộc tính msg còn chứa thông tin tương tự như thuộc tính reason --- cụm từ lý do được máy chủ trả về --- thay vì tiêu đề phản hồi như được chỉ định trong tài liệu dành cho HTTPResponse.

Đối với các URL FTP, tệp và dữ liệu, hàm này trả về một đối tượng urllib.response.addinfourl.

Tăng URLError do lỗi giao thức.

Lưu ý rằng None có thể được trả về nếu không có trình xử lý nào xử lý yêu cầu (mặc dù OpenerDirector toàn cục được cài đặt mặc định sử dụng UnknownHandler để đảm bảo điều này không bao giờ xảy ra).

Ngoài ra, nếu phát hiện cài đặt proxy (ví dụ: khi biến môi trường *_proxy như http_proxy được đặt), ProxyHandler được cài đặt mặc định và đảm bảo các yêu cầu được xử lý thông qua proxy.

Hàm urllib.urlopen kế thừa từ Python 2.6 trở về trước đã bị ngừng hoạt động; urllib.request.urlopen() tương ứng với urllib2.urlopen cũ. Việc xử lý proxy, được thực hiện bằng cách chuyển tham số từ điển tới urllib.urlopen, có thể thu được bằng cách sử dụng các đối tượng ProxyHandler.

Công cụ mở mặc định tạo ra một auditing event urllib.Request với các đối số fullurl, data, headers, method được lấy từ đối tượng yêu cầu.

Thay đổi trong phiên bản 3.2: cafile và capath đã được thêm vào.

Máy chủ ảo HTTPS hiện được hỗ trợ nếu có thể (nghĩa là nếu ssl.HAS_SNI là đúng).

data có thể là một đối tượng có thể lặp lại.

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

Thay đổi trong phiên bản 3.4.3: context đã được thêm vào.

Thay đổi trong phiên bản 3.10: Kết nối HTTPS hiện gửi tiện ích mở rộng ALPN với chỉ báo giao thức http/1.1 khi không cung cấp context. Zz003zz tùy chỉnh nên đặt giao thức ALPN với set_alpn_protocols().

Thay đổi trong phiên bản 3.13: Xóa tham số cafile, capath và cadefault: thay vào đó hãy sử dụng tham số context.

urllib.request.install_opener(opener)¶: Cài đặt phiên bản OpenerDirector làm công cụ mở toàn cục mặc định. Việc cài đặt một trình mở chỉ cần thiết nếu bạn muốn urlopen sử dụng trình mở đó; nếu không, chỉ cần gọi OpenerDirector.open() thay vì urlopen(). Mã không kiểm tra OpenerDirector thực sự và bất kỳ lớp nào có giao diện phù hợp sẽ hoạt động.

urllib.request.build_opener([handler, ...])¶

Trả về một phiên bản OpenerDirector, xâu chuỗi các trình xử lý theo thứ tự đã cho. handlers có thể là phiên bản của BaseHandler hoặc lớp con của BaseHandler (trong trường hợp đó, có thể gọi hàm tạo mà không có bất kỳ tham số nào). Các phiên bản của các lớp sau sẽ ở phía trước handlers, trừ khi handlers chứa chúng, các phiên bản của chúng hoặc các lớp con của chúng: ProxyHandler (nếu phát hiện thấy cài đặt proxy), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Nếu cài đặt Python có hỗ trợ SSL (tức là nếu mô-đun ssl có thể được nhập), HTTPSHandler cũng sẽ được thêm vào.

Lớp con BaseHandler cũng có thể thay đổi thuộc tính handler_order để sửa đổi vị trí của nó trong danh sách trình xử lý.

urllib.request.pathname2url(path, *, add_scheme=False)¶

Chuyển đổi đường dẫn cục bộ đã cho thành file: URL. Hàm này sử dụng hàm quote() để mã hóa đường dẫn.

Nếu add_scheme là sai (mặc định), giá trị trả về sẽ bỏ qua tiền tố lược đồ file:. Đặt add_scheme thành true để trả về URL hoàn chỉnh.

Ví dụ này cho thấy chức năng đang được sử dụng trên Windows:

>>> từ urllib.request nhập pathname2url
>>> path = 'C:\\Program Files'
>>> pathname2url(đường dẫn, add_scheme=True)
'file:///C:/Program%20Files'

Thay đổi trong phiên bản 3.14: Các ký tự ổ đĩa Windows không còn được chuyển đổi thành chữ hoa và các ký tự : không theo sau ký tự ổ đĩa không còn gây ra ngoại lệ OSError trên Windows.

Thay đổi trong phiên bản 3.14: Đường dẫn bắt đầu bằng dấu gạch chéo được chuyển đổi thành URL có phần quyền hạn. Ví dụ: đường dẫn /etc/hosts được chuyển đổi thành URL ///etc/hosts.

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

urllib.request.url2pathname(url, *, require_scheme=False, resolve_host=False)¶

Chuyển đổi file: URL đã cho thành đường dẫn cục bộ. Hàm này sử dụng unquote() để giải mã URL.

Nếu require_scheme là sai (mặc định), giá trị đã cho sẽ bỏ qua tiền tố lược đồ file:. Nếu require_scheme được đặt thành true thì giá trị đã cho phải bao gồm tiền tố; một URLError sẽ được nâng lên nếu không.

Quyền URL sẽ bị loại bỏ nếu nó trống, localhost hoặc tên máy chủ cục bộ. Mặt khác, nếu resolve_host được đặt thành true, quyền hạn sẽ được giải quyết bằng cách sử dụng socket.gethostbyname() và bị loại bỏ nếu nó khớp với địa chỉ IP cục bộ (theo RFC 8089 §3). Nếu quyền vẫn chưa được xử lý thì trên Windows, đường dẫn UNC sẽ được trả về và trên các nền tảng khác, URLError sẽ được nâng lên.

Ví dụ này cho thấy chức năng đang được sử dụng trên Windows:

>>> từ urllib.request nhập url2pathname
>>> url = 'file:///C:/Program%20Files'
>>> url2pathname(url, require_scheme=True)
'C:\\Tệp chương trình'

Thay đổi trong phiên bản 3.14: Các ký tự ổ đĩa Windows không còn được chuyển đổi thành chữ hoa và các ký tự : không theo sau ký tự ổ đĩa không còn gây ra ngoại lệ OSError trên Windows.

Thay đổi trong phiên bản 3.14: Quyền URL sẽ bị loại bỏ nếu nó khớp với tên máy chủ cục bộ. Ngược lại, nếu quyền không trống hoặc localhost thì trên Windows, đường dẫn UNC sẽ được trả về (như trước) và trên các nền tảng khác, URLError sẽ được nâng lên.

Thay đổi trong phiên bản 3.14: Các thành phần truy vấn và phân đoạn URL sẽ bị loại bỏ nếu có.

Thay đổi trong phiên bản 3.14: Các thông số require_scheme và resolve_host đã được thêm vào.

urllib.request.getproxies()¶: Hàm trợ giúp này trả về một từ điển lược đồ cho ánh xạ URL của máy chủ proxy. Nó quét môi trường để tìm các biến có tên <scheme>_proxy, theo cách tiếp cận không phân biệt chữ hoa chữ thường, cho tất cả các hệ điều hành trước tiên và khi không thể tìm thấy biến đó, nó sẽ tìm thông tin proxy từ Cấu hình hệ thống cho macOS và Windows Systems Register cho Windows. Nếu tồn tại cả hai biến môi trường chữ thường và chữ hoa (và không đồng ý), chữ thường sẽ được ưu tiên.

Ghi chú

Nếu biến môi trường REQUEST_METHOD được đặt, điều này thường cho biết tập lệnh của bạn đang chạy trong môi trường CGI, thì biến môi trường HTTP_PROXY (chữ hoa _PROXY) sẽ bị bỏ qua. Điều này là do biến đó có thể được khách hàng đưa vào bằng cách sử dụng tiêu đề "Proxy:" HTTP. Nếu bạn cần sử dụng proxy HTTP trong môi trường CGI, hãy sử dụng ProxyHandler một cách rõ ràng hoặc đảm bảo tên biến ở dạng chữ thường (hoặc ít nhất là hậu tố _proxy).

Các lớp sau đây được cung cấp:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)¶

Lớp này là một bản tóm tắt của yêu cầu URL.

url phải là một chuỗi chứa URL hợp lệ, được mã hóa chính xác.

data phải là đối tượng chỉ định dữ liệu bổ sung để gửi đến máy chủ hoặc None nếu không cần dữ liệu đó. Hiện tại, các yêu cầu HTTP là những yêu cầu duy nhất sử dụng data. Các loại đối tượng được hỗ trợ bao gồm byte, đối tượng giống tệp và các đối tượng giống byte có thể lặp lại. Nếu không cung cấp trường tiêu đề Content-Length hay Transfer-Encoding, HTTPHandler sẽ đặt các tiêu đề này theo loại data. Content-Length sẽ được sử dụng để gửi các đối tượng byte, trong khi Transfer-Encoding: chunked như được chỉ định trong RFC 7230, Mục 3.3.1 sẽ được sử dụng để gửi các tệp và các lần lặp khác.

Đối với phương thức yêu cầu HTTP POST, data phải là bộ đệm ở định dạng application/x-www-form-urlencoded tiêu chuẩn. Hàm urllib.parse.urlencode() lấy ánh xạ hoặc chuỗi gồm 2 bộ dữ liệu và trả về chuỗi ASCII ở định dạng này. Nó phải được mã hóa thành byte trước khi được sử dụng làm tham số data.

headers phải là một từ điển và sẽ được xử lý như thể add_header() được gọi với mỗi khóa và giá trị làm đối số. Điều này thường được sử dụng để "giả mạo" giá trị tiêu đề User-Agent, được trình duyệt sử dụng để nhận dạng chính nó -- một số máy chủ HTTP chỉ cho phép các yêu cầu đến từ các trình duyệt phổ biến thay vì tập lệnh. Ví dụ: Mozilla Firefox có thể tự nhận mình là "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11", trong khi chuỗi tác nhân người dùng mặc định của urllib là "Python-urllib/2.6" (trên Python 2.6). Tất cả các khóa tiêu đề được gửi trong hộp đựng lạc đà.

Phải bao gồm tiêu đề Content-Type thích hợp nếu có đối số data. Nếu tiêu đề này chưa được cung cấp và data không phải là None thì Content-Type: application/x-www-form-urlencoded sẽ được thêm làm mặc định.

Hai đối số tiếp theo chỉ được quan tâm để xử lý chính xác cookie HTTP của bên thứ ba:

origin_req_host phải là máy chủ yêu cầu của giao dịch gốc, như được xác định bởi RFC 2965. Nó mặc định là http.cookiejar.request_host(self). Đây là tên máy chủ hoặc địa chỉ IP của yêu cầu ban đầu do người dùng thực hiện. Ví dụ: nếu yêu cầu dành cho một hình ảnh trong tài liệu HTML thì đây sẽ là máy chủ lưu trữ yêu cầu của yêu cầu đối với trang chứa hình ảnh.

unverifiable phải cho biết liệu yêu cầu có thể xác minh được hay không, như được xác định bởi RFC 2965. Nó mặc định là False. Yêu cầu không thể xác minh là yêu cầu mà người dùng không có tùy chọn phê duyệt URL. Ví dụ: nếu yêu cầu dành cho một hình ảnh trong tài liệu HTML và người dùng không có tùy chọn phê duyệt việc tìm nạp hình ảnh tự động thì điều này đúng.

method phải là một chuỗi cho biết phương thức yêu cầu HTTP sẽ được sử dụng (ví dụ: 'HEAD'). Nếu được cung cấp, giá trị của nó sẽ được lưu trữ trong thuộc tính method và được get_method() sử dụng. Mặc định là 'GET' nếu data là None hoặc 'POST' nếu ngược lại. Các lớp con có thể chỉ ra một phương thức mặc định khác bằng cách đặt thuộc tính method trong chính lớp đó.

Ghi chú

Yêu cầu sẽ không hoạt động như mong đợi nếu đối tượng dữ liệu không thể phân phối nội dung của nó nhiều lần (ví dụ: một tệp hoặc một iterable chỉ có thể tạo ra nội dung một lần) và yêu cầu được thử lại để chuyển hướng hoặc xác thực HTTP. Zz000zz được gửi đến máy chủ HTTP ngay sau tiêu đề. Không có sự hỗ trợ nào cho kỳ vọng tiếp tục 100 lần trong thư viện.

Thay đổi trong phiên bản 3.3: Đối số Request.method được thêm vào lớp Yêu cầu.

Thay đổi trong phiên bản 3.4: Request.method mặc định có thể được chỉ định ở cấp độ lớp.

Thay đổi trong phiên bản 3.6: Không đưa ra lỗi nếu Content-Length chưa được cung cấp và data không phải là None hay đối tượng byte. Thay vào đó hãy quay lại sử dụng mã hóa chuyển khối.

class urllib.request.OpenerDirector¶: Lớp OpenerDirector mở URL thông qua các BaseHandler được nối với nhau. Nó quản lý việc xâu chuỗi các trình xử lý và phục hồi sau các lỗi.

class urllib.request.BaseHandler¶: Đây là lớp cơ sở cho tất cả các trình xử lý đã đăng ký --- và chỉ xử lý các cơ chế đăng ký đơn giản.

class urllib.request.HTTPDefaultErrorHandler¶: Một lớp xác định trình xử lý mặc định cho các phản hồi lỗi HTTP; tất cả các phản hồi đều được chuyển thành ngoại lệ HTTPError.

class urllib.request.HTTPRedirectHandler¶: Một lớp để xử lý các chuyển hướng.

class urllib.request.HTTPCookieProcessor(cookiejar=None)¶: Một lớp để xử lý Cookie HTTP.

class urllib.request.ProxyHandler(proxies=None)¶

Khiến các yêu cầu phải đi qua proxy. Nếu proxies được cung cấp, nó phải là tên giao thức ánh xạ từ điển tới URL của proxy. Mặc định là đọc danh sách proxy từ các biến môi trường <protocol>_proxy. Nếu không có biến môi trường proxy nào được đặt thì cài đặt proxy trong môi trường Windows sẽ được lấy từ phần Cài đặt Internet của cơ quan đăng ký và trong môi trường macOS, thông tin proxy sẽ được lấy từ Khung cấu hình hệ thống.

Để tắt proxy được tự động phát hiện, hãy chuyển một từ điển trống.

Biến môi trường no_proxy có thể được sử dụng để chỉ định các máy chủ không thể truy cập qua proxy; nếu được đặt, nó phải là danh sách các hậu tố tên máy chủ được phân tách bằng dấu phẩy, tùy chọn có thêm :port, ví dụ: cern.ch,ncsa.uiuc.edu,some.host:8080.

Ghi chú

HTTP_PROXY sẽ bị bỏ qua nếu biến REQUEST_METHOD được đặt; xem tài liệu trên getproxies().

class urllib.request.HTTPPasswordMgr¶: Giữ cơ sở dữ liệu về ánh xạ (realm, uri) -> (user, password).

class urllib.request.HTTPPasswordMgrWithDefaultRealm¶: Giữ cơ sở dữ liệu về ánh xạ (realm, uri) -> (user, password). Một lĩnh vực của None được coi là một lĩnh vực tổng hợp, được tìm kiếm nếu không có lĩnh vực nào khác phù hợp.

class urllib.request.HTTPPasswordMgrWithPriorAuth¶: Một biến thể của HTTPPasswordMgrWithDefaultRealm cũng có cơ sở dữ liệu về ánh xạ uri -> is_authenticated. Có thể được trình xử lý BasicAuth sử dụng để xác định thời điểm gửi thông tin xác thực ngay lập tức thay vì chờ phản hồi 401 trước.

Added in version 3.5.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)¶: Đây là lớp mixin giúp xác thực HTTP, cho cả máy chủ từ xa và proxy. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ. Nếu passwd_mgr cũng cung cấp các phương thức is_authenticated và update_authenticated (xem Đối tượng HTTPPasswordMgrWithPriorAuth), thì trình xử lý sẽ sử dụng kết quả is_authenticated cho một URI nhất định để xác định xem có gửi thông tin xác thực cùng với yêu cầu hay không. Nếu is_authenticated trả về True cho URI, thông tin đăng nhập sẽ được gửi. Nếu is_authenticated là False, thông tin xác thực sẽ không được gửi và sau đó nếu nhận được phản hồi 401 thì yêu cầu sẽ được gửi lại cùng với thông tin xác thực. Nếu xác thực thành công, update_authenticated được gọi để đặt is_authenticated True cho URI, để các yêu cầu tiếp theo tới URI hoặc bất kỳ siêu URI nào của nó sẽ tự động bao gồm thông tin xác thực xác thực.

Added in version 3.5: Đã thêm hỗ trợ is_authenticated.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)¶: Xử lý xác thực với máy chủ từ xa. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ. HTTPBasicAuthHandler sẽ đưa ra ValueError khi được trình bày với sơ đồ Xác thực sai.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)¶: Xử lý xác thực bằng proxy. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)¶: Đây là lớp mixin giúp xác thực HTTP, cho cả máy chủ từ xa và proxy. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ.

Thay đổi trong phiên bản 3.14: Đã thêm hỗ trợ cho thuật toán xác thực thông báo HTTP SHA-256.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)¶: Xử lý xác thực với máy chủ từ xa. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ. Khi cả Trình xử lý xác thực thông báo và Trình xử lý xác thực cơ bản đều được thêm, Xác thực thông báo luôn được thử trước tiên. Nếu Xác thực thông báo lại trả về phản hồi 40x, nó sẽ được gửi đến trình xử lý Xác thực cơ bản để Xử lý. Phương thức Trình xử lý này sẽ đưa ra ValueError khi được trình bày với một sơ đồ xác thực không phải là Digest hoặc Basic.

Thay đổi trong phiên bản 3.3: Tăng ValueError trên Lược đồ xác thực không được hỗ trợ.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)¶: Xử lý xác thực bằng proxy. password_mgr, nếu được cung cấp, phải là thứ tương thích với HTTPPasswordMgr; tham khảo phần Đối tượng HTTPPasswordMgr để biết thông tin về giao diện phải được hỗ trợ.

class urllib.request.HTTPHandler¶: Một lớp để xử lý việc mở các URL HTTP.

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)¶: Một lớp để xử lý việc mở URL HTTPS. context và check_hostname có cùng ý nghĩa như trong http.client.HTTPSConnection.

Thay đổi trong phiên bản 3.2: context và check_hostname đã được thêm vào.

class urllib.request.FileHandler¶: Mở tập tin cục bộ.

class urllib.request.DataHandler¶: Mở URL dữ liệu.

Added in version 3.4.

class urllib.request.FTPHandler¶: Mở URL FTP.

class urllib.request.CacheFTPHandler¶: Mở URL FTP, lưu giữ bộ đệm của các kết nối FTP đang mở để giảm thiểu độ trễ.

class urllib.request.UnknownHandler¶: Một lớp tổng hợp để xử lý các URL không xác định.

class urllib.request.HTTPErrorProcessor¶: Xử lý phản hồi lỗi HTTP.

Đối tượng yêu cầu¶

Các phương thức sau đây mô tả giao diện chung của Request và do đó tất cả đều có thể bị ghi đè trong các lớp con. Nó cũng xác định một số thuộc tính công khai mà khách hàng có thể sử dụng để kiểm tra yêu cầu được phân tích cú pháp.

Request.full_url¶

Zz000zz ban đầu được chuyển cho hàm tạo.

Thay đổi trong phiên bản 3.4.

request.full_url là một thuộc tính có setter, getter và deleter. Nhận full_url trả về yêu cầu ban đầu URL với đoạn đó, nếu nó có mặt.

Request.type¶: Sơ đồ URI.

Request.host¶: Cơ quan URI, thường là máy chủ nhưng cũng có thể chứa một cổng được phân tách bằng dấu hai chấm.

Request.origin_req_host¶: Máy chủ gốc cho yêu cầu, không có cổng.

Request.selector¶: Đường dẫn URI. Nếu Request sử dụng proxy thì bộ chọn sẽ là URL đầy đủ được chuyển tới proxy.

Request.data¶: Nội dung thực thể cho yêu cầu hoặc None nếu không được chỉ định.

Thay đổi trong phiên bản 3.4: Việc thay đổi giá trị của Request.data hiện sẽ xóa tiêu đề "Độ dài nội dung" nếu nó đã được đặt hoặc tính toán trước đó.

Request.unverifiable¶: boolean, cho biết liệu yêu cầu có thể được xác minh hay không như được xác định bởi RFC 2965.

Request.method¶: Phương thức yêu cầu HTTP để sử dụng. Theo mặc định, giá trị của nó là None, có nghĩa là get_method() sẽ thực hiện tính toán bình thường đối với phương thức được sử dụng. Giá trị của nó có thể được đặt (do đó ghi đè tính toán mặc định trong get_method()) bằng cách cung cấp giá trị mặc định bằng cách đặt giá trị đó ở cấp lớp trong lớp con Request hoặc bằng cách chuyển một giá trị vào hàm tạo Request thông qua đối số method.

Added in version 3.3.

Thay đổi trong phiên bản 3.4: Bây giờ có thể đặt giá trị mặc định trong các lớp con; trước đây nó chỉ có thể được đặt thông qua đối số hàm tạo.

Request.get_method()¶: Trả về một chuỗi biểu thị phương thức yêu cầu HTTP. Nếu Request.method không phải là None, hãy trả về giá trị của nó, nếu không thì trả về 'GET' nếu Request.data là None hoặc 'POST' nếu không phải. Điều này chỉ có ý nghĩa đối với các yêu cầu HTTP.

Thay đổi trong phiên bản 3.3: get_method bây giờ xem xét giá trị của Request.method.

Request.add_header(key, val)¶: Thêm một tiêu đề khác vào yêu cầu. Các tiêu đề hiện bị bỏ qua bởi tất cả các trình xử lý ngoại trừ các trình xử lý HTTP, nơi chúng được thêm vào danh sách các tiêu đề được gửi đến máy chủ. Lưu ý rằng không thể có nhiều hơn một tiêu đề có cùng tên và các cuộc gọi sau sẽ ghi đè các cuộc gọi trước đó trong trường hợp key xung đột. Hiện tại, điều này không làm mất chức năng của HTTP, vì tất cả các tiêu đề có ý nghĩa khi được sử dụng nhiều lần đều có cách (dành riêng cho tiêu đề) để đạt được cùng chức năng chỉ bằng một tiêu đề. Lưu ý rằng các tiêu đề được thêm bằng phương pháp này cũng được thêm vào các yêu cầu được chuyển hướng.

Request.add_unredirected_header(key, header)¶: Thêm tiêu đề sẽ không được thêm vào yêu cầu được chuyển hướng.

Request.has_header(header)¶: Trả về xem phiên bản có tiêu đề được đặt tên hay không (kiểm tra cả thông thường và không được chuyển hướng).

Request.remove_header(header)¶: Xóa tiêu đề được đặt tên khỏi phiên bản yêu cầu (cả tiêu đề thông thường và tiêu đề không được chuyển hướng).

Added in version 3.4.

Request.get_full_url()¶

Trả về URL được cung cấp trong hàm tạo.

Thay đổi trong phiên bản 3.4.

Trả về Request.full_url

Request.set_proxy(host, type)¶: Chuẩn bị yêu cầu bằng cách kết nối với máy chủ proxy. host và type sẽ thay thế các phiên bản đó và bộ chọn của phiên bản sẽ là URL ban đầu được đưa ra trong hàm tạo.

Request.get_header(header_name, default=None)¶: Trả về giá trị của tiêu đề đã cho. Nếu không có tiêu đề, trả về giá trị mặc định.

Request.header_items()¶: Trả về danh sách các bộ dữ liệu (header_name, header_value) của tiêu đề Yêu cầu.

Thay đổi trong phiên bản 3.4: Các phương thức yêu cầu add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host và is_unver thể không được dùng nữa kể từ phiên bản 3.3 đã bị xóa.

Đối tượng OpenDirector¶

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

OpenerDirector.add_handler(handler)¶

handler phải là một phiên bản của BaseHandler. Các phương pháp sau đây được tìm kiếm và thêm vào các chuỗi có thể có (lưu ý rằng lỗi HTTP là trường hợp đặc biệt). Lưu ý rằng, sau đây, protocol nên được thay thế bằng giao thức thực tế để xử lý, ví dụ http_response() sẽ là trình xử lý phản hồi giao thức HTTP. Ngoài ra, type nên được thay thế bằng mã HTTP thực tế, ví dụ http_error_404() sẽ xử lý lỗi HTTP 404.

<protocol>_open() --- báo hiệu rằng trình xử lý biết cách mở URL protocol.

Xem BaseHandler.<protocol>_open() để biết thêm thông tin.
http_error_<type>() --- tín hiệu cho thấy người xử lý biết cách xử lý lỗi HTTP với mã lỗi HTTP type.

Xem BaseHandler.http_error_<nnn>() để biết thêm thông tin.
<protocol>_error() --- tín hiệu cho thấy trình xử lý biết cách xử lý lỗi từ (không phảihttp) protocol.
<protocol>_request() --- báo hiệu rằng trình xử lý biết cách xử lý trước các yêu cầu protocol.

Xem BaseHandler.<protocol>_request() để biết thêm thông tin.
<protocol>_response() --- báo hiệu rằng trình xử lý biết cách xử lý hậu kỳ các phản hồi protocol.

Xem BaseHandler.<protocol>_response() để biết thêm thông tin.

OpenerDirector.open(url, data=None[, timeout])¶: Mở url đã cho (có thể là đối tượng yêu cầu hoặc một chuỗi), tùy ý chuyển data đã cho. Các đối số, giá trị trả về và ngoại lệ được đưa ra giống như của urlopen() (chỉ gọi phương thức open() trên OpenerDirector chung hiện được cài đặt). Tham số timeout tùy chọn chỉ định thời gian chờ tính bằng giây cho các hoạt động chặn như nỗ lực kết nối (nếu không được chỉ định, cài đặt thời gian chờ mặc định chung sẽ được sử dụng). Tính năng hết thời gian thực sự chỉ hoạt động đối với các kết nối HTTP, HTTPS và FTP.

OpenerDirector.error(proto, *args)¶

Xử lý lỗi của giao thức đã cho. Điều này sẽ gọi các trình xử lý lỗi đã đăng ký cho giao thức đã cho với các đối số đã cho (dành riêng cho giao thức). Giao thức HTTP là trường hợp đặc biệt sử dụng mã phản hồi HTTP để xác định trình xử lý lỗi cụ thể; tham khảo các phương thức http_error_<type>() của các lớp xử lý.

Giá trị trả về và ngoại lệ được đưa ra giống như giá trị của urlopen().

Đối tượng OpenerDirector mở URL theo ba giai đoạn:

Thứ tự các phương thức này được gọi trong mỗi giai đoạn được xác định bằng cách sắp xếp các phiên bản xử lý.

Mọi trình xử lý có phương thức có tên như <protocol>_request() đều được gọi phương thức đó để xử lý trước yêu cầu.
Trình xử lý có phương thức có tên như <protocol>_open() được gọi để xử lý yêu cầu. Giai đoạn này kết thúc khi trình xử lý trả về giá trị không phải:const:None (tức là phản hồi) hoặc đưa ra một ngoại lệ (thường là URLError). Các ngoại lệ được phép phổ biến.

Trong thực tế, thuật toán trên lần đầu tiên được thử cho các phương thức có tên default_open(). Nếu tất cả các phương thức như vậy đều trả về None thì thuật toán sẽ được lặp lại cho các phương thức có tên như <protocol>_open(). Nếu tất cả các phương thức như vậy đều trả về None thì thuật toán sẽ được lặp lại cho các phương thức có tên unknown_open().

Lưu ý rằng việc triển khai các phương thức này có thể liên quan đến các lệnh gọi phương thức open() và error() của cá thể OpenerDirector gốc.
Mọi trình xử lý có phương thức có tên như <protocol>_response() đều có phương thức đó được gọi để xử lý hậu kỳ phản hồi.

Đối tượng BaseHandler¶

Các đối tượng BaseHandler cung cấp một số phương thức hữu ích trực tiếp và các phương thức khác được sử dụng bởi các lớp dẫn xuất. Chúng được thiết kế để sử dụng trực tiếp:

BaseHandler.add_parent(director)¶: Thêm một giám đốc làm cha mẹ.

BaseHandler.close()¶: Loại bỏ bất kỳ phụ huynh nào.

Thuộc tính và phương thức sau chỉ nên được sử dụng bởi các lớp dẫn xuất từ BaseHandler.

Ghi chú

Quy ước đã được thông qua rằng các lớp con xác định phương thức <protocol>_request() hoặc <protocol>_response() được đặt tên là *Processor; tất cả những người khác được đặt tên là *Handler.

BaseHandler.parent¶: Một OpenerDirector hợp lệ, có thể được sử dụng để mở bằng giao thức khác hoặc xử lý lỗi.

BaseHandler.default_open(req)¶

Phương thức này là not được định nghĩa trong BaseHandler, nhưng các lớp con nên định nghĩa nó nếu chúng muốn bắt tất cả các URL.

Phương thức này, nếu được triển khai, sẽ được gọi bởi OpenerDirector gốc. Nó sẽ trả về một đối tượng giống như tệp như được mô tả trong giá trị trả về của phương thức open() của OpenerDirector hoặc None. Nó sẽ tăng URLError, trừ khi có điều thực sự đặc biệt xảy ra (ví dụ: MemoryError không nên được ánh xạ tới URLError).

Phương thức này sẽ được gọi trước bất kỳ phương thức mở dành riêng cho giao thức nào.

BaseHandler.<protocol>_open(req)

Phương thức này là not được định nghĩa trong BaseHandler, nhưng các lớp con nên định nghĩa nó nếu chúng muốn xử lý các URL bằng giao thức đã cho.

Phương thức này, nếu được xác định, sẽ được gọi bởi OpenerDirector gốc. Giá trị trả về phải giống như đối với default_open().

BaseHandler.unknown_open(req)¶

Phương thức này là not được xác định trong BaseHandler, nhưng các lớp con nên xác định nó nếu chúng muốn bắt tất cả các URL mà không có trình xử lý đã đăng ký cụ thể nào để mở nó.

Phương pháp này, nếu được triển khai, sẽ được gọi bởi parent OpenerDirector. Giá trị trả về phải giống như đối với default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)¶

Phương thức này là not được xác định trong BaseHandler, nhưng các lớp con nên ghi đè lên nó nếu chúng có ý định cung cấp một bản tổng hợp các lỗi HTTP chưa được xử lý. Nó sẽ được OpenerDirector tự động gọi khi gặp lỗi và thường không được gọi trong các trường hợp khác.

OpenerDirector sẽ gọi phương thức này với năm đối số vị trí:

một đối tượng Request,
một đối tượng giống như tệp có nội dung lỗi HTTP,
mã ba chữ số của lỗi, dưới dạng một chuỗi,
phần giải thích mã mà người dùng có thể nhìn thấy dưới dạng một chuỗi và
các tiêu đề của lỗi, dưới dạng đối tượng ánh xạ.

Giá trị trả về và ngoại lệ được đưa ra phải giống với giá trị của urlopen().

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn phải là mã lỗi HTTP gồm ba chữ số. Phương thức này cũng không được định nghĩa trong BaseHandler, nhưng sẽ được gọi, nếu nó tồn tại, trên một phiên bản của lớp con, khi xảy ra lỗi HTTP với mã nnn.

Các lớp con nên ghi đè phương thức này để xử lý các lỗi HTTP cụ thể.

Các đối số, giá trị trả về và ngoại lệ được đưa ra phải giống như đối với http_error_default().

BaseHandler.<protocol>_request(req)

Phương thức này là not được định nghĩa trong BaseHandler, nhưng các lớp con nên định nghĩa nó nếu chúng muốn xử lý trước các yêu cầu của giao thức đã cho.

Phương thức này, nếu được xác định, sẽ được gọi bởi OpenerDirector gốc. req sẽ là đối tượng Request. Giá trị trả về phải là đối tượng Request.

BaseHandler.<protocol>_response(req, response)

Phương thức này là not được định nghĩa trong BaseHandler, nhưng các lớp con nên định nghĩa nó nếu chúng muốn phản hồi sau quá trình xử lý của giao thức đã cho.

Phương thức này, nếu được xác định, sẽ được gọi bởi OpenerDirector gốc. req sẽ là đối tượng Request. response sẽ là một đối tượng thực hiện giao diện giống như giá trị trả về của urlopen(). Giá trị trả về phải triển khai giao diện giống như giá trị trả về của urlopen().

Đối tượng HTTPRedirectHandler¶

Ghi chú

Một số chuyển hướng HTTP yêu cầu hành động từ mã máy khách của mô-đun này. Nếu đúng như vậy, HTTPError sẽ được nâng lên. Xem RFC 2616 để biết chi tiết về ý nghĩa chính xác của các mã chuyển hướng khác nhau.

Một ngoại lệ HTTPError được đưa ra như một sự cân nhắc về bảo mật nếu HTTPRedirectHandler được trình bày với một URL được chuyển hướng không phải là HTTP, HTTPS hoặc FTP URL.

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)¶: Trả về Request hoặc None để phản hồi chuyển hướng. Điều này được gọi bằng cách triển khai mặc định của các phương thức http_error_30*() khi nhận được chuyển hướng từ máy chủ. Nếu quá trình chuyển hướng diễn ra, hãy trả lại Request mới để cho phép http_error_30*() thực hiện chuyển hướng đến newurl. Nếu không, hãy tăng HTTPError nếu không có trình xử lý nào khác cố gắng xử lý URL này hoặc trả về None nếu bạn không thể nhưng trình xử lý khác thì có thể.

Ghi chú

Việc triển khai mặc định của phương pháp này không tuân thủ nghiêm ngặt RFC 2616, nghĩa là phản hồi 301 và 302 đối với các yêu cầu POST không được tự động chuyển hướng mà không có xác nhận của người dùng. Trong thực tế, các trình duyệt cho phép tự động chuyển hướng các phản hồi này, thay đổi POST thành GET và việc triển khai mặc định sẽ tái tạo hành vi này.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)¶: Chuyển hướng đến Location: hoặc URI: URL. Phương thức này được gọi bởi OpenerDirector gốc khi nhận được phản hồi HTTP 'được di chuyển vĩnh viễn'.

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)¶: Tương tự như http_error_301(), nhưng yêu cầu phản hồi 'tìm thấy'.

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)¶: Tương tự như http_error_301(), nhưng yêu cầu phản hồi 'xem khác'.

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)¶: Tương tự như http_error_301(), nhưng yêu cầu phản hồi 'chuyển hướng tạm thời'. Nó không cho phép thay đổi phương thức yêu cầu từ POST thành GET.

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)¶: Tương tự như http_error_301(), nhưng yêu cầu phản hồi 'chuyển hướng vĩnh viễn'. Nó không cho phép thay đổi phương thức yêu cầu từ POST thành GET.

Added in version 3.11.

Đối tượng HTTPCookieProcessor¶

Các phiên bản HTTPCookieProcessor có một thuộc tính:

HTTPCookieProcessor.cookiejar¶: Zz000zz trong đó cookie được lưu trữ.

Đối tượng ProxyHandler¶

ProxyHandler.<protocol>_open(request): ProxyHandler sẽ có một phương thức <protocol>_open() cho mỗi protocol có proxy trong từ điển proxies được cung cấp trong hàm tạo. Phương thức này sẽ sửa đổi các yêu cầu đi qua proxy bằng cách gọi request.set_proxy() và gọi trình xử lý tiếp theo trong chuỗi để thực thi giao thức.

Đối tượng HTTPPasswordMgr¶

Các phương thức này có sẵn trên các đối tượng HTTPPasswordMgr và HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶: uri có thể là một URI đơn lẻ hoặc một chuỗi URI. realm, user và passwd phải là chuỗi. Điều này khiến (user, passwd) được sử dụng làm mã thông báo xác thực khi xác thực cho realm và super-URI của bất kỳ URI nào được cung cấp.

HTTPPasswordMgr.find_user_password(realm, authuri)¶

Nhận người dùng/mật khẩu cho khu vực nhất định và URI, nếu có. Phương thức này sẽ trả về (None, None) nếu không có người dùng/mật khẩu phù hợp.

Đối với các đối tượng HTTPPasswordMgrWithDefaultRealm, vùng None sẽ được tìm kiếm nếu realm đã cho không có người dùng/mật khẩu phù hợp.

Đối tượng HTTPPasswordMgrWithPriorAuth¶

Trình quản lý mật khẩu này mở rộng HTTPPasswordMgrWithDefaultRealm để hỗ trợ các URI theo dõi mà thông tin xác thực phải luôn được gửi.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)¶: realm, uri, user, passwd tương tự như HTTPPasswordMgr.add_password(). is_authenticated đặt giá trị ban đầu của cờ is_authenticated cho URI hoặc danh sách URI nhất định. Nếu is_authenticated được chỉ định là True thì realm sẽ bị bỏ qua.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)¶: Tương tự như đối với đối tượng HTTPPasswordMgrWithDefaultRealm

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)¶: Cập nhật cờ is_authenticated cho uri hoặc danh sách URI nhất định.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)¶: Trả về trạng thái hiện tại của cờ is_authenticated cho URI đã cho.

Đối tượng Tóm tắtBasicAuthHandler¶

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

Xử lý yêu cầu xác thực bằng cách lấy cặp người dùng/mật khẩu và thử lại yêu cầu. authreq phải là tên của tiêu đề trong đó thông tin về khu vực được đưa vào yêu cầu, host chỉ định URL và đường dẫn để xác thực, req phải là đối tượng Request (không thành công) và headers phải là tiêu đề lỗi.

host là một cơ quan có thẩm quyền (ví dụ: "python.org") hoặc URL chứa thành phần cơ quan có thẩm quyền (ví dụ: "http://python.org/"). Trong cả hai trường hợp, quyền không được chứa thành phần thông tin người dùng (vì vậy, "python.org" và "python.org:80" đều được, "joe:password@python.org" thì không).

Đối tượng HTTPBasicAuthHandler¶

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶: Thử lại yêu cầu với thông tin xác thực, nếu có.

Đối tượng ProxyBasicAuthHandler¶

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶: Thử lại yêu cầu với thông tin xác thực, nếu có.

Đối tượng Tóm tắtDigestAuthHandler¶

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶: authreq phải là tên của tiêu đề trong đó thông tin về khu vực được đưa vào yêu cầu, host phải là máy chủ xác thực, req phải là đối tượng Request (không thành công) và headers phải là tiêu đề lỗi.

Đối tượng HTTPDigestAuthHandler¶

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶: Thử lại yêu cầu với thông tin xác thực, nếu có.

Đối tượng ProxyDigestAuthHandler¶

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶: Thử lại yêu cầu với thông tin xác thực, nếu có.

Đối tượng HTTPHandler¶

HTTPHandler.http_open(req)¶: Gửi yêu cầu HTTP, có thể là GET hoặc POST, tùy thuộc vào req.data.

Đối tượng HTTPSHandler¶

HTTPSHandler.https_open(req)¶: Gửi yêu cầu HTTPS, có thể là GET hoặc POST, tùy thuộc vào req.data.

Đối tượng FileHandler¶

FileHandler.file_open(req)¶: Mở tệp cục bộ nếu không có tên máy chủ hoặc tên máy chủ là 'localhost'.

Thay đổi trong phiên bản 3.2: Phương pháp này chỉ áp dụng cho tên máy chủ cục bộ. Khi tên máy chủ từ xa được cung cấp, URLError sẽ được nâng lên.

Đối tượng xử lý dữ liệu¶

DataHandler.data_open(req)¶: Đọc dữ liệu URL. Loại URL này chứa nội dung được mã hóa trong chính URL. Cú pháp dữ liệu URL được chỉ định trong RFC 2397. Việc triển khai này bỏ qua các khoảng trắng trong URL dữ liệu được mã hóa base64 để URL có thể được gói trong bất kỳ tệp nguồn nào mà nó xuất phát. Nhưng mặc dù một số trình duyệt không bận tâm đến việc thiếu phần đệm ở cuối dữ liệu được mã hóa base64 URL, việc triển khai này sẽ tạo ra ValueError trong trường hợp đó.

Đối tượng FTPHandler¶

FTPHandler.ftp_open(req)¶: Mở tệp FTP được chỉ định bởi req. Việc đăng nhập luôn được thực hiện với tên người dùng và mật khẩu trống.

Đối tượng CacheFTPHandler¶

Đối tượng CacheFTPHandler là đối tượng FTPHandler với các phương thức bổ sung sau:

CacheFTPHandler.setTimeout(t)¶: Đặt thời gian chờ của các kết nối thành t giây.

CacheFTPHandler.setMaxConns(m)¶: Đặt số lượng kết nối được lưu trong bộ nhớ cache tối đa thành m.

Đối tượng xử lý không xác định¶

UnknownHandler.unknown_open()¶: Đưa ra một ngoại lệ URLError.

Đối tượng HTTPErrorProcessor¶

HTTPErrorProcessor.http_response(request, response)¶

Xử lý phản hồi lỗi HTTP.

Đối với 200 mã lỗi, đối tượng phản hồi sẽ được trả về ngay lập tức.

Đối với các mã lỗi không phải 200, thao tác này chỉ chuyển công việc sang các phương thức xử lý http_error_<type>(), thông qua OpenerDirector.error(). Cuối cùng, HTTPDefaultErrorHandler sẽ đưa ra HTTPError nếu không có trình xử lý nào khác xử lý lỗi.

HTTPErrorProcessor.https_response(request, response)¶

Xử lý phản hồi lỗi HTTPS.

Hành vi tương tự như http_response().

Ví dụ¶

Ngoài các ví dụ bên dưới, còn có nhiều ví dụ khác được đưa ra trong HOWTO Tìm nạp tài nguyên Internet bằng gói urllib.

Ví dụ này lấy trang chính python.org và hiển thị 300 byte đầu tiên của nó

>>> nhập urllib.request
>>> với urllib.request.urlopen('http://www.python.org/') as f:
... print(f.read(300))
...
b'<!doctype html>\n<!--[if lt IE 7]> <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9"> <![endif]-->\n<!--[if IE 7]> <html class="no-js ie7 lt-ie8 lt-ie9"> <![endif]-->\n<!--[if IE 8]> <html class="no-js tức là8 lt-ie9">

Lưu ý rằng urlopen trả về một đối tượng bytes. Điều này là do không có cách nào để urlopen tự động xác định mã hóa luồng byte mà nó nhận được từ máy chủ HTTP. Nói chung, một chương trình sẽ giải mã đối tượng byte trả về thành chuỗi sau khi nó xác định hoặc đoán mã hóa thích hợp.

Tài liệu đặc tả HTML sau đây, https://html.spec.whatwg.org/#charset, liệt kê các cách khác nhau mà tài liệu HTML hoặc XML có thể chỉ định thông tin mã hóa của nó.

Để biết thêm thông tin, hãy xem tài liệu W3C: https://www.w3.org/International/questions/qa-html-encoding-declarations.

Vì trang web python.org sử dụng mã hóa utf-8 như được chỉ định trong thẻ meta của nó, nên chúng tôi sẽ sử dụng mã hóa tương tự để giải mã đối tượng byte

>>> với urllib.request.urlopen('http://www.python.org/') as f:
... print(f.read(100).decode('utf-8'))
...
<!doctype html>
<!--[if lt IE 7]> <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9"> <![endif]-->
<!-

Cũng có thể đạt được kết quả tương tự mà không cần sử dụng phương pháp context manager

>>> nhập urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> thử:
... print(f.read(100).decode('utf-8'))
... cuối cùng:
... f.close()
...
<!doctype html>
<!--[if lt IE 7]> <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9"> <![endif]-->
<!--

Trong ví dụ sau, chúng tôi đang gửi một luồng dữ liệu đến stdin của CGI và đọc dữ liệu mà nó trả về cho chúng tôi. Lưu ý rằng ví dụ này sẽ chỉ hoạt động khi cài đặt Python hỗ trợ SSL.

>>> nhập urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
... data=b'Dữ liệu này được chuyển tới stdin của CGI')
>>> với urllib.request.urlopen(req) là f:
... print(f.read().decode('utf-8'))
...
Đã nhận được dữ liệu: "Dữ liệu này được chuyển tới stdin của CGI"

Mã cho mẫu CGI được sử dụng trong ví dụ trên là:

#!/usr/bin/env trăn
hệ thống nhập khẩu
dữ liệu = sys.stdin.read()
print('Content-type: text/plain\n\nCó dữ liệu: "%s"' % data)

Dưới đây là ví dụ về thực hiện yêu cầu PUT bằng Request:

nhập urllib.request
DATA = b'một số dữ liệu'
req = urllib.request.Request(url='http://localhost:8080', data=DATA, Method='PUT')
với urllib.request.urlopen(req) là f:
    vượt qua
in(f.status)
in(f.reason)

Sử dụng Xác thực HTTP cơ bản:

nhập urllib.request
# Create một OpenerDirector có hỗ trợ Xác thực HTTP cơ bản...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Ứng dụng',
                          uri='https://mahler:8092/site-updates.py',
                          người dùng='klem',
                          passwd='kadidd!ehopper')
công cụ mở = urllib.request.build_opener(auth_handler)
# ...và cài đặt nó trên toàn cầu để có thể sử dụng nó với urlopen.
urllib.request.install_opener(opener)
với urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))

build_opener() cung cấp nhiều trình xử lý theo mặc định, bao gồm cả ProxyHandler. Theo mặc định, ProxyHandler sử dụng các biến môi trường có tên <scheme>_proxy, trong đó <scheme> là sơ đồ URL có liên quan. Ví dụ: biến môi trường http_proxy được đọc để lấy URL của proxy HTTP.

Ví dụ này thay thế ProxyHandler mặc định bằng một URL sử dụng URL proxy được cung cấp theo chương trình và thêm hỗ trợ ủy quyền proxy với ProxyBasicAuthHandler.

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This, thay vì cài đặt OpenerDirector, chúng tôi sử dụng trực tiếp:
với opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))

Thêm tiêu đề HTTP:

Sử dụng đối số headers cho hàm tạo Request hoặc:

nhập urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Người giới thiệu', 'http://www.python.org/')
# Customize giá trị tiêu đề Tác nhân người dùng mặc định:
req.add_header('User-Agent', 'urllib-example/0.1 (Liên hệ: . . .)')
với urllib.request.urlopen(req) là f:
    print(f.read().decode('utf-8'))

OpenerDirector tự động thêm tiêu đề User-Agent vào mỗi Request. Để thay đổi điều này:

nhập urllib.request
dụng cụ mở = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
với opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))

Ngoài ra, hãy nhớ rằng một số tiêu đề tiêu chuẩn (Content-Length, Content-Type và Host) được thêm vào khi Request được chuyển tới urlopen() (hoặc OpenerDirector.open()).

Đây là phiên ví dụ sử dụng phương thức GET để truy xuất URL chứa các tham số:

>>> nhập urllib.request
>>> nhập urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'trứng': 2, 'thịt xông khói': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % thông số
>>> với urllib.request.urlopen(url) là f:
... print(f.read().decode('utf-8'))
...

Ví dụ sau đây sử dụng phương thức POST. Lưu ý rằng thông số đầu ra từ urlencode được mã hóa thành byte trước khi nó được gửi tới urlopen dưới dạng dữ liệu

>>> nhập urllib.request
>>> nhập urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'trứng': 2, 'thịt xông khói': 0})
>>> data = data.encode('ascii')
>>> với urllib.request.urlopen("http://requestb.in/xrbl82xr", data) là f:
... print(f.read().decode('utf-8'))
...

Ví dụ sau sử dụng proxy HTTP được chỉ định rõ ràng, ghi đè cài đặt môi trường:

>>> nhập urllib.request
>>> proxy = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))
>>> với opener.open("http://www.python.org") as f:
... f.read().decode('utf-8')
...

Ví dụ sau không sử dụng proxy nào cả, ghi đè cài đặt môi trường:

>>> nhập urllib.request
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler({}}))
>>> với opener.open("http://www.python.org/") as f:
... f.read().decode('utf-8')
...

Giao diện kế thừa¶

Các hàm và lớp sau đây được chuyển từ mô-đun urllib của Python 2 (trái ngược với urllib2). Chúng có thể không được dùng nữa vào một thời điểm nào đó trong tương lai.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)¶

Sao chép một đối tượng mạng được biểu thị bằng URL vào một tệp cục bộ. Nếu URL trỏ đến một tệp cục bộ, đối tượng sẽ không được sao chép trừ khi tên tệp được cung cấp. Trả về một bộ (filename, headers) trong đó filename là tên tệp cục bộ mà theo đó đối tượng có thể được tìm thấy và headers là bất kỳ phương thức info() nào của đối tượng được trả về bởi urlopen() (đối với một đối tượng ở xa). Các ngoại lệ giống như đối với urlopen().

Đối số thứ hai, nếu có, chỉ định vị trí tệp cần sao chép vào (nếu không có, vị trí sẽ là tệp tạm thời có tên được tạo). Đối số thứ ba, nếu có, là một đối số có thể gọi được, nó sẽ được gọi một lần khi thiết lập kết nối mạng và một lần sau mỗi khối được đọc sau đó. Có thể gọi được sẽ được thông qua ba đối số; số lượng khối được chuyển cho đến nay, kích thước khối tính bằng byte và tổng kích thước của tệp. Đối số thứ ba có thể là -1 trên các máy chủ FTP cũ hơn không trả về kích thước tệp để đáp ứng yêu cầu truy xuất.

Ví dụ sau minh họa kịch bản sử dụng phổ biến nhất:

>>> nhập urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

Nếu url sử dụng mã định danh sơ đồ http:, đối số data tùy chọn có thể được cung cấp để chỉ định yêu cầu POST (thông thường loại yêu cầu là GET). Đối số data phải là đối tượng byte ở định dạng application/x-www-form-urlencoded tiêu chuẩn; xem chức năng urllib.parse.urlencode().

urlretrieve() sẽ tăng ContentTooShortError khi phát hiện lượng dữ liệu có sẵn ít hơn lượng dự kiến (là kích thước được báo cáo bởi tiêu đề Content-Length). Điều này có thể xảy ra, chẳng hạn như khi quá trình tải xuống bị gián đoạn.

Content-Length được coi là giới hạn dưới: nếu có nhiều dữ liệu hơn để đọc, urlretrieve sẽ đọc nhiều dữ liệu hơn, nhưng nếu có ít dữ liệu hơn, nó sẽ đưa ra ngoại lệ.

Bạn vẫn có thể truy xuất dữ liệu đã tải xuống trong trường hợp này, nó được lưu trữ trong thuộc tính content của phiên bản ngoại lệ.

Nếu không có tiêu đề Content-Length nào được cung cấp, urlretrieve không thể kiểm tra kích thước của dữ liệu mà nó đã tải xuống và chỉ trả về dữ liệu đó. Trong trường hợp này, bạn chỉ cần giả định rằng quá trình tải xuống đã thành công.

urllib.request.urlcleanup()¶: Dọn dẹp các tập tin tạm thời có thể bị bỏ lại bởi các lệnh gọi tới urlretrieve() trước đó.

`urllib.request` Hạn chế¶

Hiện tại, chỉ hỗ trợ các giao thức sau: HTTP (phiên bản 0.9 và 1.0), FTP, tệp cục bộ và URL dữ liệu.

Thay đổi trong phiên bản 3.4: Đã thêm hỗ trợ cho URL dữ liệu.
Tính năng bộ nhớ đệm của urlretrieve() đã bị vô hiệu hóa cho đến khi ai đó tìm thấy thời gian để hack xử lý thích hợp các tiêu đề Thời gian hết hạn.
Cần có một chức năng để truy vấn xem một URL cụ thể có trong bộ đệm hay không.
Để tương thích ngược, nếu URL dường như trỏ đến một tệp cục bộ nhưng không thể mở được tệp thì URL sẽ được diễn giải lại bằng giao thức FTP. Điều này đôi khi có thể gây ra các thông báo lỗi khó hiểu.
Các chức năng urlopen() và urlretrieve() có thể gây ra độ trễ dài tùy ý trong khi chờ thiết lập kết nối mạng. Điều này có nghĩa là rất khó để xây dựng một ứng dụng web tương tác sử dụng các chức năng này mà không sử dụng các luồng.
Dữ liệu được trả về bởi urlopen() hoặc urlretrieve() là dữ liệu thô được máy chủ trả về. Đây có thể là dữ liệu nhị phân (chẳng hạn như hình ảnh), văn bản thuần túy hoặc (ví dụ) HTML. Giao thức HTTP cung cấp thông tin loại trong tiêu đề trả lời, có thể kiểm tra thông tin này bằng cách xem tiêu đề Content-Type. Nếu dữ liệu trả về là HTML, bạn có thể sử dụng mô-đun html.parser để phân tích dữ liệu đó.
Mã xử lý giao thức FTP không thể phân biệt giữa tệp và thư mục. Điều này có thể dẫn đến hành vi không mong muốn khi cố đọc URL trỏ đến một tệp không thể truy cập được. Nếu URL kết thúc bằng /, nó được coi là tham chiếu đến một thư mục và sẽ được xử lý tương ứng. Nhưng nếu nỗ lực đọc tệp dẫn đến lỗi 550 (có nghĩa là không thể tìm thấy hoặc truy cập URL, thường là vì lý do được phép), thì đường dẫn sẽ được coi là một thư mục để xử lý trường hợp khi một thư mục được chỉ định bởi URL nhưng dấu / đã bị bỏ đi. Điều này có thể gây ra kết quả sai lệch khi bạn cố gắng tìm nạp một tệp có quyền đọc khiến tệp đó không thể truy cập được; mã FTP sẽ cố đọc nó nhưng không thành công với lỗi 550 và sau đó thực hiện danh sách thư mục cho tệp không thể đọc được. Nếu cần điều khiển chi tiết hơn, hãy cân nhắc sử dụng mô-đun ftplib.

`urllib.response` --- Các lớp phản hồi được sử dụng bởi urllib¶

Mô-đun urllib.response xác định các hàm và lớp xác định giao diện giống như tệp tối thiểu, bao gồm read() và readline(). Các chức năng được xác định bởi mô-đun này được sử dụng nội bộ bởi mô-đun urllib.request. Đối tượng phản hồi điển hình là một phiên bản urllib.response.addinfourl:

class urllib.response.addinfourl¶

url¶: URL của tài nguyên được truy xuất, thường được sử dụng để xác định xem có chuyển hướng hay không.

headers¶: Trả về tiêu đề của phản hồi ở dạng phiên bản EmailMessage.

status¶: Added in version 3.9.

Mã trạng thái được máy chủ trả về.

geturl()¶: Sắp loại bỏ từ phiên bản 3.9: Không được dùng nữa để ủng hộ url.

info()¶: Sắp loại bỏ từ phiên bản 3.9: Không được dùng nữa để ủng hộ headers.

code¶: Sắp loại bỏ từ phiên bản 3.9: Không được dùng nữa để ủng hộ status.

getcode()¶: Sắp loại bỏ từ phiên bản 3.9: Không được dùng nữa để ủng hộ status.

`urllib.request` --- Thư viện mở rộng để mở URL¶

Đối tượng yêu cầu¶

Đối tượng OpenDirector¶

Đối tượng BaseHandler¶

Đối tượng HTTPRedirectHandler¶

Đối tượng HTTPCookieProcessor¶

Đối tượng ProxyHandler¶

Đối tượng HTTPPasswordMgr¶

Đối tượng HTTPPasswordMgrWithPriorAuth¶

Đối tượng Tóm tắtBasicAuthHandler¶

Đối tượng HTTPBasicAuthHandler¶

Đối tượng ProxyBasicAuthHandler¶

Đối tượng Tóm tắtDigestAuthHandler¶

Đối tượng HTTPDigestAuthHandler¶

Đối tượng ProxyDigestAuthHandler¶

Đối tượng HTTPHandler¶

Đối tượng HTTPSHandler¶

Đối tượng FileHandler¶

Đối tượng xử lý dữ liệu¶

Đối tượng FTPHandler¶

Đối tượng CacheFTPHandler¶

Đối tượng xử lý không xác định¶

Đối tượng HTTPErrorProcessor¶

Ví dụ¶

Giao diện kế thừa¶

`urllib.request` Hạn chế¶

`urllib.response` --- Các lớp phản hồi được sử dụng bởi urllib¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

urllib.request --- Thư viện mở rộng để mở URL¶

Đối tượng yêu cầu¶

Đối tượng OpenDirector¶

Đối tượng BaseHandler¶

Đối tượng HTTPRedirectHandler¶

Đối tượng HTTPCookieProcessor¶

Đối tượng ProxyHandler¶

Đối tượng HTTPPasswordMgr¶

Đối tượng HTTPPasswordMgrWithPriorAuth¶

Đối tượng Tóm tắtBasicAuthHandler¶

Đối tượng HTTPBasicAuthHandler¶

Đối tượng ProxyBasicAuthHandler¶

Đối tượng Tóm tắtDigestAuthHandler¶

Đối tượng HTTPDigestAuthHandler¶

Đối tượng ProxyDigestAuthHandler¶

Đối tượng HTTPHandler¶

Đối tượng HTTPSHandler¶

Đối tượng FileHandler¶

Đối tượng xử lý dữ liệu¶

Đối tượng FTPHandler¶

Đối tượng CacheFTPHandler¶

Đối tượng xử lý không xác định¶

Đối tượng HTTPErrorProcessor¶

Ví dụ¶

Giao diện kế thừa¶

urllib.request Hạn chế¶

urllib.response --- Các lớp phản hồi được sử dụng bởi urllib¶

`urllib.request` --- Thư viện mở rộng để mở URL¶

`urllib.request` Hạn chế¶

`urllib.response` --- Các lớp phản hồi được sử dụng bởi urllib¶