`urllib.parse` --- Phân tích URL thành các thành phần¶

Source code: Lib/urllib/parse.py

Mô-đun này xác định một giao diện tiêu chuẩn để ngắt các chuỗi Bộ định vị tài nguyên thống nhất (URL) trong các thành phần (sơ đồ địa chỉ, vị trí mạng, đường dẫn, v.v.), để kết hợp các thành phần trở lại thành chuỗi URL và để chuyển đổi "URL tương đối" thành URL tuyệt đối với "URL cơ sở".

Mô-đun này đã được thiết kế để phù hợp với RFC internet trên Bộ định vị tài nguyên thống nhất tương đối. Nó hỗ trợ các sơ đồ URL sau: file, ftp, gopher, hdl, http, https, imap, itms-services, mailto, mms, news, nntp, prospero, rsync, rtsp, rtsps, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

Việc đưa vào sơ đồ itms-services URL có thể ngăn ứng dụng vượt qua quy trình đánh giá App Store của Apple đối với macOS và iOS App Store. Việc xử lý sơ đồ itms-services luôn bị xóa trên iOS; trên macOS, may sẽ bị xóa nếu CPython được xây dựng với tùy chọn --with-app-store-compliance.

Mô-đun urllib.parse xác định các hàm thuộc hai loại chính: phân tích cú pháp URL và trích dẫn URL. Chúng được trình bày chi tiết trong các phần sau.

Các chức năng của mô-đun này sử dụng thuật ngữ không dùng nữa netloc (hoặc net_loc), được giới thiệu trong RFC 1808. Tuy nhiên, thuật ngữ này đã bị lỗi thời bởi RFC 3986, họ đã giới thiệu thuật ngữ authority để thay thế. Việc sử dụng netloc được tiếp tục để tương thích ngược.

URL Phân tích cú pháp¶

Các hàm phân tích cú pháp URL tập trung vào việc tách chuỗi URL thành các thành phần của nó hoặc kết hợp các thành phần URL thành chuỗi URL.

urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True)¶

Phân tích URL thành năm thành phần, trả về named tuple SplitResult hoặc SplitResultBytes gồm 5 mục. Điều này tương ứng với cấu trúc chung của URL: scheme://netloc/path?query#fragment. Mỗi mục tuple là một chuỗi, có thể trống. Các thành phần không được chia thành các phần nhỏ hơn (ví dụ: vị trí mạng là một chuỗi) và % thoát không được mở rộng. Các dấu phân cách như được hiển thị ở trên không phải là một phần của kết quả, ngoại trừ dấu gạch chéo ở đầu trong thành phần path, được giữ lại nếu có. Ví dụ:

>>> từ urllib.parse nhập urlsplit
>>> urlsplit("sơ đồ://netloc/path?query#fragment")
SplitResult(scheme='scheme', netloc='netloc', path='/path',
            truy vấn='truy vấn', đoạn='đoạn')
>>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"
... "đánh dấu=params#url-parsing")
>>> ồ
SplitResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html',
            query='highlight=params', Fragment='phân tích cú pháp url')
>>> o.sơ đồ
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.tên máy chủ
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

Tuân theo các đặc tả cú pháp trong RFC 1808, urlsplit() chỉ nhận ra netloc nếu nó được giới thiệu đúng cách bởi '//'. Nếu không, đầu vào được coi là URL tương đối và do đó bắt đầu bằng thành phần đường dẫn.

>>> từ urllib.parse nhập urlsplit
>>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            truy vấn='', đoạn='')
>>> urlsplit('www.cwi.nl/%7Eguido/Python.html')
SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            truy vấn='', đoạn='')
>>> urlsplit('help/Python.html')
SplitResult(scheme='', netloc='', path='help/Python.html',
            truy vấn='', đoạn='')

Đối số scheme đưa ra sơ đồ địa chỉ mặc định, chỉ được sử dụng nếu URL không chỉ định một sơ đồ địa chỉ. Nó phải cùng loại (văn bản hoặc byte) với urlstring, ngoại trừ giá trị mặc định '' luôn được cho phép và được tự động chuyển đổi thành b'' nếu thích hợp.

