inspect --- Kiểm tra vật thể sống

Source code: Lib/inspect.py

---

Mô-đun inspect cung cấp một số chức năng hữu ích để giúp lấy thông tin về các đối tượng trực tiếp như mô-đun, lớp, phương thức, hàm, truy nguyên, đối tượng khung và đối tượng mã. Ví dụ: nó có thể giúp bạn kiểm tra nội dung của một lớp, truy xuất mã nguồn của một phương thức, trích xuất và định dạng danh sách đối số cho một hàm hoặc lấy tất cả thông tin bạn cần để hiển thị truy nguyên chi tiết.

Có bốn loại dịch vụ chính được cung cấp bởi mô-đun này: kiểm tra loại, lấy mã nguồn, kiểm tra các lớp và hàm cũng như kiểm tra ngăn xếp trình thông dịch.

Các loại và thành viên

Hàm getmembers() truy xuất các thành viên của một đối tượng, chẳng hạn như một lớp hoặc mô-đun. Các hàm có tên bắt đầu bằng "is" chủ yếu được cung cấp dưới dạng các lựa chọn thuận tiện cho đối số thứ hai của getmembers(). Chúng cũng giúp bạn xác định khi nào bạn có thể mong đợi tìm thấy các thuộc tính đặc biệt sau (xem Các thuộc tính liên quan đến nhập khẩu trên các đối tượng mô-đun để biết các thuộc tính mô-đun):

Loại	Thuộc tính	Mô tả
lớp học	__doc__	chuỗi tài liệu
	__tên__	tên mà lớp này được định nghĩa
	__qualname__	tên đủ điều kiện
	__mô-đun__	tên của mô-đun trong đó lớp này được xác định
	__type_params__	Một bộ dữ liệu chứa type parameters của một lớp chung
phương pháp	__doc__	chuỗi tài liệu
	__tên__	tên mà phương thức này được xác định
	__qualname__	tên đủ điều kiện
	__func__	đối tượng hàm chứa việc thực hiện phương thức
	__bản thân__	trường hợp mà phương thức này bị ràng buộc hoặc None
	__mô-đun__	tên của mô-đun trong đó phương thức này được xác định
chức năng	__doc__	chuỗi tài liệu
	__tên__	tên mà chức năng này được xác định
	__qualname__	tên đủ điều kiện
	__mã__	đối tượng mã chứa hàm được biên dịch bytecode
	__mặc định__	bộ giá trị mặc định cho tham số vị trí hoặc từ khóa
	__kwmặc định__	ánh xạ mọi giá trị mặc định cho các tham số chỉ từ khóa
	__toàn cầu__	không gian tên chung trong đó hàm này được xác định
	__dựng sẵn__	không gian tên dựng sẵn
	__chú thích__	ánh xạ tên tham số vào chú thích; Phím "return" được dành riêng cho chú thích trả về.
	__type_params__	Một bộ chứa type parameters của một hàm chung
	__mô-đun__	tên của mô-đun trong đó chức năng này được xác định
truy nguyên	tb_frame	đối tượng khung ở cấp độ này
	tb_lasti	chỉ mục của lệnh thử cuối cùng trong mã byte
	tb_lineno	số dòng hiện tại trong mã nguồn Python
	tb_next	đối tượng truy nguyên bên trong tiếp theo (được gọi theo cấp độ này)
khung	quay lại	đối tượng khung bên ngoài tiếp theo (người gọi khung này)
	f_buildins	không gian tên dựng sẵn được khung này nhìn thấy
	f_code	đối tượng mã đang được thực thi trong khung này
	f_globals	không gian tên toàn cầu được khung này nhìn thấy
	f_lasti	chỉ mục của lệnh thử cuối cùng trong mã byte
	f_lineno	số dòng hiện tại trong mã nguồn Python
	f_người dân địa phương	không gian tên cục bộ được khung này nhìn thấy
	f_generator	trả về trình tạo hoặc đối tượng coroutine sở hữu khung này hoặc None nếu khung có chức năng thông thường
	f_trace	chức năng theo dõi cho khung này hoặc None
	f_trace_lines	cho biết liệu một sự kiện theo dõi có được kích hoạt cho từng dòng nguồn nguồn hay không
	f_trace_opcodes	cho biết liệu các sự kiện trên mỗi opcode có được yêu cầu hay không
	xóa()	được sử dụng để xóa tất cả các tham chiếu đến các biến cục bộ
mã	co_argcount	số lượng đối số (không bao gồm các đối số chỉ từ khóa, * hoặc ** args)
	co_code	chuỗi mã byte được biên dịch thô
	co_cellvars	bộ tên của các biến ô (được tham chiếu bằng cách chứa phạm vi)
	co_const	bộ hằng số được sử dụng trong mã byte
	tên đồng_file	tên của tệp mà đối tượng mã này được tạo
	co_firstlineno	số dòng đầu tiên trong mã nguồn Python
	co_flags	bitmap của cờ CO_*, đọc thêm here
	co_lnotab	ánh xạ được mã hóa của số dòng thành chỉ mục mã byte
	co_freevars	bộ tên của các biến tự do (được tham chiếu thông qua việc đóng hàm)
	co_posonlyargcount	số lượng đối số chỉ vị trí
	co_kwonlyargcount	số đối số chỉ từ khóa (không bao gồm ** arg)
	đồng_tên	tên mà đối tượng mã này được xác định
	co_qualname	tên đủ điều kiện mà đối tượng mã này đã được xác định
	đồng tên	bộ tên không phải là đối số và hàm cục bộ
	đồng_nlocals	số lượng biến cục bộ
	co_stacksize	cần có không gian ngăn xếp máy ảo
	co_varnames	bộ tên của đối số và biến cục bộ
	co_lines()	trả về một trình vòng lặp tạo ra các phạm vi mã byte liên tiếp
	co_positions()	trả về một trình vòng lặp các vị trí mã nguồn cho mỗi lệnh mã byte
	thay thế()	trả về một bản sao của đối tượng mã với các giá trị mới
máy phát điện	__tên__	tên
	__qualname__	tên đủ điều kiện
	gi_frame	khung
	gi_running	máy phát điện có chạy không?
	gi_bị đình chỉ	máy phát điện có bị treo không?
	gi_code	mã
	gi_yieldfrom	đối tượng được lặp lại bởi yield from hoặc None
trình tạo không đồng bộ	__tên__	tên
	__qualname__	tên đủ điều kiện
	ag_await	đối tượng đang được chờ đợi hoặc None
	ag_frame	khung
	ag_running	máy phát điện có chạy không?
	ag_bị đình chỉ	máy phát điện có bị treo không?
	mã ag_code	mã
đội quân tuần tra	__tên__	tên
	__qualname__	tên đủ điều kiện
	cr_await	đối tượng đang được chờ đợi hoặc None
	cr_frame	khung
	cr_running	coroutine có đang chạy không?
	cr_suspend	coroutine có bị đình chỉ không?
	mã cr_code	mã
	cr_origin	nơi coroutine được tạo hoặc None. Xem sys.set_coroutine_origin_tracking_depth()
dựng sẵn	__doc__	chuỗi tài liệu
	__tên__	tên gốc của hàm hoặc phương thức này
	__qualname__	tên đủ điều kiện
	__bản thân__	ví dụ mà một phương thức bị ràng buộc hoặc None

Thay đổi trong phiên bản 3.5: Thêm thuộc tính __qualname__ và gi_yieldfrom vào trình tạo.

Thuộc tính __name__ của trình tạo hiện được đặt từ tên hàm, thay vì tên mã và giờ đây nó có thể được sửa đổi.

