Python i zagadka szablonowych skryptów

Zdjęcie: Od ikony projektu YT DLP odchodzi strzałka w górę, do ikony Python Package Index. Stamtąd odchodzi kolejna strzałka, prowadząca do ikony laptopa.

Od jakiegoś czasu chciałem zrobić wpis bardziej w stylu programistycznych blogów, jakie chętnie czytam. Ale bez nurkowania w głębiny. Skupiający się zamiast tego na czymś podstawowym, co często bierze się za pewnik.
Taki wpis, żeby była eksploracja. Radosne zaspokajanie ciekawości poznawczej. W stylu piosenkarki Björk rozbierającej telewizor na części.

Na początek pomyślałem, iż zajrzę w bebechy programiku yt-dlp. Napisanego w języku Python, który najbardziej mi leży.

Ale ostatecznie wyszedłem poza ten konkretny program. Odciągnął mnie od niego ogólniejszy temat „skryptów wejściowych”. Tego, co pozwala wzywać programy konsolowe z dowolnej części systemu.

Odkryłem, jak wygląda ich droga od twórców do użytkowników. Przy okazji mogłem wprawić się w eksploracji z użyciem programów konsolowych.

Zapraszam! Znajomość Pythona nie jest konieczna, bo cała sprawa ma w sobie więcej z łamigłówki logicznej. Poza tym będę wszystko wyjaśniał.

Spis treści

• Początek: yt-dlp
  • „Wołaj, a przybędę”
  • Kulisy dostępności
  • Znalezienie pliku
  • Wnętrze pliku
• Trendy wśród skryptów wejściowych
  • Różnice między skryptami
  • Zagadki linijki importującej
  • Zagadka znaku zapytania
• Znalezienie części zmiennej
• Znalezienie części szablonowej
  • Stare szablony
  • Nowsze szablony
  • Podsumowanie wątku
• Od strony twórców
• Czego się nauczyłem

Początek: yt-dlp

Wszystko zaczęło się od yt-dlp. To bardzo przydatny programik do pobierania multimediów z różnych stron (nie tylko z YouTube’a). Już nieraz się nad nim rozpływałem na tym blogu.

W pierwotnej postaci jest to program konsolowy. Używa się go przez wpisywanie konkretnych poleceń tekstowych w konsolę. Jakaś jest zwykle domyślnie zainstalowana na komputerach osobistych.

Analogia godna współczesności? Programy konsolowe są jak ChatGPT bez lukru.
Zamiast pytań przyjmują polecenia. Zamiast kwieciście odpowiadać, robią dobrą robotę. Ewentualnie wprost piszą, iż nas nie zrozumiały, zamiast zmyślać bzdurki.

Używając yt-dlp, można na przykład pobrać piosenkę z którejś ze wspieranych stron. Wystarczy skopiować link do niej i wpisać w konsolę:

…A piosenka po chwili trafi na dysk. Albo na jego telefonowy odpowiednik.

Smartfonowy, bo tego konkretnego programu można używać również na telefonach z systemem Android. Najpierw pobiera się apkę Termux, przez nią język programowania Python, zaś przez narzędzia Pythona – yt-dlp. Wszystko szybkie, zwięzłe i proste.

„Wołaj, a przybędę”

W konsoli po lewej stronie zwykle wyświetla się folder, w jakim w tej chwili jesteśmy (i tak, również tylda, ~, to skrót odnoszący się do folderu. Domowego).

Po tych folderach można się poruszać. Wpisać na przykład polecenie cd ŚCIEŻKA, żeby przejść do folderu o podanej ścieżce (jeśli istnieje). Mikrociekawostka: cd to skrót od change directory.

W tym miejscu ukazuje się interesująca adekwatność yt-dlp wewnątrz Termuksa. Mianowicie: w jakim folderze by się nie było, można przywołać ten program taką samą komendą.

Konsola apki Termux. Na zielono ścieżki do folderów, w których akurat byłem.

W przypadku yt-dlp w Termuksie jest to o tyle istotne, iż pobierane pliki będą zapisywane zawsze do tego folderu, w którym w tej chwili jesteśmy.
Gdyby je pobierać do domyślnego folderu (który jest w prywatnej części Termuksa), to inne aplikacje, jak odtwarzacze multimediów, nie miałyby do nich dostępu.