Nếu đối số allow_fragments là sai, thì số nhận dạng phân đoạn sẽ không được nhận dạng. Thay vào đó, chúng được phân tích cú pháp như một phần của đường dẫn, tham số hoặc thành phần truy vấn và fragment được đặt thành chuỗi trống trong giá trị trả về.

Giá trị trả về là named tuple, có nghĩa là các mục của nó có thể được truy cập theo chỉ mục hoặc dưới dạng thuộc tính được đặt tên, đó là:

Thuộc tính	chỉ mục	Giá trị	Giá trị nếu không có
`scheme`	0	công cụ xác định sơ đồ URL	thông số scheme
`netloc`	1	Phần vị trí mạng	chuỗi trống
`path`	2	Đường dẫn phân cấp	chuỗi trống
`query`	3	Thành phần truy vấn	chuỗi trống
`fragment`	4	Mã nhận dạng mảnh	chuỗi trống
`username`		Tên người dùng	`None`
`password`		Mật khẩu	`None`
`hostname`		Tên máy chủ (chữ thường)	`None`
`port`		Số cổng là số nguyên, nếu có	`None`

Đọc thuộc tính port sẽ tạo ra ValueError nếu cổng không hợp lệ được chỉ định trong URL. Xem phần Kết quả phân tích có cấu trúc để biết thêm thông tin về đối tượng kết quả.

Dấu ngoặc vuông không khớp trong thuộc tính netloc sẽ tạo ra ValueError.

Các ký tự trong thuộc tính netloc phân hủy theo chuẩn hóa NFKC (như được mã hóa IDNA sử dụng) thành bất kỳ /, ?, #, @ hoặc : nào sẽ tạo ra ValueError. Nếu URL bị phân hủy trước khi phân tích cú pháp thì sẽ không có lỗi nào phát sinh.

Sau một số WHATWG spec cập nhật RFC 3986, các ký tự khoảng trắng và điều khiển C0 hàng đầu sẽ bị loại bỏ khỏi URL. Các ký tự \n, \r và tab \t bị xóa khỏi URL ở bất kỳ vị trí nào.

Như trường hợp của tất cả các bộ dữ liệu được đặt tên, lớp con có một số phương thức và thuộc tính bổ sung đặc biệt hữu ích. Một phương pháp như vậy là _replace(). Phương thức _replace() sẽ trả về một đối tượng SplitResult mới thay thế các trường được chỉ định bằng các giá trị mới.

>>> từ urllib.parse nhập urlsplit
>>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
>>> bạn
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            truy vấn='', đoạn='')
>>> u._replace(scheme='http')
SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            truy vấn='', đoạn='')

Cảnh báo

urlsplit() không thực hiện xác thực. Xem URL parsing security để biết chi tiết.

Thay đổi trong phiên bản 3.2: Đã thêm khả năng phân tích cú pháp IPv6 URL.

Thay đổi trong phiên bản 3.3: Đoạn này hiện được phân tích cú pháp cho tất cả các lược đồ URL (trừ khi allow_fragments sai), theo RFC 3986. Trước đây, đã tồn tại một danh sách cho phép các chương trình hỗ trợ các mảnh.

Thay đổi trong phiên bản 3.6: Số cổng ngoài phạm vi hiện tăng ValueError, thay vì trả về None.

Thay đổi trong phiên bản 3.8: Các ký tự ảnh hưởng đến phân tích cú pháp netloc trong quá trình chuẩn hóa NFKC giờ đây sẽ tăng ValueError.

Thay đổi trong phiên bản 3.10: Các ký tự tab và dòng mới của ASCII bị loại bỏ khỏi URL.

Thay đổi trong phiên bản 3.12: Các ký tự khoảng trắng và điều khiển WHATWG C0 hàng đầu bị loại bỏ khỏi URL.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')¶

Phân tích chuỗi truy vấn được cung cấp dưới dạng đối số chuỗi (dữ liệu thuộc loại application/x-www-form-urlencoded). Dữ liệu được trả về dưới dạng từ điển. Các khóa từ điển là tên biến truy vấn duy nhất và các giá trị là danh sách các giá trị cho mỗi tên.

