Metadata-Version: 2.4
Name: dutch-pluralizer
Version: 0.0.42
Summary: Generates Dutch plural and singular nouns in a very imperfect way using Hunspell dictionaries. Why imperfect? Because the Dutch language is full of exceptions.
Home-page: https://github.com/KeesCBakker/dutch-pluralizer-py
Author: Kees C. Bakker / KeesTalksTech
Author-email: info@keestalkstech.com
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: cffi>=1.15.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Dutch Noun Pluralizer in Python

Generates plural and singular nouns in a _very imperfect way_ using Hunspell and <a href="https://github.com/OpenTaal/opentaal-hunspell">OpenTaal dictionaries</a> (v2.20.23, 2023-03-10) and <a href="https://github.com/OpenTaal/opentaal-wordlist">word lists</a>. Why imperfect? Because the Dutch language is full of exceptions.

The algorithm is based on the document <a href="https://sites.uclouvain.be/gramlink/Gramlink-NL/morfologie/pdf/m_nl_02_subst_03_meervoud.pdf">"Basismorfologie. Het meervoud in het Nederlands" (Dutch)</a> of the <a href="https://uclouvain.be/en/index.html">Université catholique de Louvain</a>.

_Note: I'm a .NET developer that does Python in my free time. I'm **not** a linguist, I just work for a Dutch company. Hence: this **must** be a very imperfect way of doing this._ If you have good ideas, I welcome them — just open an issue on <a href="https://github.com/KeesCBakker/dutch-pluralizer-py/issues">GitHub</a>.

## Installation

**Python version:** This package requires **Python >=3.8**. The devcontainer uses **Python 3.14**.

Install from PIP:
```
pip install dutch-pluralizer
```

### System dependencies

The package requires **libhunspell** (the C library, not the CLI):

- **Debian/Ubuntu:** `apt-get install libhunspell-dev`
- **macOS:** `brew install hunspell`
- **Windows:** Install a pre-built `libhunspell` binary or use WSL.

## CLI usage

The project can be used as a CLI tool:

```
$ python -m dutch_pluralizer -p kaas
kazen
```

See [docs/CLI.md](docs/CLI.md) for the full CLI reference with all options
and output examples.

## API

The API can be used like this:

```python
from dutch_pluralizer import pluralize, singularize

# pluralize will return the result or None
assert pluralize("kaas") == "kazen"
assert pluralize("kazen") == None

# singularize will return the result or None
assert singularize("kazen") == "kaas"
assert singularize("kaas") == None
```

Advanced pluralization will give you more options:

```python
from dutch_pluralizer import pluralize, pluralize_advanced, singularize

adv = pluralize_advanced("album")

# the plural
assert adv.plural == 'albums'

# what the algorithm (without Hunspell) created
# is probably not correct, that's why Hunspell is
# used on it. It is like a preprocessing:
assert adv.algorithmic_plural == 'alba'

# indicates that end result was found in Hunspell
assert adv.hunspell_spelled == True

# the plural was found by replacement of 
# 'a' to 'ums'
assert adv.switched_ending_from == 'a'
assert adv.switched_ending_to == 'ums'

# suggestions given by Hunspell when the algorithmic
# result was processed:
assert adv.suggestions == ( 'Alba',
                            'aba',        
                            'balba',
                            'albe',
                            'alia',
                            'alla',
                            'alma',
                            'alfa',
                            'Elba')

```

Add custom words to the dictionary:

```python
from dutch_pluralizer import pluralize, singularize
from dutch_pluralizer.speller import ensure_hunspell_nl

def test_readme_example_3():

    # default dictionary does not understand these words,
    # as they are not Dutch
    assert pluralize("fibulatie") == None
    assert singularize("fibulaties") == None

    # add the words to the dictionary
    h = ensure_hunspell_nl()
    h.add("fibulatie")
    h.add("fibulaties")

    # check again
    assert pluralize("fibulatie", speller=h) == "fibulaties"
    assert singularize("fibulaties", speller=h) == "fibulatie"
```


## Help!? The result is not correct
I told you it was imperfect! There is stuff this package can and cannot do:

- We cannot discover words that are not recognized by Hunspell
- We can only process **nouns** (Dutch: zelfstandige naamwoorden)
- We can only return a single result, but we know that the singular of _graven_ can be either _graaf_ or _graf_. We currently have no support for these use cases.
- We can add words, just open up a ticket on <a href="https://github.com/keescbakker/dutch-pluralizer-py/issues">GitHub</a>. Please make sure you provide some evidence on why the word should be added (like a VanDale.nl result).


## Development

A <a href="https://code.visualstudio.com/docs/devcontainers/containers">devcontainer</a>
configuration is provided for a consistent development environment. Open the project
in Visual Studio Code with the Dev Containers extension and it will automatically
build and set up the container.

Alternatively, see <a href="https://github.com/KeesCBakker/dutch-pluralizer-py/blob/master/docs/DEV.md">DEV.md</a> for manual setup instructions.


