Skip to main content

Python implementation of the cologne-phonetics algorithm

Project description

Cologne-phonetics

PyPI version

Contents

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

$ 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.

$ 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:

pip install cologne_phonetics

Usage

Module contents

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.

>>> 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(*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

$ 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.

>>> 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 )

  • 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cologne_phonetics-2.0.0.tar.gz (6.0 kB view details)

Uploaded Source

Built Distribution

cologne_phonetics-2.0.0-py3-none-any.whl (6.6 kB view details)

Uploaded Python 3

File details

Details for the file cologne_phonetics-2.0.0.tar.gz.

File metadata

  • Download URL: cologne_phonetics-2.0.0.tar.gz
  • Upload date:
  • Size: 6.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for cologne_phonetics-2.0.0.tar.gz
Algorithm Hash digest
SHA256 f7379dc2c78116d2c9b4f2122a2a93e9cf4c04360831a6968f6ffc1b7eb6c097
MD5 3b8738eb6854a27c30d9fdb27e655e74
BLAKE2b-256 0da4f0ff7bacaecb1b5e489e8b61677a036a54efc1f700230b29e0f83e50e9a6

See more details on using hashes here.

File details

Details for the file cologne_phonetics-2.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for cologne_phonetics-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8512deca088454c5a538bcdc93370d5c1059ab69afa8ea198bef6cc107cf8244
MD5 d213fe7aa883ae52ffd3f7d2155bc239
BLAKE2b-256 5df8eee21372300aac4b656b725efb99b7a06846a5454c6c5be991a8576ffbdb

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page