Đối số tùy chọn keep_blank_values là cờ cho biết liệu các giá trị trống trong truy vấn được mã hóa phần trăm có nên được coi là chuỗi trống hay không. Giá trị đúng cho biết các khoảng trống phải được giữ lại dưới dạng chuỗi trống. Giá trị sai mặc định cho biết rằng các giá trị trống sẽ bị bỏ qua và xử lý như thể chúng không được đưa vào.

Đối số tùy chọn strict_parsing là cờ cho biết phải làm gì với lỗi phân tích cú pháp. Nếu sai (mặc định), lỗi sẽ được âm thầm bỏ qua. Nếu đúng, lỗi sẽ tạo ra ngoại lệ ValueError.

Các tham số encoding và errors tùy chọn chỉ định cách giải mã các chuỗi được mã hóa phần trăm thành các ký tự Unicode, như được phương thức bytes.decode() chấp nhận.

Đối số tùy chọn max_num_fields là số lượng trường tối đa cần đọc. Nếu được đặt, thì sẽ gửi ValueError nếu có nhiều hơn trường max_num_fields được đọc.

Đối số tùy chọn separator là ký hiệu được sử dụng để phân tách các đối số truy vấn. Nó mặc định là &.

Sử dụng hàm urllib.parse.urlencode() (với tham số doseq được đặt thành True) để chuyển đổi các từ điển đó thành chuỗi truy vấn.

Thay đổi trong phiên bản 3.2: Thêm thông số encoding và errors.

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

Thay đổi trong phiên bản 3.10: Đã thêm tham số separator với giá trị mặc định là &. Các phiên bản Python cũ hơn Python 3.10 cho phép sử dụng cả ; và & làm dấu tách tham số truy vấn. Điều này đã được thay đổi để chỉ cho phép một phím phân cách duy nhất, với & là dấu phân cách mặc định.

Sắp loại bỏ từ phiên bản 3.14: Việc chấp nhận các đối tượng có giá trị sai (như 0 và []) ngoại trừ các chuỗi trống và các đối tượng giống byte và None hiện không được dùng nữa.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')¶

Phân tích chuỗi truy vấn được cung cấp dưới dạng đối số chuỗi (dữ liệu thuộc loại application/x-www-form-urlencoded). Dữ liệu được trả về dưới dạng danh sách các cặp tên, giá trị.

Đối số tùy chọn keep_blank_values là cờ cho biết liệu các giá trị trống trong truy vấn được mã hóa phần trăm có nên được coi là chuỗi trống hay không. Giá trị đúng cho biết các khoảng trống phải được giữ lại dưới dạng chuỗi trống. Giá trị sai mặc định cho biết rằng các giá trị trống sẽ bị bỏ qua và xử lý như thể chúng không được đưa vào.

Đối số tùy chọn strict_parsing là cờ cho biết phải làm gì với lỗi phân tích cú pháp. Nếu sai (mặc định), lỗi sẽ được âm thầm bỏ qua. Nếu đúng, lỗi sẽ tạo ra ngoại lệ ValueError.

Các tham số encoding và errors tùy chọn chỉ định cách giải mã các chuỗi được mã hóa phần trăm thành các ký tự Unicode, như được phương thức bytes.decode() chấp nhận.

Đối số tùy chọn max_num_fields là số lượng trường tối đa cần đọc. Nếu được đặt, thì sẽ gửi ValueError nếu có nhiều hơn trường max_num_fields được đọc.

Đối số tùy chọn separator là ký hiệu được sử dụng để phân tách các đối số truy vấn. Nó mặc định là &.

Sử dụng hàm urllib.parse.urlencode() để chuyển đổi danh sách các cặp đó thành chuỗi truy vấn.

Thay đổi trong phiên bản 3.2: Thêm thông số encoding và errors.

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

Thay đổi trong phiên bản 3.10: Đã thêm tham số separator với giá trị mặc định là &. Các phiên bản Python cũ hơn Python 3.10 cho phép sử dụng cả ; và & làm dấu tách tham số truy vấn. Điều này đã được thay đổi để chỉ cho phép một phím phân cách duy nhất, với & là dấu phân cách mặc định.

