Skip to content

Konfigurowalna semantyka błędów importu (on_error) + adopcja download_to_model#607

Merged
mpasternak merged 16 commits into
devfrom
feat/pbn-adopt-api4
Jul 24, 2026
Merged

Konfigurowalna semantyka błędów importu (on_error) + adopcja download_to_model#607
mpasternak merged 16 commits into
devfrom
feat/pbn-adopt-api4

Conversation

@mpasternak

@mpasternak mpasternak commented Jul 14, 2026

Copy link
Copy Markdown
Member

Ostatni element adopcji API PBN 0.2 (stack na #606). Adoptuje pakietowy
download_to_model w sposób opt-in, z zerową zmianą zachowania domyślnego.

Kontekst decyzji

pobierz_mongodb (współdzielony getter sekwencyjny) był fail-fast:
download_pbn_objects woła save() w gołej pętli bez try/except, więc błąd
zapisu jednego rekordu do lokalnego lustra BPP (IntegrityError, zły
kształt danych — po naszej stronie, nie PBN) przerywał cały import. Przy pełnych
synchronizacjach (tysiące–dziesiątki tysięcy rekordów) jeden zepsuty rekord
kasował cały przebieg.

Zmiana — parametr on_error

  • "raise" (default) — fail-fast jak dotąd. Zwraca None. Zero zmiany
    dla istniejących callerów.
  • "skip" — deleguje do pakietowego download_to_model: zły rekord
    logowany (pełny traceback) + liczony, import reszty listy kończy się. Zwraca
    DownloadResult(processed, errored).

Nieznana wartość → ValueError (głośno, bez cichego wyboru trybu).
Adopcja włączana opt-in per-getter po Twojej decyzji — ten PR tylko
udostępnia zdolność.

Dlaczego tak (a nie mechaniczna podmiana)

iter_pages nie pasuje do jedynych dwóch ręcznych page-loopów BPP
(pobierz_skasowane_prace, offline_data — oba multiprocessing per-page).
Wątkowy download_pages już ma paczkową obsługę błędów stron. Jedyny sensowny,
bezpieczny zysk to konfigurowalna semantyka błędów sekwencyjnego importu.

Weryfikacja

  • manage.py check: OK
  • pytest .../test_mongodb_ops.py .../test_pobierz_mongodb_on_error.py:
    15 passed (12 istniejących + 3 nowe: fail-fast default, skip
    kontynuuje+liczy, ValueError)
  • ruff check + format: clean

🤖 Generated with Claude Code

mpasternak and others added 10 commits July 14, 2026 20:27
@mpasternak
Extract reusable PBN client packages
792eaa8
@mpasternak @claude
Przemianuj hook getterów pbn_api_klass -> model_class
b986df8 
Atrybut wiążący model w getterach stron PBN niósł nazwę z monorepo
(pbn_api). Ujednolicony z pakietem django-pbn-client: baza deklaruje
class-attr `model_class = None`, konstruktor nie przesłania go None-em,
a InstitutionGetter/ZrodlaGetter/PublisherGetter oraz shim
ThreadedMongoDBSaver używają nowej nazwy.

manage.py check: OK; pakiet + test_helpers: 40 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
build(pbn): przepnij BPP na paczki PBN z PyPI, usuń przejściowe packa…
859e5b8 
…ges/

Krok 1 planu ekstrakcji: BPP konsumuje pbn-client i django-pbn-client jako
normalne zależności z PyPI (0.1.0, github.com/iplweb/*) zamiast lokalnych
memberów uv workspace.

- usunięto katalog packages/ (kopie robocze) — źródłem jest teraz PyPI,
- pyproject: usunięto [tool.uv.workspace] i wpisy `{ workspace = true }`
  z [tool.uv.sources] (django-import-export git-source zostaje); deps
  pbn-client/django-pbn-client bez zmian,
- pytest.ini: testpaths = src (bez packages),
- Dockerfile: usunięto 4× `COPY packages/` (obraz nie ma już tego katalogu),
- .dockerignore: usunięto regułę README paczek,
- uv.lock: przeliczony (paczki z indeksu, nie editable).

Weryfikacja: paczki zainstalowane z PyPI (==0.1.0, nie editable);
manage.py check OK; makemigrations --check bez dryfu w pbn_api/django_pbn_client
(pozostały dryf to pre-existing third-party AutoField: favicon/flexible_reports/
siteblog); test_helpers + test_validators 31 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Podnieś zależności PBN do 0.2 i zaktualizuj dokumentację
6290536 
- pbn-client / django-pbn-client: >=0.2,<0.3 (wave 0.2 z PyPI), uv.lock przeliczony,
- przepisany docs/deweloper/pakiety-pbn.md: architektura PyPI zamiast workspace
  (usunięty opis packages/ + Docker copy + komend na nieistniejące ścieżki),
- zaktualizowane docs/deweloper/index.md i newsfragment,
- usunięte 48 nieaktualnych wpisów packages/* z .test_durations.

Weryfikacja: manage.py check OK; makemigrations --check bez dryfu pbn;
test_helpers + test_validators 31 passed na paczkach 0.2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
test(pbn): użyj correlation_id w StatementsResendFailedException
a27cafa 
pbn-client 0.2 przemianował parametr konstruktora publication_pk -> correlation_id
(z property publication_pk do odczytu, ale nie jako kwarg konstruktora).
Test kolejki konstruował wyjątek z publication_pk= -> TypeError. Adopcja
nowej nazwy w teście.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Adoptuj API paczek PBN 0.2: is_deleted, is_valid_object_id, get_or_do…
e64b855 
…wnload

- 6 modeli PBN (journal, institution, publisher, publication, scientist,
  conference) używa property `is_deleted` z BasePBNMongoDBModel zamiast
  magic-stringa `status == "DELETED"` (marker „[❌ USUNIĘTY]" bez zmian)
- `check_mongoId` deleguje do `pbn_client.is_valid_object_id`
  (ta sama semantyka: 24-znakowy hex objectId)
- `ensure_publication/person/institution_exists` delegują do
  `django_pbn_client.get_or_download` z zachowaniem wrappera
  `zapisz_mongodb` (fetch przed transakcją persystencji)
- test blokujący zachowanie markera USUNIĘTY w __str__ 6 modeli

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Adoptuj pbn_client.normalize_author_name w BPP (2 site'y)
811fc31 
Dwa miejsca normalizowały dane osobowe autora z PBN własnymi,
rozjeżdżającymi się łańcuchami preferencji:

- pbn_api/models/publication.py (_normalizuj_autora): lastName +
  firstName/givenNames/name, brak familyName;
- pbn_import/.../pbn_importuj_uid.py: familyName/lastName +
  givenNames/name, brak firstName, brak guardu na nie-dict.

Oba delegują teraz do jednego źródła prawdy — pbn_client.normalize_author_name
(unia kluczy: familyName→lastName, firstName→givenNames→name; nie-dict →
brak danych). Paczka używa None jako sentinela pustki; oba site'y koerują go
do "" (szablon rekordu i str(autorzy) w logach zakładają puste stringi, a
display-line importu składa f-string).

Zysk: rozpoznanie familyName (publication) i firstName (import) tam, gdzie
wcześniej wypadało puste; bezpieczeństwo na nie-dict w komendzie importu.
Zachowany zamrożony ""-kontrakt (test goły-UID) + nowy test familyName.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Adoptuj pakietowe helpery oświadczeń w pbn_test_wysylka_interaktywna
3b763af 
Interaktywne narzędzie diagnostyczne trzymało własne kopie logiki, którą
mamy teraz w pbn-client. Podmienione na jedno źródło prawdy:

- _extract_object_id → pbn_client.decode_publication_object_id
  (mapowanie endpoint_choice → bez_oswiadczen: "publications"=all-in-one
  → False, "repositorium" → True). Paczka przy niejednoznacznej odpowiedzi
  (lista != 1 element, zły typ) RZUCA zamiast po cichu zwracać None —
  narzędzie łapie to głośno, pokazuje surową odpowiedź i pyta usera czy
  wyjść czy jechać dalej z objectId=None (decyzja usera: rzadko używane,
  niech krzyczy i pyta).
- lokalny _key → pakietowe statement_key_pbn / statement_key_intended;
  różnice liczy diff_statements, część wspólną (której paczka nie zwraca)
  liczymy lokalnie na tych samych kluczach.

Testy: nowy test integracyjny (niejednoznaczna odpowiedź → głośny błąd +
przerwanie pod --yes-all) + unit gałęzi "kontynuuj" (zwraca None).
16 passed w suicie komendy, 339 w całym pbn_api. ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
P3: BrakIDPracyPoStroniePBN = alias PublicationNotFound (rozpoznanie …
f10bd84 
…w paczce)

Rozpoznanie 422 "was not exists!" robi teraz RAZ endpoint paczki
(pbn_client.get_publication_by_id rzuca PublicationNotFound) — BPP nie
duplikuje już tej detekcji w call-site.

- pbn_api/exceptions.py: BrakIDPracyPoStroniePBN staje się aliasem
  PublicationNotFound (przypisanie, ta sama klasa, `is`) zamiast osobnej
  podklasy HttpException. Dzięki temu istniejące `except
  BrakIDPracyPoStroniePBN` (odswiez_tabele_publikacji kasujący cache;
  worker importu zwracający per-item fail) łapią wyjątek rzucany przez
  paczkę. To CO INNEGO niż BPPPublicationNotFound (brak rekordu BPP).
- pbn_integrator/utils/publications.py (_pobierz_pojedyncza_prace):
  usunięto ręczną re-detekcję markera w treści; PublicationNotFound
  propagujemy, zwykły HttpException (w tym 404) leci dalej, 500
  "Internal server error" nadal → None.

Decyzja 404 (zapisana w planie): 404 bywa przejściowy → NIE jest "brak
pracy", nie kasuje lokalnego cache'u. Ani paczka, ani BPP nie mapują 404
na PublicationNotFound.

Testy przepisane na nowy kontrakt: alias-identity, PublicationNotFound z
paczki → propagacja jako BrakID (pola HTTP zachowane), 404 ≠ BrakID, goły
422 nie jest już re-detektowany przez BPP, 500 → None.
540 passed (pbn_integrator + pbn_api), ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Konfigurowalna semantyka błędów w pobierz_mongodb (on_error, download…
baf92a1 
…_to_model)

pobierz_mongodb dostaje parametr on_error sterujący zachowaniem przy błędzie
zapisu POJEDYNCZEGO rekordu do lokalnego lustra BPP (IntegrityError, zły
kształt danych itp. — po naszej stronie, nie PBN):

- "raise" (default) — fail-fast jak dotąd: pierwszy błąd propaguje i przerywa
  batch (download_pbn_objects, goła pętla save bez try/except). Zwraca None.
- "skip" — deleguje do pakietowego download_to_model: zły rekord logowany
  (pełny traceback) + liczony, import reszty kończy się. Zwraca
  DownloadResult(processed, errored). Dla masowych synchronizacji (tysiące
  rekordów), gdzie jeden zepsuty rekord nie powinien wywalać całego przebiegu.

Zachowanie domyślne bez zmian — żaden istniejący caller nie zmienia
zachowania (default "raise"). Adopcja download_to_model włączana opt-in
per-getter po decyzji. Nieznana wartość on_error → ValueError (głośno).

Etykieta progress-baru ujednolicona między trybami (fasada nie forwarduje
pbar_label). Testy: fail-fast default, skip kontynuuje+liczy, ValueError.
3 nowe + 12 istniejących mongodb_ops passed, check OK, ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak mpasternak mentioned this pull request Jul 14, 2026
Merged
mpasternak and others added 3 commits July 24, 2026 16:45
@mpasternak @claude
Adopcja API PBN 0.2 batch 2: normalize_author_name + helpery oświadcz…
e930ff2 
…eń (#604)

* Adoptuj pbn_client.normalize_author_name w BPP (2 site'y)

Dwa miejsca normalizowały dane osobowe autora z PBN własnymi,
rozjeżdżającymi się łańcuchami preferencji:

- pbn_api/models/publication.py (_normalizuj_autora): lastName +
  firstName/givenNames/name, brak familyName;
- pbn_import/.../pbn_importuj_uid.py: familyName/lastName +
  givenNames/name, brak firstName, brak guardu na nie-dict.

Oba delegują teraz do jednego źródła prawdy — pbn_client.normalize_author_name
(unia kluczy: familyName→lastName, firstName→givenNames→name; nie-dict →
brak danych). Paczka używa None jako sentinela pustki; oba site'y koerują go
do "" (szablon rekordu i str(autorzy) w logach zakładają puste stringi, a
display-line importu składa f-string).

Zysk: rozpoznanie familyName (publication) i firstName (import) tam, gdzie
wcześniej wypadało puste; bezpieczeństwo na nie-dict w komendzie importu.
Zachowany zamrożony ""-kontrakt (test goły-UID) + nowy test familyName.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Adoptuj pakietowe helpery oświadczeń w pbn_test_wysylka_interaktywna

Interaktywne narzędzie diagnostyczne trzymało własne kopie logiki, którą
mamy teraz w pbn-client. Podmienione na jedno źródło prawdy:

- _extract_object_id → pbn_client.decode_publication_object_id
  (mapowanie endpoint_choice → bez_oswiadczen: "publications"=all-in-one
  → False, "repositorium" → True). Paczka przy niejednoznacznej odpowiedzi
  (lista != 1 element, zły typ) RZUCA zamiast po cichu zwracać None —
  narzędzie łapie to głośno, pokazuje surową odpowiedź i pyta usera czy
  wyjść czy jechać dalej z objectId=None (decyzja usera: rzadko używane,
  niech krzyczy i pyta).
- lokalny _key → pakietowe statement_key_pbn / statement_key_intended;
  różnice liczy diff_statements, część wspólną (której paczka nie zwraca)
  liczymy lokalnie na tych samych kluczach.

Testy: nowy test integracyjny (niejednoznaczna odpowiedź → głośny błąd +
przerwanie pod --yes-all) + unit gałęzi "kontynuuj" (zwraca None).
16 passed w suicie komendy, 339 w całym pbn_api. ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
Odchudź shimy PBN: usuń pbn_api.const/utils/client.transport (#609)
3c40190 
Trzy pliki w pbn_api były czystymi re-eksportami z pakietów PBN
(`from pbn_client.X import *`) — zbędna warstwa pośrednia po tym jak kod
klienta wyszedł na PyPI. Usunięte + repoint callerów wprost na paczkę:

- pbn_api/const.py            → callery: from pbn_client.const import ...   (22 plików)
- pbn_api/utils.py            → from pbn_client.dict_utils import ...        (2)
- pbn_api/client/transport.py → from pbn_client.transport import ...        (1)

Spójne z resztą kodu po ekstrakcji (mongodb_ops itd. już importują wprost
z pbn_client/django_pbn_client).

ZOSTAWIONE świadomie:
- pbn_api/exceptions.py — hybryda: wyjątki BPP-specific + alias
  BrakIDPracyPoStroniePBN = PublicationNotFound.
- pbn_api/models/base.py — seam pod przyszłą Fazę 3 (abstrakcyjne modele).

Czysto mechaniczne (tylko podmiana ścieżki modułu, nazwy bez zmian).
Review: fable PASS + codex SHIP (brak defektów). manage.py check OK,
pbn_api 339 passed, zero nowych naruszeń ruff. Pre-existing lint
(F401/I001/UP012 w tkniętych plikach) świadomie NIE ruszany — poza zakresem.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mpasternak @claude
P3: BrakIDPracyPoStroniePBN = alias PublicationNotFound (rozpoznanie …
e215199 
…422 w paczce) (#606)

* Adoptuj pbn_client.normalize_author_name w BPP (2 site'y)

Dwa miejsca normalizowały dane osobowe autora z PBN własnymi,
rozjeżdżającymi się łańcuchami preferencji:

- pbn_api/models/publication.py (_normalizuj_autora): lastName +
  firstName/givenNames/name, brak familyName;
- pbn_import/.../pbn_importuj_uid.py: familyName/lastName +
  givenNames/name, brak firstName, brak guardu na nie-dict.

Oba delegują teraz do jednego źródła prawdy — pbn_client.normalize_author_name
(unia kluczy: familyName→lastName, firstName→givenNames→name; nie-dict →
brak danych). Paczka używa None jako sentinela pustki; oba site'y koerują go
do "" (szablon rekordu i str(autorzy) w logach zakładają puste stringi, a
display-line importu składa f-string).

Zysk: rozpoznanie familyName (publication) i firstName (import) tam, gdzie
wcześniej wypadało puste; bezpieczeństwo na nie-dict w komendzie importu.
Zachowany zamrożony ""-kontrakt (test goły-UID) + nowy test familyName.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Adoptuj pakietowe helpery oświadczeń w pbn_test_wysylka_interaktywna

Interaktywne narzędzie diagnostyczne trzymało własne kopie logiki, którą
mamy teraz w pbn-client. Podmienione na jedno źródło prawdy:

- _extract_object_id → pbn_client.decode_publication_object_id
  (mapowanie endpoint_choice → bez_oswiadczen: "publications"=all-in-one
  → False, "repositorium" → True). Paczka przy niejednoznacznej odpowiedzi
  (lista != 1 element, zły typ) RZUCA zamiast po cichu zwracać None —
  narzędzie łapie to głośno, pokazuje surową odpowiedź i pyta usera czy
  wyjść czy jechać dalej z objectId=None (decyzja usera: rzadko używane,
  niech krzyczy i pyta).
- lokalny _key → pakietowe statement_key_pbn / statement_key_intended;
  różnice liczy diff_statements, część wspólną (której paczka nie zwraca)
  liczymy lokalnie na tych samych kluczach.

Testy: nowy test integracyjny (niejednoznaczna odpowiedź → głośny błąd +
przerwanie pod --yes-all) + unit gałęzi "kontynuuj" (zwraca None).
16 passed w suicie komendy, 339 w całym pbn_api. ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* P3: BrakIDPracyPoStroniePBN = alias PublicationNotFound (rozpoznanie w paczce)

Rozpoznanie 422 "was not exists!" robi teraz RAZ endpoint paczki
(pbn_client.get_publication_by_id rzuca PublicationNotFound) — BPP nie
duplikuje już tej detekcji w call-site.

- pbn_api/exceptions.py: BrakIDPracyPoStroniePBN staje się aliasem
  PublicationNotFound (przypisanie, ta sama klasa, `is`) zamiast osobnej
  podklasy HttpException. Dzięki temu istniejące `except
  BrakIDPracyPoStroniePBN` (odswiez_tabele_publikacji kasujący cache;
  worker importu zwracający per-item fail) łapią wyjątek rzucany przez
  paczkę. To CO INNEGO niż BPPPublicationNotFound (brak rekordu BPP).
- pbn_integrator/utils/publications.py (_pobierz_pojedyncza_prace):
  usunięto ręczną re-detekcję markera w treści; PublicationNotFound
  propagujemy, zwykły HttpException (w tym 404) leci dalej, 500
  "Internal server error" nadal → None.

Decyzja 404 (zapisana w planie): 404 bywa przejściowy → NIE jest "brak
pracy", nie kasuje lokalnego cache'u. Ani paczka, ani BPP nie mapują 404
na PublicationNotFound.

Testy przepisane na nowy kontrakt: alias-identity, PublicationNotFound z
paczki → propagacja jako BrakID (pola HTTP zachowane), 404 ≠ BrakID, goły
422 nie jest już re-detektowany przez BPP, 500 → None.
540 passed (pbn_integrator + pbn_api), ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Base automatically changed from feat/pbn-adopt-api3 to feat/pbn-adopt-api July 24, 2026 14:50
@mpasternak
Merge remote-tracking branch 'origin/dev' into feat/pbn-adopt-api
2a76fcf 
# Conflicts:
#	src/pbn_api/exceptions.py
#	src/pbn_integrator/utils/mongodb_ops.py
@mpasternak
Merge branch 'feat/pbn-adopt-api' into feat/pbn-adopt-api4
108a6da 
# Conflicts:
#	src/pbn_api/management/commands/pbn_test_wysylka_interaktywna.py
#	src/pbn_integrator/utils/publications.py
Base automatically changed from feat/pbn-adopt-api to dev July 24, 2026 15:03
@mpasternak
Merge remote-tracking branch 'origin/dev' into feat/pbn-adopt-api4
53ab35d 
# Conflicts:
#	src/pbn_api/management/commands/pbn_test_wysylka_interaktywna.py
#	src/pbn_integrator/utils/publications.py
@mpasternak
mpasternak merged commit a850b2d into dev Jul 24, 2026
9 of 10 checks passed
@mpasternak
mpasternak deleted the feat/pbn-adopt-api4 branch July 24, 2026 15:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mpasternak