Metadata-Version: 2.4
Name: django-polish-inflection
Version: 0.1.0
Summary: Cienka warstwa Django (template tagi i filtry) nad polish-inflection — odmiana rzeczowników przez przypadki.
Project-URL: Homepage, https://github.com/iplweb/django-polish-inflection
Project-URL: Repository, https://github.com/iplweb/django-polish-inflection
Project-URL: Issues, https://github.com/iplweb/django-polish-inflection/issues
Author-email: Michał Pasternak <m@iplweb.pl>
License: BSD-2-Clause
License-File: LICENSE
Keywords: declension,django,inflection,odmiana,polish,przypadki,templatetags
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: Polish
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: django>=5.2
Requires-Dist: polish-inflection>=0.7.0
Description-Content-Type: text/markdown

# django-polish-inflection

[![CI](https://github.com/iplweb/django-polish-inflection/actions/workflows/ci.yml/badge.svg)](https://github.com/iplweb/django-polish-inflection/actions/workflows/ci.yml)
[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD--2--Clause-blue.svg)](LICENSE)

Cienka warstwa Django (template tagi i filtry) nad
[`polish-inflection`](https://github.com/iplweb/polish-inflection) —
odmiana polszczyzny wprost w szablonach Django, oparta o słownik SGJP:

- **rzeczowniki** przez wszystkie przypadki i obie liczby (`odmien`,
  aliasy pytajne `kogo_czego`/`komu_czemu`/…),
- **frazy wielowyrazowe** (nazwy własne instytucji, np. „Uniwersytet
  Lubelski") — `odmien_fraze`,
- **przymiotniki** wg rodzaju głowy — `odmien_przymiotnik`,
- **dobór formy wg liczebnika** (1 wydział / 2 wydziały / 5 wydziałów) —
  `odmiana_liczebnikowa`.

<p align="center">
  <img src="https://raw.githubusercontent.com/iplweb/django-polish-inflection/v0.1.0/sshot1.png" alt="Odmieniarka — przykładowy projekt: pełna tabela odmiany przez przypadki" width="640">
  <br>
  <sub><i>Przykładowy projekt <a href="example_project/">„Odmieniarka"</a> — pełna tabela odmiany przez przypadki wprost w przeglądarce.</i></sub>
</p>

<p align="center">
  <b>Support graciously provided by</b><br><br>
  <a href="https://www.iplweb.pl"><img src="https://www.iplweb.pl/images/ipl-logo-large.png" width="120" alt="IPLweb"></a>
</p>

## Instalacja

```bash
pip install django-polish-inflection
```

Dodaj do `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...,
    "django_polish_inflection",
]
```

## Użycie

Wczytaj bibliotekę tagów raz na szablon przez `{% load polish_inflection %}` — od
tej chwili masz w szablonie cztery narzędzia: generyczny `odmien` (dowolny
przypadek), zestaw czytelnych aliasów pytajnych (`kogo_czego`, `komu_czemu`, …),
dobór formy wg liczebnika (`odmiana_liczebnikowa`) i odmianę wielowyrazowych nazw
własnych (`odmien_fraze`). Większość działa i jako **tag** `{% … %}`, i — gdy
wystarczy sam przypadek — jako **filtr** `|…`; oba warianty zwracają to samo.

```django
{% load polish_inflection %}
```

Dla przykładowych danych `nazwa_jednostki = "wydział"` i `liczba = 5`
(w komentarzach `{# → … #}` jest wynik renderowania):

**Dowolny przypadek — generyczny `odmien`** (w tym mianownik i wołacz, których
aliasów pytajnych brak):

```django
{{ nazwa_jednostki|odmien:"dopelniacz" }}
{# → wydziału #}

{% odmien nazwa_jednostki "dopelniacz" %}
{# → wydziału #}

{% odmien nazwa_jednostki "dopelniacz" liczba="mnoga" %}
{# → wydziałów #}

{% odmien nazwa_jednostki "dopelniacz" as forma %}{{ forma }}
{# → wydziału #}
```

**Aliasy pytajne** — czytają się jak zdanie, wystawiane automatycznie z
`polish_inflection.pytania`:

```django
Oto lista pracowników {% kogo_czego nazwa_jednostki %}
{# → Oto lista pracowników wydziału #}

Kliknij przycisk z {% z_kim_z_czym nazwa_jednostki %}
{# → Kliknij przycisk z wydziałem #}

{% komu_czemu nazwa_jednostki liczba="mnoga" %}
{# → wydziałom #}

{% podstawowa_forma "wydziałów" %}
{# → wydział #}
```

**Dobór formy wg liczebnika** — polska zgoda liczebnikowa (1 wydział / 2 wydziały
/ 5 wydziałów); numer doklejasz sam:

```django
{{ liczba }} {% odmiana_liczebnikowa nazwa_jednostki liczba %}
{# → 5 wydziałów #}

{% odmiana_liczebnikowa nazwa_jednostki liczba "narzednik" %}
{# → wydziałami #}
```

**Frazy wielowyrazowe i przymiotniki** — nazwy własne instytucji oraz sam
przymiotnik wg rodzaju:

```django
{% odmien_fraze "Uniwersytet Lubelski" "dopelniacz" %}
{# → Uniwersytetu Lubelskiego #}

{{ "Akademia Medyczna"|odmien_fraze:"narzednik" }}
{# → Akademią Medyczną #}

{% odmien_przymiotnik "lubelski" "dopelniacz" "meski" %}
{# → lubelskiego #}
```

Dostępne aliasy pytajne (dokładnie te, które eksportuje zainstalowana wersja
`polish_inflection.pytania.__all__` — nowe funkcje upstreamu o zgodnej
sygnaturze `(wyraz, *, liczba=None, default=...)` pojawiają się tu
automatycznie): `kogo_czego`, `komu_czemu`, `kogo_co`, `z_kim_z_czym`,
`o_kim_o_czym`, `podstawowa_forma`, oraz skróty `komu`, `czemu`, `z_kim`,
`z_czym`, `o_kim`, `o_czym`.

Mianownik i wołacz nie mają aliasu pytajnego (upstream też ich nie ma) —
używaj do nich generycznego `{% odmien wyraz "mianownik" %}` / `"wolacz"`.

### Odmiana liczebnikowa

`{% odmiana_liczebnikowa wyraz liczba %}` zwraca **rzeczownik** w formie
narzuconej przez liczebnik (polska zgoda liczebnikowa: `1 wydział`,
`2 wydziały`, `5 wydziałów`). Liczby słownie nie generuje — numer doklejasz
sam. Rodzaj (w tym męskoosobowy m1, np. `2 studentów` a nie `2 studenci`) jest
wykrywany automatycznie ze słownika. Opcjonalny trzeci argument to przypadek
frazy (domyślnie mianownik), np. `{% odmiana_liczebnikowa wyraz liczba "narzednik" %}`
przy `liczba=5` zwraca `wydziałami` (liczebnik „pięcioma" doklejasz sam).
Kolejność argumentów jest jak w pozostałych tagach: `wyraz` pierwszy.

### Odmiana fraz wielowyrazowych (nazw własnych instytucji)

`{% odmien_fraze fraza "przypadek" %}` odmienia **wielowyrazowe nazwy własne**
instytucji — uczelni, wydziałów, instytutów — a nie tylko pojedyncze
rzeczowniki. Silnik rozpoznaje głowę frazy, odmienia ją wraz z uzgadniającymi
się z nią przymiotnikami i **zamraża** dopełniaczowy ogon. Wymaga
`polish-inflection >= 0.5.2`.

```django
{% load polish_inflection %}

{# rzeczownik + przymiotnik — odmieniają się razem #}
{% odmien_fraze nazwa_uczelni "dopelniacz" %}
{# "Uniwersytet Lubelski"            -> "Uniwersytetu Lubelskiego" #}
{# "Akademia Medyczna" (narzednik)   -> "Akademią Medyczną"        #}

{# rzeczownik + dopełniacz zależny — odmienia się tylko głowa #}
{% odmien_fraze nazwa_instytutu "dopelniacz" %}
{# "Instytut Technologii Stosowanej" -> "Instytutu Technologii Stosowanej" #}

{# filtr — gdy wystarcza sam przypadek #}
Sprawozdanie {{ nazwa_uczelni|odmien_fraze:"dopelniacz" }}

{# przypisanie do zmiennej #}
{% odmien_fraze nazwa_uczelni "miejscownik" as forma %}Konferencja na {{ forma }}
```

Trafność heurystyki to ok. 85–95% realnych nazw; frazy, których nie łapie (np.
„Instytut Polski" — przymiotnik czy dopełniacz?), nadpisujesz ręcznie warstwą
override (patrz [Ustawienia](#ustawienia)). Liczba mnoga fraz jest obsługiwana
(`liczba="mnoga"`) — przymiotnik uzgadnia się z głową, a zależny ogon
dopełniaczowy pozostaje zamrożony (wymaga `polish-inflection >= 0.6.0`).

Dostępny jest też niższopoziomowy tag `{% odmien_przymiotnik lemat "przypadek"
"rodzaj" %}` (rodzaj: `"meski"` / `"zenski"` / `"nijaki"`), użyteczny gdy
składasz formę samodzielnie:

```django
{% odmien_przymiotnik "lubelski" "dopelniacz" "meski" %}    {# lubelskiego #}
{% odmien_przymiotnik "stosowany" "dopelniacz" "zenski" %}  {# stosowanej  #}
```

`odmien_przymiotnik` ma wymagany argument `rodzaj`, więc — jak
`odmiana_liczebnikowa` — jest tylko tagiem (filtr Django przyjmuje jeden
argument).

## Ustawienia

```python
# settings.py
POLISH_INFLECTION_STRICT = False  # domyślnie
```

- `False` (domyślnie): nieznane słowo w słowniku SGJP nigdy nie wywala
  renderowania strony — tag/filtr zwraca oryginalne słowo bez zmian.
- `True`: nieznane słowo podnosi `polish_inflection.BrakOdmiany`. Przydatne
  w testach/CI.

### Nadpisania fraz (`POLISH_INFLECTION_PHRASE_OVERRIDES`)

Zawór bezpieczeństwa dla fraz, których heurystyka `{% odmien_fraze %}` nie
rozstrzyga poprawnie. Mapa `{(fraza, "przypadek"): "gotowa forma"}` jest
konsultowana **przed** silnikiem — jeśli para pasuje, zwracana jest ręczna
forma, w przeciwnym razie działa silnik.

```python
# settings.py
POLISH_INFLECTION_PHRASE_OVERRIDES = {
    # silnik heurystycznie daje „Instytutu Polski" (czyta jako dopełniacz);
    # wymuszamy czytanie przymiotnikowe:
    ("Instytut Polski", "dopelniacz"): "Instytutu Polskiego",
    ("Instytut Polski", "miejscownik"): "Instytucie Polskim",
}
```

- Klucz przypadka to ten sam przyjazny string, którego używasz w tagu
  (`"dopelniacz"`, `"miejscownik"`, …).
- Dopasowanie frazy ignoruje nadmiarowe białe znaki (trim + collapse spacji);
  wielkość liter jest znacząca.
- Nadpisanie dotyczy liczby pojedynczej (klucz nie zawiera liczby); przy
  `liczba="mnoga"` używany jest silnik.

## Przykładowy projekt

W katalogu [`example_project/`](example_project/) jest gotowy do uruchomienia
projekt Django („Odmieniarka"): wpisujesz słowo lub nazwę własną, a strona
generuje pełną tabelę odmiany przez przypadki (l.poj. i l.mn.), łącznie z
działającą warstwą override. Uruchomienie (z korzenia repo, `uv` sam ogarnia
zależności): `uv run python example_project/manage.py runserver`.

## Zakres

Ten pakiet odmienia pojedyncze rzeczowniki pospolite obecne w słowniku SGJP
(np. "wydział", "uczelnia", "instytut") przez wszystkie przypadki i obie liczby.

Odmiana wielowyrazowych nazw własnych instytucji (np. "Uniwersytet Lubelski")
jest dostępna heurystycznie przez `{% odmien_fraze %}` (patrz wyżej) — wymaga
`polish-inflection >= 0.5.2`.

Dobór formy rzeczownika wg liczebnika (1 wydział / 2 wydziały / 5 wydziałów)
jest dostępny przez `{% odmiana_liczebnikowa %}` (patrz wyżej) — wymaga
`polish-inflection >= 0.3.0`.

## Licencja

BSD 2-Clause — patrz [LICENSE](LICENSE). Copyright © 2026 Michał Pasternak.