Ale wracając do kwestii dostępności z każdego folderu – ten ułatwiacz życia jest bardzo powszechny w świecie programów konsolowych. Jak to działa?

Kulisy dostępności

Ogólnodostępność wynika z tego, iż wiele systemów ma swoje foldery specjalne, w których domyślnie wypatruje programów.

Tak jak przeciętny obywatel wie, iż najłatwiej znaleźć policjantów na komendzie, a lekarzy w szpitalu (choć oczywiście trafiają się też poza nim) – tak samo konsola/Python wie, iż swoich programów ma szukać w określonych folderach.

Żeby zobaczyć listę takich specjalnych lokalizacji, można wpisać w konsolę:

Wyświetli się kilka ścieżek (na świeżym Termuksie – jedna). jeżeli jest więcej, to będą rozdzielane dwukropkami.

Za każdym razem, kiedy wpisuje się proste konsolowe polecenie, dajmy na to zmyślone abcd coś, konsola rozbija je na spacjach. Następnie szuka we wspomnianych folderach specjalnych pliku o takiej samej nazwie jak pierwszy człon. Czyli w tym przypadku abcd.

Idąc tym tokiem rozumowania: wpisując yt-dlp, odnoszę się do jakiegoś pliku o takiej nazwie. I powinien być w tym jedynym folderze specjalnym, jaki mi pokazuje na Termuksie powyższe polecenie.

Ale to domysły. Jak sprawdzić to dokładniej: „jaki program odpowiada poleceniu yt-dlp?”. Albo, uogólniając: „jak poznać ścieżkę wołanego programu?”.

Znalezienie pliku

Można zapytać internetów. Podczas wyszukiwania warto podać nazwę systemu, bo różnią się między sobą. Ja używałem Termuksa, ale wiem, iż to konsola w stylu systemu Linux.
Ostatecznie wpisałem w wyszukiwarkę DuckDuckGo: linux checking program path. I znalazłem odpowiedź z niezawodnego forum StackExchange.

Ludzie na forum napisali, iż ścieżkę ujawni program konsolowy which albo type.
Przy tym pierwszym Termux mówił, iż nie jest zainstalowany (ale podpowiadał gotowe polecenie instalujące). Drugi od razu śmigał.

Po wpisaniu:

Wyświetliło mi pełną ścieżkę do pliku:

Dla przypomnienia: tak to wygląda wewnątrz Termuksa, na komputerze byłaby inna ścieżka.
Co ciekawe, com.termux to folder – jeżeli ktoś się przyzwyczaił, iż kropki są tylko od rozszerzeń plików, to się może zaskoczyć.

Wnętrze pliku

Znalazłem plik, pozostało do niego zajrzeć. Termux czy nie – mogłem łatwo zaznaczyć ścieżkę i ją skopiować. Pozostało ją wrzucić do innego programu konsolowego, który odczyta plik. Wybrałem do tego less:

less ŚCIEŻKA_DO_PLIKU

Ogromna zaleta tego programu: wyświetla większe pliki „na raty”, kawałek po kawałku.
W tym przypadku akurat mi to nie pomogło, bo plik był zwięzły.

Od tego miejsca będzie odrobina kodu. Ale adekwatnie nie trzeba choćby rozumieć, o co w nim chodzi, można potraktować całość jak logiczną łamigłówkę.

Okazuje się, iż plik o nazwie yt-dlp (bez żadnego rozszerzenia) to skrypt Pythona. To on się uruchamia, gdy wpisze się w konsolę yt-dlp. A oto cała jego zawartość:

Streszczając: ten skrypt to „uruchamiacz”. Bierze (importuje) funkcję z jakiegoś innego skryptu, który nazywa się yt_dlp. I ją aktywuje.

A skąd Python wie, gdzie szukać tych pozostałych skryptów? No cóż, też ma swoje specjalne foldery. Analogiczne do tych systemowych, o których wcześniej wspomniałem.

Trendy wśród skryptów wejściowych

W tym momencie na pewien czas kończy się wątek konkretnego yt-dlp, a zaczyna ogólniejszy, związany ze skryptami Pythona.

Po poznaniu skryptu-uruchamiacza od yt-dlp, postanowiłem sprawdzić z ciekawości, jak wyglądają jego odpowiedniki dla innych modułów. W moim folderze szybkiego dostępu było bowiem więcej poinstalowanych skryptów.

