Phân tích đối số và xây dựng giá trị¶

Các hàm này rất hữu ích khi tạo các hàm và phương thức mở rộng của riêng bạn. Thông tin và ví dụ bổ sung có sẵn trong Mở rộng và nhúng trình thông dịch Python.

Ba hàm đầu tiên được mô tả, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords() và PyArg_Parse(), tất cả đều sử dụng format strings được dùng để cho hàm biết về các đối số dự kiến. Các chuỗi định dạng sử dụng cùng một cú pháp cho từng hàm này.

Phân tích đối số¶

Chuỗi định dạng bao gồm 0 hoặc nhiều "đơn vị định dạng". Một đơn vị định dạng mô tả một đối tượng Python; nó thường là một ký tự đơn hoặc một chuỗi các đơn vị định dạng được đặt trong ngoặc đơn. Với một vài ngoại lệ, đơn vị định dạng không phải là chuỗi được ngoặc đơn thường tương ứng với một đối số địa chỉ duy nhất cho các hàm này. Trong phần mô tả sau đây, biểu mẫu được trích dẫn là đơn vị định dạng; mục nhập trong dấu ngoặc đơn (tròn) là loại đối tượng Python khớp với đơn vị định dạng; và mục trong ngoặc [vuông] là loại biến C có địa chỉ cần được chuyển.

Chuỗi và bộ đệm¶

Ghi chú

Trên Python 3.12 trở lên, macro PY_SSIZE_T_CLEAN phải được xác định trước khi bao gồm Python.h để sử dụng tất cả các biến thể định dạng # (s#, y#, v.v.) được giải thích bên dưới. Điều này không cần thiết trên Python 3.13 trở lên.

Các định dạng này cho phép truy cập một đối tượng dưới dạng một đoạn bộ nhớ liền kề. Bạn không phải cung cấp bộ nhớ thô cho vùng unicode hoặc byte được trả về.

Trừ khi có quy định khác, bộ đệm không bị chấm dứt bằng NUL.

Có ba cách có thể chuyển đổi chuỗi và bộ đệm sang C:

Các định dạng như y* và s* điền vào cấu trúc Py_buffer. Điều này sẽ khóa bộ đệm cơ bản để người gọi sau đó có thể sử dụng bộ đệm ngay cả bên trong khối Py_BEGIN_ALLOW_THREADS mà không có nguy cơ dữ liệu có thể thay đổi bị thay đổi kích thước hoặc bị phá hủy. Kết quả là you have to call PyBuffer_Release() sau khi bạn xử lý xong dữ liệu (hoặc trong bất kỳ trường hợp hủy bỏ sớm nào).
Các định dạng es, es#, et và et# phân bổ bộ đệm kết quả. You have to call PyMem_Free() sau khi bạn xử lý xong dữ liệu (hoặc trong bất kỳ trường hợp hủy bỏ sớm nào).
Các định dạng khác lấy str hoặc bytes-like object chỉ đọc, chẳng hạn như bytes và cung cấp con trỏ const char * tới bộ đệm của nó. Trong trường hợp này, bộ đệm được "mượn": nó được quản lý bởi đối tượng Python tương ứng và chia sẻ thời gian tồn tại của đối tượng này. Bạn sẽ không phải tự mình giải phóng bất kỳ bộ nhớ nào.

Để đảm bảo rằng bộ đệm cơ bản có thể được mượn một cách an toàn, trường PyBufferProcs.bf_releasebuffer của đối tượng phải là NULL. Điều này không cho phép các đối tượng có thể thay đổi phổ biến như bytearray, nhưng cũng không cho phép một số đối tượng chỉ đọc như memoryview của bytes.

Ngoài yêu cầu bf_releasebuffer này, không có kiểm tra nào để xác minh xem đối tượng đầu vào có phải là bất biến hay không (ví dụ: liệu nó có đáp ứng yêu cầu về bộ đệm có thể ghi hay liệu một luồng khác có thể thay đổi dữ liệu hay không).

s (str) [const char *]

Chuyển đổi một đối tượng Unicode thành con trỏ C thành chuỗi ký tự. Một con trỏ tới một chuỗi hiện có được lưu trữ trong biến con trỏ ký tự có địa chỉ mà bạn truyền vào. Chuỗi C được kết thúc bằng NUL. Chuỗi Python không được chứa các điểm mã rỗng được nhúng; nếu có, ngoại lệ ValueError sẽ xuất hiện. Các đối tượng Unicode được chuyển đổi thành chuỗi C bằng cách sử dụng mã hóa 'utf-8'. Nếu chuyển đổi này không thành công, UnicodeError sẽ xuất hiện.

