sru-generator 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,214 @@
1
+ """
2
+ SRU Generator - A Python package for generating Swedish SRU (Skatteverket) files.
3
+
4
+ This package provides functionality to generate SRU files for Swedish tax reporting,
5
+ including support for stock trades, crypto transactions, and proper formatting
6
+ according to Swedish tax authority specifications.
7
+ """
8
+
9
+ import logging
10
+ import warnings
11
+ from typing import TYPE_CHECKING
12
+
13
+ from . import character_converters
14
+ from .amounts import to_decimal
15
+ from .builders import build_blanketter_sru, build_info_sru, encode_sru_content
16
+ from .character_converters import load_character_converter
17
+
18
+ # Enhanced features
19
+ from .config import DEFAULT_CONFIG, SRUConfig, create_config, get_default_config
20
+ from .currency import (
21
+ CurrencyAmount,
22
+ CurrencyConverter,
23
+ convert_currency,
24
+ convert_to_sek,
25
+ get_currency_converter,
26
+ set_exchange_rate,
27
+ )
28
+ from .exceptions import (
29
+ BusinessRuleError,
30
+ ConfigurationError,
31
+ CurrencyError,
32
+ DataFormatError,
33
+ FileOperationError,
34
+ SRUGeneratorError,
35
+ ValidationError,
36
+ )
37
+ from .models import CryptoSRUGroup, PersonalInfo, SRUTradeRow
38
+ from .sru_generator import (
39
+ K4_COST_BASIS_ROUNDING,
40
+ K4_SALE_PRICE_ROUNDING,
41
+ K4_SECTION_A_ROWS,
42
+ MAX_GROUP_NUMBER,
43
+ MAX_MONETARY_VALUE, # Constants
44
+ NUMBER_OF_CHARACTERS_FOR_STOCK_NAME,
45
+ SRU_ENCODING,
46
+ SRU_FIELD_BLANKETT_END,
47
+ SRU_FIELD_BLANKETT_START,
48
+ SRU_FIELD_COST_BASIS_SUFFIX,
49
+ SRU_FIELD_FILE_END,
50
+ SRU_FIELD_GROUP_TOTAL_COST_BASIS,
51
+ SRU_FIELD_GROUP_TOTAL_LOSS,
52
+ SRU_FIELD_GROUP_TOTAL_PROFIT,
53
+ SRU_FIELD_GROUP_TOTAL_SOLD,
54
+ SRU_FIELD_IDENTITET,
55
+ SRU_FIELD_LOSS_SUFFIX,
56
+ SRU_FIELD_NAMN,
57
+ SRU_FIELD_PROFIT_SUFFIX,
58
+ SRU_FIELD_QUANTITY_SUFFIX,
59
+ SRU_FIELD_SOLD_AMOUNT_SUFFIX,
60
+ SRU_FIELD_STOCK_NAME_SUFFIX,
61
+ SRU_FIELD_UPPGIFT_GROUP_START,
62
+ SRU_LINE_START,
63
+ WHOLE_NUMBER_ROUNDING,
64
+ calculate_group_totals,
65
+ decode_sru_bytes,
66
+ encode_sru_text,
67
+ format_group_totals_sru,
68
+ format_trade_item_sru,
69
+ generate_sru_footer,
70
+ generate_sru_header,
71
+ generate_sru_info_content,
72
+ generate_sru_trade_content,
73
+ merge_sru_groups,
74
+ read_crypto_sru_content,
75
+ round_k4_cost_basis,
76
+ round_k4_quantity,
77
+ round_k4_sale_price,
78
+ write_sru_file,
79
+ )
80
+ from .validators import TradeDataValidator, validate_personal_info, validate_trade_data
81
+
82
+ __version__ = "1.0.0"
83
+
84
+ # Deprecated top-level names: character conversion belongs to text-converters. They
85
+ # still work (from the bundled copy) with a DeprecationWarning, and go away in 2.0.
86
+ _DEPRECATED_CONVERTER_NAMES = frozenset(
87
+ {
88
+ "CHARACTER_CONVERTERS",
89
+ "convert_french_characters_to_english",
90
+ "convert_german_characters_to_english",
91
+ "convert_greek_characters_to_english",
92
+ "convert_spanish_characters_to_english",
93
+ "convert_swedish_characters_to_english",
94
+ "get_character_converter",
95
+ "no_conversion",
96
+ }
97
+ )
98
+
99
+ if TYPE_CHECKING: # type checkers see the real names; at runtime __getattr__ warns
100
+ from .character_converters import CHARACTER_CONVERTERS as CHARACTER_CONVERTERS
101
+ from .character_converters import (
102
+ convert_french_characters_to_english as convert_french_characters_to_english,
103
+ )
104
+ from .character_converters import (
105
+ convert_german_characters_to_english as convert_german_characters_to_english,
106
+ )
107
+ from .character_converters import (
108
+ convert_greek_characters_to_english as convert_greek_characters_to_english,
109
+ )
110
+ from .character_converters import (
111
+ convert_spanish_characters_to_english as convert_spanish_characters_to_english,
112
+ )
113
+ from .character_converters import (
114
+ convert_swedish_characters_to_english as convert_swedish_characters_to_english,
115
+ )
116
+ from .character_converters import (
117
+ get_character_converter as get_character_converter,
118
+ )
119
+ from .character_converters import no_conversion as no_conversion
120
+
121
+
122
+ def __getattr__(name: str) -> object:
123
+ if name in _DEPRECATED_CONVERTER_NAMES:
124
+ if name == "get_character_converter":
125
+ instead = "sru_generator.load_character_converter(name)"
126
+ else:
127
+ instead = f"text_converters.{name} (install text-converters)"
128
+ warnings.warn(
129
+ f"sru_generator.{name} is deprecated and will be removed in 2.0; "
130
+ f"use {instead}",
131
+ DeprecationWarning,
132
+ stacklevel=2,
133
+ )
134
+ return getattr(character_converters, name)
135
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
136
+
137
+
138
+ # Library logging etiquette: stay silent unless the application configures logging.
139
+ logging.getLogger("sru_generator").addHandler(logging.NullHandler())
140
+
141
+ __all__ = [
142
+ "DEFAULT_CONFIG",
143
+ "K4_COST_BASIS_ROUNDING",
144
+ "K4_SALE_PRICE_ROUNDING",
145
+ "K4_SECTION_A_ROWS",
146
+ "MAX_GROUP_NUMBER",
147
+ "MAX_MONETARY_VALUE",
148
+ "NUMBER_OF_CHARACTERS_FOR_STOCK_NAME",
149
+ "SRU_ENCODING",
150
+ "SRU_FIELD_BLANKETT_END",
151
+ # Constants
152
+ "SRU_FIELD_BLANKETT_START",
153
+ "SRU_FIELD_COST_BASIS_SUFFIX",
154
+ "SRU_FIELD_FILE_END",
155
+ "SRU_FIELD_GROUP_TOTAL_COST_BASIS",
156
+ "SRU_FIELD_GROUP_TOTAL_LOSS",
157
+ "SRU_FIELD_GROUP_TOTAL_PROFIT",
158
+ "SRU_FIELD_GROUP_TOTAL_SOLD",
159
+ "SRU_FIELD_IDENTITET",
160
+ "SRU_FIELD_LOSS_SUFFIX",
161
+ "SRU_FIELD_NAMN",
162
+ "SRU_FIELD_PROFIT_SUFFIX",
163
+ "SRU_FIELD_QUANTITY_SUFFIX",
164
+ "SRU_FIELD_SOLD_AMOUNT_SUFFIX",
165
+ "SRU_FIELD_STOCK_NAME_SUFFIX",
166
+ "SRU_FIELD_UPPGIFT_GROUP_START",
167
+ "SRU_LINE_START",
168
+ "WHOLE_NUMBER_ROUNDING",
169
+ "BusinessRuleError",
170
+ "ConfigurationError",
171
+ "CryptoSRUGroup",
172
+ "CurrencyAmount",
173
+ "CurrencyConverter",
174
+ "CurrencyError",
175
+ "DataFormatError",
176
+ "FileOperationError",
177
+ "PersonalInfo",
178
+ # Enhanced features
179
+ "SRUConfig",
180
+ # Exceptions
181
+ "SRUGeneratorError",
182
+ "SRUTradeRow",
183
+ "TradeDataValidator",
184
+ "ValidationError",
185
+ "build_blanketter_sru",
186
+ "build_info_sru",
187
+ "calculate_group_totals",
188
+ "convert_currency",
189
+ "convert_to_sek",
190
+ "create_config",
191
+ "decode_sru_bytes",
192
+ "encode_sru_content",
193
+ "encode_sru_text",
194
+ "format_group_totals_sru",
195
+ "format_trade_item_sru",
196
+ "generate_sru_footer",
197
+ "generate_sru_header",
198
+ # Main functions
199
+ "generate_sru_info_content",
200
+ "generate_sru_trade_content",
201
+ "get_currency_converter",
202
+ "get_default_config",
203
+ "load_character_converter",
204
+ "merge_sru_groups",
205
+ "read_crypto_sru_content",
206
+ "round_k4_cost_basis",
207
+ "round_k4_quantity",
208
+ "round_k4_sale_price",
209
+ "set_exchange_rate",
210
+ "to_decimal",
211
+ "validate_personal_info",
212
+ "validate_trade_data",
213
+ "write_sru_file",
214
+ ]
@@ -0,0 +1,27 @@
1
+ """
2
+ Reading amounts and quantities as exact decimals.
3
+ """
4
+
5
+ from decimal import Decimal
6
+
7
+ #: A double carries 15 significant decimal digits reliably (DBL_DIG); the digits after
8
+ #: that are binary noise. 0.1 * 3 * 1000 is 300.00000000000006, and Skatteverket's
9
+ #: "round öre up" rule would turn that noise into a whole extra krona.
10
+ FLOAT_SIGNIFICANT_DIGITS = 15
11
+
12
+
13
+ def to_decimal(value: object) -> Decimal:
14
+ """``value`` as a Decimal, without the binary noise a ``float`` carries.
15
+
16
+ A ``float`` is read at 15 significant digits, so 300.00000000000006 becomes 300 and
17
+ 209.99999999999997 becomes 210, at any magnitude. Everything else (``Decimal``,
18
+ ``int``, ``str``) is exact already and is converted with ``Decimal(str(value))``,
19
+ so ``Decimal("1.999")`` stays 1.999 and the K4 rounding rules see it as given.
20
+
21
+ The cut-off is a trade-off: a float with more than 15 significant digits, such as
22
+ 1.999999999999999, cannot be told apart from noise and is read as 2. Pass Decimal
23
+ or str when every digit matters.
24
+ """
25
+ if isinstance(value, float):
26
+ return Decimal(f"{value:.{FLOAT_SIGNIFICANT_DIGITS}g}")
27
+ return Decimal(str(value))
@@ -0,0 +1,79 @@
1
+ """
2
+ High-level helpers for building complete SRU file contents.
3
+ """
4
+
5
+ from collections.abc import Iterable, Sequence
6
+
7
+ from .models import CharacterConverter, CryptoSRUGroup, PersonalInfo, SRUTradeRow
8
+ from .sru_generator import (
9
+ encode_sru_text,
10
+ generate_sru_info_content,
11
+ generate_sru_trade_content,
12
+ merge_sru_groups,
13
+ )
14
+ from .validators import validate_personal_info, validate_trade_data
15
+
16
+
17
+ def build_info_sru(personal_info: PersonalInfo) -> str:
18
+ """
19
+ Build a complete ``info.sru`` file content string from generic personal info.
20
+ """
21
+ validated = validate_personal_info(dict(personal_info))
22
+ return generate_sru_info_content(
23
+ personal_number=validated["personal_number"],
24
+ full_name=validated["full_name"],
25
+ postal_code=validated["postal_code"],
26
+ city_name=validated["city_name"],
27
+ )
28
+
29
+
30
+ def build_blanketter_sru(
31
+ trade_rows: Sequence[SRUTradeRow],
32
+ personal_info: PersonalInfo,
33
+ year: int,
34
+ crypto_groups: Iterable[CryptoSRUGroup] | None = None,
35
+ *,
36
+ items_per_group: int = 9,
37
+ character_converter: CharacterConverter | None = None,
38
+ ) -> str:
39
+ """
40
+ Build a complete ``blanketter.sru`` file content string from generic trade rows.
41
+
42
+ ``trade_rows`` may be empty when ``crypto_groups`` is not: the file then holds
43
+ only the crypto pages, numbered 1..n. With neither, ``ValidationError`` is raised.
44
+ """
45
+ validated_personal = validate_personal_info(dict(personal_info))
46
+ normalized_crypto_groups: list[CryptoSRUGroup] = [
47
+ {"group_number": group["group_number"], "uppgifter": list(group["uppgifter"])}
48
+ for group in (crypto_groups or [])
49
+ ]
50
+
51
+ trade_content = ""
52
+ if trade_rows or not normalized_crypto_groups:
53
+ validated_trades = validate_trade_data([dict(row) for row in trade_rows])
54
+ trade_content = generate_sru_trade_content(
55
+ trade_data=validated_trades,
56
+ full_name=validated_personal["full_name"],
57
+ personal_number=validated_personal["personal_number"],
58
+ year=year,
59
+ items_per_group=items_per_group,
60
+ character_converter=character_converter,
61
+ )
62
+
63
+ return merge_sru_groups(
64
+ stock_content=trade_content,
65
+ crypto_groups=normalized_crypto_groups,
66
+ full_name=validated_personal["full_name"],
67
+ personal_number=validated_personal["personal_number"],
68
+ year=year,
69
+ )
70
+
71
+
72
+ def encode_sru_content(content: str) -> bytes:
73
+ """
74
+ Encode SRU content for file downloads or HTTP responses.
75
+
76
+ SRU files are ISO-8859-1. Raises ``DataFormatError`` if the content has characters
77
+ ISO-8859-1 cannot represent; transliterate them first with a character converter.
78
+ """
79
+ return encode_sru_text(content)
@@ -0,0 +1,383 @@
1
+ """
2
+ Character conversion utilities for different languages.
3
+
4
+ Each converter maps letters with diacritics (or a non-Latin script) to plain ASCII
5
+ equivalents. This matters for SRU files, which are written in ISO-8859-1: Swedish
6
+ letters (å, ä, ö) survive that encoding as they are, but Greek and other non-Latin
7
+ text does not, so it has to be transliterated before it is written.
8
+
9
+ Conversion now belongs to the separate ``text-converters`` package. Use
10
+ ``load_character_converter(name)``: it imports ``text_converters`` lazily when it is
11
+ installed, and otherwise falls back to the copy bundled below, with a
12
+ ``DeprecationWarning``. The bundled copy will be removed in 2.0. sru-generator itself
13
+ keeps no runtime dependencies: ``text-converters`` is optional and never imported at
14
+ package import time.
15
+ """
16
+
17
+ import importlib
18
+ import warnings
19
+ from collections.abc import Callable
20
+
21
+ from .models import CharacterConverter
22
+
23
+
24
+ def _translate(text: str, mapping: dict[str, str]) -> str:
25
+ return "".join(mapping.get(char, char) for char in text)
26
+
27
+
28
+ _GREEK_TO_ENGLISH: dict[str, str] = {
29
+ "Α": "A",
30
+ "Ά": "A",
31
+ "Β": "B",
32
+ "Γ": "G",
33
+ "Δ": "D",
34
+ "Ε": "E",
35
+ "Έ": "E",
36
+ "Ζ": "Z",
37
+ "Η": "I",
38
+ "Ή": "I",
39
+ "Θ": "TH",
40
+ "Ι": "I",
41
+ "Ί": "I",
42
+ "Ϊ": "I",
43
+ "Κ": "K",
44
+ "Λ": "L",
45
+ "Μ": "M",
46
+ "Ν": "N",
47
+ "Ξ": "X",
48
+ "Ο": "O",
49
+ "Ό": "O",
50
+ "Π": "P",
51
+ "Ρ": "R",
52
+ "Σ": "S",
53
+ "Τ": "T",
54
+ "Υ": "Y",
55
+ "Ύ": "Y",
56
+ "Ϋ": "Y",
57
+ "Φ": "F",
58
+ "Χ": "CH",
59
+ "Ψ": "PS",
60
+ "Ω": "O",
61
+ "Ώ": "O",
62
+ "α": "a",
63
+ "ά": "a",
64
+ "β": "b",
65
+ "γ": "g",
66
+ "δ": "d",
67
+ "ε": "e",
68
+ "έ": "e",
69
+ "ζ": "z",
70
+ "η": "i",
71
+ "ή": "i",
72
+ "θ": "th",
73
+ "ι": "i",
74
+ "ί": "i",
75
+ "ϊ": "i",
76
+ "ΐ": "i",
77
+ "κ": "k",
78
+ "λ": "l",
79
+ "μ": "m",
80
+ "ν": "n",
81
+ "ξ": "x",
82
+ "ο": "o",
83
+ "ό": "o",
84
+ "π": "p",
85
+ "ρ": "r",
86
+ "σ": "s",
87
+ "ς": "s",
88
+ "τ": "t",
89
+ "υ": "y",
90
+ "ύ": "y",
91
+ "ϋ": "y",
92
+ "ΰ": "y",
93
+ "φ": "f",
94
+ "χ": "ch",
95
+ "ψ": "ps",
96
+ "ω": "o",
97
+ "ώ": "o",
98
+ }
99
+
100
+ _SWEDISH_TO_ENGLISH: dict[str, str] = {
101
+ "Å": "A",
102
+ "å": "a",
103
+ "Ä": "A",
104
+ "ä": "a",
105
+ "Ö": "O",
106
+ "ö": "o",
107
+ "É": "E",
108
+ "é": "e",
109
+ "È": "E",
110
+ "è": "e",
111
+ "Ü": "U",
112
+ "ü": "u",
113
+ "Ñ": "N",
114
+ "ñ": "n",
115
+ "Ç": "C",
116
+ "ç": "c",
117
+ }
118
+
119
+ _GERMAN_TO_ENGLISH: dict[str, str] = {
120
+ "Ä": "Ae",
121
+ "ä": "ae",
122
+ "Ö": "Oe",
123
+ "ö": "oe",
124
+ "Ü": "Ue",
125
+ "ü": "ue",
126
+ "ß": "ss",
127
+ "É": "E",
128
+ "é": "e",
129
+ "È": "E",
130
+ "è": "e",
131
+ "À": "A",
132
+ "à": "a",
133
+ "Ò": "O",
134
+ "ò": "o",
135
+ "Ù": "U",
136
+ "ù": "u",
137
+ }
138
+
139
+ _FRENCH_TO_ENGLISH: dict[str, str] = {
140
+ "À": "A",
141
+ "à": "a",
142
+ "Á": "A",
143
+ "á": "a",
144
+ "Â": "A",
145
+ "â": "a",
146
+ "Ä": "A",
147
+ "ä": "a",
148
+ "Ç": "C",
149
+ "ç": "c",
150
+ "É": "E",
151
+ "é": "e",
152
+ "È": "E",
153
+ "è": "e",
154
+ "Ê": "E",
155
+ "ê": "e",
156
+ "Ë": "E",
157
+ "ë": "e",
158
+ "Î": "I",
159
+ "î": "i",
160
+ "Ï": "I",
161
+ "ï": "i",
162
+ "Ô": "O",
163
+ "ô": "o",
164
+ "Ö": "O",
165
+ "ö": "o",
166
+ "Ù": "U",
167
+ "ù": "u",
168
+ "Ú": "U",
169
+ "ú": "u",
170
+ "Û": "U",
171
+ "û": "u",
172
+ "Ü": "U",
173
+ "ü": "u",
174
+ "Ÿ": "Y",
175
+ "ÿ": "y",
176
+ "Æ": "Ae",
177
+ "æ": "ae",
178
+ "Œ": "Oe",
179
+ "œ": "oe",
180
+ }
181
+
182
+ _SPANISH_TO_ENGLISH: dict[str, str] = {
183
+ "Á": "A",
184
+ "á": "a",
185
+ "É": "E",
186
+ "é": "e",
187
+ "Í": "I",
188
+ "í": "i",
189
+ "Ó": "O",
190
+ "ó": "o",
191
+ "Ú": "U",
192
+ "ú": "u",
193
+ "Ñ": "N",
194
+ "ñ": "n",
195
+ "Ü": "U",
196
+ "ü": "u",
197
+ }
198
+
199
+
200
+ # Capital letters whose Latin form has two letters. "TH" is right inside an all-capitals
201
+ # word (ΑΘΗΝΑ -> ATHINA) but wrong at the start of a normal one (Θεσσαλονίκη ->
202
+ # Thessaloniki), so the case of the second letter depends on the neighbours.
203
+ _GREEK_CAPITAL_DIGRAPHS = {"Θ": "TH", "Χ": "CH", "Ψ": "PS"}
204
+ # The pair ου is written "ou" (Παπαδόπουλος -> Papadopoulos), not "oy".
205
+ _GREEK_OMICRON = frozenset("οόΟΌ")
206
+ _GREEK_UPSILON = {"υ": "u", "ύ": "u", "Υ": "U", "Ύ": "U"}
207
+
208
+
209
+ def convert_greek_characters_to_english(text: str) -> str:
210
+ """Transliterate Greek letters (with or without tonos) to Latin letters.
211
+
212
+ Letter by letter, close to the Greek standard ELOT 743 for single letters: η is
213
+ "i" (Θεσσαλονίκη -> Thessaloniki), ου is "ou" (Παπαδόπουλος -> Papadopoulos),
214
+ and Θ, Χ, Ψ give "Th", "Ch", "Ps" unless they stand in an all-capitals word
215
+ (ΑΘΗΝΑ -> ATHINA). The other letter pairs ELOT treats specially (αυ, ευ, μπ,
216
+ γγ, ...) are not handled; see the README for a library-based alternative.
217
+ """
218
+ result: list[str] = []
219
+ for index, char in enumerate(text):
220
+ preceding = text[index - 1] if index > 0 else ""
221
+ if char in _GREEK_UPSILON and preceding in _GREEK_OMICRON:
222
+ result.append(_GREEK_UPSILON[char])
223
+ continue
224
+ digraph = _GREEK_CAPITAL_DIGRAPHS.get(char)
225
+ if digraph is None:
226
+ result.append(_GREEK_TO_ENGLISH.get(char, char))
227
+ continue
228
+ following = text[index + 1] if index + 1 < len(text) else ""
229
+ in_capitals_word = following.isupper() or (
230
+ not following.isalpha() and preceding.isupper()
231
+ )
232
+ result.append(digraph if in_capitals_word else digraph.capitalize())
233
+ return "".join(result)
234
+
235
+
236
+ def convert_swedish_characters_to_english(text: str) -> str:
237
+ """Replace Swedish (and a few common European) diacritics with plain letters."""
238
+ return _translate(text, _SWEDISH_TO_ENGLISH)
239
+
240
+
241
+ def convert_german_characters_to_english(text: str) -> str:
242
+ """Replace German umlauts and ß with their conventional digraphs (ä -> ae)."""
243
+ return _translate(text, _GERMAN_TO_ENGLISH)
244
+
245
+
246
+ def convert_french_characters_to_english(text: str) -> str:
247
+ """Replace French diacritics with plain letters."""
248
+ return _translate(text, _FRENCH_TO_ENGLISH)
249
+
250
+
251
+ def convert_spanish_characters_to_english(text: str) -> str:
252
+ """Replace Spanish diacritics with plain letters."""
253
+ return _translate(text, _SPANISH_TO_ENGLISH)
254
+
255
+
256
+ def no_conversion(text: str) -> str:
257
+ """Return the text unchanged."""
258
+ return text
259
+
260
+
261
+ CHARACTER_CONVERTERS: dict[str, Callable[[str], str]] = {
262
+ "none": no_conversion,
263
+ "greek": convert_greek_characters_to_english,
264
+ "swedish": convert_swedish_characters_to_english,
265
+ "german": convert_german_characters_to_english,
266
+ "french": convert_french_characters_to_english,
267
+ "spanish": convert_spanish_characters_to_english,
268
+ }
269
+
270
+
271
+ def get_character_converter(language: str = "none") -> Callable[[str], str]:
272
+ """
273
+ Return the converter registered under ``language``.
274
+
275
+ Raises:
276
+ ValueError: if ``language`` is not one of ``CHARACTER_CONVERTERS``.
277
+ """
278
+ if language not in CHARACTER_CONVERTERS:
279
+ available = ", ".join(CHARACTER_CONVERTERS)
280
+ raise ValueError(f"Unsupported language '{language}'. Available: {available}")
281
+ return CHARACTER_CONVERTERS[language]
282
+
283
+
284
+ #: The converter names sru-generator accepts (CLI choices, SRUConfig validation).
285
+ CONVERTER_NAMES: tuple[str, ...] = (
286
+ "none",
287
+ "greek",
288
+ "swedish",
289
+ "german",
290
+ "french",
291
+ "spanish",
292
+ )
293
+
294
+ #: Where text-converters comes from (it is not on PyPI), pinned to a tested release.
295
+ TEXT_CONVERTERS_SOURCE = (
296
+ "git+https://github.com/Nikolaos-Paximadakis/text-converters.git@v0.2.0"
297
+ )
298
+ TEXT_CONVERTERS_INSTALL = f'pip install "{TEXT_CONVERTERS_SOURCE}"'
299
+ #: A text-converters whose Greek converter does not give this is outdated (its old rules
300
+ #: wrote "THessalonikh Papadopoylos") and is not used. Checking behaviour rather than a
301
+ #: version number keeps working however that package numbers its releases.
302
+ _GREEK_PROBE = ("Θεσσαλονίκη Παπαδόπουλος", "Thessaloniki Papadopoulos")
303
+ BUNDLED_CONVERTERS_WARNING = (
304
+ "sru-generator's bundled character converters will be removed in 2.0; "
305
+ f"install text-converters with {TEXT_CONVERTERS_INSTALL}"
306
+ )
307
+
308
+
309
+ def _from_text_converters(name: str) -> CharacterConverter | None:
310
+ """The converter from an installed, current text-converters, or None.
311
+
312
+ Imported lazily through importlib, so the package never needs text-converters
313
+ (or its type information) at import time or under a type checker.
314
+ """
315
+ try:
316
+ module = importlib.import_module("text_converters")
317
+ except ImportError:
318
+ return None
319
+ factory: object = getattr(module, "get_character_converter", None)
320
+ if not callable(factory):
321
+ return None
322
+ greek: object = factory("greek")
323
+ if not callable(greek) or greek(_GREEK_PROBE[0]) != _GREEK_PROBE[1]:
324
+ return None # outdated rules: the bundled copy is better
325
+ loaded: object = factory(name)
326
+ if not callable(loaded):
327
+ return None
328
+
329
+ def converter(text: str) -> str:
330
+ result: object = loaded(text)
331
+ if not isinstance(result, str):
332
+ raise TypeError(
333
+ f"text_converters' {name!r} converter returned "
334
+ f"{type(result).__name__}, not str"
335
+ )
336
+ return result
337
+
338
+ return converter
339
+
340
+
341
+ def resolve_character_converter(name: str) -> tuple[CharacterConverter, bool]:
342
+ """``(converter, from_bundled_copy)`` for ``name``, without warning.
343
+
344
+ "none" is the identity and imports nothing. Any other name comes from an installed
345
+ current text-converters when available, else from the bundled copy (second item
346
+ True). Raises ``ValueError`` for a name not in ``CONVERTER_NAMES``.
347
+ """
348
+ if name not in CONVERTER_NAMES:
349
+ available = ", ".join(CONVERTER_NAMES)
350
+ raise ValueError(f"Unsupported language '{name}'. Available: {available}")
351
+ if name == "none":
352
+ return no_conversion, False
353
+ external = _from_text_converters(name)
354
+ if external is not None:
355
+ return external, False
356
+ return CHARACTER_CONVERTERS[name], True
357
+
358
+
359
+ def load_character_converter(name: str) -> CharacterConverter:
360
+ """The converter for ``name`` (see ``resolve_character_converter``).
361
+
362
+ Warns with ``DeprecationWarning`` when it falls back to the bundled copy.
363
+ """
364
+ converter, from_bundled = resolve_character_converter(name)
365
+ if from_bundled:
366
+ warnings.warn(BUNDLED_CONVERTERS_WARNING, DeprecationWarning, stacklevel=2)
367
+ return converter
368
+
369
+
370
+ __all__ = [
371
+ "BUNDLED_CONVERTERS_WARNING",
372
+ "CHARACTER_CONVERTERS",
373
+ "CONVERTER_NAMES",
374
+ "convert_french_characters_to_english",
375
+ "convert_german_characters_to_english",
376
+ "convert_greek_characters_to_english",
377
+ "convert_spanish_characters_to_english",
378
+ "convert_swedish_characters_to_english",
379
+ "get_character_converter",
380
+ "load_character_converter",
381
+ "no_conversion",
382
+ "resolve_character_converter",
383
+ ]