1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
# $Id: __init__.py 10046 2025-03-09 01:45:28Z aa-turner $
# Author: David Goodger <goodger@python.org>
# Copyright: This module has been placed in the public domain.
# Internationalization details are documented in
# <https://docutils.sourceforge.io/docs/howto/i18n.html>.
"""
This package contains modules for language-dependent features of Docutils.
"""
from __future__ import annotations
__docformat__ = 'reStructuredText'
from importlib import import_module
from docutils.utils import normalize_language_tag
TYPE_CHECKING = False
if TYPE_CHECKING:
import types
from typing import NoReturn, Protocol, TypeVar, overload
from docutils.utils import Reporter
class LanguageModule(Protocol):
__name__: str
labels: dict[str, str]
bibliographic_fields: dict[str, str]
author_separators: list[str]
LanguageModuleT = TypeVar('LanguageModuleT')
else:
from docutils.utils._typing import overload
class LanguageImporter:
"""Import language modules.
When called with a BCP 47 language tag, instances return a module
with localisations from `docutils.languages` or the PYTHONPATH.
If there is no matching module, warn (if a `reporter` is passed)
and fall back to English.
"""
packages = ('docutils.languages.', '')
warn_msg = ('Language "%s" not supported: '
'Docutils-generated text will be in English.')
fallback = 'en'
# TODO: use a dummy module returning empty strings?, configurable?
def __init__(self) -> None:
self.cache: dict[str, LanguageModuleT] = {}
def import_from_packages(self, name: str, reporter: Reporter = None
) -> LanguageModuleT:
"""Try loading module `name` from `self.packages`."""
module = None
for package in self.packages:
try:
module = import_module(package + name)
self.check_content(module)
except (ImportError, AttributeError):
if reporter and module:
reporter.info(f'{module} is no complete '
'Docutils language module.')
elif reporter:
reporter.info(f'Module "{package+name}" not found.')
continue
break
return module
@overload
def check_content(self, module: LanguageModule) -> None:
...
@overload
def check_content(self, module: types.ModuleType) -> NoReturn:
...
def check_content(self, module: LanguageModule | types.ModuleType) -> None:
"""Check if we got a Docutils language module."""
if not (
isinstance(module.labels, dict)
and isinstance(module.bibliographic_fields, dict)
and isinstance(module.author_separators, list)
):
raise ImportError
def __call__(self, language_code: str, reporter: Reporter = None
) -> LanguageModuleT:
try:
return self.cache[language_code]
except KeyError:
pass
for tag in normalize_language_tag(language_code):
tag = tag.replace('-', '_') # '-' not valid in module names
module = self.import_from_packages(tag, reporter)
if module is not None:
break
else:
if reporter:
reporter.warning(self.warn_msg % language_code)
if self.fallback:
module = self.import_from_packages(self.fallback)
if reporter and (language_code != 'en'):
reporter.info(f'Using {module} for language "{language_code}".')
self.cache[language_code] = module
return module
def __class_getitem__(cls, name):
return cls
get_language: LanguageImporter[LanguageModule] = LanguageImporter()
|
