Przejdź do treści

Jak kontrybuować

Architektura

Toolbox dzieli się na dwie kategorie poleceń z różnymi kontraktami.

Polecenia (commands)

Operacje na zewnętrznych systemach, zaprojektowane do łączenia w potoki.

  • Dane wyjściowe trafiają na stdout jako NDJSON
  • Wyłącznie do użycia w potokach: logintegra youtrack issues "..." | jq .
  • Nie wyświetlają interaktywnych elementów UI
  • Nie pytają użytkownika o potwierdzenie
from logintegra_toolbox_cli.console import emit

for record in results:
    emit(record)

Workflow

Gotowe scenariusze domenowe orkiestrujące wiele kroków. Działają jak TUI.

  • Dane wyjściowe trafiają na stdout jako czytelny dla człowieka teskt (Rich, tabele, kolory)
  • Mogą pytać użytkownika o potwierdzenie (click.confirm, click.prompt)
  • Mogą wyświetlać paski postępu, spinnery itp.
  • Nie są przeznaczone do pipowania
from rich.console import Console

console = Console()
console.print(f"[bold green]Release {version} created[/bold green]")
confirmed = click.confirm("Assign issues to release?")

Logi

Niezależnie od kategorii, logi diagnostyczne zawsze trafiają na stderr - nigdy na stdout. Dzięki temu nie zakłócają strumienia danych przy pipowaniu.

import logging

logger = logging.getLogger(__name__)

logger.info("Found %d issues", len(results))    # widoczne domyślnie
logger.debug("Query: %s", query)                # widoczne tylko z --verbose
logger.error("Something went wrong: %s", e)    # zawsze widoczne

Dodawanie nowego polecenia (command)

  1. Stwórz moduł w odpowiednim pakiecie, np. youtrack/commands.py
  2. Zdefiniuj grupę Click lub dodaj do istniejącej
  3. Używaj emit() do wypisywania danych
  4. Używaj logger do komunikatów
  5. Dodaj polecenie do main.py

Dodawanie nowego workflow

  1. Stwórz logikę domenową w workflows/<projekt>.py
  2. Dodaj polecenie Click w workflows/commands.py
  3. Używaj Rich do prezentacji wyników
  4. Używaj click.confirm / click.prompt do interakcji z użytkownikiem
  5. Logikę domenową trzymaj oddzielnie od warstwy CLI (jak apollo.py vs commands.py)

Styl kodu

uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest

Kod piszemy po angielsku (nazwy zmiennych, komentarze, help stringi, komunikaty błędów).

Ostatnia zmiana: 2026-04-12 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e