Metadata-Version: 2.3
Name: polars-phonetics
Version: 0.2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: polars >1.2.1
License-File: LICENSE.txt
Summary: Python Polars plugin for Rust-built phonetic algorithms
Keywords: polars,plugin,polars plugin,phonetics,phonetic algorithm
Author-email: LeCodeMinister <lecodeminister@proton.me>
Maintainer-email: LeCodeMinister <lecodeminister@proton.me>
Requires-Python: >=3.8, <3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/LeCodeMinister/polars-phonetics
Project-URL: Documentation, https://github.com/LeCodeMinister/polars-phonetics/blob/master/README.md
Project-URL: Change Log, https://github.com/LeCodeMinister/polars-phonetics/releases
Project-URL: Issue Tracker, https://github.com/LeCodeMinister/polars-phonetics/issues

# Polars-Phonetics: A Polars Plugin for Phonetic Algorithms

## v0.2.0 Release: Metaphone, Soundex & Nysiis Algorithms added!

Welcome to Polars-Phonetics, a Polars plugin for phonetic algorithms built in Rust for Python users. This second release includes the Metaphone, Soundex & Nysiis algorithms, in addition to the Double-Metaphone algorithm in the initial release.

With the current algorithms, Polars-Phonetics can replace the 'phonetics' Python module, no need for `map_elements(soundex)` from now on!

## Installation

To use Polars-Phonetics, install the polars-phonetics package using pip:

```bash
pip install polars-phonetics
```

## Example Usage

Here's an example of how to use the double_metaphone, metaphone, soundex & nysiis functions in Polars Phonetics:

```python
import polars as pl
from polars_phonetics import dmetaphone, soundex, metaphone, nysiis

# Create a sample dataframe
df = pl.DataFrame(
    {
        "words": ["hello", "this", "is", "the", "phonetics", "plugin", "in", "polars", None],
    }
)

print(df)

# This would output:
# shape: (9, 1)
# ┌───────────┐
# │ words     │
# │ ---       │
# │ str       │
# ╞═══════════╡
# │ hello     │
# │ this      │
# │ is        │
# │ the       │
# │ phonetics │
# │ plugin    │
# │ in        │
# │ polars    │
# │ null      │
# └───────────┘


# Apply the double_metaphone, soundex, metaphone & nysiis functions to the 'words' column
result = df.with_columns(
    dmetaphone=dmetaphone("words"),
    soundex=soundex("words"),
    metaphone=metaphone("words"),
    nysiis=nysiis("words"),
)

print(result)

# shape: (9, 5)
# ┌───────────┬──────────────┬─────────┬───────────┬────────┐
# │ words     ┆ dmetaphone   ┆ soundex ┆ metaphone ┆ nysiis │
# │ ---       ┆ ---          ┆ ---     ┆ ---       ┆ ---    │
# │ str       ┆ str          ┆ str     ┆ str       ┆ str    │
# ╞═══════════╪══════════════╪═════════╪═══════════╪════════╡
# │ hello     ┆ [HL, HL]     ┆ H400    ┆ HL        ┆ HAL    │
# │ this      ┆ [0S, TS]     ┆ T200    ┆ 0S        ┆ T      │
# │ is        ┆ [AS, AS]     ┆ I200    ┆ IS        ┆ I      │
# │ the       ┆ [0, T]       ┆ T000    ┆ 0         ┆ T      │
# │ phonetics ┆ [FNTK, FNTK] ┆ P532    ┆ FNTK      ┆ FANATA │
# │ plugin    ┆ [PLJN, PLKN] ┆ P425    ┆ PLJN      ┆ PLAGAN │
# │ in        ┆ [AN, AN]     ┆ I500    ┆ IN        ┆ IN     │
# │ polars    ┆ [PLRS, PLRS] ┆ P462    ┆ PLRS      ┆ PALAR  │
# │ null      ┆ null         ┆ null    ┆ null      ┆ null   │
# └───────────┴──────────────┴─────────┴───────────┴────────┘
```

## Acknowledgments

I would like to extend my gratitude to:

- Marco Gorelli for his comprehensive guide on writing [Polars Plugins](https://marcogorelli.github.io/polars-plugins-tutorial/).
- The team behind the Rust crate [rphonetic](https://crates.io/crates/rphonetic).
- The Discord server for Polars, especially the [plugins channel](https://discord.com/channels/908022250106667068/1174049891794812998).

## Future Releases

Future releases of Polars-Phonetics will include additional phonetic algorithms with options to customise outputs through arguments. Stay tuned for updates!

## Contributing

If you'd like to contribute to Polars-Phonetics, please open an issue or pull request on this repository. I welcome any feedback, bug reports, or new algorithm implementations.

## License

Polars-Phonetics is licensed under the MIT License. See the LICENSE file for details.