Ghi chú

Định dạng này không chấp nhận bytes-like objects. Nếu bạn muốn chấp nhận đường dẫn hệ thống tệp và chuyển đổi chúng thành chuỗi ký tự C, tốt nhất nên sử dụng định dạng O& với PyUnicode_FSConverter() là converter.

Thay đổi trong phiên bản 3.5: Trước đây, TypeError đã được đưa ra khi gặp phải các điểm mã null được nhúng trong chuỗi Python.

s* (str hoặc bytes-like object) [Py_buffer]

Định dạng này chấp nhận các đối tượng Unicode cũng như các đối tượng giống byte. Nó điền vào cấu trúc Py_buffer do người gọi cung cấp. Trong trường hợp này, chuỗi C kết quả có thể chứa các byte NUL được nhúng. Các đối tượng Unicode được chuyển đổi thành chuỗi C bằng cách sử dụng mã hóa 'utf-8'.

s# (str, bytes-like object chỉ đọc) [const char *, Py_ssize_t]

Giống như s*, ngoại trừ việc nó cung cấp borrowed buffer. Kết quả được lưu trữ thành hai biến C, biến đầu tiên là con trỏ tới chuỗi C, biến thứ hai là độ dài của chuỗi đó. Chuỗi có thể chứa các byte rỗng được nhúng. Các đối tượng Unicode được chuyển đổi thành chuỗi C bằng cách sử dụng mã hóa 'utf-8'.

z (str hoặc None) [const char *]

Giống như s, nhưng đối tượng Python cũng có thể là None, trong trường hợp đó con trỏ C được đặt thành NULL.

z* (str, bytes-like object hoặc None) [Py_buffer]

Giống như s*, nhưng đối tượng Python cũng có thể là None, trong trường hợp đó thành viên buf của cấu trúc Py_buffer được đặt thành NULL.

z# (str, bytes-like object hoặc None chỉ đọc) [const char *, Py_ssize_t]

Giống như s#, nhưng đối tượng Python cũng có thể là None, trong trường hợp đó con trỏ C được đặt thành NULL.

y (bytes-like object chỉ đọc) [const char *]

Định dạng này chuyển đổi một đối tượng giống byte thành con trỏ C thành chuỗi ký tự borrowed; nó không chấp nhận các đối tượng Unicode. Bộ đệm byte không được chứa byte rỗng được nhúng; nếu có, ngoại lệ ValueError sẽ xuất hiện.

Thay đổi trong phiên bản 3.5: Trước đây, TypeError đã được nâng lên khi gặp phải các byte rỗng được nhúng trong bộ đệm byte.

y* (bytes-like object) [Py_buffer]

Biến thể này trên s* không chấp nhận các đối tượng Unicode, chỉ các đối tượng giống byte. This is the recommended way to accept binary data.

y# (bytes-like object chỉ đọc) [const char *, Py_ssize_t]

Biến thể này trên s# không chấp nhận các đối tượng Unicode, chỉ các đối tượng giống byte.

S (bytes) [PyBytesObject *]

Yêu cầu đối tượng Python là đối tượng bytes mà không cần thực hiện bất kỳ chuyển đổi nào. Tăng TypeError nếu đối tượng không phải là đối tượng byte. Biến C cũng có thể được khai báo là PyObject*.

Y (bytearray) [PyByteArrayObject *]

Yêu cầu đối tượng Python là đối tượng bytearray mà không cần thực hiện bất kỳ chuyển đổi nào. Tăng TypeError nếu đối tượng không phải là đối tượng bytearray. Biến C cũng có thể được khai báo là PyObject*.

U (str) [PyObject *]

Yêu cầu đối tượng Python là đối tượng Unicode mà không cần thực hiện bất kỳ chuyển đổi nào. Tăng TypeError nếu đối tượng không phải là đối tượng Unicode. Biến C cũng có thể được khai báo là PyObject*.

w* (đọc-ghi bytes-like object) [Py_buffer]

Định dạng này chấp nhận bất kỳ đối tượng nào thực hiện giao diện bộ đệm đọc-ghi. Nó điền vào cấu trúc Py_buffer do người gọi cung cấp. Bộ đệm có thể chứa các byte rỗng được nhúng. Người gọi phải gọi PyBuffer_Release() khi hoàn tất việc xử lý bộ đệm.

es (str) [const char *encoding, char **buffer]

