Wyjaśnić punkty wejścia w Pythonie?

181

Przeczytałem dokumentację dotyczącą punktów wejścia do jaj w Pylons i na stronach Peak i nadal nie rozumiem. Czy ktoś mógłby mi je wyjaśnić?

Brad Wright
źródło

Odpowiedzi:

168

„Punkt wejścia” to zazwyczaj funkcja (lub inny wywoływalny obiekt podobny do funkcji), z którego deweloper lub użytkownik pakietu Python może chcieć skorzystać, chociaż obiekt niewymagalny może być również dostarczony jako punkt wejścia (równie poprawnie wskazane w komentarzach!).

Najpopularniejszym rodzajem punktu wejścia jest punkt wejścia console_scripts , który wskazuje na funkcję, którą chcesz udostępnić jako narzędzie wiersza polecenia każdemu, kto zainstaluje twój pakiet. Dotyczy to pliku setup.py, takiego jak:

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

Mam właśnie wdrożony pakiet o nazwie „cursive.tools” i chciałem, aby udostępnił polecenie „cursive”, które ktoś mógłby uruchomić z wiersza poleceń, na przykład:

$ cursive --help
usage: cursive ...

Sposobem na to jest zdefiniowanie funkcji, na przykład funkcji „cursive_command” w cursive / tools / cmd.py, która wygląda następująco:

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

i tak dalej; powinien założyć, że został wywołany z wiersza poleceń, przeanalizować argumenty dostarczone przez użytkownika i ... cóż, zrobić wszystko, co polecenie ma wykonać.

Zainstaluj pakiet docutils jako doskonały przykład użycia punktu wejścia: zainstaluje coś w rodzaju kilku użytecznych poleceń do konwersji dokumentacji Pythona na inne formaty.

Brandon Rhodes
źródło
3
obecne dokumenty setup.pynie zawierają entry_pointswcale.
matt wilkie
2
Jest to doskonała odpowiedź, ponieważ pokazuje moc wielu projektów współużytkujących jedną nazwę grupy punktów wejścia, czyli „skrypty konsoli”. Porównaj tę odpowiedź z bardziej ogólną odpowiedzią Petri. Zobaczysz, że setuptools muszą używać tego mechanizmu pkg_resources, aby uzyskać skrypty_ konsolowe, a następnie utworzyć wokół nich opakowanie powłoki. Inspirujący? Użyj tych. Są dobre dla więcej niż tylko skryptów_ konsolowych.
Bruno Bronosky,
188

EntryPoints zapewniają trwałą, opartą na systemie plików rejestrację nazw obiektów i mechanizm bezpośredniego importu obiektów oparty na nazwie (implementowany przez pakiet setuptools ).

Kojarzą nazwy obiektów Python z dowolnymi identyfikatorami. Tak więc każdy inny kod używający tej samej instalacji w Pythonie i znający identyfikator może uzyskać dostęp do obiektu o powiązanej nazwie, bez względu na to, gdzie obiekt jest zdefiniowany. Te powiązane nazwy mogą być dowolne nazwy istniejących w moduł Pythona ; na przykład nazwa klasy, funkcji lub zmiennej. Mechanizm punktu wejścia nie dba o to, do czego odnosi się nazwa, o ile można ją importować.

Jako przykład zastosujmy (nazwa) funkcji i urojonego modułu python o w pełni kwalifikowanej nazwie „myns.mypkg.mymodule”:

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

Punkty wejścia są rejestrowane poprzez deklarację punktów wejścia w setup.py. Aby zarejestrować funkcję w punkcie wejścia o nazwie „my_ep_func”:

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

Jak pokazuje przykład, punkty wejścia są pogrupowane; istnieje odpowiedni interfejs API do wyszukiwania wszystkich punktów wejścia należących do grupy (przykład poniżej).

Po instalacji pakietu (tj. Po uruchomieniu „python setup.py install”) powyższa deklaracja jest analizowana przez setuptools. Następnie zapisuje przeanalizowane informacje w specjalnym pliku. Następnie można użyć interfejsu API pkg_resources (część setuptools), aby wyszukać punkt wejścia i uzyskać dostęp do obiektu (obiektów) o powiązanych nazwach:

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()})

Tutaj setuptools odczytuje informacje o punkcie wejścia zapisane w specjalnych plikach. Znalazł punkt wejścia, zaimportował moduł (myns.mypkg.mymodule) i odzyskał zdefiniowaną tam funkcję, po wywołaniu pkg_resources.load ().

Zakładając, że nie ma innych rejestracji punktu wejścia dla tego samego identyfikatora grupy, wywołanie funkcji_ byłoby wtedy proste:

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

Zatem, choć początkowo może być nieco trudny do uchwycenia, mechanizm punktu wejścia jest w rzeczywistości dość prosty w użyciu. Zapewnia przydatne narzędzie do programowania oprogramowania Python z możliwością podłączenia.

Petri
źródło
4
Gdzie w całym tym procesie używana jest nazwa „my_ep_func”? Wydaje się, że nie jest używany do niczego przez iterator pkg_resources.
Kamil Kisiel,
2
@KamilKisiel: w przykładzie użytym do zilustrowania tutaj nazwa punktu wejścia faktycznie nie jest używana do niczego, ani nie musi być; to, czy nazwa punktu wejścia jest używana do czegokolwiek, zależy od aplikacji. Nazwa jest dostępna po prostu jako atrybut nazwy instancji punktu wejścia.
Petri
3
Myślę, że odrzucenie ep.name i utworzenie nazwanych obiektów zamiast listy było mylące, więc zredagowałem odpowiedź. To, co pokazuje odpowiedź, pokazuje zarówno, gdzie uzyskać nazwę, jak i czy oczekiwać, że będzie to „the_function” lub „my_ep_func”. W przeciwnym razie czytelnik musiał znaleźć dodatkową dokumentację w innym miejscu. To jest DOSKONAŁA odpowiedź i jest najkrótszym, najjaśniejszym wyjaśnieniem punktów wejścia, jakie kiedykolwiek widziałem!
Bruno Bronosky,
3
Stworzyłem projekt na github, który demonstruje tę koncepcję. github.com/RichardBronosky/entrypoint_demo
Bruno Bronosky
1
Jest to bardzo jasne wyjaśnienie punktów wejścia, które zawiera szczegółowe wyjaśnienie. EntryPointsLink jest przestarzały, choć wyjaśnienie jest bardzo jasne.
Rahul Nair
18

Z abstrakcyjnego punktu widzenia punkty wejścia są używane do utworzenia ogólnosystemowego rejestru kallab Pythona, które implementują określone interfejsy. W pkg_resources znajdują się interfejsy API, które pokazują, które punkty wejścia są reklamowane przez dany pakiet, a także interfejsy API, które określają, które pakiety reklamują określony punkt wejścia.

Punkty wejścia są przydatne do umożliwienia jednemu pakietowi korzystania z wtyczek znajdujących się w innym pakiecie. Na przykład projekt wklejania Iana Bickinga intensywnie wykorzystuje punkty wejścia. W takim przypadku możesz napisać pakiet reklamujący fabrykę aplikacji WSGI przy użyciu punktu wejścia paste.app_factory.

Innym zastosowaniem punktów wejścia jest wyliczenie wszystkich pakietów w systemie, które zapewniają pewne funkcje wtyczek. TurboGears ramy internetowa wykorzystuje python.templating.enginespunkt wejścia zajrzeć do biblioteki szablonów, które są zainstalowane i dostępne.

Rick Copeland
źródło