Dla wygody użyłem oprócz Termuksa laptopa z lekko wiekowym systemem Linux Mint. Zerknąłem do folderu .local/bin w folderze domowym, który również jest folderem specjalnym na różne programy, przypisanym do konkretnego użytkownika.

Oprócz tego dałoby się również sprawdzić folder /usr/bin, na poziomie systemu, ale odpuściłem go sobie, bo był tam miks rzeczy pobranych i systemowych.

Treść plików ze specjalnego folderu odczytałem krótkim, skleconym na kolanie skryptem.

Spodziewałem się pewnej różnorodności. Myślałem, iż każda osoba publikująca swoje moduły Pythona tworzy również jakiś własny skrypt startowy. A tymczasem po sprawdzeniu innych skryptów odkryłem, iż wiele z nich było niemal identycznych.

Rzuciło to nowe światło na całą sprawę. Przyszło mi na myśl, iż skrypty są tworzone przez komputer, z jakiegoś szablonu.
Żeby go poznać, postanowiłem porównać skrypty i spróbować w nich wyróżnić części zmienne oraz niezmienne (szablonowe).

Różnice między skryptami

Oto zawartość kilku wybranych skryptów startowych (można otworzyć w nowej karcie, żeby powiększyć):

Najpierw odhaczę różnice, które uznałem za drobniejsze i zignorowałem, zostając przy istotniejszych:

• Różnice w liczbie pustych linijek.
  Ta różnica jest ściśle skorelowana z inną, o której za moment.

• Różnice w linijce numer jeden.

  To ona mówi, jakiego Pythona użyć (a ściślej – jakiego interpretera, programu odczytującego kod Pythona).
  Inną miałem na Termuksie, inną na laptopie. Ale ogólnie: linijka zawsze wskazywała tego samego Pythona, którym zainstalowałem cały skrypt.

• Różnice w ostatniej linijce.

  Jej treść to sys.exit(FUNKCJA()), a ta FUNKCJA różniła się między skryptami.
  Ale zawsze odnosiła się do funkcji importowanej parę linijek wyżej. Zatem choćby jeżeli nie ma powtarzalności tekstu, jest pełna powtarzalność zasady działania.

Po odsianiu drobnicy zostały dwie interesujące rzeczy do wyjaśnienia.

Zagadki linijki importującej

Głównym źródłem różnic wydaje się być linijka, w której dochodzi do wzięcia jakiejś funkcji z innego skryptu stworzonego przez autorów. Każdy skrypt robi to inaczej:

from chardet.cli.chardetect import main from pip._internal.cli.main import main from yt_dlp import main from mss.__main__ import main

Kolorami wyróżniłem części zmienne, reszta to niezmienniki.

Gdybym miał tylko te moduły, to mógłbym pomyśleć, iż również nazwa wyciąganej funkcji (main) zawsze jest taka sama. Ale nie! Parę nielicznych modułów, jak tld, wyłamuje się z tej konwencji:

from tld.utils import update_tld_names_cli

Zagadka znaku zapytania

Mniejsza, ale tym ciekawsza różnica pojawia się w linijce znajdującej (po czym usuwającej) końcówki nazw plików funkcją re.sub.
W kilku modułach, jak pip3, chardetect i kilku innych, pojawiał się znak zapytania nieobecny w pozostałych:

r'(-script\.pyw?|\.exe)?$' r'(-script\.pyw|\.exe)?$'

Ograniczyłem się tutaj jedynie do fragmentu linijki, reszta była bez zmian.

Znak zapytania to część elastycznych regułek szukających. Sprawia, iż rzecz stojąca przed nim staje się opcjonalna. Może być, może jej nie być. Ten wyróżniony odnosi się do literki w.
W praktyce jedna wersja skryptu będzie usuwała z nazwy aktywnego programu (Pythona) jedynie końcówki -script.pyw i .exe, druga ponadto -script.py.

Ten znak w oglądanych przeze mnie skryptach zawsze występował razem z kilkoma pustymi linijkami (ilustracja wyżej). Dlatego w myślach wydzieliłem sobie dwie kategorie skryptów: „linijki i znak zapytania” oraz „zwięzłe, bez znaku”.

