Rukovodstvo
статьи и идеи для разработчиков программного обеспечения и веб-разработчиков.
Справочная система Python
При написании и запуске программ Python вы можете застрять, и вам понадобится помощь. Возможно, вам потребуется знать значение определенных модулей, классов, функций, ключевых слов и т. Д. Хорошей новостью является то, что Python поставляется со встроенной справочной системой. Это означает, что вам не нужно искать помощи за пределами самого Python. В этой статье вы узнаете, как пользоваться встроенной справочной системой Python. Функция Python help () Эта функция помогает нам получить документацию по определенному классу, функции, переменной и т. Д.
Время чтения: 10 мин.
При написании и запуске программ Python вы можете застрять, и вам понадобится помощь. Возможно, вам потребуется знать значение определенных модулей, классов, функций, ключевых слов и т. Д. Хорошей новостью является то, что Python поставляется со встроенной справочной системой. Это означает, что вам не нужно искать помощи за пределами самого Python.
В этой статье вы узнаете, как пользоваться встроенной справочной системой Python.
Функция Python help ()
Эта функция помогает нам получить документацию по определенному классу, функции, переменной, модулю и т. Д. Функцию следует использовать в консоли Python для получения сведений о различных объектах Python.
Передача объекта в функцию help ()
Функция Python help() имеет следующий синтаксис:
В приведенном выше синтаксисе object — это имя объекта, по которому вам нужно получить справку.
Например, чтобы узнать больше о print Python, введите следующую команду в консоли Python:
Выход:
Чтобы получить справку по dict , введите в консоли Python следующее:
Выход:
Вы также можете передать фактический объект списка в функцию help()
Выход:
Мы видим, что когда вы передаете объект в help() , печатается его документация или страница справки. В следующем разделе вы узнаете о передаче строковых аргументов функции help() .
Передача строкового аргумента в help ()
Если вы передадите строку в качестве аргумента, строка будет рассматриваться как имя функции, модуля, ключевого слова, метода, класса или раздела документации, и будет напечатана соответствующая страница справки. Чтобы пометить его как строковый аргумент, заключите его в одинарные или двойные кавычки.
Выход:
Хотя мы передали print как строковый аргумент, мы все же получили документацию для функции print Вот еще один пример:
Выход:
Здесь мы передали def в качестве строкового аргумента функции help() и она вернула документацию для определения функций.
Если подходящего объекта, метода, функции, класса или модуля не найдено, вы получите уведомление. Например:
Выход:
Нам сообщают, что для нашей строки не найдено документации.
Иногда нам может потребоваться помощь по определенной функции, которая определена в определенной библиотеке Python. Для этого необходимо сначала импортировать библиотеку. Хороший пример — когда нам нужно получить документацию для log определенной в math библиотеке Python. В этом случае нам сначала нужно импортировать math библиотеку, а затем мы вызываем help() как показано ниже:
Выход:
Использование help () без аргументов
help() можно использовать без аргумента. Если вы запустите функцию без аргумента, интерактивная справочная утилита Python будет запущена на консоли интерпретатора. Вам просто нужно ввести следующую команду в консоли Python:
Это вернет утилиту справки Python, в которой вы можете ввести имя объекта, по которому вам нужна помощь. Например:
Выход:
Чтобы вернуться к предыдущему запросу, просто нажмите «q».
Вот еще один пример:
Выход:
Чтобы выйти из утилиты справки и вернуться в консоль Python, просто введите «quit» и нажмите клавишу ввода:
Выход:
В следующем разделе мы обсудим, как определить help() для наших настраиваемых объектов.
Определение справочной документации для пользовательских функций и классов
Мы можем определить вывод функции help() для наших пользовательских функций и классов, определив строку документации (строку документа). В Python первая строка комментария, добавленная в тело метода, рассматривается как его строка документации. Комментарий должен быть заключен в три двойные кавычки. Например:
В приведенном выше примере мы определили функцию с именем product . Эта функция умножает два целых числа a и b переданные ей в качестве аргументов / параметров. См. Комментарий, заключенный в три двойные кавычки:
Это будет рассматриваться как строка документации для функционального product .
Теперь создайте новый файл и дайте ему имя myfile.py. Добавьте в файл следующий код:
В приведенном выше примере строка документации была определена для функции, класса и методов.
Теперь нам нужно продемонстрировать, как мы можем получить указанную выше строку документации в качестве справочной документации на нашей консоли Python.
Во-первых, нам нужно выполнить сценарий на консоли, чтобы загрузить определение функции и класса в среду Python. Для этого мы можем использовать метод Python exec() . Выполните следующую команду в консоли Python:
В качестве альтернативы, если вы написали код в Python IDLE, вам просто нужно запустить его.
Теперь мы можем подтвердить, были ли обнаружены модули функций и классов, запустив команду globals() в консоли Python:
В моем случае я получаю следующий результат:
Как показано в выходных данных выше, и Student и product находятся в словаре глобальной области видимости. Теперь мы можем использовать help() чтобы получить справку по классу Student и функции product Просто запустите следующую команду в консоли Python:
Выход:
Давайте проверим справочную документацию по функциям product
Выход:
Теперь позвольте нам получить доступ к справочной документации для класса Student
Выход:
На выходе мы видим документацию, которую мы написали для класса Student
Заключение
Python поставляется со встроенной системой, из которой мы можем получить помощь в отношении модулей, классов, функций и ключевых слов. Доступ к этой справочной утилите можно получить с помощью функции Python help() в REPL. Когда мы вызываем эту функцию и передаем ей объект, она возвращает страницу справки или документацию для объекта. Когда мы запускаем функцию без аргумента, открывается вспомогательная утилита, где мы можем получить справку об объектах в интерактивном режиме. Наконец, чтобы получить помощь в отношении наших пользовательских классов и функций, мы можем определить строки документации.
How to list all functions in a module?
I have a Python module installed on my system and I’d like to be able to see what functions/classes/methods are available in it.
I want to call the help function on each one. In Ruby I can do something like ClassName.methods to get a list of all the methods available on that class. Is there something similar in Python?
e.g. something like:
20 Answers 20
You can use dir(module) to see all available methods/attributes. Also check out PyDocs.
Use the inspect module:
Also see the pydoc module, the help() function in the interactive interpreter and the pydoc command-line tool which generates the documentation you are after. You can just give them the class you wish to see the documentation of. They can also generate, for instance, HTML output and write it to disk.
Once you’ve import ed the module, you can just do:
. To get the docs on all the functions at once, interactively. Or you can use:
. To simply list the names of all the functions and variables defined in the module.
Use inspect.getmembers to get all the variables/classes/functions etc. in a module, and pass in inspect.isfunction as the predicate to get just the functions:
getmembers returns a list of tuples (object_name, object) sorted alphabetically by name.
You can replace isfunction with any of the other isXXX functions in the inspect module.
For completeness’ sake, I’d like to point out that sometimes you may want to parse code instead of importing it. An import will execute top-level expressions, and that could be a problem.
For example, I’m letting users select entry point functions for packages being made with zipapp. Using import and inspect risks running astray code, leading to crashes, help messages being printed out, GUI dialogs popping up and so on.
Instead I use the ast module to list all the top-level functions:
Putting this code in list.py and using itself as input, I get:
Of course, navigating an AST can be tricky sometimes, even for a relatively simple language like Python, because the AST is quite low-level. But if you have a simple and clear use case, it’s both doable and safe.
Though, a downside is that you can’t detect functions that are generated at runtime, like foo = lambda x,y: x*y .
For code that you do not wish to evaluate, I recommend an AST-based approach (like csl’s answer), e.g.:
For everything else, the inspect module is correct:
This gives a list of 2-tuples in the form [(<name:str>, <value:function>), . ] .
The simple answer above is hinted at in various responses and comments, but not called out explicitly.
This will do the trick:
However, if you find it annoying to read the returned list, just use the following loop to get one name per line.
dir(module) is the standard way when using a script or the standard interpreter, as mentioned in most answers.
However with an interactive python shell like IPython you can use tab-completion to get an overview of all objects defined in the module. This is much more convenient, than using a script and print to see what is defined in the module.
- module.<tab> will show you all objects defined in the module (functions, classes and so on)
- module.ClassX.<tab> will show you the methods and attributes of a class
- module.function_xy? or module.ClassX.method_xy? will show you the docstring of that function / method
- module.function_x?? or module.SomeClass.method_xy?? will show you the source code of the function / method.
For global functions dir() is the command to use (as mentioned in most of these answers), however this lists both public functions and non-public functions together.
For example running:
Returns functions/classes like:
Some of which are not generally meant for general programming use (but by the module itself, except in the case of DunderAliases like __doc__ , __file__ ect). For this reason it may not be useful to list them with the public ones (this is how Python knows what to get when using from module import * ).
__all__ could be used to solve this problem, it returns a list of all the public functions and classes in a module (those that do not start with underscores — _ ). See Can someone explain __all__ in Python? for the use of __all__ .
Here is an example:
All the functions and classes with underscores have been removed, leaving only those that are defined as public and can therefore be used via import * .
Note that __all__ is not always defined. If it is not included then an AttributeError is raised.
inspect-Осмотреть живые объекты
Модуль inspect предоставляет несколько полезных функций, помогающих получить информацию о живых объектах, таких как модули, классы, методы, функции, трассировки, объекты кадра и объекты кода. Например, он может помочь вам изучить содержимое класса, получить исходный код метода, извлечь и отформатировать список аргументов для функции или получить всю информацию, необходимую для отображения подробной трассировки.
Данный модуль предоставляет четыре основных вида услуг:проверка типов,получение исходного кода,проверка классов и функций,а также проверка стека интерпретаторов.
Типы и члены
Функция getmembers() извлекает членов объекта, такого как класс или модуль. Функции, имена которых начинаются с «is», в основном предоставляются в качестве удобного выбора для второго аргумента getmembers() . Они также помогают определить, когда можно ожидать появления следующих специальных атрибутов:
имя файла (отсутствует для встроенных модулей)
имя,с которым был определён этот класс
название модуля,в котором был определен данный класс
название,с помощью которого был определён этот метод
функциональный объект,содержащий реализацию метода
экземпляр, к которому привязан этот метод, или None
название модуля,в котором был определён этот метод
имя,с которым эта функция была определена
объект кода, содержащий скомпилированный байт-код функции
кортеж любых значений по умолчанию для параметров позиционирования или ключевого слова
отображение любых значений по умолчанию для параметров только для клавиатуры
глобальное пространство имён,в котором была определена эта функция
отображение имен параметров в аннотации; Клавиша «return» зарезервирована для аннотаций возврата.
название модуля,в котором эта функция была определена
объект рамы на этом уровне
индекс последней попытки обучения в байткоде
номер текущей строки в исходном коде Python
следующий внутренний объект трассировки (вызываемый этим уровнем)
следующий объект внешнего кадра (вызывающий этот кадр)
встроенное пространство имён,видимое этим фреймом
объект кода,выполняемый в данном кадре
глобальное пространство имён,которое видит эта рамка
индекс последней попытки обучения в байткоде
номер текущей строки в исходном коде Python
локальное пространство имён,видимое этой рамкой
функция трассировки для этого кадра, или None
количество аргументов (не включая только аргументы по ключевому слову,*или **аргументы)
строка скомпилированного байткода
кортеж имен переменных ячеек (с указанием диапазонов)
кортеж постоянных,используемых в байткоде
имя файла,в котором был создан данный объект кода
номер первой строки в исходном коде Python
растровое изображение флагов CO_* , подробнее здесь
кодированное отображение номеров строк на байткодовые индексы
кортеж имен свободных переменных (на которые ссылаются через закрытие функции)
количество аргументов только позиционных
количество аргументов только по ключевым словам (не включая **аргумент)
имя,с которым был определён данный объект кода
полное имя,под которым был определен данный объект кода
кортеж имен,отличных от аргументов и локалей функции
число локальных переменных
необходимое пространство стека виртуальной машины
кортеж имен аргументов и локальных переменных
объект повторяется yield from или None
ожидаемый объект или None
первоначальное название этой функции или метода
экземпляр, к которому привязан метод, или None
Изменено в версии 3.5: добавлены __qualname__ и gi_yieldfrom в генераторы.
__name__ атрибут генераторов теперь устанавливается от имени функции, вместо имени кода, и теперь он может быть изменен.
Изменено в версии 3.7: Добавлен атрибут cr_origin в сопрограммы.
Изменено в версии 3.10: Добавлен атрибут __builtins__ к функциям.
Возвращает все члены объекта в списке пар (name, value) отсортированных по имени. Если указан необязательный аргумент предиката , который будет вызываться с объектом- value каждого элемента, включаются только элементы, для которых предикат возвращает истинное значение.
getmembers() будет возвращать только атрибуты класса, определенные в метаклассе, когда аргумент является классом, и эти атрибуты были перечислены в пользовательском __dir__() метакласса .
Возвращает все члены объекта в списке пар (name, value) отсортированных по имени, без запуска динамического поиска через протокол дескриптора, __getattr__ или __getattribute__. При необходимости возвращайте только те члены, которые удовлетворяют заданному предикату.
getmembers_static() может быть не в состоянии получить все члены, которые может получить getmembers (например, динамически созданные атрибуты), и может найти элементы, которые не может получить getmembers (например, дескрипторы, вызывающие AttributeError). В некоторых случаях он также может возвращать объекты дескриптора вместо членов экземпляра.
Новинка в версии 3.11.
Вернуть имя модуля, названного по пути к файлу , без включения имен вложенных пакетов. Расширение файла проверяется по всем записям в importlib.machinery.all_suffixes() . Если он совпадает, возвращается окончательный компонент пути с удаленным расширением. В противном случае возвращается None .
Обратите внимание , что эта функция только возвращает значимое имя для реальных модулей Python — пути , которые потенциально относятся к пакетам Python по- прежнему не будет возвращать None .
Изменено в версии 3.3: Функция основана непосредственно на importlib .
Верните True , если объект является модулем.
Верните True , если объект является классом, встроенным или созданным в коде Python.
Верните True , если объект является связанным методом, написанным на Python.
Возвратите True , если объект является функцией Python, которая включает в себя функции, созданные лямбда — выражением.
Верните True , если объект является функцией генератора Python.
Изменено в версии 3.8: Функции, завернутые в functools.partial() теперь возвращают True , если завернутая функция является функцией генератора Python.
Верните True , если объект является генератором.
Верните True , если объект является функцией сопрограммы (функция, определенная с синтаксисом async def
Новинка в версии 3.5.
Изменено в версии 3.8: функции, обернутые в functools.partial() , теперь возвращают True , если обернутая функция является функцией сопрограммы .
Верните True , если объект является сопрограммой , созданной async def функцией определения.
Новинка в версии 3.5.
Верните True , если объект можно использовать в выражении await
Может также использоваться для различения корусеток на основе генераторов от обычных генераторов:
Новинка в версии 3.5.
Верните True , если объект является функцией асинхронного генератора , например:
Новинка в версии 3.6.
Изменено в версии 3.8: функции, обернутые в functools.partial() , теперь возвращают True , если обернутая функция является функцией асинхронного генератора .
Возвратите True , если объект является итератором асинхронного генератора , созданным функцией асинхронного генератора .
Новинка в версии 3.6.
Верните True , если объект является трассировкой.
Верните True , если объект является фреймом.
Верните True , если объект является кодом.
Верните True , если объект является встроенной функцией или связанным встроенным методом.
Возвратите True , если тип объекта является MethodWrapperType .
Новинка в версии 3.11.
Верните True , если объект является определяемой пользователем или встроенной функцией или методом.
Верните True , если объект является абстрактным базовым классом.
Вернуть True , если объект является дескриптором метода, но не если ismethod() , isclass() , isfunction() или isbuiltin() истинны.
Это, например, верно для int.__add__ . Объект, прошедший этот тест, имеет метод __get__() , но не метод __set__() , но помимо этого набор атрибутов различается. Атрибут __name__ обычно имеет смысл, и __doc__ часто бывает.
Методы, реализованные через дескрипторы, которые также проходят один из других тестов, возвращают False из ismethoddescriptor() просто потому, что другие тесты обещают больше — вы можете, например, рассчитывать на наличие атрибута __func__ (и т. д.), когда объект проходит ismethod() .
Верните True , если объект является дескриптором данных.
Дескрипторы данных имеют __set__ или __delete__ . Примерами являются свойства (определенные в Python), getsets и члены. Последние два определены в C, и для этих типов доступны более конкретные тесты, которые являются надежными для всех реализаций Python. Как правило, дескрипторы данных также будут иметь атрибуты __name__ и __doc__ (свойства, getsets и члены имеют оба этих атрибута), но это не гарантируется.
Верните True , если объект является дескриптором getset.
Детали реализации CPython: getsets — это атрибуты, определенные в модулях расширения через структуры PyGetSetDef . Для реализаций Python без таких типов этот метод всегда будет возвращать False .
Верните True , если объект является дескриптором члена.
Детали реализации CPython: дескрипторы членов — это атрибуты, определенные в модулях расширения через структуры PyMemberDef . Для реализаций Python без таких типов этот метод всегда будет возвращать False .
Поиск исходного кода для встроенных функций Python?
Есть ли способ увидеть, как встроенные функции работают в python? Я не имею в виду, как их использовать, но также как они были построены, каков код, отсортированный или перечислимый и т.д.
6 ответов
Поскольку Python является открытым исходным кодом, вы можете прочитать исходный код.
Чтобы узнать, какой файл используется в конкретном модуле или функции, вы обычно можете распечатать атрибут __file__ . В качестве альтернативы вы можете использовать модуль inspect , см. Раздел » Извлечение исходного кода» в документации по inspect .
Для встроенных классов и методов это не так просто, поскольку inspect.getfile и inspect.getsource возвращают ошибку типа, inspect.getsource , что объект встроен. Тем не менее, многие из встроенных типов можно найти в подкаталоге Objects соединительной линии Python. Например, см. Здесь для реализации класса enumerate или здесь для реализации типа list .
Вот ответ поваренной книги, чтобы дополнить ответ @Chris, CPython переместился в GitHub, и репозиторий Mercurial больше не будет обновляться:
-
При необходимости установите Git.
git clone https://github.com/python/cpython.git
Код будет cpython в подкаталоге cpython → cd cpython
iPython оболочка делает это проще: function? предоставит вам документацию. function?? показывает также код. НО это работает только для чистых функций python.
Тогда вы всегда можете download исходный код для (c) Python.
Если вы заинтересованы в реализации pythonic основных функций, посмотрите PyPy.
Мне пришлось немного подражать, чтобы найти источник следующих Built-in Functions поскольку поиск даст тысячи результатов. (Удачи в поиске любого из них, чтобы найти, где это источник)
Во всяком случае, все эти функции определены в bltinmodule.c Функции начинаются с builtin_