JAK OPUBLIKOWAC BIBLIOTEKE GLOBALNIE NA PYPI
Projekt: demo_colors
Data sprawdzenia linkow i stanu: 2026-03-31

Najwazniejsza uwaga:
- "Globalnie" w praktyce oznacza publikacje na publicznym indeksie pakietow, zwykle PyPI.
- Uzytkownik koncowy nadal musi ZAINSTALOWAC pakiet przynajmniej raz, np.:
  python -m pip install demo_colors
- Dopiero potem moze uzyc:
  import demo_colors
- Sam import NIE pobiera pakietu z internetu.

Stan nazwy "demo_colors" na dzien 2026-03-31:
- Strona https://pypi.org/project/demo_colors/ zwracala 404, wiec nazwa wyglada na wolna.
- To nie jest gwarancja. PyPI ostatecznie potwierdza nazwe dopiero przy pierwszym uploadzie.

ILE TRWA "PROPAGACJA" PACZKI PO PUBLIKACJI

Krotka odpowiedz praktyczna:
- najczesciej: od kilku sekund do 2-5 minut
- czasem: do kilkunastu minut
- bezpieczne zalozenie na cwiczenia: odczekaj 10-15 minut przed rozdaniem komendy instalacji uczestnikom

Co zwykle pojawia sie najszybciej:
- strona projektu na PyPI, np. https://pypi.org/project/demo_colors/
- JSON projektu, np. https://pypi.org/pypi/demo_colors/json
- indeks projektu, np. https://pypi.org/simple/demo-colors/

Dlaczego czas nie jest zawsze identyczny:
- PyPI jest globalnie keszowane i rozprowadzane przez CDN
- pip i rozne wezly sieci moga przez chwile widziec starszy stan
- pierwsza publikacja nowego projektu moze wygladac jak "juz jest na stronie, ale instalacja jeszcze nie widzi"

Wazne:
- nie znalazlem oficjalnej strony PyPI, ktora gwarantuje konkretny czas propagacji w stylu "1 minuta" albo "5 minut"
- to jest ocena praktyczna oparta na tym, ze PyPI oficjalnie informuje, iz jest mocno keszowane i dystrybuowane przez CDN, ale bez SLA dla takiego opoznienia

Jak sprawdzac, czy publikacja jest juz widoczna:
1. Otworz strone projektu:
   https://pypi.org/project/demo_colors/
2. Sprawdz JSON:
   https://pypi.org/pypi/demo_colors/json
3. Sprawdz indeks simple:
   https://pypi.org/simple/demo-colors/
4. Sprawdz instalacje w czystym venv:
   python -m pip install demo_colors

Rekomendacja do warsztatow:
- jesli chcesz uniknac losowych opoznien, opublikuj pakiet minimum 15-30 minut przed cwiczeniem
- najlepiej nawet dzien wczesniej i przetestuj:
  python -m pip install demo_colors
  python -c "import demo_colors"

OFICJALNE LINKI
- Rejestracja konta PyPI: https://pypi.org/account/register/
- Logowanie do PyPI: https://pypi.org/account/login/
- Panel konta PyPI: https://pypi.org/manage/account/
- Ustawienie 2FA: https://pypi.org/manage/account/two-factor/
- Tokeny API PyPI: https://pypi.org/manage/account/token/
- Trusted Publishers docs: https://docs.pypi.org/trusted-publishers/
- Ustawienia Trusted Publishing w PyPI: https://pypi.org/manage/account/publishing/
- Packaging flow: https://packaging.python.org/en/latest/flow/
- Publikacja przez GitHub Actions: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
- Specyfikacja .pypirc: https://packaging.python.org/en/latest/specifications/pypirc/
- PyPI Help: https://pypi.org/help/
- JSON API: https://docs.pypi.org/api/json/
- Index API: https://docs.pypi.org/api/index-api/

OPCJA A: NAJSZYBSZA DROGA, RECZNA PUBLIKACJA Z TOKENEM API

Krok 1. Zaloz konto PyPI
1. Otworz:
   https://pypi.org/account/register/
2. Uzupelnij formularz:
   - Name
   - Email address
   - Username
   - Password
3. Potwierdz rejestracje.
4. Zaloguj sie:
   https://pypi.org/account/login/

Krok 2. Zweryfikuj adres e-mail
1. Wejdz do panelu:
   https://pypi.org/manage/account/
2. Jesli adres nie jest potwierdzony, uzyj opcji wyslania maila weryfikacyjnego.
3. Kliknij link z maila i wroc do panelu konta.

Krok 3. Wlacz 2FA
PyPI wymaga 2FA do czynnosci zarzadzajacych i publikacji.
1. Otworz:
   https://pypi.org/manage/account/two-factor/
2. Wybierz metode:
   - aplikacja TOTP, albo
   - klucz sprzetowy
3. Skonfiguruj 2FA do konca.
4. Wygeneruj i zachowaj recovery codes.