Thay đổi trong phiên bản 3.7: Thêm thuộc tính cr_origin vào coroutine.

Thay đổi trong phiên bản 3.10: Thêm thuộc tính __builtins__ vào hàm.

Thay đổi trong phiên bản 3.11: Thêm thuộc tính gi_suspended vào trình tạo.

Thay đổi trong phiên bản 3.11: Thêm thuộc tính cr_suspended vào coroutine.

Thay đổi trong phiên bản 3.12: Thêm thuộc tính ag_suspended vào trình tạo không đồng bộ.

Thay đổi trong phiên bản 3.14: Thêm thuộc tính f_generator vào khung.

inspect.getmembers(object[, predicate])

Trả về tất cả các thành viên của một đối tượng trong danh sách các cặp (name, value) được sắp xếp theo tên. Nếu đối số predicate tùy chọn—sẽ được gọi với đối tượng value của mỗi thành viên—được cung cấp thì chỉ những thành viên mà vị từ trả về giá trị thực mới được đưa vào.

Ghi chú

getmembers() sẽ chỉ trả về các thuộc tính lớp được xác định trong siêu dữ liệu khi đối số là một lớp và các thuộc tính đó đã được liệt kê trong __dir__() tùy chỉnh của siêu dữ liệu.

inspect.getmembers_static(object[, predicate])

Trả về tất cả các thành viên của một đối tượng trong danh sách các cặp (name, value) được sắp xếp theo tên mà không kích hoạt tra cứu động thông qua giao thức mô tả, __getattr__ hoặc __getattribute__. Tùy chọn, chỉ trả về các thành viên thỏa mãn một vị từ nhất định.

Ghi chú

getmembers_static() có thể không truy xuất được tất cả các thành viên mà getmember có thể tìm nạp (như các thuộc tính được tạo động) và có thể tìm thấy các thành viên mà getmember không thể tìm nạp (như bộ mô tả tăng AttributionError). Nó cũng có thể trả về các đối tượng mô tả thay vì các thành viên thể hiện trong một số trường hợp.

Added in version 3.11.

inspect.getmodulename(path)

Trả về tên của mô-đun được đặt tên theo tệp path, không bao gồm tên của các gói kèm theo. Phần mở rộng tệp được kiểm tra đối với tất cả các mục trong importlib.machinery.all_suffixes(). Nếu nó khớp, thành phần đường dẫn cuối cùng sẽ được trả về cùng với phần mở rộng đã bị xóa. Nếu không, None sẽ được trả về.

Lưu ý rằng hàm only này trả về một tên có ý nghĩa cho các mô-đun Python thực tế - các đường dẫn có khả năng tham chiếu đến các gói Python sẽ vẫn trả về None.

Thay đổi trong phiên bản 3.3: Chức năng này dựa trực tiếp vào importlib.

inspect.ismodule(object)

Trả về True nếu đối tượng là một mô-đun.

inspect.isclass(object)

Trả về True nếu đối tượng là một lớp, dù được tích hợp sẵn hay được tạo bằng mã Python.

inspect.ismethod(object)

Trả về True nếu đối tượng là một phương thức liên kết được viết bằng Python.

inspect.ispackage(object)

Trả về True nếu đối tượng là package.

Added in version 3.14.

inspect.isfunction(object)

Trả về True nếu đối tượng là hàm Python, bao gồm các hàm được tạo bởi biểu thức lambda.

inspect.isgeneratorfunction(object)

Trả về True nếu đối tượng là hàm tạo Python.

Thay đổi trong phiên bản 3.8: Các hàm được gói trong functools.partial() hiện trả về True nếu hàm được gói là hàm tạo Python.

Thay đổi trong phiên bản 3.13: Các hàm được gói trong functools.partialmethod() hiện trả về True nếu hàm được gói là hàm tạo Python.

inspect.isgenerator(object)

Trả về True nếu đối tượng là một trình tạo.

inspect.iscoroutinefunction(object)

Trả về True nếu đối tượng là coroutine function (một hàm được xác định bằng cú pháp async def), functools.partial() bao bọc một coroutine function hoặc một hàm đồng bộ hóa được đánh dấu bằng markcoroutinefunction().

Added in version 3.5.

Thay đổi trong phiên bản 3.8: Các hàm được gói trong functools.partial() hiện trả về True nếu hàm được gói là coroutine function.

Thay đổi trong phiên bản 3.12: Các chức năng đồng bộ hóa được đánh dấu bằng markcoroutinefunction() giờ sẽ trả về True.

Thay đổi trong phiên bản 3.13: Các hàm được gói trong functools.partialmethod() hiện trả về True nếu hàm được gói là coroutine function.

inspect.markcoroutinefunction(func)

Công cụ trang trí để đánh dấu một cuộc gọi có thể là coroutine function nếu iscoroutinefunction() không phát hiện ra nó.

Điều này có thể được sử dụng cho các hàm đồng bộ trả về coroutine, nếu hàm này được chuyển đến API yêu cầu iscoroutinefunction().

Khi có thể, nên sử dụng chức năng async def. Việc gọi hàm và kiểm tra kết quả trả về bằng iscoroutine() cũng được chấp nhận.

Added in version 3.12.

inspect.iscoroutine(object)

Trả về True nếu đối tượng là coroutine được tạo bởi hàm async def.

Added in version 3.5.

inspect.isawaitable(object)

Trả về True nếu đối tượng có thể được sử dụng trong biểu thức await.

Cũng có thể được sử dụng để phân biệt các coroutine dựa trên trình tạo với các trình tạo thông thường:

nhập khẩu các loại

gen def():
    năng suất
@types.coroutine
def gen_coro():
    năng suất

khẳng định không thể chờ đợi(gen())
khẳng định có thể chờ đợi(gen_coro())

Added in version 3.5.

inspect.isasyncgenfunction(object)

Trả về True nếu đối tượng là hàm asynchronous generator, ví dụ:

>>> agen def async():
... nhường 1
...
>>> kiểm tra.isasyncgenfunction(agen)
đúng

Added in version 3.6.

Thay đổi trong phiên bản 3.8: Các hàm được gói trong functools.partial() hiện trả về True nếu hàm được gói là hàm asynchronous generator.

Thay đổi trong phiên bản 3.13: Các hàm được gói trong functools.partialmethod() hiện trả về True nếu hàm được gói là hàm asynchronous generator.

inspect.isasyncgen(object)

Trả về True nếu đối tượng là asynchronous generator iterator được tạo bởi hàm asynchronous generator.

Added in version 3.6.

inspect.istraceback(object)

Trả về True nếu đối tượng là một truy nguyên.

inspect.isframe(object)

Trả về True nếu đối tượng là một khung.

inspect.iscode(object)

Trả về True nếu đối tượng là mã.

inspect.isbuiltin(object)

Trả về True nếu đối tượng là hàm tích hợp hoặc phương thức tích hợp sẵn.

inspect.ismethodwrapper(object)

Trả về True nếu loại đối tượng là MethodWrapperType.

Đây là các phiên bản của MethodWrapperType, chẳng hạn như __str__(), __eq__() và __repr__().

Added in version 3.11.

inspect.isroutine(object)

Trả về True nếu đối tượng là hàm hoặc phương thức do người dùng xác định hoặc tích hợp sẵn.

inspect.isabstract(object)

Trả về True nếu đối tượng là lớp cơ sở trừu tượng.

inspect.ismethoddescriptor(object)

Trả về True nếu đối tượng là một bộ mô tả phương thức, nhưng không trả về nếu ismethod(), isclass(), isfunction() hoặc isbuiltin() là đúng.

