Anthillo /blog
← Wszystkie wpisy

Projekt pod kontrolą

Mikołaj Wojciuk

Software and Data Engineer ·

Praca nad kilkoma projektami jednocześnie szybko uczy jednej rzeczy – czasami największym problemem nie jest sam kod. Równie dużo uwagi potrafią wymagać środowiska, wersje bibliotek, zasady jakości i różne sposoby pracy z każdym repozytorium. Dlatego dobry tooling powinien te rzeczy porządkować, a nie dokładać kolejną warstwę do pamiętania. I właśnie z tej perspektywy coraz ciekawiej wyglądają uv i Ruff.

Projekt to nie tylko kod

Kod jest oczywiście najważniejszą częścią każdego projektu programistycznego, ale nie działa w próżni. Obok niego mamy wersję języka, zewnętrzne biblioteki, środowisko uruchomieniowe, sposób instalowania zależności, narzędzia jakościowe czy konwencje ustalane wewnątrz zespołu.

Im więcej osób i projektów pojawia się w codziennej pracy, tym wyraźniej widać, że ta wiedza nie powinna istnieć wyłącznie w głowie developera. Projekt sam powinien możliwie jasno określać, jak się z nim pracuje, czego wymaga i jakie zasady w nim obowiązują. Powrót do repozytorium po kilku miesiącach nie powinien zaczynać się od przypominania sobie jego całego technicznego otoczenia i ponownego podejmowania decyzji, które zostały już kiedyś podjęte.

To podejście jest dla nas częścią jakości projektu. Nie chodzi wyłącznie o to, czy kod działa dzisiaj, ale również o to, czy za pół roku nadal będzie można go przewidywalnie uruchomić, rozwijać i przekazać kolejnej osobie bez odtwarzania wiedzy z historii terminala, README i pamięci zespołu.

Jakość, której nie powinien pilnować człowiek

Skoro projekt to nie tylko sam kod, naturalnym krokiem jest uporządkowanie również tego, co dzieje się wokół niego. Wiele zasad dotyczących jakości jest przecież powtarzalnych i możliwych do jednoznacznego sprawdzenia: sposób formatowania, kolejność importów, nieużywane zmienne, podejrzane konstrukcje czy sposób dokumentowania funkcji.

Od dawna korzystamy z narzędzi, które pozwalają takie reguły zapisać i egzekwować automatycznie. Black pilnuje formatowania, isort porządkuje importy, Pylint lub Flake8 analizują kod, a pre-commit pozwala spiąć kontrole i wykonać je jeszcze zanim zmiana trafi do zdalnego repozytorium.

Dzięki temu zasady przestają być jedynie ustaleniem wewnątrz zespołu – stają się częścią projektu.

Ma to również bardzo praktyczny efekt. Code review może służyć do oceny logiki, architektury, czytelności rozwiązania czy przypadków brzegowych, zamiast zamieniać się w dyskusję o nieużywanym imporcie albo formatowaniu kilku linii kodu. Jeśli coś można jednoznacznie sprawdzić automatycznie, nie ma większego sensu poświęcać na to czasu drugiego człowieka.

W klasycznym podejściu taka konfiguracja może wyglądać mniej więcej tak:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: <wersja>
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

  - repo: https://github.com/psf/black
    rev: <wersja>
    hooks:
      - id: black

  - repo: https://github.com/PyCQA/isort
    rev: <wersja>
    hooks:
      - id: isort

  - repo: https://github.com/PyCQA/flake8
    rev: <wersja>
    hooks:
      - id: flake8

I to działa. Black formatuje kod, isort porządkuje importy, Flake8 pilnuje zdefiniowanych reguł, a prostsze hooki mogą wychwycić chociażby zbędne białe znaki czy problemy z plikami konfiguracyjnymi. Commit może zostać zatrzymany zanim błąd opuści lokalne repozytorium.

Takie podejście przez lata sprawdzało się bardzo dobrze i nadal może być całkowicie poprawnym rozwiązaniem. Problem pojawia się gdzie indziej: wraz z rozwojem projektu sam mechanizm kontroli jakości zaczyna składać się z coraz większej liczby elementów. Osobny formatter, linter, narzędzie do importów, dodatkowe pluginy i konfiguracje – każde z własną wersją, ustawieniami i zakresem odpowiedzialności.

