django-polish-inflection 0.1.0__tar.gz

django_polish_inflection-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} / dj${{ matrix.django-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        django-version: ["5.2", "6.0"]
+        exclude:
+          # Django 6.0 wymaga Pythona >= 3.12
+          - python-version: "3.10"
+            django-version: "6.0"
+          - python-version: "3.11"
+            django-version: "6.0"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install "django==${{ matrix.django-version }}.*" pytest pytest-django
+      - name: Test
+        run: pytest -q
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check .

django_polish_inflection-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.superpowers/
+.venv/
+__pycache__/
+*.pyc
+uv.lock
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# wewnętrzne dokumenty planistyczne (superpowers)
+docs/superpowers/

django_polish_inflection-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: detect-private-key
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

django_polish_inflection-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Michał Pasternak
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_polish_inflection-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+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.

django_polish_inflection-0.1.0/README.md

@@ -0,0 +1,245 @@
+# 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.

django_polish_inflection-0.1.0/example_project/README.md

@@ -0,0 +1,49 @@
+# Odmieniarka — przykładowy projekt
+
+Minimalny projekt Django pokazujący `django-polish-inflection` w akcji. Strona
+startowa (`/`) daje wybór między dwoma narzędziami:
+
+- **Odmiana wyrazów** (`/odmien/`) — wpisujesz słowo lub wielowyrazową nazwę
+  własną, a strona generuje pełną odmianę przez wszystkie przypadki (liczba
+  pojedyncza i mnoga) w szablonie przez tag `{% odmien_fraze %}`.
+- **Podawanie form** (`/podaj/`) — kierunek odwrotny: wpisujesz dowolną formę,
+  a widok pokazuje jej analizy (forma podstawowa, przypadek, liczba, rodzaj)
+  zarówno jako **rzeczownik** (`podaj()`), jak i **przymiotnik**
+  (`podaj_przymiotnik()`) — obie słownikowe (SGJP), łącznie z synkretyzmem
+  i homografią.
+
+## Uruchomienie
+
+Z tego katalogu — `uv` sam znajdzie projekt w katalogu nadrzędnym i ogarnie
+zależności (Django i `django-polish-inflection`) w izolowanym środowisku:
+
+```bash
+uv run python manage.py runserver
+```
+
+Otwórz http://127.0.0.1:8000/ i wybierz jedno z dwóch narzędzi.
+
+Projekt nie używa bazy danych — `runserver` startuje bez migracji.
+
+## Co pokazuje
+
+- **Odmianę słów i fraz** przez jeden tag `{% odmien_fraze %}` (działa dla obu —
+  patrz `demo/templates/demo/odmien.html`).
+- **Odmianę w pętli**: przypadek jest zmienną (`{% odmien_fraze wyraz p.key %}`),
+  więc jedna pętla generuje całą tabelę.
+- **Warstwę override**: `odmieniarka/settings.py` zawiera
+  `POLISH_INFLECTION_PHRASE_OVERRIDES` dla „Instytut Polski" — wpisz tę frazę
+  na stronie odmiany, by zobaczyć ręczną formę zamiast heurystycznej.
+- **Analizę form** jako rzeczownik i przymiotnik: strona „Podawanie form"
+  łączy `podaj()` (rzeczowniki) i `podaj_przymiotnik()` (przymiotniki) w widoku
+  (`demo/views.py`), bo obie zwracają listy obiektów, nie tekst — dlatego nie są
+  tagami szablonu jak odmiana. Od `polish-inflection` 0.7.0 analiza przymiotnika
+  jest słownikowa (bazy z SGJP), więc nie nadgeneruje form, które tylko wyglądają
+  jak przymiotnik.
+
+## Struktura
+
+- `odmieniarka/urls.py` — trzy trasy: `/` (wybór), `/odmien/`, `/podaj/`.
+- `demo/views.py` — widoki `index`, `odmien`, `analiza`.
+- `demo/templates/demo/` — `base.html` (wspólny szkielet) + `index`, `odmien`,
+  `podaj`.

django_polish_inflection-0.1.0/example_project/demo/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DemoConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "demo"