Ví dụ, điều này đúng với int.__add__. Đối tượng vượt qua bài kiểm tra này có phương thức __get__() nhưng không phải là phương thức __set__() hoặc phương thức __delete__(). Ngoài ra, tập hợp các thuộc tính khác nhau. Thuộc tính __name__ thường hợp lý và __doc__ thường là như vậy.

Các phương thức được triển khai thông qua bộ mô tả cũng vượt qua một trong các thử nghiệm khác trả về False từ thử nghiệm ismethoddescriptor(), đơn giản vì các thử nghiệm khác hứa hẹn nhiều hơn -- ví dụ: bạn có thể tin tưởng vào việc có thuộc tính __func__ (v.v.) khi một đối tượng vượt qua ismethod().

Thay đổi trong phiên bản 3.13: Hàm này không còn báo cáo không chính xác các đối tượng có __get__() và __delete__(), nhưng không phải là __set__(), dưới dạng bộ mô tả phương thức (các đối tượng đó là bộ mô tả dữ liệu, không phải bộ mô tả phương thức).

inspect.isdatadescriptor(object)

Trả về True nếu đối tượng là bộ mô tả dữ liệu.

Bộ mô tả dữ liệu có phương thức __set__ hoặc __delete__. Ví dụ là các thuộc tính (được xác định bằng Python), getset và thành viên. Hai loại sau được định nghĩa trong C và có nhiều thử nghiệm cụ thể hơn dành cho các loại đó, điều này mạnh mẽ trong quá trình triển khai Python. Thông thường, bộ mô tả dữ liệu cũng sẽ có thuộc tính __name__ và __doc__ (thuộc tính, getset và thành viên có cả hai thuộc tính này), nhưng điều này không được đảm bảo.

inspect.isgetsetdescriptor(object)

Trả về True nếu đối tượng là bộ mô tả getset.

getset là các thuộc tính được xác định trong các mô-đun mở rộng thông qua cấu trúc PyGetSetDef. Đối với việc triển khai Python không có các kiểu như vậy, phương thức này sẽ luôn trả về False.

inspect.ismemberdescriptor(object)

Trả về True nếu đối tượng là bộ mô tả thành viên.

Bộ mô tả thành viên là các thuộc tính được xác định trong các mô-đun mở rộng thông qua cấu trúc PyMemberDef. Đối với việc triển khai Python không có các kiểu như vậy, phương thức này sẽ luôn trả về False.

Truy xuất mã nguồn

inspect.getdoc(object)

Lấy chuỗi tài liệu cho một đối tượng, được làm sạch bằng cleandoc(). Nếu chuỗi tài liệu cho một đối tượng không được cung cấp và đối tượng đó là một lớp, một phương thức, một thuộc tính hoặc một bộ mô tả, hãy truy xuất chuỗi tài liệu từ hệ thống phân cấp kế thừa. Trả về None nếu chuỗi tài liệu không hợp lệ hoặc bị thiếu.

Thay đổi trong phiên bản 3.5: Chuỗi tài liệu hiện được kế thừa nếu không bị ghi đè.

inspect.getcomments(object)

Trả về trong một chuỗi bất kỳ dòng nhận xét nào ngay trước mã nguồn của đối tượng (đối với một lớp, hàm hoặc phương thức) hoặc ở đầu tệp nguồn Python (nếu đối tượng là một mô-đun). Nếu mã nguồn của đối tượng không có sẵn, hãy trả về None. Điều này có thể xảy ra nếu đối tượng đã được xác định trong C hoặc shell tương tác.

inspect.getfile(object)

Trả về tên của tệp (văn bản hoặc nhị phân) trong đó đối tượng được xác định. Điều này sẽ không thành công với TypeError nếu đối tượng là mô-đun, lớp hoặc hàm tích hợp.

inspect.getmodule(object)

Hãy thử đoán xem đối tượng được xác định trong mô-đun nào. Trả về None nếu không thể xác định được mô-đun.

inspect.getsourcefile(object)

Trả về tên của tệp nguồn Python trong đó một đối tượng đã được xác định hoặc None nếu không thể xác định được cách nào để lấy nguồn. Điều này sẽ không thành công với TypeError nếu đối tượng là mô-đun, lớp hoặc hàm tích hợp.

inspect.getsourcelines(object)

Trả về danh sách các dòng nguồn và số dòng bắt đầu cho một đối tượng. Đối số có thể là một mô-đun, lớp, phương thức, hàm, truy nguyên, khung hoặc đối tượng mã. Mã nguồn được trả về dưới dạng danh sách các dòng tương ứng với đối tượng và số dòng cho biết vị trí trong tệp nguồn gốc, dòng mã đầu tiên được tìm thấy. Một OSError sẽ xuất hiện nếu không thể truy xuất mã nguồn. Một TypeError được nâng lên nếu đối tượng là một mô-đun, lớp hoặc hàm tích hợp sẵn.

Thay đổi trong phiên bản 3.3: OSError được nâng lên thay vì IOError, hiện là bí danh của trước đây.

inspect.getsource(object)

Trả về văn bản mã nguồn của một đối tượng. Đối số có thể là một mô-đun, lớp, phương thức, hàm, truy nguyên, khung hoặc đối tượng mã. Mã nguồn được trả về dưới dạng một chuỗi đơn. Một OSError sẽ xuất hiện nếu không thể truy xuất mã nguồn. Một TypeError được nâng lên nếu đối tượng là một mô-đun, lớp hoặc hàm tích hợp sẵn.

Thay đổi trong phiên bản 3.3: OSError được nâng lên thay vì IOError, hiện là bí danh của trước đây.

inspect.cleandoc(doc)

Làm sạch vết thụt lề khỏi các chuỗi tài liệu được thụt lề để thẳng hàng với các khối mã.

Tất cả khoảng trắng ở đầu sẽ bị xóa khỏi dòng đầu tiên. Mọi khoảng trắng ở đầu có thể được loại bỏ một cách thống nhất từ ​​dòng thứ hai trở đi sẽ bị loại bỏ. Các dòng trống ở đầu và cuối sau đó sẽ bị xóa. Ngoài ra, tất cả các tab đều được mở rộng sang khoảng trắng.

Xem xét các khả năng có thể gọi được bằng đối tượng Chữ ký

Added in version 3.3.

Đối tượng Signature đại diện cho chữ ký cuộc gọi của một đối tượng có thể gọi được và chú thích trả về của nó. Để truy xuất đối tượng Signature, hãy sử dụng hàm signature().

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)

Trả về một đối tượng Signature cho callable đã cho:

>>> từ kiểm tra chữ ký nhập khẩu
>>> def foo(a, *, b:int, **kwargs):
... vượt qua

>>> sig = chữ ký(foo)

>>> str(sig)
'(a, *, b: int, **kwargs)'

>>> str(sig.parameters['b'])
'b: int'

>>> sig.parameters['b'].annotation
<lớp 'int'>

Chấp nhận nhiều loại lệnh gọi Python, từ các hàm và lớp đơn giản đến các đối tượng functools.partial().

Nếu một số chú thích là chuỗi (ví dụ: vì from __future__ import annotations đã được sử dụng), signature() sẽ cố gắng tự động hủy chuỗi các chú thích bằng annotationlib.get_annotations(). Các tham số globals, locals và eval_str được chuyển vào annotationlib.get_annotations() khi phân giải các chú thích; xem tài liệu dành cho annotationlib.get_annotations() để biết hướng dẫn về cách sử dụng các tham số này. Một thành viên của enum annotationlib.Format có thể được chuyển tới tham số annotation_format để kiểm soát định dạng của các chú thích được trả về. Ví dụ: sử dụng annotation_format=annotationlib.Format.STRING để trả về các chú thích ở định dạng chuỗi.