Biến thể này trên s được sử dụng để mã hóa Unicode thành bộ đệm ký tự. Nó chỉ hoạt động đối với dữ liệu được mã hóa mà không nhúng byte NUL.

Định dạng này yêu cầu hai đối số. Chuỗi đầu tiên chỉ được sử dụng làm đầu vào và phải là const char* trỏ đến tên của mã hóa dưới dạng chuỗi kết thúc bằng NUL hoặc NULL, trong trường hợp đó mã hóa 'utf-8' được sử dụng. Một ngoại lệ được đưa ra nếu mã hóa được đặt tên không được Python biết đến. Đối số thứ hai phải là char**; giá trị của con trỏ mà nó tham chiếu sẽ được đặt thành bộ đệm có nội dung của văn bản đối số. Văn bản sẽ được mã hóa theo kiểu mã hóa được chỉ định bởi đối số đầu tiên.

PyArg_ParseTuple() sẽ phân bổ bộ đệm có kích thước cần thiết, sao chép dữ liệu được mã hóa vào bộ đệm này và điều chỉnh *buffer để tham chiếu bộ nhớ mới được phân bổ. Người gọi có trách nhiệm gọi PyMem_Free() để giải phóng bộ đệm được phân bổ sau khi sử dụng.

et (str, bytes hoặc bytearray) [const char *encoding, char **buffer]

Tương tự như es ngoại trừ các đối tượng chuỗi byte được truyền qua mà không mã hóa lại chúng. Thay vào đó, việc triển khai giả định rằng đối tượng chuỗi byte sử dụng mã hóa được truyền vào làm tham số.

es# (str) [const char *encoding, char **buffer, zz001zz *buffer_length]

Biến thể này trên s# được sử dụng để mã hóa Unicode thành bộ đệm ký tự. Không giống như định dạng es, biến thể này cho phép nhập dữ liệu chứa các ký tự NUL.

Nó đòi hỏi ba đối số. Chuỗi đầu tiên chỉ được sử dụng làm đầu vào và phải là const char* trỏ đến tên của mã hóa dưới dạng chuỗi kết thúc bằng NUL hoặc NULL, trong trường hợp đó mã hóa 'utf-8' được sử dụng. Một ngoại lệ được đưa ra nếu mã hóa được đặt tên không được Python biết đến. Đối số thứ hai phải là char**; giá trị của con trỏ mà nó tham chiếu sẽ được đặt thành bộ đệm có nội dung của văn bản đối số. Văn bản sẽ được mã hóa theo kiểu mã hóa được chỉ định bởi đối số đầu tiên. Đối số thứ ba phải là một con trỏ tới một số nguyên; số nguyên được tham chiếu sẽ được đặt thành số byte trong bộ đệm đầu ra.

Có hai chế độ hoạt động:

Nếu *buffer trỏ đến một con trỏ NULL, hàm sẽ phân bổ bộ đệm có kích thước cần thiết, sao chép dữ liệu được mã hóa vào bộ đệm này và đặt *buffer để tham chiếu bộ lưu trữ mới được phân bổ. Người gọi có trách nhiệm gọi PyMem_Free() để giải phóng bộ đệm được phân bổ sau khi sử dụng.

Nếu *buffer trỏ đến một con trỏ không phải NULL (bộ đệm đã được phân bổ), PyArg_ParseTuple() sẽ sử dụng vị trí này làm bộ đệm và diễn giải giá trị ban đầu của *buffer_length làm kích thước bộ đệm. Sau đó, nó sẽ sao chép dữ liệu được mã hóa vào bộ đệm và chấm dứt nó bằng NUL. Nếu bộ đệm không đủ lớn, ValueError sẽ được đặt.

Trong cả hai trường hợp, *buffer_length được đặt thành độ dài của dữ liệu được mã hóa mà không có byte NUL ở cuối.

et# (str, bytes hoặc bytearray) [const char *encoding, char **buffer, zz003zz *buffer_length]

Tương tự như es# ngoại trừ các đối tượng chuỗi byte được truyền qua mà không mã hóa lại chúng. Thay vào đó, việc triển khai giả định rằng đối tượng chuỗi byte sử dụng mã hóa được truyền vào làm tham số.

Thay đổi trong phiên bản 3.12: u, u#, Z và Z# bị xóa vì chúng sử dụng biểu diễn Py_UNICODE* cũ.

số¶

Các định dạng này cho phép biểu diễn số Python hoặc ký tự đơn dưới dạng số C. Các định dạng yêu cầu int, float hoặc complex cũng có thể sử dụng các phương thức đặc biệt tương ứng __index__(), __float__() hoặc __complex__() để chuyển đổi đối tượng Python sang loại được yêu cầu.

