Объясните точки входа Python?

181

Я прочитал документацию о точках входа яиц в Pylons и на страницах Peak, и до сих пор не совсем понимаю. Может ли кто-нибудь объяснить мне их?

Брэд Райт
источник

Ответы:

168

«Точка входа» - это, как правило, функция (или другой вызываемый функциональный объект), который может захотеть использовать разработчик или пользователь вашего пакета Python, хотя в качестве точки входа может быть также предоставлен не вызываемый объект (как правильно). указал в комментариях!).

Наиболее популярный тип точки входа - точка входа console_scripts , которая указывает на функцию, которую вы хотите сделать доступной в качестве инструмента командной строки для любого, кто устанавливает ваш пакет. Это идет в ваш setup.py как:

entry_points={
    'console_scripts': [
        'cursive = cursive.tools.cmd:cursive_command',
    ],
},

У меня есть только что развернутый пакет, который называется cursive.tools, и я хотел, чтобы он сделал доступной команду cursive, которую кто-то может запустить из командной строки, например:

$ cursive --help
usage: cursive ...

Способ сделать это - определить функцию, например, функцию cursive_command в cursive / tools / cmd.py, которая выглядит следующим образом:

def cursive_command():
    args = sys.argv[1:]
    if len(args) < 1:
        print "usage: ..."

и так далее; следует предположить, что он был вызван из командной строки, проанализировать аргументы, предоставленные пользователем, и ... ну, делать то, для чего предназначена команда.

Установите пакет Docutils для отличного примера использования точки входа: он установит примерно полдюжины полезных команд для преобразования документации Python в другие форматы.

Брэндон Роудс
источник
3
текущие документы setup.pyне содержат entry_pointsвообще.
Мэтт Уилки
2
Это отличный ответ, поскольку он демонстрирует мощь нескольких проектов, совместно использующих одно имя группы entry_point, которое называется "console_scripts". Сравните этот ответ с более общим ответом Петри. Вы увидите, что setuptools должен использовать этот механизм pkg_resources, чтобы получить console_scripts, а затем создать оболочку оболочки вокруг них. Воодушевление? Используйте это. Они хороши не только для console_scripts.
Бруно Броноски
188

EntryPoints обеспечивают постоянную регистрацию имен объектов на основе файловой системы и механизм прямого импорта объектов на основе имен (реализуется пакетом setuptools ).

Они связывают имена объектов Python с идентификаторами свободной формы. Таким образом, любой другой код, использующий ту же установку Python и знающий идентификатор, может получить доступ к объекту со связанным именем, независимо от того, где объект определен. Эти связанные имена могут быть любыми именами существующих в модуле Python ; например, имя класса, функции или переменной. Механизм точки входа не заботится о том, к чему относится имя, пока оно импортируется.

В качестве примера, давайте использовать (имя) функцию и воображаемый модуль Python с полностью определенным именем «myns.mypkg.mymodule»:

def the_function():
   "function whose name is 'the_function', in 'mymodule' module"
   print "hello from the_function"

Точки входа регистрируются через объявление точек входа в setup.py. Чтобы зарегистрировать функцию в точке входа под названием my_ep_func:

    entry_points = {
        'my_ep_group_id': [
            'my_ep_func = myns.mypkg.mymodule:the_function'
        ]
    },

Как показывает пример, точки входа сгруппированы; есть соответствующий API для поиска всех точек входа, принадлежащих группе (пример ниже).

После установки пакета (т. Е. Запуска «python setup.py install») вышеуказанное объявление анализируется программой setuptools. Затем он записывает разобранную информацию в специальный файл. После этого API pkg_resources (часть setuptools) можно использовать для поиска точки входа и доступа к объекту (ам) с соответствующими именами:

import pkg_resources

named_objects = {}
for ep in pkg_resources.iter_entry_points(group='my_ep_group_id'):
   named_objects.update({ep.name: ep.load()})

Здесь setuptools считывает информацию о точке входа, которая была записана в специальных файлах. Она нашла точку входа, импортировала модуль (myns.mypkg.mymodule) и извлекла определенную там функцию после вызова pkg_resources.load ().

Предполагая, что не было других регистраций точек входа для того же идентификатора группы, вызов функции _ был бы простым:

>>> named_objects['my_ep_func']()
hello from the_function

Таким образом, хотя поначалу это немного сложно понять, механизм точки входа на самом деле довольно прост в использовании. Он предоставляет полезный инструмент для разработки подключаемого программного обеспечения Python.

Петри
источник
4
Где имя 'my_ep_func' используется во всем этом процессе? Кажется, он не используется ни для чего итератором pkg_resources.
Камил Кисиэль
2
@KamilKisiel: в примере, используемом здесь для иллюстрации, имя точки входа действительно ни для чего не используется и не должно быть; независимо от того, используется ли имя точки входа для чего-либо, зависит от приложения. Название можно просто как имя атрибут экземпляра точки входа.
Петри
3
Я думаю, что отбрасывание ep.name и создание named_objects в виде списка вместо словаря приводило в замешательство, поэтому я отредактировал ответ. Это то, что ответ показывает, как получить имя и ожидать, что оно будет 'the_function' или 'my_ep_func'. В противном случае читатель должен был найти дополнительную документацию в другом месте. Это ОТЛИЧНЫЙ ответ и самое короткое и ясное объяснение точки входа, которое я когда-либо видел!
Бруно Броноски
3
Я создал проект на GitHub, который демонстрирует эту концепцию. github.com/RichardBronosky/entrypoint_demo
Бруно Броноски
1
Это очень четкое объяснение точек входа, что вам для подробного объяснения. EntryPointsСсылка несвежая, хотя объяснение очень ясно.
Рахул Наир
18

С абстрактной точки зрения точки входа используются для создания общесистемного реестра вызовов Python, которые реализуют определенные интерфейсы. В pkg_resources есть API для просмотра того, какие точки входа объявляются данным пакетом, а также API для определения того, какие пакеты рекламируют определенную точку входа.

Точки входа полезны для того, чтобы один пакет мог использовать плагины из другого пакета. Например, в проекте Paste Яна Бикинга широко используются точки входа. В этом случае вы можете написать пакет, который рекламирует свою фабрику приложений WSGI, используя точку входа paste.app_factory.

Другое использование точек входа - перечисление всех пакетов в системе, которые предоставляют некоторые функциональные возможности плагинов. TurboGears веб - фреймворк использует python.templating.enginesточку входа для поиска шаблонных библиотек, которые установлены и доступны.

Рик Коупленд
источник