urllib.parse.urlunsplit(parts)¶: Xây dựng một URL từ một bộ dữ liệu được trả về bởi urlsplit(). Đối số parts có thể lặp lại năm mục bất kỳ. Điều này có thể dẫn đến một URL hơi khác một chút nhưng tương đương, nếu URL được phân tích cú pháp ban đầu có các dấu phân cách không cần thiết (ví dụ: ? có truy vấn trống; RFC cho biết những dấu phân cách này là tương đương).

urllib.parse.urlparse(urlstring, scheme=None, allow_fragments=True)¶

Điều này tương tự như urlsplit() nhưng còn phân chia thành phần path trên path và params. Hàm này trả về named tuple ParseResult hoặc ParseResultBytes gồm 6 mục. Các mục của nó giống như đối với kết quả urlsplit(), ngoại trừ việc params được chèn ở chỉ mục 3, giữa path và query.

Hàm này dựa trên RFC 1738 và RFC 1808 đã lỗi thời, liệt kê params là thành phần URL chính. Cú pháp URL gần đây hơn cho phép áp dụng các tham số cho từng phân đoạn của phần path của URL (xem RFC 3986). urlsplit() thường nên được sử dụng thay vì urlparse(). Cần có một chức năng riêng biệt để phân tách các đoạn đường dẫn và tham số.

urllib.parse.urlunparse(parts)¶: Kết hợp các phần tử của một bộ dữ liệu được trả về bởi urlparse() thành một URL hoàn chỉnh dưới dạng một chuỗi. Đối số parts có thể lặp lại sáu mục bất kỳ. Điều này có thể dẫn đến một URL hơi khác một chút nhưng tương đương, nếu URL được phân tích cú pháp ban đầu có các dấu phân cách không cần thiết (ví dụ: một ? với một truy vấn trống; RFC cho biết những dấu phân cách này là tương đương).

urllib.parse.urljoin(base, url, allow_fragments=True)¶

Tạo một URL ("tuyệt đối") đầy đủ bằng cách kết hợp một "URL cơ sở" (base) với một URL (url) khác. Một cách không chính thức, điều này sử dụng các thành phần của URL cơ sở, đặc biệt là sơ đồ địa chỉ, vị trí mạng và (một phần) đường dẫn, để cung cấp các thành phần còn thiếu trong URL tương đối. Ví dụ:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

Đối số allow_fragments có cùng ý nghĩa và mặc định như đối với urlsplit().

Ghi chú