Đối với các định dạng số nguyên có dấu, OverflowError được tăng lên nếu giá trị nằm ngoài phạm vi của loại C. Đối với các định dạng số nguyên không dấu, không có kiểm tra phạm vi nào được thực hiện --- các bit quan trọng nhất bị cắt bớt một cách âm thầm khi trường nhận quá nhỏ để nhận giá trị.

b (int) [ký tự không dấu]: Chuyển đổi số nguyên Python không âm thành số nguyên nhỏ không dấu, được lưu trữ trong C unsigned char.
B (int) [ký tự không dấu]: Chuyển đổi số nguyên Python thành số nguyên nhỏ mà không cần kiểm tra tràn, được lưu trữ trong C unsigned char.
h (int) [ngắn int]: Chuyển đổi số nguyên Python thành C short int.
H (int) [unsign int ngắn]: Chuyển đổi số nguyên Python thành C unsigned short int mà không cần kiểm tra tràn.
i (int) [int]: Chuyển đổi số nguyên Python thành C int đơn giản.
I (int) [unsign int]: Chuyển đổi số nguyên Python thành C unsigned int mà không cần kiểm tra tràn.
l (int) [dài]: Chuyển đổi số nguyên Python thành C long int.
k (int) [dài không dấu]: Chuyển đổi số nguyên Python thành C unsigned long mà không cần kiểm tra tràn.

Thay đổi trong phiên bản 3.14: Sử dụng __index__() nếu có.
L (int) [dài dài]: Chuyển đổi số nguyên Python thành C long long.
K (int) [dài không dấu]: Chuyển đổi số nguyên Python thành C unsigned long long mà không cần kiểm tra tràn.

Thay đổi trong phiên bản 3.14: Sử dụng __index__() nếu có.
n (int) [Py_ssize_t]: Chuyển đổi số nguyên Python thành C Py_ssize_t.
c (bytes hoặc bytearray có độ dài 1) [char]: Chuyển đổi một byte Python, được biểu thị dưới dạng đối tượng bytes hoặc bytearray có độ dài 1, thành C char.

Thay đổi trong phiên bản 3.3: Cho phép các đối tượng bytearray.
C (str có độ dài 1) [int]: Chuyển đổi một ký tự Python, được biểu thị dưới dạng đối tượng str có độ dài 1, thành C int.
f (float) [thả nổi]: Chuyển đổi số dấu phẩy động Python thành C float.
d (float) [gấp đôi]: Chuyển đổi số dấu phẩy động Python thành C double.
D (complex) [Py_complex]: Chuyển đổi số phức Python thành cấu trúc C Py_complex.

Các đối tượng khác¶

O (đối tượng) [PyObject *]: Lưu trữ một đối tượng Python (không có bất kỳ chuyển đổi nào) trong con trỏ đối tượng C. Do đó, chương trình C nhận được đối tượng thực tế đã được truyền. Một strong reference mới cho đối tượng không được tạo (tức là số lượng tham chiếu của nó không tăng lên). Con trỏ được lưu trữ không phải là NULL.
O! (đối tượng) [typeobject, PyObject *]: Lưu trữ một đối tượng Python trong một con trỏ đối tượng C. Điều này tương tự như O, nhưng có hai đối số C: đối số đầu tiên là địa chỉ của đối tượng kiểu Python, đối số thứ hai là địa chỉ của biến C (thuộc loại PyObject*) mà con trỏ đối tượng được lưu trữ. Nếu đối tượng Python không có loại được yêu cầu, TypeError sẽ được nâng lên.

O& (đối tượng) [converter, address]

Chuyển đổi một đối tượng Python thành biến C thông qua hàm converter. Điều này có hai đối số: đối số thứ nhất là hàm, thứ hai là địa chỉ của biến C (thuộc loại tùy ý), được chuyển đổi thành void*. Hàm converter lần lượt được gọi như sau:

trạng thái = trình chuyển đổi (đối tượng, địa chỉ);

trong đó object là đối tượng Python được chuyển đổi và address là đối số void* được truyền cho hàm PyArg_Parse*. status được trả về phải là 1 để chuyển đổi thành công và 0 nếu chuyển đổi không thành công. Khi chuyển đổi không thành công, hàm converter sẽ đưa ra một ngoại lệ và giữ nguyên nội dung của address.

