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.
- tgmark-0.1.0/.gitignore +30 -0
- tgmark-0.1.0/LICENSE +21 -0
- tgmark-0.1.0/PKG-INFO +111 -0
- tgmark-0.1.0/README.md +84 -0
- tgmark-0.1.0/pyproject.toml +155 -0
- tgmark-0.1.0/src/tgmark/__init__.py +25 -0
- tgmark-0.1.0/src/tgmark/conversion.py +196 -0
- tgmark-0.1.0/src/tgmark/exceptions.py +42 -0
- tgmark-0.1.0/src/tgmark/fit/__init__.py +1 -0
- tgmark-0.1.0/src/tgmark/fit/graphemes.py +222 -0
- tgmark-0.1.0/src/tgmark/fit/parts.py +270 -0
- tgmark-0.1.0/src/tgmark/lower/__init__.py +1 -0
- tgmark-0.1.0/src/tgmark/lower/characters.py +87 -0
- tgmark-0.1.0/src/tgmark/lower/table.py +26 -0
- tgmark-0.1.0/src/tgmark/model/__init__.py +1 -0
- tgmark-0.1.0/src/tgmark/model/diagnostics.py +76 -0
- tgmark-0.1.0/src/tgmark/model/document.py +84 -0
- tgmark-0.1.0/src/tgmark/model/formatted.py +84 -0
- tgmark-0.1.0/src/tgmark/model/server.py +41 -0
- tgmark-0.1.0/src/tgmark/parse/__init__.py +1 -0
- tgmark-0.1.0/src/tgmark/parse/decoding.py +24 -0
- tgmark-0.1.0/src/tgmark/parse/plain.py +26 -0
- tgmark-0.1.0/src/tgmark/py.typed +0 -0
tgmark-0.1.0/.gitignore
ADDED
|
@@ -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
|
+
[](https://github.com/theodiv/tgmark/blob/main/LICENSE)
|
|
33
|
+
[](https://www.python.org/downloads/)
|
|
34
|
+
[](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
|
+
[](https://github.com/theodiv/tgmark/blob/main/LICENSE)
|
|
6
|
+
[](https://www.python.org/downloads/)
|
|
7
|
+
[](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."""
|