Welcome to translator’s documentation!

Introduction

translator is a module that provides abstract classes and implementations for mapping strings (such as file paths) to other information. It supports several translation mechanisms including Python dictionaries, regular expression patterns, and sequences of translators.

translator is a product of the PDS Ring-Moon Systems Node.

Installation

The translator module is available via the rms-translator package on PyPI and can be installed with:

pip install rms-translator

Getting Started

The translator module provides several translator classes:

  • Translator - Abstract base class defining the translator interface

  • TranslatorByDict - Fast dictionary-based translation

  • TranslatorByRegex - Flexible regex pattern-based translation with substitution

  • TranslatorBySequence - Combines multiple translators in sequence

  • NullTranslator - Returns nothing (useful as a placeholder)

  • SelfTranslator - Returns the input unchanged

All translator subclasses implement two key methods:

  • all(strings, strings_first=False) - Returns all matching translations

  • first(strings, strings_first=False) - Returns the first matching translation

Details of each class are available in the module documentation.

Example: Dictionary Translator

from translator import TranslatorByDict

# Create a simple dictionary translator
trans = TranslatorByDict({
    'apple': 'fruit',
    'carrot': 'vegetable',
    'chicken': 'meat'
})

print(trans.first('apple'))    # Output: 'fruit'
print(trans.all(['apple', 'carrot']))  # Output: ['fruit', 'vegetable']

Example: Regex Translator

from translator import TranslatorByRegex
import re

# Create a regex translator for file paths
trans = TranslatorByRegex([
    (r'data/(\w+)/(\w+)\.txt', r'processed/\1/\2.dat'),
    (r'images/(\w+)\.jpg', r'thumbnails/\1_thumb.jpg')
])

print(trans.first('data/2024/observations.txt'))
# Output: 'processed/2024/observations.dat'

print(trans.first('images/saturn.jpg'))
# Output: 'thumbnails/saturn_thumb.jpg'

Example: Sequence of Translators

from translator import TranslatorByDict, TranslatorByRegex, TranslatorBySequence

# Combine multiple translators
dict_trans = TranslatorByDict({'special': 'handled'})
regex_trans = TranslatorByRegex([(r'(\w+)', r'default_\1')])

seq_trans = TranslatorBySequence([dict_trans, regex_trans])

print(seq_trans.first('special'))  # Output: 'handled' (from dictionary)
print(seq_trans.first('other'))    # Output: 'default_other' (from regex)

Contributing

Information on contributing to this package can be found in the Contributing Guide.

Licensing

This code is licensed under the Apache License v2.0.

Contents:

Indices and tables