Nếu url là URL tuyệt đối (nghĩa là nó bắt đầu bằng // hoặc scheme://), thì tên máy chủ và/hoặc lược đồ của url sẽ xuất hiện trong kết quả. Ví dụ:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
... '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

Nếu bạn không muốn hành vi đó, hãy xử lý trước url bằng urlsplit() và urlunsplit(), loại bỏ các phần scheme và netloc có thể có.

Cảnh báo

Bởi vì một URL tuyệt đối có thể được chuyển dưới dạng tham số url, nên thông thường not secure sẽ sử dụng urljoin với url do kẻ tấn công kiểm soát. Ví dụ: trong urljoin("https://website.com/users/", username), nếu username có thể chứa URL tuyệt đối thì kết quả của urljoin sẽ là URL tuyệt đối.

Thay đổi trong phiên bản 3.5: Hành vi được cập nhật để phù hợp với ngữ nghĩa được xác định trong RFC 3986.

urllib.parse.urldefrag(url)¶

Nếu url chứa mã định danh phân đoạn, hãy trả về phiên bản sửa đổi của url không có mã định danh phân đoạn và mã định danh phân đoạn dưới dạng một chuỗi riêng biệt. Nếu không có mã định danh phân đoạn trong url, hãy trả về url chưa sửa đổi và một chuỗi trống.

Giá trị trả về là named tuple, các mục của nó có thể được truy cập theo chỉ mục hoặc dưới dạng thuộc tính được đặt tên:

Thuộc tính	chỉ mục	Giá trị	Giá trị nếu không có
`url`	0	URL không có mảnh vỡ	chuỗi trống
`fragment`	1	Mã nhận dạng mảnh	chuỗi trống

Xem phần Kết quả phân tích có cấu trúc để biết thêm thông tin về đối tượng kết quả.

Thay đổi trong phiên bản 3.2: Kết quả là một đối tượng có cấu trúc chứ không phải là một bộ 2 đơn giản.

urllib.parse.unwrap(url)¶: Trích xuất url từ một URL được bao bọc (nghĩa là một chuỗi được định dạng là <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path hoặc scheme://host/path). Nếu url không phải là URL được gói, nó sẽ được trả về mà không thay đổi.

bảo mật phân tích cú pháp URL¶

API urlsplit() và urlparse() không thực hiện validation đầu vào. Chúng có thể không gây ra lỗi ở đầu vào mà các ứng dụng khác cho là không hợp lệ. Họ cũng có thể thành công trên một số thông tin đầu vào có thể không được coi là URL ở những nơi khác. Mục đích của chúng là dành cho chức năng thực tế hơn là độ tinh khiết.

Thay vì đưa ra một ngoại lệ đối với đầu vào bất thường, thay vào đó, chúng có thể trả về một số bộ phận dưới dạng chuỗi trống. Hoặc các thành phần có thể chứa nhiều hơn mức cần thiết.

Chúng tôi khuyên người dùng các API này trong đó các giá trị có thể được sử dụng ở bất kỳ đâu có mã bảo mật có ý nghĩa phòng thủ. Thực hiện một số xác minh trong mã của bạn trước khi tin cậy một phần thành phần được trả về. Liệu scheme đó có hợp lý không? Đó có phải là một path hợp lý? hostname đó có gì lạ không? v.v.

Những gì tạo nên URL không được xác định rõ ràng trên toàn cầu. Các ứng dụng khác nhau có nhu cầu và ràng buộc mong muốn khác nhau. Ví dụ: WHATWG spec sống mô tả những gì người dùng phải đối mặt với các máy khách web như trình duyệt web yêu cầu. Trong khi RFC 3986 tổng quát hơn. Các chức năng này kết hợp một số khía cạnh của cả hai, nhưng không thể được tuyên bố là tuân thủ cả hai. Các API và mã người dùng hiện tại có kỳ vọng về các hành vi cụ thể có trước cả hai tiêu chuẩn, khiến chúng tôi phải hết sức thận trọng khi thực hiện các thay đổi về hành vi của API.

Phân tích byte được mã hóa ASCII¶

Các hàm phân tích cú pháp URL ban đầu được thiết kế để chỉ hoạt động trên các chuỗi ký tự. Trong thực tế, sẽ rất hữu ích khi có thể thao tác các URL được trích dẫn và mã hóa chính xác dưới dạng chuỗi byte ASCII. Theo đó, các chức năng phân tích cú pháp URL trong mô-đun này đều hoạt động trên các đối tượng bytes và bytearray ngoài các đối tượng str.

Nếu dữ liệu str được truyền vào, kết quả cũng sẽ chỉ chứa dữ liệu str. Nếu dữ liệu bytes hoặc bytearray được truyền vào, kết quả sẽ chỉ chứa dữ liệu bytes.

Việc cố gắng trộn dữ liệu str với bytes hoặc bytearray trong một lệnh gọi hàm sẽ dẫn đến TypeError được nâng lên, trong khi việc cố gắng chuyển các giá trị byte không phải ASCII sẽ kích hoạt UnicodeDecodeError.

Để hỗ trợ chuyển đổi dễ dàng hơn các đối tượng kết quả giữa str và bytes, tất cả các giá trị trả về từ các hàm phân tích cú pháp URL đều cung cấp phương thức encode() (khi kết quả chứa dữ liệu str) hoặc phương thức decode() (khi kết quả chứa dữ liệu bytes). Chữ ký của các phương thức này khớp với chữ ký của các phương thức str và bytes tương ứng (ngoại trừ mã hóa mặc định là 'ascii' chứ không phải 'utf-8'). Mỗi cái tạo ra một giá trị thuộc loại tương ứng chứa dữ liệu bytes (đối với phương thức encode()) hoặc dữ liệu str (đối với phương thức decode()).

Các ứng dụng cần hoạt động trên các URL có khả năng được trích dẫn không chính xác có thể chứa dữ liệu không phải ASCII sẽ cần phải thực hiện giải mã riêng từ byte thành ký tự trước khi gọi các phương thức phân tích cú pháp URL.

Hành vi được mô tả trong phần này chỉ áp dụng cho các hàm phân tích cú pháp URL. Các hàm trích dẫn URL sử dụng các quy tắc riêng của chúng khi tạo hoặc tiêu thụ các chuỗi byte như được nêu chi tiết trong tài liệu về các hàm trích dẫn URL riêng lẻ.

Thay đổi trong phiên bản 3.2: Các hàm phân tích cú pháp URL hiện chấp nhận chuỗi byte được mã hóa ASCII

Kết quả phân tích có cấu trúc¶

Các đối tượng kết quả từ các hàm urlsplit(), urlparse() và urldefrag() là các lớp con của loại tuple. Các lớp con này thêm các thuộc tính được liệt kê trong tài liệu dành cho các hàm đó, hỗ trợ mã hóa và giải mã được mô tả trong phần trước cũng như một phương thức bổ sung:

urllib.parse.SplitResult.geturl()¶

Trả về phiên bản được kết hợp lại của URL gốc dưới dạng chuỗi. Điều này có thể khác với URL ban đầu ở chỗ sơ đồ có thể được chuẩn hóa thành chữ thường và các thành phần trống có thể bị loại bỏ. Cụ thể, các tham số, truy vấn và mã nhận dạng phân đoạn trống sẽ bị xóa.

Đối với kết quả urldefrag(), chỉ các số nhận dạng đoạn trống sẽ bị xóa. Đối với kết quả urlsplit() và urlparse(), tất cả các thay đổi đã ghi chú sẽ được thực hiện đối với URL được trả về bằng phương pháp này.

Kết quả của phương thức này không thay đổi nếu được truyền trở lại qua hàm phân tích ban đầu:

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

Các lớp sau đây cung cấp cách triển khai các kết quả phân tích cú pháp có cấu trúc khi hoạt động trên các đối tượng str:

class urllib.parse.DefragResult(url, fragment)¶: Lớp cụ thể cho kết quả urldefrag() chứa dữ liệu str. Phương thức encode() trả về một phiên bản DefragResultBytes.

Added in version 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)¶: Lớp cụ thể cho kết quả urlparse() chứa dữ liệu str. Phương thức encode() trả về một phiên bản ParseResultBytes.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)¶: Lớp cụ thể cho kết quả urlsplit() chứa dữ liệu str. Phương thức encode() trả về một phiên bản SplitResultBytes.

