exactedit 0.0.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,50 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.2.0] - 2026-11-22
10
+
11
+ ### Fixed
12
+
13
+ - `apply_edits` silently produced wrong output whenever an operation that
14
+ changed the number of lines was followed by another operation, because edits
15
+ were applied top-to-bottom against original line numbers. Edits are now
16
+ applied bottom-to-top regardless of the order they appear in the payload.
17
+ - Lines are now split only on `\n`, `\r\n` and `\r`, as documented.
18
+ Previously `str.splitlines()` also split on form feed, vertical tab,
19
+ `U+0085`, `U+2028`, `U+2029` and similar characters.
20
+ - Deeply nested JSON no longer escapes as `RecursionError`; it raises
21
+ `InvalidInstructionsError`.
22
+
23
+ ### Changed
24
+
25
+ - The project is renamed from `text-edit` to `exactedit` (import `exactedit`), because
26
+ PyPI rejected `text-edit` as too similar to an existing project. The
27
+ `text-edit-v1` instruction format is unchanged.
28
+ - Errors now derive from the new `TextEditError` (itself a `ValueError`):
29
+ `InvalidInstructionsError` for bad payloads and `ContentMismatchError` for
30
+ text that does not match `expected`. Existing `except ValueError` handlers
31
+ keep working.
32
+ - Error messages name the offending operation (`operations[N]`); mismatch
33
+ messages report the first differing line and truncate long content.
34
+ - `apply_edits` parameter `instruction_code` is renamed to `instructions` and
35
+ now also accepts `bytes` and an already-parsed mapping.
36
+ - Implementation moved to the private module `exactedit._core`; import from
37
+ `exactedit`. The module `exactedit.core` no longer exists.
38
+ - `generate_pair` skips the unchanged head and tail of the texts before
39
+ diffing, making localised edits to large or repetitive files much faster.
40
+
41
+ ### Added
42
+
43
+ - `TextEditError`, `InvalidInstructionsError`, `ContentMismatchError`,
44
+ `FORMAT_VERSION` and `__version__` in the public API.
45
+ - Type information (`py.typed`), license (MIT), project metadata, CI, and a
46
+ much larger test suite.
47
+
48
+ ## [0.1.0]
49
+
50
+ - Initial version: `number_lines`, `generate_pair` and `apply_edits`.
@@ -0,0 +1,47 @@
1
+ # Contributing
2
+
3
+ Bug reports and pull requests are welcome. For anything beyond a small fix,
4
+ please open an issue first so the approach can be agreed.
5
+
6
+ ## Development setup
7
+
8
+ Requires Python 3.10+ and pip 25.1+ (for `--group`).
9
+
10
+ ```bash
11
+ python -m venv .venv
12
+ source .venv/bin/activate # Windows: .venv\Scripts\activate
13
+ pip install -e . --group dev
14
+ ```
15
+
16
+ ## Checks
17
+
18
+ Run all of these before opening a pull request; CI runs the same ones.
19
+
20
+ ```bash
21
+ pytest # tests, including the README examples
22
+ ruff check . # lint
23
+ ruff format --check . # formatting (run `ruff format .` to fix)
24
+ mypy # strict type checking
25
+ ```
26
+
27
+ Please add or update tests with every behaviour change, and note user-visible
28
+ changes under "Unreleased" in [CHANGELOG.md](CHANGELOG.md). The project aims to
29
+ stay small and dependency-free; new runtime dependencies need a strong reason.
30
+
31
+ ## Releasing
32
+
33
+ The project follows [Semantic Versioning](https://semver.org/). The version
34
+ lives in one place, `__version__` in `src/exactedit/__init__.py`.
35
+
36
+ 1. Update `__version__` and move the "Unreleased" changelog entries under the
37
+ new version and date.
38
+ 2. Run the checks above.
39
+ 3. Build and verify the distributions:
40
+
41
+ ```bash
42
+ rm -rf dist
43
+ python -m build
44
+ twine check dist/*
45
+ ```
46
+
47
+ 4. Tag the release (`git tag vX.Y.Z`), then upload with `twine upload dist/*`.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 exactedit contributors
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.
@@ -0,0 +1,5 @@
1
+ # setuptools already includes the package, README, LICENSE and pyproject.toml.
2
+ # Also ship what downstream packagers and users of the sdist need.
3
+ include CHANGELOG.md CONTRIBUTING.md
4
+ graft tests
5
+ global-exclude __pycache__ *.py[cod]
@@ -0,0 +1,156 @@
1
+ Metadata-Version: 2.4
2
+ Name: exactedit
3
+ Version: 0.0.0
4
+ Summary: Generate and safely apply line-based JSON edit instructions, preserving line endings exactly.
5
+ Author-email: Alan Tseng <langesant@outlook.com>
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/agentlans/exactedit.git
8
+ Keywords: diff,patch,edit,text,lines,json
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Text Processing
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # exactedit
28
+
29
+ Generate, validate, and apply line-based JSON edit instructions with exact line-ending preservation and zero external dependencies.
30
+
31
+ ## Features
32
+
33
+ * **Explicit numbered views:** Format text with zero-padded line numbers (at least six digits) and JSON-encoded line strings so line endings and invisible characters are unambiguous.
34
+ * **Line-stable JSON edit format (`exactedit-v1`):** Express insertions, deletions, and replacements using 1-based line numbers anchored to the original text.
35
+ * **Atomic, non-overlapping validation:** Verify instructions and expected lines before applying changes, leaving untouched text byte-for-byte intact and never mutating inputs.
36
+ * **Convention-faithful line splitting:** Split on `"\n"`, `"\r\n"`, and `"\r"` (with an optional final terminator) while treating other `str.splitlines()` boundary characters as ordinary text.
37
+ * **Safe error reporting:** Raise `ContentMismatchError` or `InvalidInstructionsError` (both subclasses of `TextEditError` and `ValueError`) with operation indices, first mismatch details, and truncated line excerpts.
38
+ * **Typed and self-contained:** Includes `py.typed` type annotations as well as `FORMAT_VERSION` and `__version__`.
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ pip install exactedit
44
+
45
+ ```
46
+
47
+ ## Quick Start
48
+
49
+ ```python
50
+ from exactedit import apply_edits, generate_pair, number_lines
51
+
52
+ original = "alpha\nbeta\ngamma\n"
53
+ edited = "alpha\nBETA\ngamma\ndelta\n"
54
+
55
+ numbered, instructions = generate_pair(original, edited)
56
+ assert numbered == number_lines(original)
57
+ assert apply_edits(original, instructions) == edited
58
+
59
+ ```
60
+
61
+ `number_lines(original)` produces:
62
+
63
+ ```text
64
+ 000001 | "alpha\n"
65
+ 000002 | "beta\n"
66
+ 000003 | "gamma\n"
67
+
68
+ ```
69
+
70
+ And `generate_pair(original, edited)` returns that numbered view alongside a `exactedit-v1` JSON document:
71
+
72
+ ```json
73
+ {
74
+ "format": "exactedit-v1",
75
+ "indexing": "1-based",
76
+ "position_reference": "original",
77
+ "line_ending_policy": "preserve-exactly",
78
+ "operations": [
79
+ {
80
+ "at_line": 4,
81
+ "delete_count": 0,
82
+ "expected": [],
83
+ "replacement": [
84
+ "delta\n"
85
+ ]
86
+ },
87
+ {
88
+ "at_line": 2,
89
+ "delete_count": 1,
90
+ "expected": [
91
+ "beta\n"
92
+ ],
93
+ "replacement": [
94
+ "BETA\n"
95
+ ]
96
+ }
97
+ ]
98
+ }
99
+
100
+ ```
101
+
102
+ ## Usage
103
+
104
+ ### Writing and Applying `exactedit-v1` Instructions
105
+
106
+ Instructions do not have to come from `generate_pair`; `apply_edits` accepts a JSON string, `bytes`, or an already-parsed mapping. Every payload must include the four header fields shown above with their exact values and a list of non-overlapping operations:
107
+
108
+ | Field | Type | Description |
109
+ | --- | --- | --- |
110
+ | `at_line` | `int` | 1-based line number in the original text where the operation starts (`len(lines) + 1` appends at the end). |
111
+ | `delete_count` | `int` (`>= 0`) | Number of original lines to remove (`0` for a pure insertion). |
112
+ | `expected` | `list[str]` | Exact original lines being removed, including line terminators; must contain `delete_count` items. |
113
+ | `replacement` | `list[str]` | Lines inserted in place of removed lines, used verbatim without adding or normalizing terminators. |
114
+
115
+ Key rules when constructing operations:
116
+
117
+ * **Original line coordinates:** Line positions always refer to the original text rather than a partially edited state, so operation order does not affect application (though `generate_pair` orders operations bottom-to-top for readability).
118
+ * **No overlapping or ambiguous edits:** Adjacent operations are allowed (such as deleting line 1 and inserting at line 2), while two insertions at the same line or an insertion at the first line of a deleted range are rejected.
119
+ * **Line splitting:** Only `"\n"`, `"\r\n"`, and `"\r"` split lines (the final line need not end with a terminator); `"".join(lines)` reproduces the original text exactly.
120
+
121
+ ### Handling Mismatches and Invalid Payloads
122
+
123
+ If `expected` does not match the original text, nothing is modified and `ContentMismatchError` is raised. Malformed JSON, invalid fields, out-of-range positions, or overlapping operations raise `InvalidInstructionsError`.
124
+
125
+ ```python
126
+ from exactedit import ContentMismatchError, apply_edits, generate_pair
127
+
128
+ _, instructions = generate_pair("alpha\nbeta\ngamma\n", "alpha\nBETA\ngamma\n")
129
+
130
+ try:
131
+ apply_edits("alpha\nDIFFERENT\ngamma\n", instructions)
132
+ except ContentMismatchError as exc:
133
+ print(exc)
134
+ # Content mismatch at line 2 (operations[0]): expected 'beta\n', found 'DIFFERENT\n'
135
+
136
+ ```
137
+
138
+ ## Public API and Performance Notes
139
+
140
+ * **Functions:**
141
+ - `number_lines(text: str) -> str`
142
+ - `generate_pair(original: str, edited: str) -> tuple[str, str]`
143
+ - `apply_edits(original: str, instructions: str | bytes | Mapping[str, Any]) -> str`.
144
+ * **Constants and exceptions:** `FORMAT_VERSION` (`"exactedit-v1"`), `__version__`, `TextEditError` (subclass of `ValueError`), `InvalidInstructionsError`, and `ContentMismatchError`. Line excerpts in error messages are truncated to avoid dumping large or sensitive text into logs.
145
+ * **Performance:** `number_lines` and `apply_edits` run in linear time with respect to text size. `generate_pair` relies on `difflib` after skipping unchanged leading and trailing lines, so localized edits are fast, while repeated lines in changed regions increase cost quadratically (in testing, localized edits across 20,000 and 50,000 lines took under a second and about four seconds, respectively, and 200,000 mostly unique lines took about half a second).
146
+
147
+ ## Requirements and Compatibility
148
+
149
+ * **Python:** Python 3.10 or newer.
150
+ * **Dependencies:** None (standard library only).
151
+ * **Typing:** Ships with a `py.typed` marker for static type checkers.
152
+
153
+ ## Licence
154
+
155
+ MIT
156
+
@@ -0,0 +1,130 @@
1
+ # exactedit
2
+
3
+ Generate, validate, and apply line-based JSON edit instructions with exact line-ending preservation and zero external dependencies.
4
+
5
+ ## Features
6
+
7
+ * **Explicit numbered views:** Format text with zero-padded line numbers (at least six digits) and JSON-encoded line strings so line endings and invisible characters are unambiguous.
8
+ * **Line-stable JSON edit format (`exactedit-v1`):** Express insertions, deletions, and replacements using 1-based line numbers anchored to the original text.
9
+ * **Atomic, non-overlapping validation:** Verify instructions and expected lines before applying changes, leaving untouched text byte-for-byte intact and never mutating inputs.
10
+ * **Convention-faithful line splitting:** Split on `"\n"`, `"\r\n"`, and `"\r"` (with an optional final terminator) while treating other `str.splitlines()` boundary characters as ordinary text.
11
+ * **Safe error reporting:** Raise `ContentMismatchError` or `InvalidInstructionsError` (both subclasses of `TextEditError` and `ValueError`) with operation indices, first mismatch details, and truncated line excerpts.
12
+ * **Typed and self-contained:** Includes `py.typed` type annotations as well as `FORMAT_VERSION` and `__version__`.
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ pip install exactedit
18
+
19
+ ```
20
+
21
+ ## Quick Start
22
+
23
+ ```python
24
+ from exactedit import apply_edits, generate_pair, number_lines
25
+
26
+ original = "alpha\nbeta\ngamma\n"
27
+ edited = "alpha\nBETA\ngamma\ndelta\n"
28
+
29
+ numbered, instructions = generate_pair(original, edited)
30
+ assert numbered == number_lines(original)
31
+ assert apply_edits(original, instructions) == edited
32
+
33
+ ```
34
+
35
+ `number_lines(original)` produces:
36
+
37
+ ```text
38
+ 000001 | "alpha\n"
39
+ 000002 | "beta\n"
40
+ 000003 | "gamma\n"
41
+
42
+ ```
43
+
44
+ And `generate_pair(original, edited)` returns that numbered view alongside a `exactedit-v1` JSON document:
45
+
46
+ ```json
47
+ {
48
+ "format": "exactedit-v1",
49
+ "indexing": "1-based",
50
+ "position_reference": "original",
51
+ "line_ending_policy": "preserve-exactly",
52
+ "operations": [
53
+ {
54
+ "at_line": 4,
55
+ "delete_count": 0,
56
+ "expected": [],
57
+ "replacement": [
58
+ "delta\n"
59
+ ]
60
+ },
61
+ {
62
+ "at_line": 2,
63
+ "delete_count": 1,
64
+ "expected": [
65
+ "beta\n"
66
+ ],
67
+ "replacement": [
68
+ "BETA\n"
69
+ ]
70
+ }
71
+ ]
72
+ }
73
+
74
+ ```
75
+
76
+ ## Usage
77
+
78
+ ### Writing and Applying `exactedit-v1` Instructions
79
+
80
+ Instructions do not have to come from `generate_pair`; `apply_edits` accepts a JSON string, `bytes`, or an already-parsed mapping. Every payload must include the four header fields shown above with their exact values and a list of non-overlapping operations:
81
+
82
+ | Field | Type | Description |
83
+ | --- | --- | --- |
84
+ | `at_line` | `int` | 1-based line number in the original text where the operation starts (`len(lines) + 1` appends at the end). |
85
+ | `delete_count` | `int` (`>= 0`) | Number of original lines to remove (`0` for a pure insertion). |
86
+ | `expected` | `list[str]` | Exact original lines being removed, including line terminators; must contain `delete_count` items. |
87
+ | `replacement` | `list[str]` | Lines inserted in place of removed lines, used verbatim without adding or normalizing terminators. |
88
+
89
+ Key rules when constructing operations:
90
+
91
+ * **Original line coordinates:** Line positions always refer to the original text rather than a partially edited state, so operation order does not affect application (though `generate_pair` orders operations bottom-to-top for readability).
92
+ * **No overlapping or ambiguous edits:** Adjacent operations are allowed (such as deleting line 1 and inserting at line 2), while two insertions at the same line or an insertion at the first line of a deleted range are rejected.
93
+ * **Line splitting:** Only `"\n"`, `"\r\n"`, and `"\r"` split lines (the final line need not end with a terminator); `"".join(lines)` reproduces the original text exactly.
94
+
95
+ ### Handling Mismatches and Invalid Payloads
96
+
97
+ If `expected` does not match the original text, nothing is modified and `ContentMismatchError` is raised. Malformed JSON, invalid fields, out-of-range positions, or overlapping operations raise `InvalidInstructionsError`.
98
+
99
+ ```python
100
+ from exactedit import ContentMismatchError, apply_edits, generate_pair
101
+
102
+ _, instructions = generate_pair("alpha\nbeta\ngamma\n", "alpha\nBETA\ngamma\n")
103
+
104
+ try:
105
+ apply_edits("alpha\nDIFFERENT\ngamma\n", instructions)
106
+ except ContentMismatchError as exc:
107
+ print(exc)
108
+ # Content mismatch at line 2 (operations[0]): expected 'beta\n', found 'DIFFERENT\n'
109
+
110
+ ```
111
+
112
+ ## Public API and Performance Notes
113
+
114
+ * **Functions:**
115
+ - `number_lines(text: str) -> str`
116
+ - `generate_pair(original: str, edited: str) -> tuple[str, str]`
117
+ - `apply_edits(original: str, instructions: str | bytes | Mapping[str, Any]) -> str`.
118
+ * **Constants and exceptions:** `FORMAT_VERSION` (`"exactedit-v1"`), `__version__`, `TextEditError` (subclass of `ValueError`), `InvalidInstructionsError`, and `ContentMismatchError`. Line excerpts in error messages are truncated to avoid dumping large or sensitive text into logs.
119
+ * **Performance:** `number_lines` and `apply_edits` run in linear time with respect to text size. `generate_pair` relies on `difflib` after skipping unchanged leading and trailing lines, so localized edits are fast, while repeated lines in changed regions increase cost quadratically (in testing, localized edits across 20,000 and 50,000 lines took under a second and about four seconds, respectively, and 200,000 mostly unique lines took about half a second).
120
+
121
+ ## Requirements and Compatibility
122
+
123
+ * **Python:** Python 3.10 or newer.
124
+ * **Dependencies:** None (standard library only).
125
+ * **Typing:** Ships with a `py.typed` marker for static type checkers.
126
+
127
+ ## Licence
128
+
129
+ MIT
130
+
@@ -0,0 +1,58 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "exactedit"
7
+ dynamic = ["version"]
8
+ description = "Generate and safely apply line-based JSON edit instructions, preserving line endings exactly."
9
+ authors = [
10
+ { name="Alan Tseng", email="langesant@outlook.com" },
11
+ ]
12
+ readme = "README.md"
13
+ requires-python = ">=3.10"
14
+ license = "MIT"
15
+ license-files = ["LICENSE"]
16
+ keywords = ["diff", "patch", "edit", "text", "lines", "json"]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Intended Audience :: Developers",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ "Programming Language :: Python :: 3.10",
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
+ "Topic :: Software Development :: Libraries :: Python Modules",
29
+ "Topic :: Text Processing",
30
+ "Typing :: Typed",
31
+ ]
32
+ dependencies = []
33
+
34
+ [dependency-groups]
35
+ dev = ["pytest", "ruff", "mypy", "build", "twine"]
36
+
37
+ [project.urls]
38
+ Repository = "https://github.com/agentlans/exactedit.git"
39
+
40
+ [tool.setuptools.package-data]
41
+ exactedit = ["py.typed"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+ addopts = ["-ra", "--strict-markers", "--strict-config"]
46
+ filterwarnings = ["error"]
47
+
48
+ [tool.ruff]
49
+ target-version = "py310"
50
+ src = ["src", "tests"]
51
+
52
+ [tool.ruff.lint]
53
+ select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "PT"]
54
+
55
+ [tool.mypy]
56
+ strict = true
57
+ files = ["src", "tests"]
58
+ python_version = "3.10"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,24 @@
1
+ """Generate and apply line-based JSON edit instructions (``text-edit-v1``)."""
2
+
3
+ from ._core import (
4
+ FORMAT_VERSION,
5
+ ContentMismatchError,
6
+ InvalidInstructionsError,
7
+ TextEditError,
8
+ apply_edits,
9
+ generate_pair,
10
+ number_lines,
11
+ )
12
+
13
+ __version__ = "0.2.0"
14
+
15
+ __all__ = [
16
+ "FORMAT_VERSION",
17
+ "ContentMismatchError",
18
+ "InvalidInstructionsError",
19
+ "TextEditError",
20
+ "__version__",
21
+ "apply_edits",
22
+ "generate_pair",
23
+ "number_lines",
24
+ ]