tgmark 0.1.0__tar.gz

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,30 @@
1
+ # Build and distribution
2
+ dist/
3
+ build/
4
+ *.egg-info/
5
+
6
+ # Bytecode
7
+ __pycache__/
8
+ *.py[cod]
9
+
10
+ # Virtual environment
11
+ .venv/
12
+
13
+ # Testing and coverage
14
+ .pytest_cache/
15
+ .hypothesis/
16
+ .coverage
17
+ coverage.json
18
+ coverage.xml
19
+ htmlcov/
20
+
21
+ # Tool caches
22
+ .mypy_cache/
23
+ .ruff_cache/
24
+
25
+ # Editors and operating systems
26
+ .idea/
27
+ .vscode/
28
+ *.swp
29
+ .DS_Store
30
+ Thumbs.db
tgmark-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Theodosios Divolis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
tgmark-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,111 @@
1
+ Metadata-Version: 2.5
2
+ Name: tgmark
3
+ Version: 0.1.0
4
+ Summary: Telegram Bot API markup converter for HTML, Markdown, and plain text
5
+ Project-URL: Bug Tracker, https://github.com/theodiv/tgmark/issues
6
+ Project-URL: Changelog, https://github.com/theodiv/tgmark/blob/main/CHANGELOG.md
7
+ Project-URL: Documentation, https://github.com/theodiv/tgmark/tree/main/docs
8
+ Project-URL: Repository, https://github.com/theodiv/tgmark
9
+ Author: Theodosios Divolis
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: bot-api,commonmark,converter,entities,html,markdown,markdownv2,parse-mode,telegram
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Topic :: Communications :: Chat
22
+ Classifier: Topic :: Text Processing :: Markup :: HTML
23
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.11
26
+ Description-Content-Type: text/markdown
27
+
28
+ # TGMark
29
+
30
+ Turn any text into messages Telegram never refuses.
31
+
32
+ [![License: MIT](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/theodiv/tgmark/main/pyproject.toml&query=$.project.license&style=flat-square&label=License&color=yellow)](https://github.com/theodiv/tgmark/blob/main/LICENSE)
33
+ [![Python: 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/theodiv/tgmark/main/pyproject.toml&style=flat-square&label=Python)](https://www.python.org/downloads/)
34
+ [![CI](https://img.shields.io/github/actions/workflow/status/theodiv/tgmark/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/theodiv/tgmark/actions/workflows/ci.yml)
35
+
36
+ ---
37
+
38
+ ## Overview
39
+
40
+ TGMark turns plain text into Telegram messages that the Bot API server accepts
41
+ and keeps exactly as sent, split to fit its limits, and reports each change it
42
+ makes to get there. It serves Python bot authors whose text comes from
43
+ elsewhere, such as an LLM's reply or a script's output. Sending the messages
44
+ stays with the caller's Bot API client.
45
+
46
+ ## Features
47
+
48
+ - **Kept as sent** — the characters the server removes or replaces are removed
49
+ or replaced first, so the server keeps every message exactly as `convert`
50
+ returns it.
51
+ - **Split to fit** — text longer than one message splits at the last paragraph
52
+ break, line break, sentence end, or space that fits, and keeps flags, emoji
53
+ sequences, and accented letters whole wherever they fit; `max_length` lowers
54
+ the limit and `max_parts` caps the count.
55
+ - **Every change reported** — each repair or removal comes back as a diagnostic
56
+ with a stable code, a line, and a column, and never quotes the input.
57
+ - **Strict mode** — `strict=True` raises `ConversionError` at the earliest
58
+ change instead, for text that must arrive as written.
59
+
60
+ ## Example
61
+
62
+ ```pycon
63
+ >>> from tgmark import convert
64
+ >>> conversion = convert("Build #42:\tpassed\n", source="plain", target="entities")
65
+ >>> conversion.messages[0].params()
66
+ {'text': 'Build #42: passed'}
67
+ >>> conversion.diagnostics
68
+ (Diagnostic(code='control-character', message='control character replaced with a space', line=1, column=11),)
69
+ ```
70
+
71
+ ## Requirements
72
+
73
+ Python 3.11 or later. No runtime dependencies.
74
+
75
+ ## Installation
76
+
77
+ ```console
78
+ $ pip install tgmark
79
+ ```
80
+
81
+ ## Documentation
82
+
83
+ - [Library](https://github.com/theodiv/tgmark/blob/main/docs/library.md) — every
84
+ public name, with its parameters, return value, and exceptions.
85
+ - [Behavior](https://github.com/theodiv/tgmark/blob/main/docs/behavior.md) —
86
+ what happens to the input, step by step, and the limits on it.
87
+ - [Compatibility](https://github.com/theodiv/tgmark/blob/main/docs/compatibility.md) —
88
+ what a release may change, and what stays stable.
89
+
90
+ ## Contributing
91
+
92
+ Development setup, coding standards, and the pull request process are documented
93
+ in the [contributing guide](https://github.com/theodiv/tgmark/blob/main/CONTRIBUTING.md).
94
+
95
+ ## Code of Conduct
96
+
97
+ Expectations for every participant are set in the
98
+ [code of conduct](https://github.com/theodiv/tgmark/blob/main/CODE_OF_CONDUCT.md).
99
+
100
+ ## Changelog
101
+
102
+ Every change is recorded in the [changelog](https://github.com/theodiv/tgmark/blob/main/CHANGELOG.md).
103
+
104
+ ## Security
105
+
106
+ The vulnerability reporting and disclosure process is documented in the
107
+ [security policy](https://github.com/theodiv/tgmark/blob/main/SECURITY.md).
108
+
109
+ ---
110
+
111
+ Distributed under the [MIT License](https://github.com/theodiv/tgmark/blob/main/LICENSE).
tgmark-0.1.0/README.md ADDED
@@ -0,0 +1,84 @@
1
+ # TGMark
2
+
3
+ Turn any text into messages Telegram never refuses.
4
+
5
+ [![License: MIT](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/theodiv/tgmark/main/pyproject.toml&query=$.project.license&style=flat-square&label=License&color=yellow)](https://github.com/theodiv/tgmark/blob/main/LICENSE)
6
+ [![Python: 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/theodiv/tgmark/main/pyproject.toml&style=flat-square&label=Python)](https://www.python.org/downloads/)
7
+ [![CI](https://img.shields.io/github/actions/workflow/status/theodiv/tgmark/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/theodiv/tgmark/actions/workflows/ci.yml)
8
+
9
+ ---
10
+
11
+ ## Overview
12
+
13
+ TGMark turns plain text into Telegram messages that the Bot API server accepts
14
+ and keeps exactly as sent, split to fit its limits, and reports each change it
15
+ makes to get there. It serves Python bot authors whose text comes from
16
+ elsewhere, such as an LLM's reply or a script's output. Sending the messages
17
+ stays with the caller's Bot API client.
18
+
19
+ ## Features
20
+
21
+ - **Kept as sent** — the characters the server removes or replaces are removed
22
+ or replaced first, so the server keeps every message exactly as `convert`
23
+ returns it.
24
+ - **Split to fit** — text longer than one message splits at the last paragraph
25
+ break, line break, sentence end, or space that fits, and keeps flags, emoji
26
+ sequences, and accented letters whole wherever they fit; `max_length` lowers
27
+ the limit and `max_parts` caps the count.
28
+ - **Every change reported** — each repair or removal comes back as a diagnostic
29
+ with a stable code, a line, and a column, and never quotes the input.
30
+ - **Strict mode** — `strict=True` raises `ConversionError` at the earliest
31
+ change instead, for text that must arrive as written.
32
+
33
+ ## Example
34
+
35
+ ```pycon
36
+ >>> from tgmark import convert
37
+ >>> conversion = convert("Build #42:\tpassed\n", source="plain", target="entities")
38
+ >>> conversion.messages[0].params()
39
+ {'text': 'Build #42: passed'}
40
+ >>> conversion.diagnostics
41
+ (Diagnostic(code='control-character', message='control character replaced with a space', line=1, column=11),)
42
+ ```
43
+
44
+ ## Requirements
45
+
46
+ Python 3.11 or later. No runtime dependencies.
47
+
48
+ ## Installation
49
+
50
+ ```console
51
+ $ pip install tgmark
52
+ ```
53
+
54
+ ## Documentation
55
+
56
+ - [Library](https://github.com/theodiv/tgmark/blob/main/docs/library.md) — every
57
+ public name, with its parameters, return value, and exceptions.
58
+ - [Behavior](https://github.com/theodiv/tgmark/blob/main/docs/behavior.md) —
59
+ what happens to the input, step by step, and the limits on it.
60
+ - [Compatibility](https://github.com/theodiv/tgmark/blob/main/docs/compatibility.md) —
61
+ what a release may change, and what stays stable.
62
+
63
+ ## Contributing
64
+
65
+ Development setup, coding standards, and the pull request process are documented
66
+ in the [contributing guide](https://github.com/theodiv/tgmark/blob/main/CONTRIBUTING.md).
67
+
68
+ ## Code of Conduct
69
+
70
+ Expectations for every participant are set in the
71
+ [code of conduct](https://github.com/theodiv/tgmark/blob/main/CODE_OF_CONDUCT.md).
72
+
73
+ ## Changelog
74
+
75
+ Every change is recorded in the [changelog](https://github.com/theodiv/tgmark/blob/main/CHANGELOG.md).
76
+
77
+ ## Security
78
+
79
+ The vulnerability reporting and disclosure process is documented in the
80
+ [security policy](https://github.com/theodiv/tgmark/blob/main/SECURITY.md).
81
+
82
+ ---
83
+
84
+ Distributed under the [MIT License](https://github.com/theodiv/tgmark/blob/main/LICENSE).
@@ -0,0 +1,155 @@
1
+ [project]
2
+ name = "tgmark"
3
+ description = "Telegram Bot API markup converter for HTML, Markdown, and plain text"
4
+ readme = "README.md"
5
+ requires-python = ">=3.11"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Theodosios Divolis" }]
9
+ keywords = [
10
+ "bot-api",
11
+ "commonmark",
12
+ "converter",
13
+ "entities",
14
+ "html",
15
+ "markdown",
16
+ "markdownv2",
17
+ "parse-mode",
18
+ "telegram",
19
+ ]
20
+ classifiers = [
21
+ "Development Status :: 3 - Alpha",
22
+ "Intended Audience :: Developers",
23
+ "Programming Language :: Python :: 3",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Programming Language :: Python :: 3.15",
29
+ "Topic :: Communications :: Chat",
30
+ "Topic :: Text Processing :: Markup :: HTML",
31
+ "Topic :: Text Processing :: Markup :: Markdown",
32
+ "Typing :: Typed",
33
+ ]
34
+ dependencies = []
35
+ dynamic = ["version"]
36
+
37
+ [project.urls]
38
+ "Bug Tracker" = "https://github.com/theodiv/tgmark/issues"
39
+ Changelog = "https://github.com/theodiv/tgmark/blob/main/CHANGELOG.md"
40
+ Documentation = "https://github.com/theodiv/tgmark/tree/main/docs"
41
+ Repository = "https://github.com/theodiv/tgmark"
42
+
43
+ [dependency-groups]
44
+ dev = [
45
+ "hypothesis==6.170.15",
46
+ "mypy==2.4.1",
47
+ "pre-commit==4.7.0",
48
+ "pytest==9.2.0",
49
+ "pytest-cov==7.1.0",
50
+ "ruff==0.17.4",
51
+ "tdlib-oracle==0.1.0",
52
+ "zizmor==1.32.0",
53
+ ]
54
+ release = [
55
+ "build==1.6.1",
56
+ "twine==7.0.0",
57
+ ]
58
+
59
+ [build-system]
60
+ requires = ["hatchling>=1.27"]
61
+ build-backend = "hatchling.build"
62
+
63
+ [tool.coverage.run]
64
+ branch = true
65
+ source_pkgs = ["tgmark"]
66
+
67
+ [tool.coverage.report]
68
+ fail_under = 90
69
+
70
+ [tool.hatch.version]
71
+ path = "src/tgmark/__init__.py"
72
+
73
+ [tool.hatch.build.targets.sdist]
74
+ only-include = ["src"]
75
+
76
+ [tool.hatch.build.targets.wheel]
77
+ packages = ["src/tgmark"]
78
+
79
+ [tool.mypy]
80
+ python_version = "3.11"
81
+ strict = true
82
+ mypy_path = "src"
83
+ warn_unreachable = true
84
+ enable_error_code = ["ignore-without-code"]
85
+
86
+ [[tool.mypy.overrides]]
87
+ module = "tests.*"
88
+ warn_unreachable = false
89
+ warn_return_any = false
90
+ disallow_untyped_decorators = false
91
+
92
+ [tool.pytest.ini_options]
93
+ addopts = "--cov-report=term-missing"
94
+ filterwarnings = ["error"]
95
+ strict = true
96
+ testpaths = ["tests"]
97
+
98
+ [tool.ruff]
99
+ line-length = 88
100
+ src = ["src", "tests"]
101
+
102
+ [tool.ruff.lint]
103
+ select = [
104
+ "B",
105
+ "D",
106
+ "E",
107
+ "F",
108
+ "G",
109
+ "I",
110
+ "PGH",
111
+ "PL",
112
+ "PT",
113
+ "RUF",
114
+ "S",
115
+ "T20",
116
+ "TID",
117
+ "UP",
118
+ "W",
119
+ ]
120
+ extend-select = ["D401", "D404", "TRY002"]
121
+ ignore = ["D105", "D107", "PLR2004"]
122
+
123
+ [tool.ruff.lint.per-file-ignores]
124
+ "tests/*" = [
125
+ "D100",
126
+ "D101",
127
+ "D102",
128
+ "D104",
129
+ "E741",
130
+ "PLC0415",
131
+ "PLR0913",
132
+ "PLR0917",
133
+ "S101",
134
+ "S105",
135
+ "S106",
136
+ "S311",
137
+ "S603",
138
+ ]
139
+ "tests/**/test_*.py" = ["D103"]
140
+
141
+ [tool.ruff.lint.flake8-tidy-imports]
142
+ ban-relative-imports = "all"
143
+
144
+ [tool.ruff.lint.flake8-tidy-imports.banned-api]
145
+ "os.chmod".msg = "Use os.fchmod on the open descriptor."
146
+
147
+ [tool.ruff.lint.pylint]
148
+ max-returns = 8
149
+ max-args = 6
150
+
151
+ [tool.ruff.lint.pycodestyle]
152
+ ignore-overlong-task-comments = true
153
+
154
+ [tool.ruff.lint.pydocstyle]
155
+ convention = "google"
@@ -0,0 +1,25 @@
1
+ """Telegram Bot API markup converter for HTML, Markdown, and plain text.
2
+
3
+ Public surface
4
+ --------------
5
+ - `convert`: converts text into messages that the Bot API server keeps as sent.
6
+ - `Conversion`: the messages and the diagnostics of one conversion.
7
+ - `Message`: one message's text and its Bot API parameters.
8
+ - `Diagnostic`: a condition lenient mode repaired or dropped, and where it starts.
9
+ - `TGMarkError`: root of the exception hierarchy.
10
+ - `ConversionError`: raised in strict mode for the earliest such condition.
11
+ """
12
+
13
+ from tgmark.conversion import Conversion, Diagnostic, Message, convert
14
+ from tgmark.exceptions import ConversionError, TGMarkError
15
+
16
+ __version__ = "0.1.0"
17
+
18
+ __all__ = [
19
+ "Conversion",
20
+ "ConversionError",
21
+ "Diagnostic",
22
+ "Message",
23
+ "TGMarkError",
24
+ "convert",
25
+ ]
@@ -0,0 +1,196 @@
1
+ """Conversion of text into Telegram messages: `convert` and the types it returns.
2
+
3
+ This module alone wires the stages together, `parse`, then `lower`, then `fit`, so no
4
+ domain imports another. The domains report each condition they repair or drop as a
5
+ foundation record, which this module maps onto `Diagnostic`; in strict mode it raises
6
+ for the record at the earliest position instead.
7
+ """
8
+
9
+ from dataclasses import dataclass
10
+ from typing import Any, Literal
11
+
12
+ from tgmark.exceptions import ConversionError
13
+ from tgmark.fit.parts import fit_text
14
+ from tgmark.lower.table import lower_document
15
+ from tgmark.model.diagnostics import Notice
16
+ from tgmark.model.server import MESSAGE_LENGTH
17
+ from tgmark.parse.decoding import replace_surrogates
18
+ from tgmark.parse.plain import read_plain
19
+
20
+ # The values `source` and `target` take.
21
+ _SOURCES = ("plain",)
22
+ _TARGETS = ("entities",)
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class Diagnostic:
27
+ """A condition in the input that lenient mode repaired or dropped.
28
+
29
+ Attributes:
30
+ code: The condition's code, such as `control-character`, which never changes
31
+ once released.
32
+ message: The condition and what lenient mode did instead, in one clause that
33
+ never quotes the input.
34
+ line: The line where the condition starts in the input, counted from 1.
35
+ column: The column in that line, counted from 1 in code points.
36
+ """
37
+
38
+ code: str
39
+ message: str
40
+ line: int
41
+ column: int
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class Message:
46
+ """One Telegram message, as the Bot API server keeps it.
47
+
48
+ Attributes:
49
+ text: The text of the message.
50
+ """
51
+
52
+ text: str
53
+
54
+ # The parameters' values differ in type from one name to the next, so `Any` lets
55
+ # them unpack into the keyword arguments of any Bot API client.
56
+ def params(self) -> dict[str, Any]:
57
+ """Return the message's parameters for the Bot API's `sendMessage` method.
58
+
59
+ Each call returns a new `dict`, so a caller can add `chat_id` and the other
60
+ parameters of the call to it.
61
+ """
62
+ return {"text": self.text}
63
+
64
+
65
+ @dataclass(frozen=True)
66
+ class Conversion:
67
+ """What converting a text produced: its messages and its diagnostics.
68
+
69
+ Attributes:
70
+ messages: The messages, in input order; empty when nothing remains to send.
71
+ diagnostics: Each condition lenient mode repaired or dropped, in input order.
72
+ """
73
+
74
+ messages: tuple[Message, ...]
75
+ diagnostics: tuple[Diagnostic, ...]
76
+
77
+
78
+ def convert(
79
+ text: str,
80
+ *,
81
+ source: Literal["plain"],
82
+ target: Literal["entities"],
83
+ max_length: int | None = None,
84
+ max_parts: int | None = None,
85
+ strict: bool = False,
86
+ ) -> Conversion:
87
+ """Convert `text` into Telegram messages that the Bot API server keeps as sent.
88
+
89
+ Lenient mode repairs or drops what the server would refuse or change and reports
90
+ each repair or drop as a diagnostic; strict mode raises at the earliest instead, for
91
+ a caller that refuses input that would not arrive unchanged. Text longer than one
92
+ message splits into several, each ending at the best break that fits. The options
93
+ are keyword-only so that a new option never changes the meaning of an existing call.
94
+
95
+ Args:
96
+ text: The text to convert.
97
+ source: The format of `text`: `plain` reads every character as written.
98
+ target: The form of each message: `entities` sends its text with no parse mode.
99
+ max_length: The most code points the text of each message keeps, from 1 to
100
+ 4,096; `None` for 4,096, the server's limit.
101
+ max_parts: The most messages to return, 1 or more; `None` for no cap. The text
102
+ past the last of them is dropped.
103
+ strict: Whether to raise `ConversionError` instead of repairing or dropping.
104
+
105
+ Raises:
106
+ TypeError: If `text`, `source`, or `target` is not a `str`, `max_length` or
107
+ `max_parts` is neither an `int` nor `None`, or `strict` is not a `bool`.
108
+ ValueError: If `source` or `target` names a format other than those above, or
109
+ `max_length` or `max_parts` is out of its range.
110
+ ConversionError: If `strict` is set and lenient mode would repair or
111
+ drop anything.
112
+ """
113
+ _check_arguments(text, source, target, max_length, max_parts, strict)
114
+
115
+ valid, decoding = replace_surrogates(text)
116
+ formatted, lowering = lower_document(read_plain(valid))
117
+ parts, fitting = fit_text(
118
+ formatted,
119
+ max_length=MESSAGE_LENGTH if max_length is None else max_length,
120
+ max_parts=max_parts,
121
+ )
122
+
123
+ notices = sorted((*decoding, *lowering, *fitting), key=lambda n: n.position)
124
+ if strict and notices:
125
+ raise _error(notices[0])
126
+
127
+ return Conversion(
128
+ messages=tuple(Message(part.text) for part in parts),
129
+ diagnostics=tuple(_diagnostic(notice) for notice in notices),
130
+ )
131
+
132
+
133
+ def _check_arguments(
134
+ text: object,
135
+ source: object,
136
+ target: object,
137
+ max_length: object,
138
+ max_parts: object,
139
+ strict: object,
140
+ ) -> None:
141
+ """Raise for an argument of `convert` of the wrong type or value."""
142
+ if not isinstance(text, str):
143
+ raise TypeError(f"text must be str, not {type(text).__name__}")
144
+ _check_choice("source", source, _SOURCES)
145
+ _check_choice("target", target, _TARGETS)
146
+ _check_count("max_length", max_length, MESSAGE_LENGTH)
147
+ _check_count("max_parts", max_parts, None)
148
+ if not isinstance(strict, bool):
149
+ raise TypeError(f"strict must be bool, not {type(strict).__name__}")
150
+
151
+
152
+ def _check_choice(name: str, value: object, choices: tuple[str, ...]) -> None:
153
+ """Raise unless `value`, the argument called `name`, is one of `choices`."""
154
+ if not isinstance(value, str):
155
+ raise TypeError(f"{name} must be str, not {type(value).__name__}")
156
+ if value not in choices:
157
+ alternatives = " or ".join(f"'{choice}'" for choice in choices)
158
+ raise ValueError(f"{name} must be {alternatives}")
159
+
160
+
161
+ def _check_count(name: str, value: object, highest: int | None) -> None:
162
+ """Raise unless `value`, the argument called `name`, is `None` or a count.
163
+
164
+ A count is an `int` from 1 up to `highest`, or with no upper bound when `highest` is
165
+ `None`. A `bool` is refused although it is an `int`, since `True` would read as 1.
166
+ """
167
+ if value is None:
168
+ return
169
+ if isinstance(value, bool) or not isinstance(value, int):
170
+ raise TypeError(f"{name} must be int or None, not {type(value).__name__}")
171
+ if highest is None and value < 1:
172
+ raise ValueError(f"{name} must be at least 1")
173
+ if highest is not None and not 1 <= value <= highest:
174
+ raise ValueError(f"{name} must be from 1 to {highest}")
175
+
176
+
177
+ def _diagnostic(notice: Notice) -> Diagnostic:
178
+ """Return the diagnostic that reports `notice`."""
179
+ condition = notice.condition
180
+ return Diagnostic(
181
+ code=condition.code,
182
+ message=f"{condition.name} {condition.outcome}",
183
+ line=notice.position.line,
184
+ column=notice.position.column,
185
+ )
186
+
187
+
188
+ def _error(notice: Notice) -> ConversionError:
189
+ """Return the error strict mode raises for `notice`."""
190
+ line, column = notice.position.line, notice.position.column
191
+ return ConversionError(
192
+ f"{notice.condition.name} at line {line}, column {column}",
193
+ code=notice.condition.code,
194
+ line=line,
195
+ column=column,
196
+ )
@@ -0,0 +1,42 @@
1
+ """Exception hierarchy rooted at `TGMarkError`."""
2
+
3
+ from functools import partial
4
+
5
+
6
+ class TGMarkError(Exception):
7
+ """Root of the exceptions the package defines.
8
+
9
+ Each exception class the package defines derives from it, so one `except` clause
10
+ catches them all.
11
+ """
12
+
13
+
14
+ class ConversionError(TGMarkError):
15
+ """Raised in strict mode where lenient mode would repair or drop the input.
16
+
17
+ Strict mode converts as lenient mode does, then raises for the condition at the
18
+ earliest input position, the one the input's author fixes first, instead of
19
+ returning a conversion that changes the input. The message names the condition and
20
+ its position and never quotes the input.
21
+
22
+ Attributes:
23
+ code: The condition's code, as a `Diagnostic` carries it.
24
+ line: The line where the condition starts in the input, counted from 1.
25
+ column: The column in that line, counted from 1 in code points.
26
+ """
27
+
28
+ def __init__(self, message: str, *, code: str, line: int, column: int) -> None:
29
+ super().__init__(message)
30
+ self.code = code
31
+ self.line = line
32
+ self.column = column
33
+
34
+ def __reduce__(
35
+ self,
36
+ ) -> tuple[partial["ConversionError"], tuple[object, ...], dict[str, object]]:
37
+ # Unpickling calls the class with `args` alone, which lack the keyword-only
38
+ # attributes, so they travel in a partial.
39
+ rebuild = partial(
40
+ type(self), code=self.code, line=self.line, column=self.column
41
+ )
42
+ return rebuild, self.args, self.__dict__
@@ -0,0 +1 @@
1
+ """Fitting of formatted text into messages."""