Tăng ValueError nếu không thể cung cấp chữ ký và TypeError nếu loại đối tượng đó không được hỗ trợ. Ngoài ra, nếu các chú thích được xâu chuỗi và eval_str không sai, thì (các) lệnh gọi eval() để hủy xâu chuỗi các chú thích trong annotationlib.get_annotations() có thể có khả năng đưa ra bất kỳ loại ngoại lệ nào.

Dấu gạch chéo (/) trong chữ ký của hàm biểu thị rằng các tham số trước nó chỉ mang tính vị trí. Để biết thêm thông tin, xem the FAQ entry on positional-only parameters.

Thay đổi trong phiên bản 3.5: Tham số follow_wrapped đã được thêm vào. Vượt qua False để nhận được chữ ký cụ thể của callable (callable.__wrapped__ sẽ không được sử dụng để mở gói các lệnh gọi được trang trí.)

Thay đổi trong phiên bản 3.10: Các thông số globals, locals và eval_str đã được thêm vào.

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

Ghi chú

Một số lệnh gọi có thể không thể xem được trong một số triển khai nhất định của Python. Ví dụ: trong CPython, một số hàm dựng sẵn được xác định trong C không cung cấp siêu dữ liệu về các đối số của chúng.

Nếu đối tượng được truyền có thuộc tính __signature__, chúng ta có thể sử dụng nó để tạo chữ ký. Ngữ nghĩa chính xác là chi tiết triển khai và có thể thay đổi không báo trước. Tham khảo mã nguồn cho ngữ nghĩa hiện tại.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

Đối tượng Signature đại diện cho chữ ký cuộc gọi của một hàm và chú thích trả về của nó. Đối với mỗi tham số được hàm chấp nhận, nó lưu trữ một đối tượng Parameter trong bộ sưu tập parameters của nó.

Đối số parameters tùy chọn là một chuỗi các đối tượng Parameter, được xác thực để kiểm tra xem không có tham số nào có tên trùng lặp hay không và các tham số có theo đúng thứ tự hay không, tức là chỉ vị trí trước tiên, sau đó là vị trí hoặc từ khóa và các tham số có giá trị mặc định sẽ tuân theo các tham số không có giá trị mặc định.

Đối số return_annotation tùy chọn có thể là một đối tượng Python tùy ý. Nó đại diện cho chú thích "return" của hàm có thể gọi được.

đối tượng Signature là immutable. Sử dụng Signature.replace() hoặc copy.replace() để tạo một bản sao sửa đổi.

Thay đổi trong phiên bản 3.5: Các đối tượng Signature hiện có thể chọn được và hashable.

empty

Điểm đánh dấu cấp độ lớp đặc biệt để xác định sự vắng mặt của chú thích trả về.

parameters

Ánh xạ có thứ tự tên của các tham số tới các đối tượng Parameter tương ứng. Các tham số xuất hiện theo thứ tự định nghĩa chặt chẽ, bao gồm các tham số chỉ có từ khóa.

Thay đổi trong phiên bản 3.7: Python chỉ đảm bảo rõ ràng rằng nó giữ nguyên thứ tự khai báo các tham số chỉ từ khóa kể từ phiên bản 3.7, mặc dù trên thực tế, thứ tự này luôn được giữ nguyên trong Python 3.

return_annotation

Chú thích "trả lại" cho lệnh gọi được. Nếu lệnh gọi không có chú thích "return", thuộc tính này được đặt thành Signature.empty.

bind(*args, **kwargs)

Tạo ánh xạ từ các đối số vị trí và từ khóa tới các tham số. Trả về BoundArguments nếu *args và **kwargs khớp với chữ ký hoặc tăng TypeError.

bind_partial(*args, **kwargs)

Hoạt động theo cách tương tự như Signature.bind(), nhưng cho phép bỏ qua một số đối số bắt buộc (bắt chước hành vi của functools.partial().) Trả về BoundArguments hoặc tăng TypeError nếu các đối số được truyền không khớp với chữ ký.

replace(*[, parameters][, return_annotation])

Tạo một phiên bản Signature mới dựa trên phiên bản replace() đã được gọi. Có thể chuyển parameters và/hoặc return_annotation khác nhau để ghi đè các thuộc tính tương ứng của chữ ký cơ sở. Để xóa return_annotation khỏi Signature đã sao chép, hãy chuyển vào Signature.empty.

>>> kiểm tra def(a, b):
... vượt qua
...
>>> sig = chữ ký(kiểm tra)
>>> new_sig = sig.replace(return_annotation="thông báo trả lại mới")
>>> str(new_sig)
"(a, b) -> 'thông báo trả hàng mới'"

Các đối tượng Signature cũng được hỗ trợ bởi hàm chung copy.replace().

format(*, max_width=None, quote_annotation_strings=True)

Tạo một chuỗi biểu diễn của đối tượng Signature.

Nếu max_width được thông qua, phương thức sẽ cố gắng khớp chữ ký vào các dòng có tối đa max_width ký tự. Nếu chữ ký dài hơn max_width thì tất cả các tham số sẽ nằm trên các dòng riêng biệt.

Nếu quote_annotation_strings là Sai, annotations trong chữ ký sẽ được hiển thị mà không mở và đóng dấu ngoặc kép nếu chúng là chuỗi. Điều này hữu ích nếu chữ ký được tạo bằng định dạng STRING hoặc nếu from __future__ import annotations được sử dụng.

Added in version 3.13.

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

classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Trả về một đối tượng Signature (hoặc lớp con của nó) cho một obj có thể gọi được.

Phương pháp này đơn giản hóa việc phân lớp con của Signature:

lớp MySignature(Chữ ký):
    vượt qua
sig = MySignature.from_callable(sum)
khẳng định isinstance(sig, MySignature)

Hành vi của nó giống hệt với signature().

Added in version 3.5.

Thay đổi trong phiên bản 3.10: Các thông số globals, locals và eval_str đã được thêm vào.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

đối tượng Parameter là immutable. Thay vì sửa đổi đối tượng Parameter, bạn có thể sử dụng Parameter.replace() hoặc copy.replace() để tạo một bản sao đã sửa đổi.

Thay đổi trong phiên bản 3.5: Các đối tượng tham số hiện có thể chọn được và hashable.

empty

Điểm đánh dấu cấp độ lớp đặc biệt để xác định sự vắng mặt của các giá trị và chú thích mặc định.

name

Tên của tham số ở dạng chuỗi. Tên phải là mã định danh Python hợp lệ.

CPython tạo các tên tham số ngầm định có dạng .0 trên các đối tượng mã được sử dụng để triển khai khả năng hiểu và biểu thức trình tạo.

Thay đổi trong phiên bản 3.6: Các tên tham số này hiện được mô-đun này hiển thị dưới dạng các tên như implicit0.

default

Giá trị mặc định cho tham số. Nếu tham số không có giá trị mặc định thì thuộc tính này được đặt thành Parameter.empty.

annotation

Chú thích cho tham số. Nếu tham số không có chú thích thì thuộc tính này được đặt thành Parameter.empty.

kind

Mô tả cách các giá trị đối số được liên kết với tham số. Các giá trị có thể có thể truy cập được thông qua Parameter (như Parameter.KEYWORD_ONLY) và hỗ trợ so sánh và sắp xếp theo thứ tự sau:

Tên	Ý nghĩa
POSITIONAL_ONLY	Giá trị phải được cung cấp dưới dạng đối số vị trí. Tham số chỉ vị trí là những tham số xuất hiện trước mục nhập / (nếu có) trong định nghĩa hàm Python.
POSITIONAL_OR_KEYWORD	Giá trị có thể được cung cấp dưới dạng từ khóa hoặc đối số vị trí (đây là hành vi ràng buộc tiêu chuẩn cho các hàm được triển khai trong Python.)
VAR_POSITIONAL	Một bộ đối số vị trí không bị ràng buộc với bất kỳ tham số nào khác. Điều này tương ứng với tham số *args trong định nghĩa hàm Python.
KEYWORD_ONLY	Giá trị phải được cung cấp dưới dạng đối số từ khóa. Tham số chỉ từ khóa là những tham số xuất hiện sau mục nhập * hoặc *args trong định nghĩa hàm Python.
VAR_KEYWORD	Một mệnh lệnh về các đối số từ khóa không bị ràng buộc với bất kỳ tham số nào khác. Điều này tương ứng với tham số **kwargs trong định nghĩa hàm Python.

Ví dụ: in tất cả các đối số chỉ có từ khóa không có giá trị mặc định:

>>> def foo(a, b, *, c, d=10):
... vượt qua

>>> sig = chữ ký(foo)
>>> cho thông số trong sig.parameters.values():
... if (param.kind == param.KEYWORD_ONLY và
... param.default là param.empty):
... print('Tham số:', param)
Tham số: c

kind.description

Mô tả giá trị enum của Parameter.kind.

Added in version 3.8.

Ví dụ: in tất cả các mô tả của đối số:

>>> def foo(a, b, *, c, d=10):
... vượt qua

>>> sig = chữ ký(foo)
>>> cho thông số trong sig.parameters.values():
... print(param.kind.description)
vị trí hoặc từ khóa
vị trí hoặc từ khóa
chỉ từ khóa
chỉ từ khóa

replace(*[, name][, kind][, default][, annotation])

Tạo một phiên bản Parameter mới dựa trên phiên bản được thay thế đã được gọi. Để ghi đè thuộc tính Parameter, hãy chuyển đối số tương ứng. Để xóa giá trị mặc định hoặc/và chú thích khỏi Parameter, hãy chuyển Parameter.empty.

>>> từ kiểm tra tham số nhập
>>> param = Tham số('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will tạo bản sao nông của 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, chú thích='spam'))
"foo: 'thư rác'"

Các đối tượng Parameter cũng được hỗ trợ bởi hàm chung copy.replace().

Thay đổi trong phiên bản 3.4: Trong Python 3.3, các đối tượng Parameter được phép đặt name thành None nếu kind của chúng được đặt thành POSITIONAL_ONLY. Điều này không còn được phép.

class inspect.BoundArguments

Kết quả của lệnh gọi Signature.bind() hoặc Signature.bind_partial(). Giữ ánh xạ các đối số tới các tham số của hàm.

arguments

Ánh xạ có thể thay đổi tên của tham số thành giá trị của đối số. Chỉ chứa các đối số bị ràng buộc rõ ràng. Những thay đổi trong arguments sẽ phản ánh trong args và kwargs.

Nên sử dụng kết hợp với Signature.parameters cho bất kỳ mục đích xử lý đối số nào.

Ghi chú

Các đối số mà Signature.bind() hoặc Signature.bind_partial() dựa vào giá trị mặc định sẽ bị bỏ qua. Tuy nhiên, nếu cần, hãy sử dụng BoundArguments.apply_defaults() để thêm chúng.

Thay đổi trong phiên bản 3.9: arguments hiện thuộc loại dict. Trước đây nó thuộc loại collections.OrderedDict.

args

Một bộ giá trị đối số vị trí. Được tính toán động từ thuộc tính arguments.

kwargs

Một mệnh lệnh về các giá trị đối số từ khóa. Được tính toán động từ thuộc tính arguments. Thay vào đó, các đối số có thể được truyền theo vị trí sẽ được đưa vào args.

signature

Tham chiếu tới đối tượng Signature gốc.

apply_defaults()

Đặt giá trị mặc định cho các đối số bị thiếu.

Đối với các đối số có vị trí thay đổi (*args), giá trị mặc định là một bộ dữ liệu trống.

Đối với các đối số từ khóa thay đổi (**kwargs), mặc định là một lệnh trống.

>>> def foo(a, b='ham', *args): vượt qua
>>> ba = kiểm tra.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

Added in version 3.5.

Thuộc tính args và kwargs có thể được sử dụng để gọi các hàm:

kiểm tra def(a, *, b):
    ...

sig = chữ ký (kiểm tra)
ba = sig.bind(10, b=20)
kiểm tra(*ba.args, **ba.kwargs)

Xem thêm

PEP 362 - Đối tượng chữ ký hàm.

Thông số kỹ thuật chi tiết, chi tiết triển khai và ví dụ.

Các lớp và hàm

inspect.getclasstree(classes, unique=False)

Sắp xếp danh sách các lớp đã cho thành một hệ thống phân cấp các danh sách lồng nhau. Khi một danh sách lồng nhau xuất hiện, nó chứa các lớp dẫn xuất từ ​​lớp có mục nhập ngay trước danh sách. Mỗi mục là một bộ gồm 2 bộ chứa một lớp và một bộ các lớp cơ sở của nó. Nếu đối số unique là đúng, chính xác một mục xuất hiện trong cấu trúc trả về cho mỗi lớp trong danh sách đã cho. Nếu không, các lớp sử dụng đa kế thừa và các lớp con của chúng sẽ xuất hiện nhiều lần.

inspect.getfullargspec(func)

Lấy tên và giá trị mặc định của các tham số của hàm Python. Một named tuple được trả về:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args là danh sách tên tham số vị trí. varargs là tên của tham số * hoặc None nếu các đối số vị trí tùy ý không được chấp nhận. varkw là tên của tham số ** hoặc None nếu đối số từ khóa tùy ý không được chấp nhận. defaults là một bộ n gồm các giá trị đối số mặc định tương ứng với các tham số vị trí n cuối cùng hoặc None nếu không có giá trị mặc định nào được xác định. kwonlyargs là danh sách các tên tham số chỉ có từ khóa theo thứ tự khai báo. kwonlydefaults là tên tham số ánh xạ từ điển từ kwonlyargs đến các giá trị mặc định được sử dụng nếu không có đối số nào được cung cấp. annotations là một từ điển ánh xạ tên tham số vào các chú thích. Phím đặc biệt "return" dùng để báo cáo chú thích giá trị trả về của hàm (nếu có).

Lưu ý rằng signature() và Signature Object cung cấp API được đề xuất để xem xét nội tâm có thể gọi được và hỗ trợ các hành vi bổ sung (như đối số chỉ vị trí) đôi khi gặp phải trong API mô-đun mở rộng. Hàm này được giữ lại chủ yếu để sử dụng trong mã cần duy trì khả năng tương thích với mô-đun inspect API của Python 2.

Thay đổi trong phiên bản 3.4: Hàm này hiện dựa trên signature(), nhưng vẫn bỏ qua các thuộc tính __wrapped__ và bao gồm tham số đầu tiên đã bị ràng buộc trong đầu ra chữ ký cho các phương thức bị ràng buộc.

Thay đổi trong phiên bản 3.6: Phương pháp này trước đây được ghi nhận là không được dùng nữa để thay thế cho signature() trong Python 3.5, nhưng quyết định đó đã bị hủy bỏ để khôi phục giao diện tiêu chuẩn được hỗ trợ rõ ràng cho mã Python 2/3 nguồn đơn di chuyển khỏi getargspec() API cũ.

Thay đổi trong phiên bản 3.7: Python chỉ đảm bảo rõ ràng rằng nó giữ nguyên thứ tự khai báo các tham số chỉ từ khóa kể từ phiên bản 3.7, mặc dù trên thực tế, thứ tự này luôn được giữ nguyên trong Python 3.

inspect.getargvalues(frame)

Nhận thông tin về các đối số được truyền vào một khung cụ thể. Một named tuple ArgInfo(args, varargs, keywords, locals) được trả về. args là danh sách tên đối số. varargs và keywords là tên của các đối số * và ** hoặc None. locals là từ điển cục bộ của khung đã cho.

Ghi chú

Hàm này vô tình bị đánh dấu là không dùng nữa trong Python 3.5.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Định dạng một thông số đối số đẹp mắt từ bốn giá trị được trả về bởi getargvalues(). Các đối số format* là các hàm định dạng tùy chọn tương ứng được gọi để biến tên và giá trị thành chuỗi.

Ghi chú

Hàm này vô tình bị đánh dấu là không dùng nữa trong Python 3.5.

inspect.getmro(cls)

Trả về một bộ các lớp cơ sở của lớp cls, bao gồm cls, theo thứ tự phân giải phương thức. Không có lớp nào xuất hiện nhiều hơn một lần trong bộ dữ liệu này. Lưu ý rằng thứ tự phân giải phương thức phụ thuộc vào loại cls. Trừ khi một siêu dữ liệu đặc biệt do người dùng định nghĩa được sử dụng, cls sẽ là thành phần đầu tiên của bộ dữ liệu.

inspect.getcallargs(func, /, *args, **kwds)

Liên kết args và kwds với tên đối số của hàm hoặc phương thức Python func, như thể nó được gọi cùng với chúng. Đối với các phương thức bị ràng buộc, cũng liên kết đối số đầu tiên (thường được đặt tên là self) với phiên bản được liên kết. Một lệnh được trả về, ánh xạ các tên đối số (bao gồm tên của các đối số * và **, nếu có) tới các giá trị của chúng từ args và kwds. Trong trường hợp gọi func không chính xác, tức là bất cứ khi nào func(*args, **kwds) đưa ra một ngoại lệ do chữ ký không tương thích, một ngoại lệ cùng loại và thông báo giống nhau hoặc tương tự sẽ được đưa ra. Ví dụ:

>>> từ kiểm tra nhập getcallargs
>>> def f(a, b=1, *pos, **named):
... vượt qua
...
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
đúng
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
đúng
>>> getcallargs(f)
Traceback (cuộc gọi gần đây nhất):
...
TypeError: f() thiếu 1 đối số vị trí bắt buộc: 'a'

Added in version 3.2.

Sắp loại bỏ từ phiên bản 3.5: Thay vào đó hãy sử dụng Signature.bind() và Signature.bind_partial().

inspect.getclosurevars(func)

Nhận ánh xạ các tham chiếu tên bên ngoài trong hàm hoặc phương thức func của Python tới các giá trị hiện tại của chúng. Một named tuple ClosureVars(nonlocals, globals, builtins, unbound) được trả về. nonlocals ánh xạ các tên được tham chiếu tới các biến đóng từ vựng, globals tới các mô-đun toàn cầu của hàm và builtins tới các nội dung hiển thị từ thân hàm. unbound là tập hợp các tên được tham chiếu trong hàm hoàn toàn không thể giải quyết được dựa trên các nội dung và nội dung toàn cục của mô-đun hiện tại.

TypeError được nâng lên nếu func không phải là hàm hoặc phương thức Python.

Added in version 3.3.

inspect.unwrap(func, *, stop=None)

Lấy đối tượng được bao bọc bởi func. Nó tuân theo chuỗi thuộc tính __wrapped__ trả về đối tượng cuối cùng trong chuỗi.

stop là một lệnh gọi lại tùy chọn chấp nhận một đối tượng trong chuỗi trình bao bọc làm đối số duy nhất của nó cho phép quá trình hủy ghép nối kết thúc sớm nếu lệnh gọi lại trả về giá trị thực. Nếu lệnh gọi lại không bao giờ trả về giá trị thực thì đối tượng cuối cùng trong chuỗi sẽ được trả về như bình thường. Ví dụ: signature() sử dụng điều này để dừng việc hủy ghép nối nếu bất kỳ đối tượng nào trong chuỗi có thuộc tính __signature__ được xác định.

ValueError được nâng lên nếu gặp phải một chu kỳ.

Added in version 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)