Znalezienie części zmiennej

Co wspólnego miały ze sobą różne skrypty, które sprawdzałem? To, iż powstały po zainstalowaniu modułu programem pip. Wziąłem swego czasu i wpisałem w konsolę:

pip install NAZWA_MODUŁU

Dokładniej rzecz biorąc, na komputerze musiałem wpisać pip3, bo miałem domyślnie dwie wersje Pythona. Ale to detal.

W ten sposób zdobyłem yt-dlp. Innym razem mss od robienia screenshotów, też pokazany powyżej. W każdym z tych przypadków do folderu specjalnego bin trafił szablonowy skrypt uruchamiający.

Pomyślałem, iż rozwiązania zagadki trzeba poszukać u źródła. Wewnątrz PIP-a, czyli tego pythonowego instalatora.

Co się dzieje, kiedy używam powyższego polecenia?
Ano to, iż pip łączy się z PyPI – centralną bazą, do której ludzie mogą wrzucać swoje własne moduły Pythona. PIP sprawdza, czy ma w tej bazie moduł o wpisanej przeze mnie nazwie. jeżeli tak, to go pobiera.

Do plików, które pobiera PIP, można również dobrać się manualnie. Wejść na stronę konkretnego modułu (tu: yt-dlp), kliknąć zakładkę Download Files. Pod nagłówkiem Built Distribution (sugerującym, iż to wersja dla użytkowników) znalazłem plik z rozszerzeniem .whl.

Pobrałem pliki dla modułów yt-dlp oraz mss. jeżeli to na ich podstawie instalator tworzył skrypty wejściowe, to gdzieś powinny w nich być odpowiednie informacje.

Wnętrze plików WHL

Pobrany plik .whl (skrót od wheel) to tak naprawdę archiwum ZIP. Jak wiele innych plików, po których nie każdy by się tego spodziewał (dokumenty pakietu Office, aplikacje na Androida…).
W każdym razie mogłem go rozpakować. Na Linuksie – bez zmian rozszerzenia, po prostu prawe kliknięcie i wybranie odpowiedniej opcji.

Pierwsza myśl – poszukam charakterystycznych słów ze skryptu startowego i zobaczę, czy gdzieś je znajdę w rozpakowanym folderze. Być może wszyscy twórcy osobiście załączają szablonowe skrypty startowe, a instalator jedynie je kopiuje w odpowiednie miejsce?

Do przeszukiwania zawartości folderów idealnie się nadaje programik grep, który we właściwym trybie odwiedza każdy plik po kolei:

grep -r -F "SZUKANY_TEKST" ROZPAKOWANY_FOLDER

Argument -r po to, żeby przeszukać wszystkie pliki oraz podfoldery we wskazanym folderze;
-F po to, żeby nie traktowało żadnych znaków jak znaków specjalnych.

Najpierw poszukałem tekstu sys.exit. Części niby szablonowej, ale z drugiej strony na tym etapie dopuszczałem myśl, iż każdy moduł trzyma gdzieś własny szablon.
Ale grep niczego nie znalazł. Ani w yt-dlp, ani w paru innych.

W związku z tym, zamiast szukać części szablonowej, postanowiłem poszukać części zmiennych, różniących się między skryptami. Jak nazwy importowanych modułów i funkcji.

W przypadku MSS-a linijka ze skryptu startowego brzmiała:

Drugi zmienny człon, main, brzmiał dla mnie ciut zbyt ogólnie. Dlatego w rozpakowanym pliku WHL poszukałem pierwszego:

grep -r -F "mss.__main__" mss-9.0.1-py3-none-any.whl_FILES

I eureka! Grep znalazł szukany tekst w podfolderze zakończonym na dist-info, w pliku o nazwie entry_points.txt. Zresztą cały plik zawierał tylko to:

Zgadzały się: nazwa skryptu startowego, nazwa importowanego, nazwa konkretnej funkcji (po dwukropku), cel tego wszystkiego („skrypty konsolowe” w nawiasach kwadratowych). Miałem mocne podejrzenie, iż to na podstawie tego pliku instalator uzupełnia szablon skryptów startowych.

…Ale skąd brał sam szablon?

Znalezienie części szablonowej

