rga-ocr 0.1.1__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.
Files changed (36) hide show
  1. rga_ocr-0.1.1/CHANGELOG.md +104 -0
  2. rga_ocr-0.1.1/CONTRIBUTING.md +95 -0
  3. rga_ocr-0.1.1/LICENSE +21 -0
  4. rga_ocr-0.1.1/MANIFEST.in +5 -0
  5. rga_ocr-0.1.1/PKG-INFO +618 -0
  6. rga_ocr-0.1.1/README.md +567 -0
  7. rga_ocr-0.1.1/SECURITY.md +24 -0
  8. rga_ocr-0.1.1/docs/design/glossary.md +97 -0
  9. rga_ocr-0.1.1/pyproject.toml +79 -0
  10. rga_ocr-0.1.1/setup.cfg +4 -0
  11. rga_ocr-0.1.1/src/rga_ocr/__init__.py +9 -0
  12. rga_ocr-0.1.1/src/rga_ocr/adapter.py +290 -0
  13. rga_ocr-0.1.1/src/rga_ocr/cli.py +1100 -0
  14. rga_ocr-0.1.1/src/rga_ocr/engines/__init__.py +195 -0
  15. rga_ocr-0.1.1/src/rga_ocr/engines/rapidocr.py +110 -0
  16. rga_ocr-0.1.1/src/rga_ocr/engines/tesseract.py +107 -0
  17. rga_ocr-0.1.1/src/rga_ocr/engines/vision.py +82 -0
  18. rga_ocr-0.1.1/src/rga_ocr/engines/winocr.py +130 -0
  19. rga_ocr-0.1.1/src/rga_ocr/paths.py +61 -0
  20. rga_ocr-0.1.1/src/rga_ocr/setup_cmd.py +490 -0
  21. rga_ocr-0.1.1/src/rga_ocr.egg-info/PKG-INFO +618 -0
  22. rga_ocr-0.1.1/src/rga_ocr.egg-info/SOURCES.txt +34 -0
  23. rga_ocr-0.1.1/src/rga_ocr.egg-info/dependency_links.txt +1 -0
  24. rga_ocr-0.1.1/src/rga_ocr.egg-info/entry_points.txt +2 -0
  25. rga_ocr-0.1.1/src/rga_ocr.egg-info/requires.txt +31 -0
  26. rga_ocr-0.1.1/src/rga_ocr.egg-info/top_level.txt +1 -0
  27. rga_ocr-0.1.1/tests/conftest.py +206 -0
  28. rga_ocr-0.1.1/tests/data/shot.heic +0 -0
  29. rga_ocr-0.1.1/tests/make_fixtures.py +249 -0
  30. rga_ocr-0.1.1/tests/ptyrun.py +35 -0
  31. rga_ocr-0.1.1/tests/test_adapter.py +132 -0
  32. rga_ocr-0.1.1/tests/test_cli.py +161 -0
  33. rga_ocr-0.1.1/tests/test_e2e.py +413 -0
  34. rga_ocr-0.1.1/tests/test_setup.py +243 -0
  35. rga_ocr-0.1.1/tools/check_licences.py +73 -0
  36. rga_ocr-0.1.1/tools/check_tools.py +61 -0