Tính toán các chú thích cho một đối tượng.

Đây là bí danh của annotationlib.get_annotations(); xem tài liệu về chức năng đó để biết thêm thông tin.

Cảnh báo

Hàm này có thể thực thi mã tùy ý có trong chú thích. Xem Ý nghĩa bảo mật của các chú thích nội tâm để biết thêm thông tin.

Added in version 3.10.

Thay đổi trong phiên bản 3.14: Chức năng này hiện là bí danh cho annotationlib.get_annotations(). Gọi nó là inspect.get_annotations sẽ tiếp tục hoạt động.

Ngăn xếp thông dịch viên

Một số hàm sau trả về đối tượng FrameInfo. Để tương thích ngược, các đối tượng này cho phép các hoạt động giống như bộ dữ liệu trên tất cả các thuộc tính ngoại trừ positions. Hành vi này được coi là không được dùng nữa và có thể bị xóa trong tương lai.

class inspect.FrameInfo

frame

frame object mà bản ghi tương ứng.

filename

Tên tệp được liên kết với mã đang được thực thi bởi khung mà bản ghi này tương ứng.

lineno

Số dòng của dòng hiện tại được liên kết với mã đang được thực thi bởi khung mà bản ghi này tương ứng.

function

Tên hàm đang được thực thi bởi khung mà bản ghi này tương ứng.

code_context

Danh sách các dòng ngữ cảnh từ mã nguồn đang được thực thi bởi khung mà bản ghi này tương ứng.

index

Chỉ mục của dòng hiện tại đang được thực thi trong danh sách code_context.

positions

Một đối tượng dis.Positions chứa số dòng bắt đầu, số dòng cuối, độ lệch cột bắt đầu và độ lệch cột cuối được liên kết với lệnh đang được thực thi bởi khung mà bản ghi này tương ứng.

Thay đổi trong phiên bản 3.5: Trả về named tuple thay vì tuple.

Thay đổi trong phiên bản 3.11: FrameInfo hiện là một phiên bản lớp (tương thích ngược với named tuple trước đó).

class inspect.Traceback

filename

Tên tệp được liên kết với mã đang được thực thi bởi khung mà truy nguyên này tương ứng.

lineno

Số dòng của dòng hiện tại được liên kết với mã đang được thực thi bởi khung mà truy nguyên này tương ứng.

function

Tên hàm đang được thực thi bởi khung mà truy nguyên này tương ứng.

code_context

Danh sách các dòng ngữ cảnh từ mã nguồn đang được thực thi bởi khung mà lần truy nguyên này tương ứng.

index

Chỉ mục của dòng hiện tại đang được thực thi trong danh sách code_context.

positions

Một đối tượng dis.Positions chứa số dòng bắt đầu, số dòng cuối, độ lệch cột bắt đầu và độ lệch cột cuối được liên kết với lệnh đang được thực thi bởi khung mà dấu vết này tương ứng.

Thay đổi trong phiên bản 3.11: Traceback hiện là một phiên bản lớp (tương thích ngược với named tuple trước đó).

