ID Translation

Convert IDs to human-readable labels.

Country IDs translated using the standard id:name-format. Click here for source.

What is it?

A package suite for translating IDs typically found in databases. Translation is highly configurable and tested for multiple different SQL dialects and schema naming paradigms. The included TOML configuration format as well as the support functions make it easy to create and share working configurations with anyone who needs them.

Getting started

The fastest way to get started with id-translation is the 🍪id-translation-project Cookiecutter template. It is designed to allow power users to quickly specify shared configurations that "just work" for other users; see the example below.

# Generated by: cookiecutter https://github.com/rsundqvist/id-translation-project.git
from big_corporation_inc.id_translation import translate
print(
  "The first employee at Big Corporation Inc. was:", 
  translate(1, names="employee_id"),
)

The template generates an installable {your_namespace}.id_translation module, with functions such as the one used above. Check out the demo project (and its 📚generated documentation) to get a preview of what your generated project might look like, or continue to the next section for a brief feature overview.

Already have an application that maps IDs by hand? See the migration guide instead -- it walks through adding id-translation to an existing codebase.

Highlighted Features

• Convenient interface: Translator.translate().
• Intuitive Format strings (e.g. '{id}:{name}'), including full Format Specification Mini-Language support. Extensions for optional keys.
• Fetchers for SQL and local or remote file-system sources.
• Powerful Name-to-source and Placeholder-to-column mapping and name extraction.
• Configurable using TOML - see the 🍪id-translation-project Cookiecutter template.

Supported types

• Supported ID types: int, str, and UUID. Optional heuristics for UUID-like strings.
• Supports translation of built-in collections: list, dict, set, tuple.
• Supports translation of pandas types, including pandas.MultiIndex types.
• Optional and user-extensible integration of data types, such as polars, pyarrow, and dask.

Installation

The package is published through the Python Package Index (PyPI). Source code is available on GitHub: https://github.com/rsundqvist/id-translation

pip install -U id-translation

This is the preferred method to install id-translation, as it will always install the most recent stable release.

License

MIT

Documentation

Hosted on Read the Docs: https://id-translation.readthedocs.io

Contributing

All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. To get started, see the Contributing Guide and Code of Conduct.