| Name | cologne-phonetics JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | |
| Summary | Python implementation of the cologne-phonetics algorithm |
| upload_time | 2024-01-14 09:46:53 |
| maintainer | |
| docs_url | None |
| author | Janek Nouvertné |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. _`PyPi`: https://pypi.org/project/cologne-phonetics/
=================
Cologne-phonetics
=================
.. image:: https://img.shields.io/pypi/pyversions/cologne-phonetics.svg
:alt: PyPI version
Contents
========
- `Cologne-phonetics`_
- `Introduction`_
- `Examples`_
- `Installation`_
- `Usage`_
- `Module contents`_
- `encode`_
- `compare`_
- `Examples`_
- `Command line interface`_
- `Special characters`_
- `Word breaks and hyphens`_
- `Umlaut and special character replacement`_
- `Changelog`_
- `1.2.0`_
- `1.2.1`_
- `1.2.2`_
- `1.2.3`_
- `1.2.4`_
- `1.3.0`_
- `1.3.1`_
- `2.0.0`_
Introduction
============
Cologne-phonetics is a phonetic algorithm similar to Soundex, wich encodes words
into a phonetic code, making it possible to compare how they *sound* rather than how they're *written*.
It was developed by Hans Postel and contrary to Soundex, it's designed specific
for the german language.
It involves three steps:
- Generate a code by representing every letter from left to right with a digit, according to a conversion table
- Remove double digits
- Remove every occurrence of '0', except as a leading digit
The module itself is quite simple and consists only of the `encode`_ and `compare`_ functions
and a simple command line interface.
Examples
========
.. code-block:: bash
$ cologne_phonetics.py "peter pédter"
127, 127
$ cologne_phonetics.py "umwelt umhwält"
06352, 06352
$ cologne_phonetics.py "urlaub uhrlaup"
0751, 0751
As you can see, similar sounding names produce the same result, with respect to the *correct* pronunciation.
.. code-block:: bash
$ cologne_phonetics.py "peter peta"
127, 12
This does not give the same result for each word because they may *look* similar,
but (when pronounced correctly) don't really *sound* alike.
============
Installation
============
cologne_phonetics runs with Python 3.4+ or PyPy 3.5.
It is available on `PyPi`_ and can be installed it via pip:
.. code-block:: bash
pip install cologne_phonetics
=====
Usage
=====
Module contents
===============
.. _encode:
encode(data, *concat=False*)
Return a list of result tuples.
Each tuple consists of the string that was encoded and its result.
If the input string is altered in any way before encoding, the tuple will
contain the altered version.
.. code-block:: python
>>> cologne_phonetics.encode("bäteS")
>>> [('baetes', '128')]
If ``concat=True`` is passed, words connected with hyphens will be treated as
a single words.
Most of the time, the list will be ``len(result_list) == 1``. Only if the input string
contains a space character or a hyphen it is splitted into substrings and each
substring will be encoded seperately.
.. _compare:
compare(\*data, *concat=False*)
Parameter
\*data. Either at last 2 positional arguments or an iterable
Returns
`True` if all encoded strings are equal, else `False`
Raises
`ValueError`.
If only one value is submitted or the submitted Iterable is of lenght 1.
Command line interface
======================
.. code-block:: bash
$ cologne_phonetics.py hello
05
$ cologne_phonetics.py hello world
05, 3752
Optional arguments
~~~~~~~~~~~~~~~~~~~~
-h, --help
show this help message and exit
-c, --concat
treat words connected by hyphens as seperate words
-v, --verbose
show detailed information
-p, --pretty
format output nicely
===================
Special characters
===================
Special characters are all characters that are not ascii-characters between A and Z.
Most special characters are simply ignored, but even within the set of special characters,
there are some that are even *more* special.
Word breaks and hyphens
========================
By default, words connected by hyphens, e.g. ``meier-lüdenscheid`` are seperated.
So ``meier-lüdenscheid`` would become ``'67', '52682'``. If you
want it to be treated as a single word, you can pass a ``concat=True``
to the encode functions.
While at first this doesn't seem to make a difference in the result, other than it being split
into a list of strings, in some cases it can make a difference.
.. code-block:: python
>>> cologne_phonetics.encode("weiss-chemie")
>>> [('weiss', '38'), ('chemie', '46')]
>>> cologne_phonetics.encode("weiss-chemie", concat=True)
>>> [('weiss-chemie', '386')]
As you can see, a ``4`` got lost here.
In case you *really* want to compare the concatenated words you may use this option,
but in general there's not much use to it.
Umlaut and special character replacement
=========================================
Umlaute and some other special characters are converted to their non-special equivalent.
====== ==========
Umlaut conversion
====== ==========
ü ue
ö oe
ä ae
ß s
é e
è e
á a
à a
====== ==========
=========
Changelog
=========
1.2.0
=====
- Removed `encode_many()`
- `encode()` now allways returns a list of result tuples
- Added `--verbose` and `--pretty` options to CLI
- New function: `compare()`
1.2.1
=====
- Fixed an error that would lead to case sensitive comparison in `compare`_
1.2.2
=====
- Another error in `compare`_ was found (and fixed); Compare didn't actually compare output. It compared input. This was due to bad tests and introduced in 1.2.0, with the change that made `encode`_ always return a tuple as a result
1.2.3
=====
- PyPy 3.5 is now officially supported
- A bug was fixed that would lead `encode`_ to sometimes an preprocessed rather than the altered string in the result tuple
1.2.4
=====
- Drop support for Python 3.4 and 3.5
- Add tests for Python 3.8 and 3.9
- Remove deprecated ``Iterable`` import. See #1
1.3.0
=====
- Add more robust replacement of diacritic using ``unicodedata`` (provided by `Tobias Bengfort <https://github.com/xi>`_ )
- Add type hints
- Fix issue where ``concat`` parameter of `compare`_ wasn't passed to `encode`_
1.3.1
=====
- Run tests against Python 3.10
- Add missing Readme to pyproject.toml
- Drop Python 3.6 support
2.0.0
=====
- Drop Python 3.7 support
- Test against Python 3.11 and 3.12
Raw data
{
"_id": null,
"home_page": "",
"name": "cologne-phonetics",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Janek Nouvertn\u00e9",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0d/a4/f0ff7bacaecb1b5e489e8b61677a036a54efc1f700230b29e0f83e50e9a6/cologne_phonetics-2.0.0.tar.gz",
"platform": null,
"description": ".. _`PyPi`: https://pypi.org/project/cologne-phonetics/\n\n\n=================\nCologne-phonetics\n=================\n\n\n.. image:: https://img.shields.io/pypi/pyversions/cologne-phonetics.svg\n :alt: PyPI version\n\n\nContents\n========\n\n- `Cologne-phonetics`_\n\n - `Introduction`_\n - `Examples`_\n- `Installation`_\n- `Usage`_\n\n - `Module contents`_\n\n - `encode`_\n - `compare`_\n - `Examples`_\n - `Command line interface`_\n- `Special characters`_\n\n - `Word breaks and hyphens`_\n - `Umlaut and special character replacement`_\n\n- `Changelog`_\n\n - `1.2.0`_\n - `1.2.1`_\n - `1.2.2`_\n - `1.2.3`_\n - `1.2.4`_\n - `1.3.0`_\n - `1.3.1`_\n - `2.0.0`_\n\n\n\nIntroduction\n============\n\nCologne-phonetics is a phonetic algorithm similar to Soundex, wich encodes words\ninto a phonetic code, making it possible to compare how they *sound* rather than how they're *written*.\nIt was developed by Hans Postel and contrary to Soundex, it's designed specific\nfor the german language.\n\nIt involves three steps:\n\n- Generate a code by representing every letter from left to right with a digit, according to a conversion table\n- Remove double digits\n- Remove every occurrence of '0', except as a leading digit\n\nThe module itself is quite simple and consists only of the `encode`_ and `compare`_ functions\nand a simple command line interface.\n\n\nExamples\n========\n\n.. code-block:: bash\n\n $ cologne_phonetics.py \"peter p\u00e9dter\"\n 127, 127\n $ cologne_phonetics.py \"umwelt umhw\u00e4lt\"\n 06352, 06352\n $ cologne_phonetics.py \"urlaub uhrlaup\"\n 0751, 0751\n\nAs you can see, similar sounding names produce the same result, with respect to the *correct* pronunciation.\n\n.. code-block:: bash\n\n $ cologne_phonetics.py \"peter peta\"\n 127, 12\n\nThis does not give the same result for each word because they may *look* similar,\nbut (when pronounced correctly) don't really *sound* alike.\n\n\n============\nInstallation\n============\n\ncologne_phonetics runs with Python 3.4+ or PyPy 3.5.\nIt is available on `PyPi`_ and can be installed it via pip:\n\n.. code-block:: bash\n\n pip install cologne_phonetics\n\n\n=====\nUsage\n=====\n\nModule contents\n===============\n\n.. _encode:\n\nencode(data, *concat=False*)\n Return a list of result tuples.\n\n Each tuple consists of the string that was encoded and its result.\n\n If the input string is altered in any way before encoding, the tuple will\n contain the altered version.\n\n .. code-block:: python\n\n >>> cologne_phonetics.encode(\"b\u00e4teS\")\n >>> [('baetes', '128')]\n\n If ``concat=True`` is passed, words connected with hyphens will be treated as\n a single words.\n\n Most of the time, the list will be ``len(result_list) == 1``. Only if the input string\n contains a space character or a hyphen it is splitted into substrings and each\n substring will be encoded seperately.\n\n.. _compare:\n\ncompare(\\*data, *concat=False*)\n Parameter\n \\*data. Either at last 2 positional arguments or an iterable\n Returns\n `True` if all encoded strings are equal, else `False`\n Raises\n `ValueError`.\n If only one value is submitted or the submitted Iterable is of lenght 1.\n\n\nCommand line interface\n======================\n\n.. code-block:: bash\n\n $ cologne_phonetics.py hello\n 05\n $ cologne_phonetics.py hello world\n 05, 3752\n\n\nOptional arguments\n~~~~~~~~~~~~~~~~~~~~\n\n-h, --help\n show this help message and exit\n-c, --concat\n treat words connected by hyphens as seperate words\n-v, --verbose\n show detailed information\n-p, --pretty\n format output nicely\n\n\n\n===================\nSpecial characters\n===================\n\nSpecial characters are all characters that are not ascii-characters between A and Z.\nMost special characters are simply ignored, but even within the set of special characters,\nthere are some that are even *more* special.\n\n\nWord breaks and hyphens\n========================\n\nBy default, words connected by hyphens, e.g. ``meier-l\u00fcdenscheid`` are seperated.\nSo ``meier-l\u00fcdenscheid`` would become ``'67', '52682'``. If you\nwant it to be treated as a single word, you can pass a ``concat=True``\nto the encode functions.\n\nWhile at first this doesn't seem to make a difference in the result, other than it being split\ninto a list of strings, in some cases it can make a difference.\n\n.. code-block:: python\n\n >>> cologne_phonetics.encode(\"weiss-chemie\")\n >>> [('weiss', '38'), ('chemie', '46')]\n >>> cologne_phonetics.encode(\"weiss-chemie\", concat=True)\n >>> [('weiss-chemie', '386')]\n\nAs you can see, a ``4`` got lost here.\nIn case you *really* want to compare the concatenated words you may use this option,\nbut in general there's not much use to it.\n\n\nUmlaut and special character replacement\n=========================================\n\nUmlaute and some other special characters are converted to their non-special equivalent.\n\n====== ==========\nUmlaut conversion\n====== ==========\n\u00fc ue\n\u00f6 oe\n\u00e4 ae\n\u00df s\n\u00e9 e\n\u00e8 e\n\u00e1 a\n\u00e0 a\n====== ==========\n\n\n=========\nChangelog\n=========\n\n1.2.0\n=====\n\n- Removed `encode_many()`\n- `encode()` now allways returns a list of result tuples\n- Added `--verbose` and `--pretty` options to CLI\n- New function: `compare()`\n\n1.2.1\n=====\n\n- Fixed an error that would lead to case sensitive comparison in `compare`_\n\n1.2.2\n=====\n\n- Another error in `compare`_ was found (and fixed); Compare didn't actually compare output. It compared input. This was due to bad tests and introduced in 1.2.0, with the change that made `encode`_ always return a tuple as a result\n\n1.2.3\n=====\n\n- PyPy 3.5 is now officially supported\n- A bug was fixed that would lead `encode`_ to sometimes an preprocessed rather than the altered string in the result tuple\n\n\n1.2.4\n=====\n\n- Drop support for Python 3.4 and 3.5\n- Add tests for Python 3.8 and 3.9\n- Remove deprecated ``Iterable`` import. See #1\n\n\n1.3.0\n=====\n\n- Add more robust replacement of diacritic using ``unicodedata`` (provided by `Tobias Bengfort <https://github.com/xi>`_ )\n- Add type hints\n- Fix issue where ``concat`` parameter of `compare`_ wasn't passed to `encode`_\n\n\n1.3.1\n=====\n\n- Run tests against Python 3.10\n- Add missing Readme to pyproject.toml\n- Drop Python 3.6 support\n\n\n2.0.0\n=====\n\n- Drop Python 3.7 support\n- Test against Python 3.11 and 3.12\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python implementation of the cologne-phonetics algorithm",
"version": "2.0.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5df8eee21372300aac4b656b725efb99b7a06846a5454c6c5be991a8576ffbdb",
"md5": "d213fe7aa883ae52ffd3f7d2155bc239",
"sha256": "8512deca088454c5a538bcdc93370d5c1059ab69afa8ea198bef6cc107cf8244"
},
"downloads": -1,
"filename": "cologne_phonetics-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d213fe7aa883ae52ffd3f7d2155bc239",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6612,
"upload_time": "2024-01-14T09:46:50",
"upload_time_iso_8601": "2024-01-14T09:46:50.043608Z",
"url": "https://files.pythonhosted.org/packages/5d/f8/eee21372300aac4b656b725efb99b7a06846a5454c6c5be991a8576ffbdb/cologne_phonetics-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0da4f0ff7bacaecb1b5e489e8b61677a036a54efc1f700230b29e0f83e50e9a6",
"md5": "3b8738eb6854a27c30d9fdb27e655e74",
"sha256": "f7379dc2c78116d2c9b4f2122a2a93e9cf4c04360831a6968f6ffc1b7eb6c097"
},
"downloads": -1,
"filename": "cologne_phonetics-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3b8738eb6854a27c30d9fdb27e655e74",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5986,
"upload_time": "2024-01-14T09:46:53",
"upload_time_iso_8601": "2024-01-14T09:46:53.067539Z",
"url": "https://files.pythonhosted.org/packages/0d/a4/f0ff7bacaecb1b5e489e8b61677a036a54efc1f700230b29e0f83e50e9a6/cologne_phonetics-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-14 09:46:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cologne-phonetics"
}