Nếu converter trả về Py_CLEANUP_SUPPORTED, nó có thể được gọi lần thứ hai nếu việc phân tích cú pháp đối số cuối cùng không thành công, tạo cơ hội cho bộ chuyển đổi giải phóng bất kỳ bộ nhớ nào mà nó đã phân bổ. Trong lệnh gọi thứ hai này, tham số object sẽ là NULL; address sẽ có cùng giá trị như trong lệnh gọi ban đầu.

Ví dụ về bộ chuyển đổi: PyUnicode_FSConverter() và PyUnicode_FSDecoder().

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

p (bool) [int]

Kiểm tra giá trị được truyền vào để tìm sự thật (một boolean predicate) và chuyển đổi kết quả thành giá trị số nguyên C đúng/sai tương đương của nó. Đặt int thành 1 nếu biểu thức đúng và 0 nếu nó sai. Điều này chấp nhận mọi giá trị Python hợp lệ. Xem Kiểm tra giá trị thật để biết thêm thông tin về cách Python kiểm tra các giá trị đúng.

Added in version 3.3.

(items) (chuỗi) [matching-items]

Đối tượng phải là một chuỗi Python (ngoại trừ str, bytes hoặc bytearray) có độ dài là số đơn vị định dạng trong items. Đối số C phải tương ứng với các đơn vị định dạng riêng lẻ trong items. Đơn vị định dạng cho các chuỗi có thể được lồng vào nhau.

Nếu items chứa các đơn vị định dạng lưu trữ borrowed buffer (s, s#, z, z#, y hoặc y#) hoặc borrowed reference (S, Y, U, O hoặc O!), thì đối tượng phải là một bộ dữ liệu Python. Zz015zz cho đơn vị định dạng O& trong items không được lưu trữ bộ đệm mượn hoặc tham chiếu mượn.

Thay đổi trong phiên bản 3.14: Các đối tượng str và bytearray không còn được chấp nhận dưới dạng một chuỗi nữa.

Sắp loại bỏ từ phiên bản 3.14: Các chuỗi không phải bộ dữ liệu sẽ không được dùng nữa nếu items chứa các đơn vị định dạng lưu trữ bộ đệm mượn hoặc tham chiếu mượn.

Một vài ký tự khác có ý nghĩa trong chuỗi định dạng. Những điều này có thể không xảy ra bên trong dấu ngoặc đơn lồng nhau. Họ là:

|: Cho biết các đối số còn lại trong danh sách đối số Python là tùy chọn. Các biến C tương ứng với các đối số tùy chọn phải được khởi tạo về giá trị mặc định của chúng --- khi một đối số tùy chọn không được chỉ định, PyArg_ParseTuple() không chạm vào nội dung của (các) biến C tương ứng.
$: PyArg_ParseTupleAndKeywords() only: Cho biết các đối số còn lại trong danh sách đối số Python chỉ là từ khóa. Hiện tại, tất cả các đối số chỉ có từ khóa cũng phải là đối số tùy chọn, do đó, | phải luôn được chỉ định trước $ trong chuỗi định dạng.

Added in version 3.3.
:: Danh sách các đơn vị định dạng kết thúc ở đây; chuỗi sau dấu hai chấm được sử dụng làm tên hàm trong thông báo lỗi ("giá trị liên quan" của ngoại lệ mà PyArg_ParseTuple() đưa ra).
;: Danh sách các đơn vị định dạng kết thúc ở đây; chuỗi sau dấu chấm phẩy được sử dụng làm thông báo lỗi instead của thông báo lỗi mặc định. : và ; loại trừ lẫn nhau.

Lưu ý rằng mọi tham chiếu đối tượng Python được cung cấp cho người gọi đều là tham chiếu borrowed; không giải phóng chúng (tức là không giảm số lượng tham chiếu của chúng)!

Các đối số bổ sung được truyền cho các hàm này phải là địa chỉ của các biến có kiểu được xác định bởi chuỗi định dạng; chúng được sử dụng để lưu trữ các giá trị từ bộ dữ liệu đầu vào. Có một số trường hợp, như được mô tả trong danh sách đơn vị định dạng ở trên, trong đó các tham số này được sử dụng làm giá trị đầu vào; chúng phải khớp với những gì được chỉ định cho đơn vị định dạng tương ứng trong trường hợp đó.

Để chuyển đổi thành công, đối tượng arg phải phù hợp với định dạng và định dạng phải hết. Khi thành công, các hàm PyArg_Parse* trả về true, nếu không chúng sẽ trả về false và đưa ra một ngoại lệ thích hợp. Khi các chức năng PyArg_Parse* không thành công do lỗi chuyển đổi ở một trong các đơn vị định dạng, các biến tại địa chỉ tương ứng với đơn vị định dạng đó và các đơn vị định dạng sau sẽ không bị ảnh hưởng.

Chức năng API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Một phần của ABI ổn định.
Phân tích các tham số của hàm chỉ lấy tham số vị trí thành các biến cục bộ. Trả về true nếu thành công; nếu thất bại, nó trả về sai và đưa ra ngoại lệ thích hợp.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Một phần của ABI ổn định.
Giống hệt PyArg_ParseTuple(), ngoại trừ việc nó chấp nhận va_list thay vì số lượng đối số thay đổi.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: Một phần của ABI ổn định.
Phân tích các tham số của hàm lấy cả tham số vị trí và từ khóa vào các biến cục bộ. Đối số keywords là một mảng tên tham số từ khóa được kết thúc bằng NULL được chỉ định dưới dạng chuỗi C được mã hóa ASCII hoặc UTF-8 kết thúc bằng null. Tên trống biểu thị positional-only parameters. Trả về true nếu thành công; nếu thất bại, nó trả về sai và đưa ra ngoại lệ thích hợp.

Ghi chú

Khai báo tham số keywords là char *const* trong C và const char *const* trong C++. Điều này có thể được ghi đè bằng macro PY_CXX_CONST.

Thay đổi trong phiên bản 3.6: Đã thêm hỗ trợ cho positional-only parameters.

Thay đổi trong phiên bản 3.13: Tham số keywords hiện có kiểu char *const* trong C và const char *const* trong C++, thay vì char**. Đã thêm hỗ trợ cho tên tham số từ khóa không phải ASCII.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: Một phần của ABI ổn định.
Giống hệt PyArg_ParseTupleAndKeywords(), ngoại trừ việc nó chấp nhận va_list thay vì số lượng đối số thay đổi.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Một phần của ABI ổn định.
Đảm bảo rằng các khóa trong từ điển đối số từ khóa là chuỗi. Điều này chỉ cần thiết nếu PyArg_ParseTupleAndKeywords() không được sử dụng, vì PyArg_ParseTupleAndKeywords() đã thực hiện việc kiểm tra này.

Added in version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)¶