Skoro więc celem automatyzacji było zmniejszenie liczby rzeczy, których musi pilnować człowiek, warto od czasu do czasu zadać sobie pytanie, czy sam tooling nie zaczął przypadkiem wymagać zbyt dużo uwagi.

Mniej rzeczy do pilnowania

Oczywiście można prościej – i właśnie w tym miejscu pojawiają się uv i Ruff.

Oba narzędzia odpowiadają za różne części projektu, ale łączy je podobna filozofia: ograniczyć liczbę osobnych elementów, które trzeba konfigurować, aktualizować i pamiętać. Ruff porządkuje obszar jakości kodu, uv natomiast zajmuje się środowiskiem, wersją Pythona, zależnościami i sposobem pracy z projektem.

W poprzednim rozdziale pokazaliśmy, jak kilka narzędzi może wspólnie pilnować jakości kodu. Wokół samego uruchomienia projektu sytuacja często wygląda podobnie: pip, venv, pliki z zależnościami, dodatkowe rozwiązanie do wersji Pythona, osobne mechanizmy do synchronizacji środowiska i kolejne pliki dla różnych wariantów projektu.

Nie chodzi o to, że każde z tych narzędzi jest złe. Wręcz przeciwnie – wiele z nich przez lata rozwiązywało konkretne problemy bardzo dobrze. Pytanie brzmi raczej: czy tę samą odpowiedzialność możemy dziś opisać prościej i w bardziej spójny sposób?

Dobrze widać to w pyproject.toml, który może stać się jednym z głównych miejsc opisujących projekt:

pyproject.toml
[project]
requires-python = ">=3.12,<3.13"

dependencies = [
    "requests>=2.32,<3",
]

[dependency-groups]
dev = [
    "pytest",
    "ruff",
    "pre-commit",
]

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I"]

W jednym miejscu widzimy wersję Pythona, wymagania aplikacji, zależności potrzebne podczas developmentu oraz część zasad dotyczących jakości kodu.

Ruff może przejąć linting, formatowanie, porządkowanie importów i część obowiązków realizowanych wcześniej przez kilka osobnych narzędzi. Nie oznacza to, że pre-commit przestaje być potrzebny – nadal może być świetnym mechanizmem egzekwującym kontrole przed commitem. Zmienia się natomiast liczba elementów, które trzeba pod nim utrzymywać.

uv porządkuje drugą stronę projektu. Nie sprowadza zarządzania bibliotekami wyłącznie do ich instalowania. Potrafi zarządzać środowiskiem, wersją Pythona, zależnościami oraz ich konkretnym rozwiązaniem zapisanym w lockfile.

To szczególnie ważne wtedy, kiedy projekt nie może po prostu korzystać z dowolnej wersji biblioteki. W organizacjach konkretne wydania mogą być wcześniej przetestowane, zaakceptowane pod kątem bezpieczeństwa albo wynikać z kompatybilności z innymi elementami systemu. Takie ograniczenia powinny być częścią projektu, a nie ustaleniem przekazywanym między osobami.

Przykładowo:

pyproject.toml
[project]
dependencies = [
    "pydantic>=2.11,<2.12",
    "httpx>=0.27,<0.29",
]

Sam zapis zakresu wersji nie jest oczywiście niczym nowym – podobną kontrolę można było osiągnąć wcześniej za pomocą requirements.txt czy pyproject.toml. Ciekawie robi się wtedy, kiedy zaczynamy patrzeć na cały graf zależności.

Jedna biblioteka może wymagać:

common-lib >=2.0,<4.0

a druga:

common-lib >=3.1,<3.5

W takim przypadku istnieje wspólny zakres i resolver może znaleźć poprawne rozwiązanie.

Jeśli jednak wymagania wynoszą:

common-lib >=4.0
common-lib <4.0

żadne ręczne eksperymentowanie z instalacją pakietów nie zmieni faktu, że projekt ma sprzeczne wymagania.

Wniosek. Nie chodzi tylko o pobranie bibliotek, ale o znalezienie spójnego zestawu spełniającego wszystkie przyjęte ograniczenia – albo możliwie wczesne wykrycie, że taki zestaw nie istnieje.

Kiedy rozwiązanie zostanie znalezione, konkretny stan projektu może zostać zapisany w uv.lock. pyproject.toml opisuje więc, czego projekt wymaga i jakie zakresy akceptujemy, a lockfile przechowuje wynik rozwiązania tych wymagań. Dzięki temu kolejne środowisko nie musi podejmować tej samej decyzji od początku.