Krok 4. Utworz token API do publikacji
1. Otworz:
   https://pypi.org/manage/account/token/
2. Kliknij "Add API token".
3. Na pierwszy upload mozesz wybrac token dla calego konta albo ograniczyc go do projektu pozniej.
4. Skopiuj token OD RAZU po utworzeniu.
5. Zachowaj go bezpiecznie. PyPI nie pokazuje go ponownie.

Krok 5. Przygotuj lokalnie paczke do uploadu
W PowerShell:

cd C:\tworzenie_biblioteki\demo_colors
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Po tych komendach powinienes miec pliki w folderze:
  C:\tworzenie_biblioteki\demo_colors\dist

Krok 6. Opublikuj pierwsza wersje na PyPI
W tym samym katalogu uruchom:

python -m twine upload dist/*

Podczas logowania przez Twine:
- username: __token__
- password: wklej caly token PyPI, lacznie z prefiksem pypi-

Uwaga:
- Nie trzeba rejestrowac nazwy projektu osobno przed uploadem.
- Pierwszy poprawny upload tworzy projekt na PyPI.

Krok 7. Sprawdz, czy projekt jest publiczny
Po udanym uploadzie sprawdz:
  https://pypi.org/project/demo_colors/

Krok 8. Sprawdz instalacje jako uzytkownik koncowy
Na innej maszynie lub w czystym venv:

python -m pip install demo_colors
python -c "import demo_colors"

Oczekiwany efekt:
- pakiet sie instaluje bez wskazywania repozytorium
- samo "import demo_colors" wypisuje:
  Def_Con_PoC_2026

OPCJA B: PREFEROWANA, BEZPIECZNIEJSZA PUBLIKACJA PRZEZ GITHUB ACTIONS + TRUSTED PUBLISHING

Ta opcja jest rekomendowana oficjalnie, bo nie trzymasz stalego tokena w komendach ani sekretach.

Krok 1. Zaloz konto PyPI
- Te same kroki jak wyzej: rejestracja, weryfikacja email, 2FA.

Krok 2. Miej repozytorium na GitHub
- Potrzebujesz repo, z ktorego bedzie publikowana paczka.
- Jesli nie masz konta GitHub:
  https://github.com/signup

Krok 3. Dodaj Trusted Publisher w PyPI
1. Otworz:
   https://pypi.org/manage/account/publishing/
2. Dodaj nowy Trusted Publisher.
3. W formularzu podaj:
   - PyPI project name: demo_colors
   - Owner: nazwa uzytkownika lub organizacji na GitHub
   - Repository name: nazwa repozytorium GitHub
   - Workflow name: nazwa workflow publikujacego, np. publish.yml albo release.yml
   - Environment name: np. pypi

Krok 4. Dodaj workflow na GitHub
Najbardziej aktualny oficjalny przewodnik:
https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

Ten przewodnik pokazuje:
- budowanie wheel i sdist
- ustawienie permissions: id-token: write
- publikacje przez pypa/gh-action-pypi-publish
- publikacje po pushu taga

Krok 5. Wypchnij tag/release
- Po poprawnym workflow GitHub opublikuje pakiet na PyPI.
- Potem sprawdzasz:
  https://pypi.org/project/demo_colors/

KIEDY WARTO UZYC TESTPYPI

Jesli chcesz przetestowac publikacje przed prawdziwym PyPI:
- Rejestracja TestPyPI: https://test.pypi.org/account/register/
- Konto TestPyPI jest osobne od PyPI.
- Token TestPyPI: https://test.pypi.org/manage/account/token/
- Upload do TestPyPI:
  python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Potem test instalacji:
  python -m pip install --index-url https://test.pypi.org/simple/ demo_colors

NAJKROTSZA SCIEZKA DLA TEGO KONKRETNEGO PROJEKTU

1. Zaloz konto na https://pypi.org/account/register/
2. Potwierdz email w https://pypi.org/manage/account/
3. Wlacz 2FA w https://pypi.org/manage/account/two-factor/
4. Utworz token w https://pypi.org/manage/account/token/
5. W katalogu C:\tworzenie_biblioteki\demo_colors uruchom:
   python -m pip install --upgrade build twine
   python -m build
   python -m twine check dist/*
   python -m twine upload dist/*
6. Sprawdz:
   https://pypi.org/project/demo_colors/
7. Uzytkownicy beda mogli instalowac bez podawania repo:
   python -m pip install demo_colors

JESLI CHCESZ MAKSYMALNIE MALO KROKOW

Najprostsza praktyczna odpowiedz brzmi:
- zaloz konto PyPI
- wlacz 2FA
- utworz token API
- wykonaj "twine upload dist/*"

JESLI CHCESZ MAKSYMALNIE BEZPIECZNIE

Lepsza odpowiedz brzmi:
- zaloz konto PyPI
- wlacz 2FA
- ustaw GitHub + Trusted Publishing
- publikuj z workflow GitHub Actions