Một phần của ABI ổn định.

Phân tích tham số của hàm lấy một tham số vị trí duy nhất thành một biến cục bộ. Trả về true nếu thành công; nếu thất bại, nó trả về sai và đưa ra ngoại lệ thích hợp.

Ví dụ:

// Hàm sử dụng quy ước gọi METH_O
PyObject tĩnh*
my_function(PyObject *module, PyObject *arg)
{
    giá trị int;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        trả lại NULL;
    }
    // ... giá trị sử dụng ...
}

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)¶

Một phần của ABI ổn định.

Một dạng truy xuất tham số đơn giản hơn không sử dụng chuỗi định dạng để chỉ định loại đối số. Các hàm sử dụng phương thức này để truy xuất tham số của chúng phải được khai báo là METH_VARARGS trong bảng hàm hoặc phương thức. Bộ dữ liệu chứa các tham số thực tế phải được chuyển dưới dạng args; nó thực sự phải là một tuple. Độ dài của bộ dữ liệu ít nhất phải là min và không quá max; min và max có thể bằng nhau. Các đối số bổ sung phải được truyền cho hàm, mỗi đối số phải là một con trỏ tới biến PyObject*; những thứ này sẽ được điền với các giá trị từ args; chúng sẽ chứa borrowed references. Các biến tương ứng với các tham số tùy chọn không được args đưa ra sẽ không được điền vào; những thứ này nên được khởi tạo bởi người gọi. Hàm này trả về true nếu thành công và trả về false nếu args không phải là một bộ dữ liệu hoặc chứa sai số phần tử; một ngoại lệ sẽ được đặt nếu có lỗi.

Đây là một ví dụ về việc sử dụng chức năng này, được lấy từ các nguồn của mô-đun trợ giúp _weakref dành cho các tài liệu tham khảo yếu:

PyObject tĩnh *
yếuref_ref(PyObject *self, PyObject *args)
{
    đối tượng PyObject *;
    PyObject *gọi lại = NULL;
    PyObject *kết quả = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        kết quả = PyWeakref_NewRef(đối tượng, gọi lại);
    }
    trả về kết quả;
}

Lệnh gọi tới PyArg_UnpackTuple() trong ví dụ này hoàn toàn tương đương với lệnh gọi tới PyArg_ParseTuple():

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