Widać to również w codziennej pracy z projektem. Zamiast ręcznie tworzyć środowisko, aktywować je, instalować zależności i dopiero później uruchamiać aplikację, można wykonać polecenie bezpośrednio w środowisku zarządzanym przez uv:

uv run python main.py

Tak samo możemy uruchamiać narzędzia będące częścią projektu:

uv run pytest
uv run ruff check .

uv przed wykonaniem polecenia dba o środowisko projektu i jego zgodność z zadeklarowanymi zależnościami. Jeśli środowisko jeszcze nie istnieje, może zostać utworzone automatycznie. Nie trzeba więc pamiętać osobnej sekwencji tworzenia virtualenv, jego aktywowania i ręcznej synchronizacji pakietów przed rozpoczęciem pracy.

Nie chodzi przy tym o samo skrócenie kilku komend. Ważniejsze jest to, że również sposób uruchamiania projektu staje się przewidywalny. Osoba, która pobierze repozytorium kilka miesięcy później, nie musi odtwarzać z dokumentacji właściwej kolejności przygotowania środowiska – projekt zawiera informacje potrzebne do wykonania tej pracy.

Podobnie wygląda kwestia różnych sposobów pracy z jednym repozytorium. Projekt może potrzebować innego zestawu bibliotek podczas developmentu, testów czy przygotowania wersji demonstracyjnej:

pyproject.toml
[dependency-groups]
dev = [
    "pytest",
    "ruff",
]

demo = [
    "faker",
    "rich",
]

Nie chodzi o samą wygodę posiadania kilku grup. Ważniejsze jest to, że również ta wiedza staje się częścią projektu. Nie trzeba pamiętać, że „do demo instalujemy jeszcze trzy dodatkowe paczki” albo szukać odpowiedniej instrukcji sprzed kilku miesięcy.

To właśnie jest dla nas najciekawsze w połączeniu uv i Ruffa. Nie dlatego, że wykonują więcej pracy za developera, lecz dlatego, że pozwalają więcej decyzji podjąć raz, zapisać je w projekcie i później konsekwentnie egzekwować.

Mniej decyzji, które musimy podjąć drugi raz

Ruff i uv nie są rozwiązaniem każdego problemu w projekcie i nie stanowią jedynej drogi do tworzenia dobrej jakości oprogramowania. Ruff nie podejmie za nas decyzji architektonicznej, resolver nie powie, czy aktualizacja biblioteki jest dobrym pomysłem biznesowo, a lockfile nie zastąpi testów.

I właśnie nie o to chodzi.

W naszej pracy zależy nam na tym, żeby człowiek podejmował przede wszystkim te decyzje, które rzeczywiście wymagają jego wiedzy i oceny. Wszystko, co jest powtarzalne, jednoznaczne i możliwe do zapisania jako reguła, warto możliwie wcześnie przenieść do samego projektu.

Dlatego nie traktujemy uv i Ruffa jako kolejnej technologicznej mody ani obowiązkowej wymiany narzędzi tylko dlatego, że pojawiło się coś nowego. Są szybkie, napisane w Rust i technicznie bardzo ciekawe, ale nie to jest dla nas najważniejsze.

Znacznie istotniejsze jest to, że dobrze wpisują się w sposób, w jaki chcemy tworzyć i utrzymywać projekty: zasady mają być jawne, środowiska możliwe do odtworzenia, wersje zależności kontrolowane, jakość egzekwowana automatycznie, a liczba rzeczy zależnych wyłącznie od pamięci człowieka możliwie mała.

Narzędzia będą się zmieniać. Za kilka lat część obecnego stacku może wyglądać zupełnie inaczej i to jest naturalne. Ważniejsza od przywiązania do konkretnego narzędzia jest zasada stojąca za jego wyborem: jeśli możemy uprościć sposób pracy bez utraty kontroli i jakości, warto to zrobić.

Dobre narzędzia nie powinny wymagać od nas większej uwagi. Powinny działać w tle i pilnować rzeczy powtarzalnych, pozostawiając ludziom czas na problemy, których nie da się sprowadzić do konfiguracji, reguły lintera czy lockfile’a.

Wniosek. Mniej narzędzi w głowie to po prostu więcej miejsca na sam projekt.

← Wszystkie wpisy