Na logikę: jeżeli instalowane pliki zawierają tylko informacje do umieszczenia w szablonie, to sam szablon powinien tkwić na moim komputerze, wewnątrz instalatora. Może samego PIP-a. Może innego modułu, z którego korzysta.

Tyle iż nie wiedziałem, gdzie szukać, zaś mój własny system zawierał więcej poinstalowanych modułów Pythona, które mogłyby wchodzić w drogę.
Dlatego postanowiłem stworzyć jakieś czyste środowisko do eksperymentów, w którym wyizoluję sobie instalatora i to jego przeszukam.

W Pythonie taką możliwość zapewniają środowiska wirtualne.
To coś w rodzaju odgrodzonej części systemu. Pozwalają eksperymentować z różnymi modułami Pythona, instalować je i usuwać, ale bez wpływu na główne pliki na komputerze.

W jakimś folderze X stworzyłem folder skrypty-testy, po czym uruchomiłem w tym samym folderze X konsolę i wpisałem:

Użyłem tu nieco starszej wersji Pythona (3.7), jaką u siebie miałem. Jak się potem okaże, ma to istotne znaczenie.

To polecenie wypełniło folder kilkoma podstawowymi modułami Pythona. Również tymi odpowiedzialnymi za instalację, jak PIP.

Środowisko wirtualne, choć ma nietypowe możliwości, jest dla systemu najzwyklejszym folderem skrypty-testy, całkiem publicznym. Wiedząc, iż w środku mam instalatory, mogłem poszukać tekstu typowego dla szablonów. Postawiłem na fragment reguły ucinającej końcówki:

grep -rF "re.sub(r'(-script\.py" skrypty-testy

Stare szablony

Wynik wyszukania? Wzmianka o dwóch plikach binarnych, których nie odczytało, oraz kilka tekstowych:

skrypty-testy/lib/python3.7/site-packages/pip/wheel.py skrypty-testy/lib/python3.7/site-packages/setuptools/command/easy_install.py skrypty-testy/bin/pip3.7 skrypty-testy/bin/pip skrypty-testy/bin/pip3 skrypty-testy/bin/easy_install skrypty-testy/bin/easy_install-3.7

Gdybym chciał celowo pominąć pliki binarne, nie dostając o nich choćby wzmianki, to mógłbym dopisać -I po słowie grep. Albo zwięźlej: zmienić -rF na -rFI.

Pliki, które zawierały w swojej ścieżce bin, same były skryptami startowymi. Stworzonymi z szablonu, więc nie mogły być szablonem. Olałem je.

Skrypt easy_install.py zawierał klasę ScriptWriter, która miała swój szablon… Tyle iż nieco zbyt długi. Zawierał szereg rzeczy nieobecnych w moich skryptach startowych.

Za to plik wheel.py był strzałem w dziesiątkę! Już sama nazwa sugeruje, iż odpowiada za pliki WHL, do tego jego zawartość idealnie pasowała do niektórych skryptów startowych (nie zawierał jedynie pierwszej linijki, dodanej w innym miejscu):

…Ale ten szablon nie wyjaśniał wszystkiego. Pasował do skryptów rozstrzelonych na więcej linijek, z dodatkowym znakiem zapytania w regułce.
Nie powstał z niego natomiast ten drugi, zwięzły typ skryptów startowych. Co więcej: w żadnym ze znalezionych wyżej plików nie było pasującego szablonu.

Nowsze szablony

Korzystałem w środowisku wirtualnym ze starszej wersji Pythona, która siłą rzeczy korzystała ze starszych wersji instalatorów. Uznałem, iż je zaktualizuję do najnowszych wersji i zobaczę, czy to coś zmienia.

Żeby zaktualizować coś wewnątrz środowiska wirtualnego, musiałem w nie „wejść”. Będąc w tym samym folderze, w którym tkwił folder skrypty-testy, wpisałem:

source skrypty-testy/bin/activate

Programik konsolowy source służy do uruchamiania innych programów. Odnoszę się tu do programu activate, zakopanego w folderze skrypty-testy, podfolderze bin.

Mogłem łatwo poznać, iż środowisko się włączyło, bo na początku linijki, między nawiasami, pojawiło się skrypty-testy. Nazwa aktualnego środowiska. Póki jestem w tym trybie, moduły Pythona są instalowane wyłącznie w jego obrębie.