Các lớp sau đây cung cấp cách triển khai các kết quả phân tích cú pháp khi hoạt động trên các đối tượng bytes hoặc bytearray:

class urllib.parse.DefragResultBytes(url, fragment)¶: Lớp cụ thể cho kết quả urldefrag() chứa dữ liệu bytes. Phương thức decode() trả về một phiên bản DefragResult.

Added in version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)¶: Lớp cụ thể cho kết quả urlparse() chứa dữ liệu bytes. Phương thức decode() trả về một phiên bản ParseResult.

Added in version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)¶: Lớp cụ thể cho kết quả urlsplit() chứa dữ liệu bytes. Phương thức decode() trả về một phiên bản SplitResult.

Added in version 3.2.

trích dẫn URL¶

Các chức năng trích dẫn URL tập trung vào việc lấy dữ liệu chương trình và đảm bảo an toàn khi sử dụng làm thành phần URL bằng cách trích dẫn các ký tự đặc biệt và mã hóa văn bản không phải ASCII một cách thích hợp. Chúng cũng hỗ trợ đảo ngược các thao tác này để tạo lại dữ liệu gốc từ nội dung của thành phần URL nếu tác vụ đó chưa được các hàm phân tích cú pháp URL ở trên thực hiện.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)¶

Thay thế các ký tự đặc biệt trong string bằng cách sử dụng lối thoát %xx. Các chữ cái, chữ số và ký tự '_.-~' không bao giờ được trích dẫn. Theo mặc định, chức năng này nhằm mục đích trích dẫn phần đường dẫn của URL. Tham số safe tùy chọn chỉ định các ký tự ASCII bổ sung không được trích dẫn --- giá trị mặc định của nó là '/'.

string có thể là đối tượng str hoặc bytes.

