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.
- rga_ocr-0.1.1/CHANGELOG.md +104 -0
- rga_ocr-0.1.1/CONTRIBUTING.md +95 -0
- rga_ocr-0.1.1/LICENSE +21 -0
- rga_ocr-0.1.1/MANIFEST.in +5 -0
- rga_ocr-0.1.1/PKG-INFO +618 -0
- rga_ocr-0.1.1/README.md +567 -0
- rga_ocr-0.1.1/SECURITY.md +24 -0
- rga_ocr-0.1.1/docs/design/glossary.md +97 -0
- rga_ocr-0.1.1/pyproject.toml +79 -0
- rga_ocr-0.1.1/setup.cfg +4 -0
- rga_ocr-0.1.1/src/rga_ocr/__init__.py +9 -0
- rga_ocr-0.1.1/src/rga_ocr/adapter.py +290 -0
- rga_ocr-0.1.1/src/rga_ocr/cli.py +1100 -0
- rga_ocr-0.1.1/src/rga_ocr/engines/__init__.py +195 -0
- rga_ocr-0.1.1/src/rga_ocr/engines/rapidocr.py +110 -0
- rga_ocr-0.1.1/src/rga_ocr/engines/tesseract.py +107 -0
- rga_ocr-0.1.1/src/rga_ocr/engines/vision.py +82 -0
- rga_ocr-0.1.1/src/rga_ocr/engines/winocr.py +130 -0
- rga_ocr-0.1.1/src/rga_ocr/paths.py +61 -0
- rga_ocr-0.1.1/src/rga_ocr/setup_cmd.py +490 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/PKG-INFO +618 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/SOURCES.txt +34 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/dependency_links.txt +1 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/entry_points.txt +2 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/requires.txt +31 -0
- rga_ocr-0.1.1/src/rga_ocr.egg-info/top_level.txt +1 -0
- rga_ocr-0.1.1/tests/conftest.py +206 -0
- rga_ocr-0.1.1/tests/data/shot.heic +0 -0
- rga_ocr-0.1.1/tests/make_fixtures.py +249 -0
- rga_ocr-0.1.1/tests/ptyrun.py +35 -0
- rga_ocr-0.1.1/tests/test_adapter.py +132 -0
- rga_ocr-0.1.1/tests/test_cli.py +161 -0
- rga_ocr-0.1.1/tests/test_e2e.py +413 -0
- rga_ocr-0.1.1/tests/test_setup.py +243 -0
- rga_ocr-0.1.1/tools/check_licences.py +73 -0
- 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.
|