@@ -0,0 +1,104 @@
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/).
6
+
7
+ ## [Unreleased]
8
+
9
+ Nothing yet.
10
+
11
+ ## [0.1.1] - 2026-11-18
12
+
13
+ ### Added
14
+
15
+ - `rga-ocr` is on PyPI: `pipx install "rga-ocr[vision]"`. The README and the
16
+ install hints of `rga-ocr setup` use the PyPI name instead of the git URL.
17
+ - The sdist carries the test suite and the fixture builder, so
18
+ `python -m pytest` works from an unpacked source archive.
19
+ - A release workflow that publishes to PyPI through trusted publishing.
20
+ - CI checks the declared licence of every dependency, extras included,
21
+ against an allow-list without GPL or AGPL.
22
+
23
+ ### Changed
24
+
25
+ - The quick start names the Python 3.15 workaround (`--python python3.14`).
26
+ - The `rga_ocr.engines` entry-point hook stays in the code but is
27
+ experimental and no longer advertised: the engine protocol is not a
28
+ stable interface yet.
29
+
30
+ ## [0.1.0] - 2026-11-18
31
+
32
+ First public release.
33
+
34
+ ### Added
35
+
36
+ - macOS, Linux and Windows. OCR engines behind one protocol: `vision`
37
+ (Apple Vision), `winocr` (Windows.Media.Ocr), `rapidocr` (PP-OCR models
38
+ on ONNX Runtime, any platform; per-script models for Cyrillic, Arabic,
39
+ Devanagari, Korean, Thai, Greek, Tamil, Telugu and Georgian), `tesseract`
40
+ (tesserocr); `--engine`, the `engine` profile key and `RGA_OCR_ENGINE`;
41
+ `--engines` lists what works on the machine and what `auto` picks;
42
+ third-party engines via the `rga_ocr.engines` entry-point group.
43
+ - `rga-ocr setup [--apply] [--engine NAME] [--lang L] [--config PATH]`:
44
+ checks tools and engine, prints install commands per package manager,
45
+ fetches Tesseract language files, merges the adapter entries into rga's
46
+ config (first run keeps a `.bak`, later runs a timestamped copy) and
47
+ honours `--rga-config-file=PATH`; exit 0 ready, 1 something to do,
48
+ 2 usage error.
49
+ - Image decoding through Pillow and pi-heif (HEIC/HEIF) on every platform;
50
+ PDF text layers through pypdfium2 (PDFium), pages without one are
51
+ rendered and OCR'd.
52
+ - `rga-ocr` CLI: file-name pass plus a ripgrep-all content pass in one
53
+ command, exit codes 0/1/2.
54
+ - ripgrep-all custom adapters `ocrpdf`, `ocrimg`, `officexml`: OCR of PDF
55
+ pages and images through the configured engine; xlsx, pptx, ods, odp
56
+ text extraction.
57
+ - Profile file `~/.config/rga-ocr/config` (`%APPDATA%\rga-ocr\config` on
58
+ Windows) with keys `engine`, `lang`, `exclude`, `case`, `name_blank`,
59
+ `name_blank_optional`, `snippet`, `cache_dir`, `adapters_extra`,
60
+ `progress`; `RGA_OCR_<KEY>` environment mirrors; `--init-config`.
61
+ - Snippet window around content matches (`--snippet N`, `--full`) with
62
+ `Page N:` and archive-member prefixes kept; grouped, highlighted output on
63
+ a terminal; `--json` pass-through with name events.
64
+ - Name-pass blank handling: `nonletter` (default), `separators`, `strict`,
65
+ optional empty run.
66
+ - Language auto-detection where the engine supports it, `--lang` to pin
67
+ languages; one OCR cache directory per engine and language setting
68
+ (`<engine>-<lang>[-force]`, `none` for `--no-ocr`).
69
+ - Live status line on a terminal while the content pass runs (spinner,
70
+ elapsed time, hits, files OCR'd, current file) and a one-line summary
71
+ after the content pass (`searched 12.4 s · 3 hits · 14 files OCR'd`);
72
+ `--progress` /
73
+ `--no-progress` and the `progress` profile key.
74
+ - Adapter errors are reported after the run; rg discards a preprocessor's
75
+ stderr on exit 0, so the adapters write progress and errors to a per-run
76
+ report file (`RGA_OCR_REPORT`).
77
+ - `--no-cache` uses a throwaway cache directory per run instead of
78
+ `--rga-no-cache`, which fails on custom adapters in ripgrep-all 0.10.10.
79
+ - The `rapidocr` engine sets `ORT_DISABLE_TELEMETRY=1` before ONNX Runtime
80
+ loads, so the telemetry that the official wheels switch on by default
81
+ never starts (it also removed a hang of the adapter process at exit
82
+ inside that telemetry's shutdown). The adapter ends with `os._exit(0)`
83
+ after flushing its output, so native library teardown cannot change its
84
+ exit status or keep ripgrep-all waiting.
85
+ - The cache database is created with ripgrep-all's schema before each run
86
+ and held open until ripgrep-all exits, so parallel `rga-preproc`
87
+ processes do not race on creating it or on rebuilding its WAL index
88
+ (`The database file is locked`, file skipped).
89
+ - `--cache-info` lists the caches as a table with a stable cache-id (sha1
90
+ of the directory name), engine, language, entries, size, last added date
91
+ and the folders the entries come from; `--clear-cache CACHE-ID|DIR ...|all`
92
+ deletes the named caches or every cache (files under `cache_dir` that are
93
+ not caches stay), lists them first for `all`, and exits 2 without
94
+ arguments; `--dry-run` shows what would go.
95
+ - rg's output-format flags (`-l`, `-c`, `--count-matches`,
96
+ `--files-without-match`, `--files`, `-q`) are refused with exit 2 because
97
+ the content pass reads rg's JSON events; usage errors exit 2.
98
+ - pytest suite split into end-to-end, adapter and setup tests, runnable
99
+ per engine with `RGA_OCR_ENGINE`; GitHub Actions matrix across macOS,
100
+ Ubuntu and Windows.
101
+
102
+ [Unreleased]: https://github.com/luca-rui/rga-ocr/compare/v0.1.1...HEAD
103
+ [0.1.1]: https://github.com/luca-rui/rga-ocr/compare/v0.1.0...v0.1.1
104
+ [0.1.0]: https://github.com/luca-rui/rga-ocr/releases/tag/v0.1.0
@@ -0,0 +1,95 @@
1
+ # Contributing
2
+
3
+ Bug reports and pull requests are welcome. For anything larger than a fix,
4
+ open an issue first so the approach can be discussed.
5
+
6
+ ## Development setup
7
+
8
+ ```
9
+ git clone https://github.com/luca-rui/rga-ocr
10
+ cd rga-ocr
11
+ python -m venv .venv
12
+ .venv/bin/pip install -e '.[vision,tesseract,rapidocr,test]' # the extras your platform supports
13
+ .venv/bin/python -m pytest -q
14
+ ```
15
+
16
+ The end-to-end tests need `rga`, `rg` and `pandoc` on PATH (see the
17
+ Install section of the README) and one working OCR engine. The unit tests
18
+ in `tests/test_adapter.py`, `tests/test_cli.py` and `tests/test_setup.py`
19
+ run without them:
20
+
21
+ ```
22
+ .venv/bin/python -m pytest -q tests/test_adapter.py tests/test_cli.py tests/test_setup.py
23
+ ```
24
+
25
+ Run the suite per engine with `RGA_OCR_ENGINE`:
26
+
27
+ ```
28
+ RGA_OCR_ENGINE=tesseract .venv/bin/python -m pytest -q
29
+ RGA_OCR_ENGINE=rapidocr .venv/bin/python -m pytest -q
30
+ ```
31
+
32
+ The tesseract leg fetches the `eng` and `deu` language files into its temp
33
+ root when it finds none; the rapidocr leg downloads nothing for the default
34
+ model. Apple Vision needs a GUI session.
35
+
36
+ ## Fixtures
37
+
38
+ `tests/make_fixtures.py` builds the fixture tree at test time (text files,
39
+ PDFs written by hand, images drawn with Pillow, Office files). It needs no
40
+ OCR engine, only Pillow. `tests/data/shot.heic` is the one
41
+ tracked binary: a HEIC encoding of the generated `photo.png`, used where
42
+ `sips` is not available to encode one. Regenerate it on a Mac with
43
+ `sips -s format heic photo.png --out tests/data/shot.heic` after changing
44
+ the photo text.
45
+
46
+ ## Adapter versions
47
+
48
+ The three rga adapters (`ocrpdf`, `ocrimg`, `officexml`) carry a `version`
49
+ in `src/rga_ocr/setup_cmd.py`. rga keys its cache on it: bump the version
50
+ of an adapter whenever its output for the same input changes (text
51
+ extraction, paragraph grouping, page breaks), so that cached entries are
52
+ not served stale. Users pick the new version up with
53
+ `rga-ocr setup --apply`.
54
+
55
+ ## CI
56
+
57
+ GitHub Actions runs the suite on macOS (vision, tesseract), Ubuntu
58
+ (rapidocr, tesseract, and an `auto` leg that relies on `setup --apply`)
59
+ and Windows (rapidocr, winocr), plus a build job that checks the sdist and
60
+ wheel, installs the wheel into a clean venv and verifies that neither
61
+ PyMuPDF nor pillow-heif comes along. The build job also runs
62
+ `tools/check_licences.py` over an install with the `rapidocr` and
63
+ `tesseract` extras on Linux and runs the unit tests from the unpacked
64
+ sdist. The licence check reads the licence each distribution declares in
65
+ its metadata and accepts only names on its allow-list, which holds no GPL
66
+ or AGPL; it does not inspect files inside the wheels.
67
+
68
+ ## Releases
69
+
70
+ `.github/workflows/release.yml` publishes through PyPI trusted publishing;
71
+ the repository holds no API token.
72
+
73
+ 1. Dry run: start the workflow by hand ("Run workflow") on a branch whose
74
+ `VERSION` in `src/rga_ocr/__init__.py` is a pre-release such as
75
+ `0.2.0rc1`. It uploads to TestPyPI only. Install from there into a clean
76
+ venv:
77
+ `pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ rga-ocr==0.2.0rc1`.
78
+ 2. Set `VERSION`, move the `[Unreleased]` entries in `CHANGELOG.md` under
79
+ the new version, merge.
80
+ 3. Tag the merge commit on `main` as `vX.Y.Z` and push the tag. The
81
+ workflow refuses a tag that differs from `VERSION` or points at a commit
82
+ that is not on `main`, then uploads to PyPI. Tags and PyPI versions are
83
+ immutable: a wrong release is fixed by the next version.
84
+ 4. Create the GitHub release from the tag with the changelog section.
85
+
86
+ Repeat the dry run after any change to `release.yml`, including a
87
+ Dependabot update of the actions it uses: CI does not exercise that
88
+ workflow.
89
+
90
+ ## Style
91
+
92
+ Plain Python, standard library where it suffices, no framework for the
93
+ CLI. Keep the README and `docs/design/glossary.md` in step with
94
+ user-visible changes, and add a line to `CHANGELOG.md` under
95
+ `[Unreleased]`.
rga_ocr-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luca Rui
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
+ graft tests
2
+ graft tools
3
+ graft docs
4
+ include CHANGELOG.md CONTRIBUTING.md SECURITY.md
5
+ global-exclude __pycache__ *.py[cod]