PY_CXX_CONST¶: Giá trị được chèn, nếu có, trước char *const* trong phần khai báo tham số keywords của PyArg_ParseTupleAndKeywords() và PyArg_VaParseTupleAndKeywords(). Mặc định trống đối với C và const đối với C++ (const char *const*). Để ghi đè, hãy xác định giá trị đó theo giá trị mong muốn trước khi thêm Python.h.

Added in version 3.13.

Xây dựng giá trị¶

PyObject *Py_BuildValue(const char *format, ...)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Tạo một giá trị mới dựa trên chuỗi định dạng tương tự như chuỗi định dạng được chấp nhận bởi nhóm hàm PyArg_Parse* và một chuỗi giá trị. Trả về giá trị hoặc NULL trong trường hợp có lỗi; một ngoại lệ sẽ được đưa ra nếu NULL được trả về.

Py_BuildValue() không phải lúc nào cũng tạo một bộ dữ liệu. Nó chỉ xây dựng một bộ nếu chuỗi định dạng của nó chứa hai hoặc nhiều đơn vị định dạng. Nếu chuỗi định dạng trống, nó sẽ trả về None; nếu nó chứa chính xác một đơn vị định dạng, nó sẽ trả về bất kỳ đối tượng nào được mô tả bởi đơn vị định dạng đó. Để buộc nó trả về một bộ có kích thước 0 hoặc một, hãy đặt dấu ngoặc đơn vào chuỗi định dạng.

Khi bộ đệm bộ nhớ được truyền dưới dạng tham số để cung cấp dữ liệu cho việc xây dựng đối tượng, như đối với định dạng s và s#, dữ liệu cần thiết sẽ được sao chép. Bộ đệm do người gọi cung cấp không bao giờ được tham chiếu bởi các đối tượng được tạo bởi Py_BuildValue(). Nói cách khác, nếu mã của bạn gọi malloc() và chuyển bộ nhớ được phân bổ cho Py_BuildValue(), thì mã của bạn chịu trách nhiệm gọi free() cho bộ nhớ đó sau khi Py_BuildValue() quay trở lại.

Trong phần mô tả sau đây, biểu mẫu được trích dẫn là đơn vị định dạng; mục nhập trong dấu ngoặc đơn (tròn) là loại đối tượng Python mà đơn vị định dạng sẽ trả về; và mục nhập trong ngoặc [vuông] là loại giá trị C được chuyển.