Ghi chú

Việc giữ các tham chiếu đến các đối tượng khung, như được tìm thấy trong phần tử đầu tiên của bản ghi khung mà các hàm này trả về, có thể khiến chương trình của bạn tạo các chu trình tham chiếu. Khi một chu trình tham chiếu đã được tạo, tuổi thọ của tất cả các đối tượng có thể được truy cập từ các đối tượng tạo thành chu trình có thể dài hơn nhiều ngay cả khi bật trình phát hiện chu trình tùy chọn của Python. Nếu các chu trình như vậy phải được tạo, điều quan trọng là phải đảm bảo chúng bị phá vỡ một cách rõ ràng để tránh việc phá hủy các đối tượng bị trì hoãn và tăng mức tiêu thụ bộ nhớ xảy ra.

Mặc dù trình phát hiện chu trình sẽ phát hiện được những điều này, nhưng việc phá hủy các khung (và các biến cục bộ) có thể được xác định bằng cách loại bỏ chu trình trong mệnh đề finally. Điều này cũng quan trọng nếu trình phát hiện chu trình bị tắt khi Python được biên dịch hoặc sử dụng gc.disable(). Ví dụ:

def hand_stackframe_without_leak():
    frame = kiểm tra.currentframe()
    thử:
        # do cái gì đó với cái khung
    cuối cùng:
        xóa khung

Nếu bạn muốn giữ khung xung quanh (ví dụ để in truy nguyên sau), bạn cũng có thể ngắt chu trình tham chiếu bằng cách sử dụng phương pháp frame.clear().

Đối số context tùy chọn được hỗ trợ bởi hầu hết các hàm này chỉ định số dòng ngữ cảnh cần trả về, được căn giữa xung quanh dòng hiện tại.

inspect.getframeinfo(frame, context=1)

Nhận thông tin về một khung hoặc đối tượng truy nguyên. Một đối tượng Traceback được trả về.

Thay đổi trong phiên bản 3.11: Một đối tượng Traceback được trả về thay vì một bộ dữ liệu có tên.

inspect.getouterframes(frame, context=1)

Lấy danh sách các đối tượng FrameInfo cho một khung và tất cả các khung bên ngoài. Các khung này đại diện cho các lệnh gọi dẫn đến việc tạo frame. Mục đầu tiên trong danh sách trả về đại diện cho frame; mục cuối cùng thể hiện lệnh gọi ngoài cùng trên ngăn xếp của frame.

Thay đổi trong phiên bản 3.5: Một danh sách named tuples FrameInfo(frame, filename, lineno, function, code_context, index) được trả về.

Thay đổi trong phiên bản 3.11: Một danh sách các đối tượng FrameInfo được trả về.

inspect.getinnerframes(traceback, context=1)

Nhận danh sách các đối tượng FrameInfo cho khung của traceback và tất cả các khung bên trong. Các khung này thể hiện các cuộc gọi được thực hiện do frame. Mục đầu tiên trong danh sách đại diện cho traceback; mục cuối cùng thể hiện nơi ngoại lệ được đưa ra.

Thay đổi trong phiên bản 3.5: Một danh sách named tuples FrameInfo(frame, filename, lineno, function, code_context, index) được trả về.

Thay đổi trong phiên bản 3.11: Một danh sách các đối tượng FrameInfo được trả về.

inspect.currentframe()

Trả về đối tượng khung cho khung ngăn xếp của người gọi.

Hàm này dựa vào hỗ trợ khung ngăn xếp Python trong trình thông dịch, điều này không đảm bảo tồn tại trong tất cả các triển khai Python. Nếu chạy trong một triển khai không hỗ trợ khung ngăn xếp Python, hàm này sẽ trả về None.

inspect.stack(context=1)

Trả về danh sách các đối tượng FrameInfo cho ngăn xếp của người gọi. Mục đầu tiên trong danh sách trả về đại diện cho người gọi; mục cuối cùng đại diện cho lệnh gọi ngoài cùng trên ngăn xếp.

Thay đổi trong phiên bản 3.5: Một danh sách named tuples FrameInfo(frame, filename, lineno, function, code_context, index) được trả về.

Thay đổi trong phiên bản 3.11: Một danh sách các đối tượng FrameInfo được trả về.

inspect.trace(context=1)

Trả về danh sách các đối tượng FrameInfo cho ngăn xếp giữa khung hiện tại và khung trong đó một ngoại lệ hiện đang được xử lý đã được đưa ra. Mục nhập đầu tiên trong danh sách đại diện cho người gọi; mục cuối cùng thể hiện nơi ngoại lệ được đưa ra.

Thay đổi trong phiên bản 3.5: Một danh sách named tuples FrameInfo(frame, filename, lineno, function, code_context, index) được trả về.

Thay đổi trong phiên bản 3.11: Một danh sách các đối tượng FrameInfo được trả về.

Tìm nạp thuộc tính tĩnh

Cả getattr() và hasattr() đều có thể kích hoạt thực thi mã khi tìm nạp hoặc kiểm tra sự tồn tại của các thuộc tính. Các bộ mô tả, giống như các thuộc tính, sẽ được gọi và __getattr__() và __getattribute__() có thể được gọi.

Đối với những trường hợp bạn muốn xem xét nội tâm thụ động, chẳng hạn như các công cụ tài liệu, điều này có thể bất tiện. getattr_static() có chữ ký giống như getattr() nhưng tránh thực thi mã khi tìm nạp thuộc tính.

inspect.getattr_static(obj, attr, default=None)

Truy xuất các thuộc tính mà không kích hoạt tra cứu động thông qua giao thức mô tả, __getattr__() hoặc __getattribute__().

Lưu ý: hàm này có thể không truy xuất được tất cả các thuộc tính mà getattr có thể tìm nạp (như các thuộc tính được tạo động) và có thể tìm thấy các thuộc tính mà getattr không thể tìm nạp (như bộ mô tả gây ra AttributionError). Nó cũng có thể trả về các đối tượng mô tả thay vì các thành viên thể hiện.

Nếu phiên bản __dict__ bị một thành viên khác che khuất (ví dụ như một thuộc tính) thì hàm này sẽ không thể tìm thấy các thành viên phiên bản.

Added in version 3.2.

getattr_static() không giải quyết các bộ mô tả, ví dụ như bộ mô tả vị trí hoặc bộ mô tả getset trên các đối tượng được triển khai trong C. Đối tượng bộ mô tả được trả về thay vì thuộc tính cơ bản.

Bạn có thể xử lý chúng bằng mã như sau. Lưu ý rằng đối với các bộ mô tả getset tùy ý, việc gọi những bộ mô tả này có thể kích hoạt việc thực thi mã:

Mã # example để giải quyết các loại mô tả dựng sẵn
lớp _foo:
    __slots__ = ['foo']