Thay đổi trong phiên bản 3.7: Đã chuyển từ RFC 2396 sang RFC 3986 để trích dẫn chuỗi URL. "~" hiện được bao gồm trong bộ ký tự không được đặt trước.

Các tham số encoding và errors tùy chọn chỉ định cách xử lý các ký tự không phải ASCII, như được phương thức str.encode() chấp nhận. encoding mặc định là 'utf-8'. errors mặc định là 'strict', nghĩa là các ký tự không được hỗ trợ sẽ tạo ra UnicodeEncodeError. Không được cung cấp encoding và errors nếu string là bytes hoặc TypeError được nâng lên.

Lưu ý rằng quote(string, safe, encoding, errors) tương đương với quote_from_bytes(string.encode(encoding, errors), safe).

Ví dụ: quote('/El Niño/') mang lại '/El%20Ni%C3%B1o/'.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)¶

Giống như quote(), nhưng cũng thay thế dấu cách bằng dấu cộng, theo yêu cầu để trích dẫn các giá trị biểu mẫu HTML khi xây dựng chuỗi truy vấn để đi vào URL. Dấu cộng trong chuỗi gốc được thoát trừ khi chúng được đưa vào safe. Nó cũng không có safe mặc định là '/'.

Ví dụ: quote_plus('/El Niño/') mang lại '%2FEl+Ni%C3%B1o%2F'.

urllib.parse.quote_from_bytes(bytes, safe='/')¶

Giống như quote(), nhưng chấp nhận đối tượng bytes thay vì str và không thực hiện mã hóa chuỗi thành byte.

Ví dụ: quote_from_bytes(b'a&\xef') mang lại 'a%26%EF'.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')¶

Thay thế các ký tự thoát %xx bằng ký tự đơn tương đương của chúng. Các tham số encoding và errors tùy chọn chỉ định cách giải mã các chuỗi được mã hóa phần trăm thành các ký tự Unicode, như được phương thức bytes.decode() chấp nhận.

string có thể là đối tượng str hoặc bytes.

encoding mặc định là 'utf-8'. errors mặc định là 'replace', nghĩa là các chuỗi không hợp lệ được thay thế bằng ký tự giữ chỗ.

Ví dụ: unquote('/El%20Ni%C3%B1o/') mang lại '/El Niño/'.

Thay đổi trong phiên bản 3.9: Tham số string hỗ trợ các đối tượng byte và str (trước đây chỉ có str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')¶

Giống như unquote(), nhưng cũng thay thế dấu cộng bằng dấu cách, theo yêu cầu để bỏ trích dẫn các giá trị biểu mẫu HTML.

string phải là str.

Ví dụ: unquote_plus('/El+Ni%C3%B1o/') mang lại '/El Niño/'.

urllib.parse.unquote_to_bytes(string)¶

Thay thế các ký tự thoát %xx bằng ký tự octet đơn tương đương của chúng và trả về một đối tượng bytes.

string có thể là đối tượng str hoặc bytes.

Nếu là str, các ký tự không phải ASCII không thoát trong string sẽ được mã hóa thành UTF-8 byte.

Ví dụ: unquote_to_bytes('a%26%EF') mang lại b'a&\xef'.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)¶

Chuyển đổi một đối tượng ánh xạ hoặc một chuỗi gồm các bộ dữ liệu hai phần tử, có thể chứa các đối tượng str hoặc bytes, thành chuỗi văn bản ASCII được mã hóa phần trăm. Nếu chuỗi kết quả được sử dụng làm data cho thao tác POST với hàm urlopen() thì chuỗi đó phải được mã hóa thành byte, nếu không thì chuỗi đó sẽ tạo ra TypeError.

Chuỗi kết quả là một chuỗi các cặp key=value được phân tách bằng các ký tự '&', trong đó cả key và value đều được trích dẫn bằng hàm quote_via. Theo mặc định, quote_plus() được sử dụng để trích dẫn các giá trị, nghĩa là khoảng trắng được trích dẫn dưới dạng ký tự '+' và ký tự '/' được mã hóa thành %2F, tuân theo tiêu chuẩn cho các yêu cầu GET (application/x-www-form-urlencoded). Một hàm thay thế có thể được chuyển dưới dạng quote_via là quote(), hàm này sẽ mã hóa khoảng trắng dưới dạng %20 và không mã hóa các ký tự '/'. Để kiểm soát tối đa nội dung được trích dẫn, hãy sử dụng quote và chỉ định giá trị cho safe.