Khoảng trắng ký tự, tab, dấu hai chấm và dấu phẩy bị bỏ qua trong chuỗi định dạng (nhưng không nằm trong các đơn vị định dạng như s#). Điều này có thể được sử dụng để làm cho các chuỗi định dạng dài dễ đọc hơn một chút.

s (str hoặc None) [const char *]: Chuyển đổi chuỗi C kết thúc bằng null thành đối tượng Python str bằng cách sử dụng mã hóa 'utf-8'. Nếu con trỏ chuỗi C là NULL thì None sẽ được sử dụng.
s# (str hoặc None) [const char *, Py_ssize_t]: Chuyển đổi chuỗi C và độ dài của chuỗi đó thành đối tượng Python str bằng cách sử dụng mã hóa 'utf-8'. Nếu con trỏ chuỗi C là NULL, độ dài sẽ bị bỏ qua và None được trả về.
y (bytes) [const char *]: Điều này chuyển đổi chuỗi C thành đối tượng Python bytes. Nếu con trỏ chuỗi C là NULL, None sẽ được trả về.
y# (bytes) [const char *, Py_ssize_t]: Điều này chuyển đổi chuỗi C và độ dài của nó thành đối tượng Python. Nếu con trỏ chuỗi C là NULL, None sẽ được trả về.
z (str hoặc None) [const char *]: Tương tự với s
z# (str hoặc None) [const char *, Py_ssize_t]: Tương tự với s#
u (str) [const wchar_t *]: Chuyển đổi bộ đệm wchar_t kết thúc bằng null của dữ liệu Unicode (UTF-16 hoặc UCS-4) thành đối tượng Python Unicode. Nếu con trỏ bộ đệm Unicode là NULL, None sẽ được trả về.
u# (str) [const wchar_t *, Py_ssize_t]: Chuyển đổi bộ đệm dữ liệu Unicode (UTF-16 hoặc UCS-4) và độ dài của nó thành đối tượng Python Unicode. Nếu con trỏ bộ đệm Unicode là NULL thì độ dài sẽ bị bỏ qua và None được trả về.
U (str hoặc None) [const char *]: Tương tự với s
U# (str hoặc None) [const char *, Py_ssize_t]: Tương tự với s#
i (int) [int]: Chuyển đổi một int C đơn giản thành một đối tượng số nguyên Python.
b (int) [char]: Chuyển đổi một char C đơn giản thành một đối tượng số nguyên Python.
h (int) [ngắn int]: Chuyển đổi một short int C đơn giản thành một đối tượng số nguyên Python.
l (int) [dài]: Chuyển đổi C long int thành đối tượng số nguyên Python.
B (int) [ký tự không dấu]: Chuyển đổi C unsigned char thành đối tượng số nguyên Python.
H (int) [unsign int ngắn]: Chuyển đổi C unsigned short int thành đối tượng số nguyên Python.
I (int) [unsign int]: Chuyển đổi C unsigned int thành đối tượng số nguyên Python.
k (int) [dài không dấu]: Chuyển đổi C unsigned long thành đối tượng số nguyên Python.
L (int) [dài dài]: Chuyển đổi C long long thành đối tượng số nguyên Python.

K (int) [dài không dấu]

Chuyển đổi C unsigned long long thành đối tượng số nguyên Python.

n (int) [Py_ssize_t]

Chuyển đổi C Py_ssize_t thành số nguyên Python.

p (bool) [int]

Chuyển đổi một int C thành đối tượng Python bool.

Xin lưu ý rằng định dạng này yêu cầu đối số int. Không giống như hầu hết các bối cảnh khác trong C, các đối số biến đổi không tự động bị ép buộc thành một loại phù hợp. Bạn có thể chuyển đổi một loại khác (ví dụ: con trỏ hoặc dấu phẩy) thành giá trị int phù hợp bằng cách sử dụng (x) ? 1 : 0 hoặc !!x.

Added in version 3.14.

c (bytes có độ dài 1) [char]

Chuyển đổi một C int đại diện cho một byte thành đối tượng Python bytes có độ dài 1.

C (str có độ dài 1) [int]

Chuyển đổi một C int đại diện cho một ký tự thành đối tượng Python str có độ dài 1.

d (float) [gấp đôi]

Chuyển đổi C double thành số dấu phẩy động Python.

f (float) [thả nổi]

Chuyển đổi C float thành số dấu phẩy động Python.

D (complex) [Py_complex *]

Chuyển đổi cấu trúc C Py_complex thành số phức Python.

O (đối tượng) [PyObject *]

Truyền một đối tượng Python mà không bị ảnh hưởng nhưng tạo một strong reference mới cho nó (tức là số tham chiếu của nó được tăng lên một). Nếu đối tượng được truyền vào là một con trỏ NULL, thì giả định rằng điều này xảy ra là do lệnh gọi tạo ra đối số đã tìm thấy lỗi và đặt một ngoại lệ. Do đó, Py_BuildValue() sẽ trả về NULL nhưng sẽ không đưa ra ngoại lệ. Nếu chưa có ngoại lệ nào được nêu ra thì SystemError sẽ được đặt.

S (đối tượng) [PyObject *]

Tương tự với O

N (đối tượng) [PyObject *]

Tương tự như O, ngoại trừ việc nó không tạo ra strong reference mới. Hữu ích khi đối tượng được tạo bằng lệnh gọi hàm tạo đối tượng trong danh sách đối số.

O& (đối tượng) [converter, anything]

Chuyển đổi anything thành đối tượng Python thông qua hàm converter. Hàm này được gọi với anything (phải tương thích với void*) làm đối số và sẽ trả về một đối tượng Python "mới" hoặc NULL nếu xảy ra lỗi.

(items) (tuple) [matching-items]

Chuyển đổi một chuỗi các giá trị C thành một bộ dữ liệu Python có cùng số lượng mục.

[items] (list) [matching-items]

Chuyển đổi một chuỗi các giá trị C thành danh sách Python có cùng số mục.

{items} (dict) [matching-items]

Chuyển đổi một chuỗi các giá trị C sang từ điển Python. Mỗi cặp giá trị C liên tiếp sẽ thêm một mục vào từ điển, đóng vai trò tương ứng là khóa và giá trị.

Nếu có lỗi trong chuỗi định dạng, ngoại lệ SystemError được đặt và NULL được trả về.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Giống hệt Py_BuildValue(), ngoại trừ việc nó chấp nhận va_list thay vì số lượng đối số thay đổi.

Phân tích đối số và xây dựng giá trị¶