slot_descriptor = loại(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
Wrapper_descriptor = loại(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, bao bọc_descriptor)

kết quả = getattr_static(some_object, 'foo')
nếu loại (kết quả) trong descriptor_types:
    thử:
        kết quả = kết quả.__get__()
    ngoại trừ AttributionError:
        # descriptors có thể nâng AttributionError lên
        # indicate không có giá trị cơ bản
        # in trường hợp nào chính bộ mô tả sẽ
        # have để làm
        vượt qua

Trạng thái hiện tại của trình tạo, coroutine và trình tạo không đồng bộ

Khi triển khai bộ lập lịch coroutine và cho các mục đích sử dụng trình tạo nâng cao khác, việc xác định xem trình tạo hiện đang thực thi, đang chờ để bắt đầu, tiếp tục hoặc thực thi hay đã chấm dứt là rất hữu ích. getgeneratorstate() cho phép xác định trạng thái hiện tại của máy phát một cách dễ dàng.

inspect.getgeneratorstate(generator)

Nhận trạng thái hiện tại của trình tạo-iterator.

Các trạng thái có thể là:

• GEN_CREATED: Đang chờ bắt đầu thực thi.

• GEN_RUNNING: Hiện đang được trình thông dịch thực thi.

• GEN_SUSPENDED: Hiện đang bị tạm dừng ở biểu thức lợi nhuận.

• GEN_CLOSED: Quá trình thực thi đã hoàn tất.

Added in version 3.2.

inspect.getcoroutinestate(coroutine)

Nhận trạng thái hiện tại của một đối tượng coroutine. Hàm này dự định sẽ được sử dụng với các đối tượng coroutine được tạo bởi các hàm async def nhưng sẽ chấp nhận mọi đối tượng giống coroutine có thuộc tính cr_running và cr_frame.

Các trạng thái có thể là:

• CORO_CREATED: Đang chờ bắt đầu thực thi.

• CORO_RUNNING: Hiện đang được trình thông dịch thực thi.

• CORO_SUSPENDED: Hiện đang bị tạm dừng ở biểu thức đang chờ.

• CORO_CLOSED: Quá trình thực thi đã hoàn tất.

Added in version 3.5.

inspect.getasyncgenstate(agen)

Nhận trạng thái hiện tại của đối tượng trình tạo không đồng bộ. Hàm này dự định sẽ được sử dụng với các đối tượng trình vòng lặp không đồng bộ được tạo bởi các hàm async def sử dụng câu lệnh yield nhưng sẽ chấp nhận bất kỳ đối tượng giống trình tạo không đồng bộ nào có thuộc tính ag_running và ag_frame.

Các trạng thái có thể là:

• AGEN_CREATED: Đang chờ bắt đầu thực thi.

• AGEN_RUNNING: Hiện đang được trình thông dịch thực thi.

• AGEN_SUSPENDED: Hiện đang bị tạm dừng ở biểu thức lợi nhuận.

• AGEN_CLOSED: Quá trình thực thi đã hoàn tất.

Added in version 3.12.

Trạng thái bên trong hiện tại của máy phát điện cũng có thể được truy vấn. Điều này chủ yếu hữu ích cho mục đích thử nghiệm, để đảm bảo rằng trạng thái nội bộ được cập nhật như mong đợi:

inspect.getgeneratorlocals(generator)

Nhận ánh xạ các biến cục bộ trực tiếp trong generator tới giá trị hiện tại của chúng. Một từ điển được trả về sẽ ánh xạ từ tên biến tới giá trị. Điều này tương đương với việc gọi locals() trong phần thân của trình tạo và tất cả các cảnh báo tương tự đều được áp dụng.

Nếu generator là generator hiện không có khung được liên kết thì sẽ trả về một từ điển trống. TypeError được nâng lên nếu generator không phải là đối tượng trình tạo Python.

Hàm này dựa vào trình tạo hiển thị khung ngăn xếp Python để xem xét nội tâm, điều này không được đảm bảo đúng trong mọi trường hợp triển khai Python. Trong những trường hợp như vậy, hàm này sẽ luôn trả về một từ điển trống.

Added in version 3.3.

inspect.getcoroutinelocals(coroutine)

Hàm này tương tự như getgeneratorlocals(), nhưng hoạt động với các đối tượng coroutine được tạo bởi các hàm async def.

Added in version 3.5.

inspect.getasyncgenlocals(agen)

Hàm này tương tự như getgeneratorlocals(), nhưng hoạt động với các đối tượng trình tạo không đồng bộ được tạo bởi các hàm async def sử dụng câu lệnh yield.

Added in version 3.12.

Cờ bit đối tượng mã

Các đối tượng mã Python có thuộc tính co_flags, là một bitmap của các cờ sau:

inspect.CO_OPTIMIZED

Đối tượng mã được tối ưu hóa, sử dụng tính năng cục bộ nhanh.

inspect.CO_NEWLOCALS

Nếu được đặt, một lệnh mới sẽ được tạo cho f_locals của khung khi đối tượng mã được thực thi.

inspect.CO_VARARGS

Đối tượng mã có tham số vị trí thay đổi (giống *args).

inspect.CO_VARKEYWORDS

Đối tượng mã có tham số từ khóa thay đổi (giống như **kwargs).

inspect.CO_NESTED

Cờ được đặt khi đối tượng mã là hàm lồng nhau.

inspect.CO_GENERATOR

Cờ được đặt khi đối tượng mã là hàm tạo, tức là đối tượng trình tạo được trả về khi đối tượng mã được thực thi.

inspect.CO_COROUTINE

Cờ được đặt khi đối tượng mã là hàm coroutine. Khi đối tượng mã được thực thi, nó sẽ trả về một đối tượng coroutine. Xem PEP 492 để biết thêm chi tiết.

Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE

Cờ được sử dụng để chuyển đổi trình tạo thành coroutine dựa trên trình tạo. Các đối tượng trình tạo có cờ này có thể được sử dụng trong biểu thức await và có thể sử dụng các đối tượng coroutine yield from. Xem PEP 492 để biết thêm chi tiết.

Added in version 3.5.

inspect.CO_ASYNC_GENERATOR

Cờ được đặt khi đối tượng mã là hàm tạo không đồng bộ. Khi đối tượng mã được thực thi, nó trả về một đối tượng trình tạo không đồng bộ. Xem PEP 525 để biết thêm chi tiết.

Added in version 3.6.

inspect.CO_HAS_DOCSTRING

Cờ được đặt khi có chuỗi tài liệu cho đối tượng mã trong mã nguồn. Nếu được đặt, nó sẽ là mục đầu tiên trong co_consts.

Added in version 3.14.

inspect.CO_METHOD

Cờ được đặt khi đối tượng mã là một hàm được xác định trong phạm vi lớp.

Added in version 3.14.

Ghi chú

Các cờ dành riêng cho CPython và có thể không được xác định trong các triển khai Python khác. Hơn nữa, các cờ là một chi tiết triển khai và có thể bị xóa hoặc không được dùng nữa trong các bản phát hành Python trong tương lai. Bạn nên sử dụng các API công khai từ mô-đun inspect cho bất kỳ nhu cầu xem xét nội tâm nào.

Cờ đệm

class inspect.BufferFlags

Đây là enum.IntFlag đại diện cho các cờ có thể được truyền tới phương thức __buffer__() của các đối tượng triển khai buffer protocol.

Ý nghĩa của các lá cờ được giải thích tại Các loại yêu cầu bộ đệm.

SIMPLE

WRITABLE

FORMAT

ND

STRIDES

C_CONTIGUOUS

F_CONTIGUOUS

ANY_CONTIGUOUS

INDIRECT

CONTIG

CONTIG_RO

STRIDED

STRIDED_RO

RECORDS

RECORDS_RO

FULL

FULL_RO

READ

WRITE

Added in version 3.12.

Giao diện dòng lệnh

Mô-đun inspect cũng cung cấp khả năng xem xét nội tâm cơ bản từ dòng lệnh.

Theo mặc định, chấp nhận tên của mô-đun và in nguồn của mô-đun đó. Thay vào đó, một lớp hoặc hàm trong mô-đun có thể được in bằng cách thêm dấu hai chấm và tên đủ điều kiện của đối tượng đích.

--details

In thông tin về đối tượng được chỉ định thay vì mã nguồn