Khi một chuỗi các bộ dữ liệu hai phần tử được sử dụng làm đối số query, phần tử đầu tiên của mỗi bộ dữ liệu là một khóa và phần tử thứ hai là một giá trị. Bản thân phần tử giá trị có thể là một chuỗi và trong trường hợp đó, nếu tham số tùy chọn doseq ước tính là True thì các cặp key=value riêng lẻ được phân tách bằng '&' sẽ được tạo cho mỗi phần tử của chuỗi giá trị cho khóa. Thứ tự của các tham số trong chuỗi được mã hóa sẽ khớp với thứ tự của các bộ tham số trong chuỗi.

Các tham số safe, encoding và errors được truyền xuống quote_via (các tham số encoding và errors chỉ được truyền khi phần tử truy vấn là str).

Để đảo ngược quá trình mã hóa này, parse_qs() và parse_qsl() được cung cấp trong mô-đun này để phân tích các chuỗi truy vấn thành cấu trúc dữ liệu Python.

Tham khảo urllib examples để tìm hiểu cách sử dụng phương thức urllib.parse.urlencode() để tạo chuỗi truy vấn của URL hoặc dữ liệu cho yêu cầu POST.

Thay đổi trong phiên bản 3.2: query hỗ trợ các đối tượng byte và chuỗi.

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

Sắp loại bỏ từ phiên bản 3.14: Việc chấp nhận các đối tượng có giá trị sai (như 0 và []) ngoại trừ các chuỗi trống và các đối tượng giống byte và None hiện không được dùng nữa.

Xem thêm

WHATWG - URL Mức sống: Nhóm làm việc về Tiêu chuẩn URL xác định URL, tên miền, địa chỉ IP, định dạng ứng dụng/x-www-form-urlencoded và API của chúng.
RFC 3986 - Mã định danh tài nguyên thống nhất: Đây là tiêu chuẩn hiện hành (STD66). Mọi thay đổi đối với mô-đun urllib.parse đều phải tuân theo điều này. Có thể quan sát thấy một số sai lệch nhất định, phần lớn là nhằm mục đích tương thích ngược và cho một số yêu cầu phân tích cú pháp thực tế nhất định như thường thấy trong các trình duyệt chính.
RFC 2732 - Định dạng cho địa chỉ IPv6 theo nghĩa đen trong URL.: Điều này chỉ định các yêu cầu phân tích cú pháp của URL IPv6.
RFC 2396 - Mã định danh tài nguyên thống nhất (URI): Cú pháp chung: Tài liệu mô tả các yêu cầu cú pháp chung cho cả Tên tài nguyên thống nhất (URN) và Bộ định vị tài nguyên thống nhất (URL).
RFC 2368 - Lược đồ mailto URL.: Yêu cầu phân tích cú pháp cho các lược đồ mailto URL.
RFC 1808 - Bộ định vị tài nguyên thống nhất tương đối: Yêu cầu Nhận xét này bao gồm các quy tắc để tham gia URL tuyệt đối và tương đối, bao gồm một số lượng lớn "Ví dụ bất thường" chi phối việc xử lý các trường hợp biên giới.
RFC 1738 - Bộ định vị tài nguyên thống nhất (URL): Điều này chỉ định cú pháp chính thức và ngữ nghĩa của các URL tuyệt đối.

`urllib.parse` --- Phân tích URL thành các thành phần¶

URL Phân tích cú pháp¶

bảo mật phân tích cú pháp URL¶

Phân tích byte được mã hóa ASCII¶

Kết quả phân tích có cấu trúc¶

trích dẫn URL¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

urllib.parse --- Phân tích URL thành các thành phần¶

URL Phân tích cú pháp¶

bảo mật phân tích cú pháp URL¶

Phân tích byte được mã hóa ASCII¶

Kết quả phân tích có cấu trúc¶

trích dẫn URL¶

`urllib.parse` --- Phân tích URL thành các thành phần¶