i21y package

Subpackages

Submodules

i21y.abc module

class i21y.abc.Loader

Bases: ABC

Abstract specification class for the class used to search Translations.

abstract search_impl(locale: str, key: str, default: ~i21y.abc.SearchT | type[~i21y.utils.Undefined] = <class 'i21y.utils.Undefined'>) → str | SearchT

Implementation of abc.Loader.search(). Arguments is same as .search.

search(locale: str, key: str, default: type[Undefined] = Undefined) → str
search(locale: str, key: str, default: SearchT = Undefined) → SearchT

Search translations.

Parameters:

  • locale – The locale of translations.

  • key – The key to translations.

  • default – If it is specified, it will be returned when translation is not found.

Raises:

TranslationNotFound – If translation is not found, this function will raise it.

i21y.error module

exception i21y.error.I21YError

Bases: Exception

The exception class used to throw the exception on i21y.

exception i21y.error.TranslationNotFound(key: str, *args: Any, **kwargs: Any)

Bases: I21YError

The exception class will be raised when text is not found.

Parameters:

  • key – The key of text.

  • *args – The arguments to be passed to I21YError.

  • *kwargs – The keyword arguments to be passed to I21YError.

i21y.translator module

class i21y.translator.Translator(loader: LoaderT | Loader, default_locale: str = 'en')

Bases: Generic[LoaderT]

This class is for translation.

Parameters:

  • loader – It is for searching translations.

  • default_locale – It will be used for default locale. If you don’t specify it, it will be set en.

format_(text: str, *args: Any, **kwargs: Any) → str

Format text.

Parameters:

  • text – Target text.

  • *args – The arguments to be passed to text.format.

  • **kwargs – The keyword arguments to be passed to text.format.

translate(key: str | locale_str, *args: Any, locale: str | None = None, do_format: bool = True, **kwargs: Any) → str

Do translation. The translation will be formated by Translator.format_().

Parameters:

  • key – It will be used for searching text.

  • *args – The arguments to be passed to format_().

  • locale – The locale of text.

  • do_format – Whether or not to perform formatting.

  • **kwargs – The arguments to be passed to format_().

Note

It can be called by calling instance of Translator. Like:

t = Translator()
print(t("responses.not_found"))
Raises:

TranslationNotFound – If translation is not found, this function will raise it.

i21y.utils module

class i21y.utils.Undefined

Bases: object

This class is used to represent undefined.

class i21y.utils.locale_str(key: Any, **extras: Any)

Bases: object

This class is designed to allow for the graceful creation of keys to translations.

Operations

x + y

It is alias for locale_str.join(). y can be specified str or Iterable, and y will be passed to join() as arguments.

x & y

It is alias for locale_str.join_raw(). y can be specified str or Iterable, and y will be passed to join_raw() as arguments.

x == y

Checks if locale_str.key of x and y are the same.

x != y

Checks if locale_str.key of x and y are not the same.

Parameters:

  • key – The key to ranslation.

  • **extras – It is for some data.

Notes

Attribute can be used as the argument of join().

join_raw(*other: str | locale_str) → str

Concatenate strings to self and return string of it.

Parameters:

*other – Target strings.

join(*other: str | locale_str, cls: type[AdtnlClsT], **extras: Any) → AdtnlClsT
join(*other: str | locale_str, cls: None = None, **extras: Any) → SelfT

A version of locale_str.join_raw() that returns the instance of the class that self.

Parameters:

  • *other – Target strings.

  • cls – The locale_str used to create the instance.

  • **extras – The value to pass to the extras argument of the constructor of locale_str.

update_extras(**extras: Any) → SelfT

Function to gracefully update extras.

Parameters:

extras – The extras to override.

Module contents

class i21y.Translator(loader: LoaderT | Loader, default_locale: str = 'en')

Bases: Generic[LoaderT]

This class is for translation.

Parameters:

  • loader – It is for searching translations.

  • default_locale – It will be used for default locale. If you don’t specify it, it will be set en.

format_(text: str, *args: Any, **kwargs: Any) → str

Format text.

Parameters:

  • text – Target text.

  • *args – The arguments to be passed to text.format.

  • **kwargs – The keyword arguments to be passed to text.format.

translate(key: str | locale_str, *args: Any, locale: str | None = None, do_format: bool = True, **kwargs: Any) → str

Do translation. The translation will be formated by Translator.format_().

Parameters:

  • key – It will be used for searching text.

  • *args – The arguments to be passed to format_().

  • locale – The locale of text.

  • do_format – Whether or not to perform formatting.

  • **kwargs – The arguments to be passed to format_().

Note

It can be called by calling instance of Translator. Like:

t = Translator()
print(t("responses.not_found"))
Raises:

TranslationNotFound – If translation is not found, this function will raise it.

exception i21y.I21YError

Bases: Exception

The exception class used to throw the exception on i21y.

exception i21y.TranslationNotFound(key: str, *args: Any, **kwargs: Any)

Bases: I21YError

The exception class will be raised when text is not found.

Parameters:

  • key – The key of text.

  • *args – The arguments to be passed to I21YError.

  • *kwargs – The keyword arguments to be passed to I21YError.

class i21y.locale_str(key: Any, **extras: Any)

Bases: object

This class is designed to allow for the graceful creation of keys to translations.

Operations

x + y

It is alias for locale_str.join(). y can be specified str or Iterable, and y will be passed to join() as arguments.

x & y

It is alias for locale_str.join_raw(). y can be specified str or Iterable, and y will be passed to join_raw() as arguments.

x == y

Checks if locale_str.key of x and y are the same.

x != y

Checks if locale_str.key of x and y are not the same.

Parameters:

  • key – The key to ranslation.

  • **extras – It is for some data.

Notes

Attribute can be used as the argument of join().

join_raw(*other: str | locale_str) → str

Concatenate strings to self and return string of it.

Parameters:

*other – Target strings.

join(*other: str | locale_str, cls: type[AdtnlClsT], **extras: Any) → AdtnlClsT
join(*other: str | locale_str, cls: None = None, **extras: Any) → SelfT

A version of locale_str.join_raw() that returns the instance of the class that self.

Parameters:

  • *other – Target strings.

  • cls – The locale_str used to create the instance.

  • **extras – The value to pass to the extras argument of the constructor of locale_str.

update_extras(**extras: Any) → SelfT

Function to gracefully update extras.

Parameters:

extras – The extras to override.