Żeby zaktualizować rzeczy związane z instalacją, wpisałem:

Potem powtórzyłem polecenie do Grepa, jakim wcześniej znalazłem starszy szablon.
Ponownie znalazło mi dwa potencjalnie interesujące skrypty. Jeden był tym samym easy-install.py co poprzednio, który miał zbyt długi szablon.
Drugi znaleziony skrypt różnił się natomiast od tego ze starszego instalatora:

Zajrzałem do niego… I bingo! Był tam szablon pasujący do drugiego rodzaju skryptów startowych. Tych zwięzłych i bez znaku zapytania.

Podsumowanie wątku

Na tym etapie byłem już przekonany, iż rozgryzłem instalację skryptów startowych przez Pythona:

• instalator zdobywa plik WHL z centralnej bazy Pythona,
• znajduje w pakiecie plik entry_points.txt,
• odczytuje z niego, iż powinien stworzyć skrypt startowy w folderze ogólnodostępnym,
• uzupełnia szablon ze swoich bebechów szczegółami z pliku,
• tworzy skrypt.

Gdybym chciał mieć pewność, mógłbym spróbować użyć PIP-a z jakimś profilerem albo programikiem typu strace. Zobaczyłbym dokładnie, jakie funkcje kolejno się włączały i jakie stworzyły mi pliki.
Ale zadowoliłem się eksploracją samej treści skryptów.

A różnice między wyglądem finalnych skryptów? Wynikały z tego, iż sama ekipa tworząca Pythona na przestrzeni wersji zmieniała swoje szablony.

A ja aktualizowałem instalatory, nie zmieniając przy tym niektórych rzeczy, które już wcześniej zainstalowałem. W folderze bin wymieszały mi się przez to skrypty startowe w wariantach starszych i nowszych.

Od strony twórców

Główna zagadka wyjaśniona, ale czułem niedosyt. Sama instalacja przez użytkowników to dopiero druga połowa drogi. A jak to wygląda między niezależnymi twórcami a bazą PyPI? Czy tworzą plik entry_points.txt oraz kilka innych manualnie, przed dodaniem do pliku WHL?

Wyszukałem w sieci entry_points.txt oraz console scripts.
Wyskoczyła mi stronka Pythona opisująca konwencje związane ze skryptami startowymi. Poznałem też ich oficjalną nazwę – entry points (dosł. punkty wejściowe).

Strona wspomniała również, iż twórcy nie dodają plików manualnie. Zostawiają wytyczne dla programu łączącego ich skrypty w plik WHL, po czym to on tworzy pliki tekstowe.

Te wytyczne mogą umieszczać w kilku miejscach. Programik yt-dlp postawił na plik pyproject.toml. W przypadku ich projektu dość obszerny.
Tam (na dzień dzisiejszy – w linijkach 78 i 79 – znajdują się instrukcje dotyczące skryptów startowych.

Podsumowując całą drogę skryptów startowych – od twórców po użytkowników – w formie schematu:

Czego się nauczyłem

Podczas eksploracji trochę się dowiedziałem na temat tego, jak udostępniać moduły Pythona. Tak, żeby dało się ich używać jako programów konsolowych, reagujących na wezwanie z każdego folderu. To mi się przyda!

Okazuje się, iż to nie takie trudne. Wiele sprowadza się do wpisania paru linijek w plik tekstowy.
Resztę bierze na siebie najpierw program pakujący wszystko do jednego pliku WHL. A potem – po stronie użytkowników – wszystko załatwia instalator, czyli PIP. Oraz jego skrypty towarzyszące.

Zapewne twórcy każdego języka programowania stają przed podobnymi kwestiami – „jak ułatwić tworzenie programów konsolowych w naszym języku?”, „czy mieć centralną bazę skryptów od różnych ludzi?”.

Nie zdziwiłbym się, gdyby wiele projektów dryfowało ku temu samemu rozwiązaniu, zwięzłym plikom konfiguracyjnym. Choć skupiłem się na Pythonie, prawdopodobnie wchłonąłem w głowę też parę ogólnych konwencji.

A czy nie mogłem po prostu zacząć od dokumentacji, zamiast odkrywać koło (WHL) na nowo? Pewnie mogłem. Ale nie miałbym z tego takiej frajdy :smile: