Creați un CLI Python cu Click+Cookiecutter (repost)

Repostat din original la https://blog.stephenturner.us/p/python-cli-click-cookiecutter.

—

În spiritul Învățarea în publicam vrut o scuză pentru a explora (1) clic pentru crearea de interfețe de linie de comandă, (2) Tăiător de prăjituri șabloane de proiect și (3) instrumente moderne în ecosistemul de ambalare Python. Dacă sunteți în primul rând un dezvoltator R ca mine, am scris recent despre resurse pentru a vă îmbunătăți la Python pentru utilizatorii R.

Clic este un pachet foarte frumos pentru a crea interfețe de linie de comandă și îmi place mai mult decât argparse sau alte utilitare similare. a lui Simon Willison faceți clic pe șablon cookiecutter aplicație a fost de mare ajutor în configurarea boilerplate pentru un pachet python și, în timp ce m-am uitat la construirea de backend-uri precum Flit, Poetry, uv etc., am ajuns să folosesc doar setuptools cu un pyproject.toml.

Nu sunt complet sigur cât de precisă este formula aici, dar o folosesc pentru a calcula câtă cofeină rămâne în circulație (și merg cu 90 mg pentru „o ceașcă de cafea”).

Unde:

• N
  name = „caffeinated”
  version = „0.1.1”
  dependencies = („click”)

  (project.scripts)
  caffeinated = „caffeinated.cli:caffeinated”

  The __init__.py va fi gol, iar __main__.py va avea doar o linie care importă funcția din cli.py:

  from .cli import caffeinated
  
  if __name__ == "__main__":
      caffeinated()

  The cli.py are de fapt codul pentru instrumentul de linie de comandă. Acesta este un program cu adevărat simplu, care reflectă cantitatea de cofeină pe care ați consumat-o și ora dvs. de culcare:

  import click
  
  @click.command()
  @click.option("-c", "--caffeine", default=100)
  @click.option("-b", "--bedtime", default=2100)
  def caffeinated(caffeine, bedtime):
      click.echo(f"Caffeine consumed: {caffeine} mg")
      click.echo(f"Your bedtime is:   {bedtime}")

  Acum, pip instalează pachetul pe care tocmai l-ai scris:

  pip install .

  Și acum utilitarul de linie de comandă cu cofeină este gata de utilizare. În primul rând, obțineți ajutor. Observați cum specificând o valoare implicită

  $ caffeinated --help
  Usage: caffeinated (OPTIONS)
  
  Options:
    -c, --caffeine INTEGER
    -b, --bedtime INTEGER
    --help                  Show this message and exit.

  Acum rulează-l:

  $ caffeinated -c 200 -b 2100
  Caffeine consumed: 200 mg
  Your bedtime is:   2100

  Puteți vedea codul real pentru cookiecutter aici: github.com/stephenturner/caffeinated. Iată link-uri către codul de lucru real. Totul important este în cli.py fişier. Mai adaugă câteva argumente, preia versiunea din pyproject.toml și definește funcții pentru a face toate calculele și facilitățile, cum ar fi traducerea „9pm” în 2100 (ore).

  Odată ce actualizați toate sursele sau doar pip install caffeinated din nou de la PyPI, instrumentul vă va spune aproximativ câtă cofeină veți rămâne în sistem după ce ați consumat o anumită cantitate de cofeină la ora de culcare aleasă. Fugi caffeinated --help pentru a obține ajutor cu privire la opțiuni.

  Organizarea proiectului dumneavoastră ca un pachet Python bine structurat poate simplifica dezvoltarea și distribuția. The Tăiător de prăjituri pachetul oferă o modalitate simplă de a genera șabloane de proiect, asigurând consecvența și cele mai bune practici în cadrul proiectelor dvs. Instalează-l cu pip, apoi îl voi folosi Șablonul cookiecutter pentru clic-app al lui Simon Willison.

  pip install cookiecutter
  cookiecutter gh:simonw/click-app

  Puteți vedea cum arată asta după ce ați rulat-o la acest demo. Rularea acestui lucru și răspunsul la câteva dintre solicitări va crea:

  1. Structura directorului descrisă mai sus

  2. The __init__.py, __main__.pyși cli.py fișiere cu unele standarde pentru a începe.

  3. Un fișier pyproject.toml bazat pe răspunsurile dvs. la solicitări.

  4. Un director de teste cu boilerplate pentru scrierea de teste cu pytest.

  Codul final cu cofeină realizat din șablonul Simon’s click-app cookiecutter este aici github.com/stephenturner/caffeinated.

  Am scris zeci de pachete R pentru distracție și profit. Există într-adevăr un singur lanț de instrumente backend pentru pachetele R pe care îl folosește toată lumea: devtools cu Roxygen documentatie cu asistenta liberala din foloseste asta.

  Documentația Python are un ghid bun Impachetarea proiectelor Python. Ecosistemul backend de construcție în Python este mai divers. Mi-am dorit foarte mult să arunc o privire mai atentă Flutura, Poezie, Trapași altele, dar pentru că șablonul cookiecutter pe care l-am folosit a creat un pyproject.toml folosind setuptools implicit, așa că am alergat cu asta.

  setuptools este probabil cel mai vechi și cel mai utilizat instrument de ambalare din Python, cu o documentare bună și sprijin comunitar. Și cu PEP 517standardul a devenit folosind un pyproject.toml mai simplu decât vechiul setup.py. Poți să-mi vezi pyproject.toml pentru cafeină aici. Este destul de simplu și o caracteristică cheie este readme="README.md" intrare, care are ca rezultat documentația de pe pagina de destinație PyPI (pypi.org/project/caffeinated/) populat cu README.md în rădăcina proiectului, evitând necesitatea duplicării.

  Flutura (flit.pypa.io) arată ca un backend de compilare foarte minim, foarte simplu pentru ambalarea codului Python simplu. Am aruncat si eu o privire Poezie (python-poetry.org), pentru că dacă aș construi ceva mai complex, cred că mi-aș dori ceva care să mă ajute să gestionez dependențele în loc să trebuiască să le adaug manual la pyproject.toml. Poezia ajută la asta. În sfârșit, există mult interes pentru uv (docs.astral.sh/uv) chiar acum. Este un pachet Python și un manager de proiect scris în Rust, iar benchmark-urile sunt impresionante. Vezi „uv: ambalaj Python unificat” postare pe blog pentru mai multe. uv nu are încă un backend de construcție, dar asta este în lucru la astral-sh/uv#3957.

  Construirea de pachete Python cu setuptools vs Flit vs Poetry vs uv ar putea fi subiectul unei postări viitoare, dar deocamdată, folosesc doar setuptools+build.

  pyproject.toml creat de șablonul cookiecutter pe care l-am folosit avea cam tot ce aveam nevoie pentru a construi pachetul. De aici a fost simplu. Aceasta va construi .whl fișier binar și .tar.gz pachete sursă în a dist/ pliant.

  python -m build

  După aceasta, este destul de simplu să încărcați acest lucru în PyPI. Dar, înainte de a încărca în producție pypi.orgprobabil că ar trebui să încărcați în depozitul de testare (test.pypi.org) mai întâi pentru a evita poluarea PyPI cu pachete sparte sau de testare.

  twine upload -r testpypi dist/*

  Încărcarea în PyPI real urmează aceeași convenție. Recomand folosirea unui jeton în dvs .pypirc fişier în loc de un prompt de nume de utilizator/parolă.

  twine upload dist/*

  Câteva secunde mai târziu, pachetul dvs. va fi pe PyPI și îl puteți instala cu pip install la fel ca orice alt pachet. Pachetul cu cofeină este pe PyPI la https://pypi.org/project/caffeinated/.

  Dacă ați încercat vreodată să introduceți un pachet în CRAN, știți cât de oneros poate fi procesul și cât de stricti pot fi întreținerii CRAN și ați putea fi șocat să vedeți cât de ușor este să obțineți un pachet pe PyPI. Nu există niciun proces de curatare sau de revizuire cu PyPI. Încărcați fișierele sursă și roată cu sfoară și pachetul dvs. este live.

  Odată ce aplicația este pe PyPI, este ușor să creați un container Docker. Există un Dockerfile în repo care arată astfel:

  FROM python:3.11-alpine
  RUN pip install caffeinated
  WORKDIR /files
  ENTRYPOINT ("caffeinated")
  CMD ("--help")

  Îl puteți construi astfel (înlocuiți stephenturner cu numele de utilizator Docker):

  docker build -t stephenturner/caffeinated

  Și împingeți-l în Docker Hub:

  docker push stephenturner/caffeinated 

  Acest container se află pe hub-ul Docker la stephenturner/cofeinizat. Acum îl puteți rula:

  $ docker run stephenturner/caffeinated -c 200 -b 9pm
  
  You would have 35.4mg of caffeine in your system if you went to bed at 9:00pm (in 15.0 hours).
  That's like having 39% of a cup of coffee before bed.

  Alternativ, puteți crea cu ușurință o imagine cu noul instrument și instrumente suplimentare pe care le doriți în același container folosind Containere Seqera (vezi videoclipul legat mai jos pentru mai multe detalii). am creat această imagine care include atât cofeinizate cât și cowsayși introduc rezultatul cofeinei în cowsay.

  $ docker run --rm community.wave.seqera.io/library/pip_caffeinated_python-cowsay:5a33eb2abfe4e6a5 sh -c 'caffeinated --caffeine 200 --bedtime 9pm --start-time 8am | cowsay'
   __________________________________________ 
  / You would have 44.5mg of caffeine in     
  | your system if you went to bed at 9:00pm |
  | (in 13.0 hours). That's like having 49%  |
   of a cup of coffee before bed.           /
   ------------------------------------------ 
             ^__^
             (oo)_______
              (__)       )/
                  ||----w |
                  ||     ||

  Aceasta face parte din seria mea TIL / Learning in Public, despre care am scris recent:

  

  Pentru o introducere rapidă la Click, vedeți videoclipul oficial de introducere Click. Are peste 10 ani în acest moment, este încă aplicabil în mare parte.

  Acest videoclip de la NeuralNine demonstrează cum să creați grupuri de clic pentru a crea utilitare CLI cu subcomenzi:

  Acest videoclip de la ArjanCodes explică cum se creează un pachet Python și cum se publică pe PyPI. Folosește vechiul setup.py în loc de convenția mai modernă pyproject.toml, dar în rest este bine să înțelegeți pașii procesului.

  În sfârșit, puțin mai multe despre crearea cu ușurință a containerelor cu mai multe instrumente pentru mai multe arhitecturi Containere Seqera: