Python Academy · Lekcja

Wersjonowanie i metadane

Zarządzaj metadanymi pakietu

Wersjonowanie i metadane to bezpłatna lekcja Python Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Python Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Python Academy zawiera 4 lekcji w sumie.

Dlaczego metadane są ważne

Metadane to wszystkie informacje o pakiecie oprócz kodu: jego wersja, opis, licencja, autor i odnośniki. PyPI używa ich do prezentowania projektu, a pip — do rozwiązywania zależności.

Dobre metadane sprawiają, że pakiet budzi zaufanie i można go zainstalować.

Wersjonowanie semantyczne

Konwencja ma postać MAJOR.MINOR.PATCH:

MAJOR — zmiany niezgodne wstecz
MINOR — nowe funkcje zgodne wstecz
PATCH — poprawki błędów zgodne wstecz

Użytkownicy polegają na tej konwencji, aby wiedzieć, czy aktualizacja jest bezpieczna.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

Wybór kolejnej wersji

Wybór rodzaju zwiększenia wersji opiera się na regule: czy API zostało zmienione w sposób niezgodny wstecz, dodano funkcję, czy tylko naprawiono błąd? Zapisanie tej reguły sprawia, że wydania są spójne.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

Wersje przedpremierowe i deweloperskie

Python pozwala używać przyrostków: 1.0.0a1 (wersja alfa), 1.0.0b2 (wersja beta), 1.0.0rc1 (kandydat do wydania) oraz 1.0.0.dev3. pip traktuje je jako wcześniejsze od finalnej wersji 1.0.0, dzięki czemu testerzy mogą z nich korzystać bez wpływu na zwykłych użytkowników.

Jedno źródło prawdy

Wersję należy przechowywać dokładnie w jednym miejscu. Można zadeklarować ją statycznie w pliku pyproject.toml albo oznaczyć jako dynamic i odczytywać z kodu (lub znacznika) za pomocą narzędzi takich jak setuptools-scm. Dwie kopie nieuchronnie zaczną się od siebie różnić.

Opis i README

Krótki description pojawia się w wynikach wyszukiwania. Długi opis pochodzi z pola readme (zwykle README.md) i jest wyświetlany jako strona projektu w PyPI. Należy wskazać go za pomocą readme = 'README.md'.

Przejrzysty plik README to najlepsza forma promocji pakietu.

Licencja

Należy zadeklarować licencję, aby użytkownicy wiedzieli, jakie mają prawa. We współczesnych projektach używa się wyrażenia SPDX, takiego jak license = 'MIT'. Brak licencji oznacza zastrzeżenie wszystkich praw, co zniechęca do korzystania z projektu.

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

Klasyfikatory

classifiers to ustandaryzowane tagi z listy PyPI, takie jak 'Programming Language :: Python :: 3.11' lub 'Development Status :: 4 - Beta'. Zasilają one filtry PyPI i informują o dojrzałości projektu oraz obsługiwanych wersjach.

Adresy URL projektu

W sekcji [project.urls] należy dodać odnośniki, takie jak Homepage, Documentation, Source i Changelog. Są one wyświetlane na pasku bocznym w PyPI i pomagają użytkownikom znaleźć repozytorium oraz dokumentację.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

Słowa kluczowe ułatwiające znalezienie

Pole keywords to lista krótkich terminów, które pomagają użytkownikom znaleźć pakiet podczas wyszukiwania. Należy wybierać słowa, które użytkownicy rzeczywiście wpisaliby w wyszukiwarkę, takie jak ['cli', 'automation', 'excel'], zamiast ogólników.

W połączeniu z klasyfikatorami słowa kluczowe zwiększają widoczność projektu.

Dziennik zmian

Należy prowadzić plik CHANGELOG, w którym zapisywane są zmiany w każdej wersji. Użytkownicy czytają go przed aktualizacją, aby poznać nowe funkcje i zmiany niezgodne wstecz. Umieszczenie odnośnika do niego w sekcji [project.urls] sprawia, że można go otworzyć jednym kliknięciem ze strony w PyPI.

Dobry dziennik zmian zamienia numer wersji w historię, którą użytkownicy mogą śledzić.

Szybkie sprawdzenie

Proszę sprawdzić swoją wiedzę na temat wersjonowania.

Podsumowanie

Poznali Państwo metadane pakietu:

Wersjonowanie semantyczne MAJOR.MINOR.PATCH oraz przyrostki wersji przedpremierowych
Przechowywanie wersji w jednym źródle prawdy
Podanie description, długiego opisu w pliku README oraz license
Dodanie classifiers i [project.urls], aby PyPI dobrze prezentowało projekt

Często zadawane pytania

Czy lekcja „Wersjonowanie i metadane” jest bezpłatna?

Tak — pełny tekst „Wersjonowanie i metadane” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Python Academy, przejdź na CoddyKit PRO. Kurs Python Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Wersjonowanie i metadane”?

Zarządzaj metadanymi pakietu Ćwiczysz Python Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Python Academy?

Nie wymagamy żadnego doświadczenia. Python Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Wersjonowanie i metadane”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Python Academy?

Tak. Każda lekcja Python Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Python Academy