ocr-software 0.1.0__tar.gz → 0.1.2__tar.gz

ocr_software-0.1.2/INSTALL.txt

@@ -0,0 +1,106 @@
+# ocr-software
+
+Python client and command line for the [ocr-software.com](https://ocr-software.com/) OCR API. MIT, standard library only, Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install ocr-software        # command line only, in its own environment
+pip install ocr-software         # client library, inside a venv
+uvx ocr-software --version       # run once without installing (uv)
+```
+
+First call (list the pipelines, then read one file):
+
+```sh
+ocr-software --list-pipelines
+ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
+```
+
+## Settings
+
+Environment variables; the command line flag wins.
+
+| Variable | Meaning |
+|---|---|
+| `OCR_SOFTWARE_API_KEY` | API key (starts with `ocr_`). `OCR_KEY` is read too, it is the name used in the API docs; if both are set, `OCR_SOFTWARE_API_KEY` wins. |
+| `OCR_SOFTWARE_BASE_URL` | Default `https://api.ocr-software.com`; own server e.g. `http://127.0.0.1:8080` (also `--base-url`). `OCR_BASE_URL` is read too. |
+| `OCR_SOFTWARE_ALLOWED_DIR` | Optional: read documents only from below this folder (symlinks and `..` do not escape). |
+
+The key is never printed and never part of an error message. Without `--pipeline` the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr (`-q` silences that line for bulk runs; `-o NUL` or `-o /dev/null` discards the result); `--list-pipelines` marks it. Warnings of the service (`dpi_ignored`, `job_budget`, `free_limit`, `balance_too_low`) are printed as `warning CODE: text` lines on stderr by `--dry-run` and before a job that uses `--dpi` or `--job-budget` (that job asks once with a dry run first). In Python: `client.ocr(path, client.default_pipeline())`.
+
+## Command line
+
+```sh
+ocr-software --list-pipelines                         # available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
+ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   # page count and price in euros, nothing runs, nothing is billed
+ocr-software scan.pdf                                 # text to stdout, with the default pipeline (named on stderr)
+ocr-software scan.pdf --pipeline NAME@VERSION         # text to stdout
+ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
+ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
+ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf   # searchable PDF, -o is required
+ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
+ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080  # your own server
+python -m ocr_software ...                            # the same command without the script on PATH
+```
+
+Options:
+- `--format text` (default) `| md | json | hocr | pdf`
+- `--dpi 150|200|300` (PDF render resolution)
+- `--timeout SECONDS` (wait for the job, default 3600)
+- `--job-budget MILLICENTS` (cap; ignored where billing is off)
+- `-q`, `--dry-run`, `--version`
+
+Without `-o` the result goes to stdout as UTF-8 (not for pdf). With `-o` the file appears whole or not at all, an existing file is replaced, and the input file itself is refused as output.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done, every page read |
+| 1 | error from the service or the network (message on stderr with the API error code, for example 401 unauthorized); also an address that does not answer: a typo and an outage look the same, so a script may retry this |
+| 2 | wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https) |
+| 3 | the job is done but a page failed or did not run, or the job stopped early: the result is written anyway, stderr says what is missing and names the job; treat the file as incomplete |
+| 4 | the job did not finish within `--timeout`; it keeps running, stderr names the job |
+
+## Python
+
+```python
+from ocr_software import Client, PagesUnread
+client = Client()                                    # key and address from the environment
+text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes (text.decode("utf-8") for a string); raises PagesUnread (with .data) if a page was not read
+pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
+job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
+client.wait(job["job_id"]); client.result(job["job_id"], "json")
+q = client.quote("scan.pdf", "NAME@VERSION")         # dry run: page count and price, nothing runs
+from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
+```
+
+**Price:** the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001). Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits: [fair usage](https://ocr-software.com/legal/fair-usage/); for more volume write to info@ocr-software.com.
+
+**Word boxes (json):** `box = [x0, y0, x1, y1]` in pixels of the page image, origin top left; `width`, `height` and `dpi` of the page say which image. In PDF points: pixels * 72 / dpi. Per word, `verified` is true only where a second reader confirmed it (`scan-vlm-ctc@2`); `safe_ok` is always false today. Judge by `confidence` (0 to 1). Every field: [reference](https://ocr-software.com/docs/reference/).
+
+**Retries** follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or `Retry-After`). An upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A `Retry-After` over 60 s (`locked_out`) is not waited for. A submit carries an `Idempotency-Key`, so a retry never creates a second job.
+
+Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
+
+## Paperless-ngx
+
+Pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
+
+```sh
+#!/bin/sh
+ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
+```
+
+with `OCR_SOFTWARE_API_KEY` and `OCR_SOFTWARE_BASE_URL` set in the environment of the Paperless container.
+
+## Tests
+
+Fake local service, no network, no key:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install pytest                          # Windows: .venv\Scripts\pip install pytest
+.venv/bin/python -m pytest -p no:cacheprovider .      # Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .
+```

ocr_software-0.1.2/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: ocr-software
+Version: 0.1.2
+Summary: Client and command line for the ocr-software.com OCR API: text, word boxes, layout, searchable PDF.
+License-Expression: MIT
+Project-URL: Homepage, https://ocr-software.com/integrations/python/
+Project-URL: Repository, https://github.com/ocr-software/ocr-software-python
+Keywords: ocr,pdf,searchable-pdf,hocr,markdown,document-ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest==9.0.2; extra == "test"
+Dynamic: license-file
+
+# ocr-software
+
+Python client and command line for the [ocr-software.com](https://ocr-software.com/) OCR API. MIT, standard library only, Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install ocr-software        # command line only, in its own environment
+pip install ocr-software         # client library, inside a venv
+uvx ocr-software --version       # run once without installing (uv)
+```
+
+First call (list the pipelines, then read one file):
+
+```sh
+ocr-software --list-pipelines
+ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
+```
+
+## Settings
+
+Environment variables; the command line flag wins.
+
+| Variable | Meaning |
+|---|---|
+| `OCR_SOFTWARE_API_KEY` | API key (starts with `ocr_`). `OCR_KEY` is read too, it is the name used in the API docs; if both are set, `OCR_SOFTWARE_API_KEY` wins. |
+| `OCR_SOFTWARE_BASE_URL` | Default `https://api.ocr-software.com`; own server e.g. `http://127.0.0.1:8080` (also `--base-url`). `OCR_BASE_URL` is read too. |
+| `OCR_SOFTWARE_ALLOWED_DIR` | Optional: read documents only from below this folder (symlinks and `..` do not escape). |
+
+The key is never printed and never part of an error message. Without `--pipeline` the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr (`-q` silences that line for bulk runs; `-o NUL` or `-o /dev/null` discards the result); `--list-pipelines` marks it. Warnings of the service (`dpi_ignored`, `job_budget`, `free_limit`, `balance_too_low`) are printed as `warning CODE: text` lines on stderr by `--dry-run` and before a job that uses `--dpi` or `--job-budget` (that job asks once with a dry run first). In Python: `client.ocr(path, client.default_pipeline())`.
+
+## Command line
+
+```sh
+ocr-software --list-pipelines                         # available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
+ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   # page count and price in euros, nothing runs, nothing is billed
+ocr-software scan.pdf                                 # text to stdout, with the default pipeline (named on stderr)
+ocr-software scan.pdf --pipeline NAME@VERSION         # text to stdout
+ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
+ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
+ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf   # searchable PDF, -o is required
+ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
+ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080  # your own server
+python -m ocr_software ...                            # the same command without the script on PATH
+```
+
+Options:
+- `--format text` (default) `| md | json | hocr | pdf`
+- `--dpi 150|200|300` (PDF render resolution)
+- `--timeout SECONDS` (wait for the job, default 3600)
+- `--job-budget MILLICENTS` (cap; ignored where billing is off)
+- `-q`, `--dry-run`, `--version`
+
+Without `-o` the result goes to stdout as UTF-8 (not for pdf). With `-o` the file appears whole or not at all, an existing file is replaced, and the input file itself is refused as output.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done, every page read |
+| 1 | error from the service or the network (message on stderr with the API error code, for example 401 unauthorized); also an address that does not answer: a typo and an outage look the same, so a script may retry this |
+| 2 | wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https) |
+| 3 | the job is done but a page failed or did not run, or the job stopped early: the result is written anyway, stderr says what is missing and names the job; treat the file as incomplete |
+| 4 | the job did not finish within `--timeout`; it keeps running, stderr names the job |
+
+## Python
+
+```python
+from ocr_software import Client, PagesUnread
+client = Client()                                    # key and address from the environment
+text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes (text.decode("utf-8") for a string); raises PagesUnread (with .data) if a page was not read
+pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
+job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
+client.wait(job["job_id"]); client.result(job["job_id"], "json")
+q = client.quote("scan.pdf", "NAME@VERSION")         # dry run: page count and price, nothing runs
+from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
+```
+
+**Price:** the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001). Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits: [fair usage](https://ocr-software.com/legal/fair-usage/); for more volume write to info@ocr-software.com.
+
+**Word boxes (json):** `box = [x0, y0, x1, y1]` in pixels of the page image, origin top left; `width`, `height` and `dpi` of the page say which image. In PDF points: pixels * 72 / dpi. Per word, `verified` is true only where a second reader confirmed it (`scan-vlm-ctc@2`); `safe_ok` is always false today. Judge by `confidence` (0 to 1). Every field: [reference](https://ocr-software.com/docs/reference/).
+
+**Retries** follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or `Retry-After`). An upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A `Retry-After` over 60 s (`locked_out`) is not waited for. A submit carries an `Idempotency-Key`, so a retry never creates a second job.
+
+Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
+
+## Paperless-ngx
+
+Pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
+
+```sh
+#!/bin/sh
+ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
+```
+
+with `OCR_SOFTWARE_API_KEY` and `OCR_SOFTWARE_BASE_URL` set in the environment of the Paperless container.
+
+## Tests
+
+Fake local service, no network, no key:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install pytest                          # Windows: .venv\Scripts\pip install pytest
+.venv/bin/python -m pytest -p no:cacheprovider .      # Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .
+```

ocr_software-0.1.2/README.md

@@ -0,0 +1,106 @@
+# ocr-software
+
+Python client and command line for the [ocr-software.com](https://ocr-software.com/) OCR API. MIT, standard library only, Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install ocr-software        # command line only, in its own environment
+pip install ocr-software         # client library, inside a venv
+uvx ocr-software --version       # run once without installing (uv)
+```
+
+First call (list the pipelines, then read one file):
+
+```sh
+ocr-software --list-pipelines
+ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
+```
+
+## Settings
+
+Environment variables; the command line flag wins.
+
+| Variable | Meaning |
+|---|---|
+| `OCR_SOFTWARE_API_KEY` | API key (starts with `ocr_`). `OCR_KEY` is read too, it is the name used in the API docs; if both are set, `OCR_SOFTWARE_API_KEY` wins. |
+| `OCR_SOFTWARE_BASE_URL` | Default `https://api.ocr-software.com`; own server e.g. `http://127.0.0.1:8080` (also `--base-url`). `OCR_BASE_URL` is read too. |
+| `OCR_SOFTWARE_ALLOWED_DIR` | Optional: read documents only from below this folder (symlinks and `..` do not escape). |
+
+The key is never printed and never part of an error message. Without `--pipeline` the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr (`-q` silences that line for bulk runs; `-o NUL` or `-o /dev/null` discards the result); `--list-pipelines` marks it. Warnings of the service (`dpi_ignored`, `job_budget`, `free_limit`, `balance_too_low`) are printed as `warning CODE: text` lines on stderr by `--dry-run` and before a job that uses `--dpi` or `--job-budget` (that job asks once with a dry run first). In Python: `client.ocr(path, client.default_pipeline())`.
+
+## Command line
+
+```sh
+ocr-software --list-pipelines                         # available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
+ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   # page count and price in euros, nothing runs, nothing is billed
+ocr-software scan.pdf                                 # text to stdout, with the default pipeline (named on stderr)
+ocr-software scan.pdf --pipeline NAME@VERSION         # text to stdout
+ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
+ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
+ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf   # searchable PDF, -o is required
+ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
+ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080  # your own server
+python -m ocr_software ...                            # the same command without the script on PATH
+```
+
+Options:
+- `--format text` (default) `| md | json | hocr | pdf`
+- `--dpi 150|200|300` (PDF render resolution)
+- `--timeout SECONDS` (wait for the job, default 3600)
+- `--job-budget MILLICENTS` (cap; ignored where billing is off)
+- `-q`, `--dry-run`, `--version`
+
+Without `-o` the result goes to stdout as UTF-8 (not for pdf). With `-o` the file appears whole or not at all, an existing file is replaced, and the input file itself is refused as output.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done, every page read |
+| 1 | error from the service or the network (message on stderr with the API error code, for example 401 unauthorized); also an address that does not answer: a typo and an outage look the same, so a script may retry this |
+| 2 | wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https) |
+| 3 | the job is done but a page failed or did not run, or the job stopped early: the result is written anyway, stderr says what is missing and names the job; treat the file as incomplete |
+| 4 | the job did not finish within `--timeout`; it keeps running, stderr names the job |
+
+## Python
+
+```python
+from ocr_software import Client, PagesUnread
+client = Client()                                    # key and address from the environment
+text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes (text.decode("utf-8") for a string); raises PagesUnread (with .data) if a page was not read
+pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
+job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
+client.wait(job["job_id"]); client.result(job["job_id"], "json")
+q = client.quote("scan.pdf", "NAME@VERSION")         # dry run: page count and price, nothing runs
+from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
+```
+
+**Price:** the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001). Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits: [fair usage](https://ocr-software.com/legal/fair-usage/); for more volume write to info@ocr-software.com.
+
+**Word boxes (json):** `box = [x0, y0, x1, y1]` in pixels of the page image, origin top left; `width`, `height` and `dpi` of the page say which image. In PDF points: pixels * 72 / dpi. Per word, `verified` is true only where a second reader confirmed it (`scan-vlm-ctc@2`); `safe_ok` is always false today. Judge by `confidence` (0 to 1). Every field: [reference](https://ocr-software.com/docs/reference/).
+
+**Retries** follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or `Retry-After`). An upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A `Retry-After` over 60 s (`locked_out`) is not waited for. A submit carries an `Idempotency-Key`, so a retry never creates a second job.
+
+Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
+
+## Paperless-ngx
+
+Pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
+
+```sh
+#!/bin/sh
+ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
+```
+
+with `OCR_SOFTWARE_API_KEY` and `OCR_SOFTWARE_BASE_URL` set in the environment of the Paperless container.
+
+## Tests
+
+Fake local service, no network, no key:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install pytest                          # Windows: .venv\Scripts\pip install pytest
+.venv/bin/python -m pytest -p no:cacheprovider .      # Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .
+```

{ocr_software-0.1.0 → ocr_software-0.1.2}/ocr_software/__init__.py

@@ -2,5 +2,5 @@
 from .advice import default_pipeline, price_sentence
 from .client import Client, OcrError, PagesUnread, split_pages, unread_message
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __all__ = ["Client", "OcrError", "PagesUnread", "split_pages", "unread_message", "default_pipeline", "price_sentence", "__version__"]

{ocr_software-0.1.0 → ocr_software-0.1.2}/ocr_software/advice.py

@@ -43,6 +43,12 @@ def price_sentence(q, show_list_price=True):
     return text
 
 
+def warning_lines(q):
+    """One line per warning of a dry run (dpi_ignored, job_budget, free_limit, balance, balance_too_low), for stderr:
+    price_sentence says what it costs, these say why fewer pages run or why an option does nothing."""
+    return ["warning %s: %s" % (w.get("code", "?"), w.get("message", "")) for w in q.get("warnings") or []]
+
+
 def cost(p):
     """Price per page in millicents, comparable between pipelines: the catalog price, else factor * 100 (the catalog hides the
     price while billing is off, the factor stays)."""

{ocr_software-0.1.0 → ocr_software-0.1.2}/ocr_software/cli.py

@@ -11,7 +11,7 @@ import os
 import sys
 
 from . import __version__
-from .advice import default_pipeline, price_sentence, summary
+from .advice import default_pipeline, price_sentence, summary, warning_lines
 from .client import DEFAULT_WAIT_TIMEOUT_S, FORMATS, Client, OcrError, PagesUnread
 
 EXIT_ERROR, EXIT_USAGE, EXIT_UNREAD, EXIT_TIMEOUT = 1, 2, 3, 4
@@ -26,6 +26,7 @@ def _parser():
     p.add_argument("--format", default="text", choices=FORMATS, help="default text")
     p.add_argument("--dpi", type=int, choices=(150, 200, 300), help="render resolution of a PDF (default 150)")
     p.add_argument("--job-budget", type=int, help="cap in millicents (100,000 = 1 EUR; one page of the cheapest pipeline = 100). Where billing is off it is ignored")
+    p.add_argument("-q", "--quiet", action="store_true", help="do not name the default pipeline on stderr (for bulk runs); errors and warnings stay")
     p.add_argument("--dry-run", action="store_true", help="show the page count and the price in euros, run nothing, cost nothing")
     p.add_argument("--timeout", type=int, default=DEFAULT_WAIT_TIMEOUT_S, help="seconds to wait for the job (default %(default)s)")
     p.add_argument("--base-url", help="address of the service (default OCR_SOFTWARE_BASE_URL, else the hosted API)")
@@ -54,7 +55,19 @@ def _same_file(a, b):
         return False
 
 
+def _is_devnull(path):
+    # "-o NUL" on Windows, "-o /dev/null" everywhere (also typed on Windows from Git Bash, where no folder \dev exists)
+    return bool(path) and os.path.normcase(path) in (os.path.normcase(os.devnull), os.path.normcase("/dev/null"))
+
+
+def _print_warnings(answer):
+    for line in warning_lines(answer):  # an older service sends none: nothing to print
+        print("ocr-software: " + line, file=sys.stderr)
+
+
 def _emit(data, output):
+    if _is_devnull(output):
+        return  # discard: a .part file next to the null device cannot exist
     if output:
         _write(output, data)
     else:
@@ -83,21 +96,24 @@ def main(argv=None):
             parser.error("IN is required (--list-pipelines shows the pipelines)")
         if args.format == "pdf" and not args.output:
             parser.error("--format pdf needs -o OUT (a PDF is not written to the terminal)")
-        if args.output and _same_file(args.input, args.output):
+        if args.output and not _is_devnull(args.output) and _same_file(args.input, args.output):
             parser.error("OUT is the input file; it would be overwritten")
-        if args.output and not os.path.isdir(os.path.dirname(os.path.abspath(args.output))):
+        if args.output and not _is_devnull(args.output) and not os.path.isdir(os.path.dirname(os.path.abspath(args.output))):
             parser.error("folder of %s does not exist; nothing was sent" % args.output)  # before the job, not after it
         pipeline = args.pipeline
         if not pipeline:  # the default is named, never silent (ziel.md: fastest and cheapest available; stdout stays the result)
             pipeline = client.default_pipeline()
-            print("ocr-software: no --pipeline given, using %s (the fastest and cheapest available one; --list-pipelines shows the others)" % pipeline,
-                  file=sys.stderr)
+            if not args.quiet:
+                print("ocr-software: no --pipeline given, using %s (the fastest and cheapest available one; --list-pipelines shows the others)" % pipeline,
+                      file=sys.stderr)
         if args.dry_run:
             q = client.quote(args.input, pipeline, args.dpi)
             q.setdefault("pipeline", pipeline)
             print(price_sentence(q))
+            _print_warnings(q)
             return 0
-        data = client.ocr(args.input, pipeline, args.format, timeout=args.timeout, dpi=args.dpi, job_budget=args.job_budget)
+        data = client.ocr(args.input, pipeline, args.format, timeout=args.timeout, dpi=args.dpi, job_budget=args.job_budget,
+                          on_accepted=_print_warnings)  # the service names the warnings in its answer: no extra dry run
         _emit(data, args.output)
         return 0
     except PagesUnread as e:

{ocr_software-0.1.0 → ocr_software-0.1.2}/ocr_software/client.py

@@ -1,6 +1,6 @@
 """Client for the ocr-software.com API (standard library only, Python 3.9 or newer).
 
-Settings: OCR_SOFTWARE_API_KEY (or OCR_KEY, the name used in the API docs), OCR_SOFTWARE_BASE_URL (or OCR_BASE_URL),
+Settings (the OCR_SOFTWARE_ name wins if both are set): OCR_SOFTWARE_API_KEY (or OCR_KEY, the name used in the API docs), OCR_SOFTWARE_BASE_URL (or OCR_BASE_URL),
 OCR_SOFTWARE_ALLOWED_DIR (optional). The key is never printed, never in an error message, never in a log.
 Spec of every path, field and error code: <base>/openapi.json.
 """
@@ -233,7 +233,7 @@ class Client:
         head = dict(headers or {})
         if key_needed:
             if not self._key:
-                raise OcrError("API key missing: set OCR_SOFTWARE_API_KEY (the key starts with ocr_)", "no_key")
+                raise OcrError("API key missing: set OCR_SOFTWARE_API_KEY or OCR_KEY (the key starts with ocr_)", "no_key")
             if not KEY_CHARS.fullmatch(self._key):  # fullmatch: "$" would let a trailing newline pass  # a bad character would make http.client echo the key
                 raise OcrError("API key contains characters that are not allowed in a header", "no_key")
             head["Authorization"] = "Bearer " + self._key
@@ -345,13 +345,17 @@ class Client:
             data, _ = self._call("GET", "/v1/jobs/%s/result" % job_id, query={"format": format})
         return data
 
-    def ocr(self, path, pipeline, format="text", timeout=DEFAULT_WAIT_TIMEOUT_S, **options):
-        """Submit, wait, fetch: the result bytes. options go to submit (dpi, client_ref, job_budget, formats, features).
-        Raises PagesUnread (with .data, the result anyway) if a page failed or was not run: never silent."""
+    def ocr(self, path, pipeline, format="text", timeout=DEFAULT_WAIT_TIMEOUT_S, on_accepted=None, **options):
+        """Submit, wait, fetch: the result as bytes, also for text, md, json and hocr (use .decode("utf-8") for a string). options go to submit (dpi, client_ref, job_budget, formats, features).
+        Raises PagesUnread (with .data, the result anyway) if a page failed or was not run: never silent.
+        on_accepted(answer) is called with the answer to the submit; its "warnings" (absent from an older service) say why fewer pages run."""
         if format not in FORMATS:
             raise OcrError("format must be one of %s" % ", ".join(FORMATS), "bad_input")
         source = read_document(path, self.allowed_dir)  # read once: PDF output needs the same bytes again
-        job_id = self._submit(source, pipeline, **options).get("job_id")
+        accepted = self._submit(source, pipeline, **options)
+        if on_accepted:
+            on_accepted(accepted)
+        job_id = accepted.get("job_id")
         if not job_id:
             raise OcrError("the answer of %s has no job_id: check OCR_SOFTWARE_BASE_URL" % self.base_url, "bad_response")
         done = self.wait(job_id, timeout)

ocr_software-0.1.2/ocr_software.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: ocr-software
+Version: 0.1.2
+Summary: Client and command line for the ocr-software.com OCR API: text, word boxes, layout, searchable PDF.
+License-Expression: MIT
+Project-URL: Homepage, https://ocr-software.com/integrations/python/
+Project-URL: Repository, https://github.com/ocr-software/ocr-software-python
+Keywords: ocr,pdf,searchable-pdf,hocr,markdown,document-ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest==9.0.2; extra == "test"
+Dynamic: license-file
+
+# ocr-software
+
+Python client and command line for the [ocr-software.com](https://ocr-software.com/) OCR API. MIT, standard library only, Python 3.9 or newer.
+
+## Install
+
+```sh
+pipx install ocr-software        # command line only, in its own environment
+pip install ocr-software         # client library, inside a venv
+uvx ocr-software --version       # run once without installing (uv)
+```
+
+First call (list the pipelines, then read one file):
+
+```sh
+ocr-software --list-pipelines
+ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
+```
+
+## Settings
+
+Environment variables; the command line flag wins.
+
+| Variable | Meaning |
+|---|---|
+| `OCR_SOFTWARE_API_KEY` | API key (starts with `ocr_`). `OCR_KEY` is read too, it is the name used in the API docs; if both are set, `OCR_SOFTWARE_API_KEY` wins. |
+| `OCR_SOFTWARE_BASE_URL` | Default `https://api.ocr-software.com`; own server e.g. `http://127.0.0.1:8080` (also `--base-url`). `OCR_BASE_URL` is read too. |
+| `OCR_SOFTWARE_ALLOWED_DIR` | Optional: read documents only from below this folder (symlinks and `..` do not escape). |
+
+The key is never printed and never part of an error message. Without `--pipeline` the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr (`-q` silences that line for bulk runs; `-o NUL` or `-o /dev/null` discards the result); `--list-pipelines` marks it. Warnings of the service (`dpi_ignored`, `job_budget`, `free_limit`, `balance_too_low`) are printed as `warning CODE: text` lines on stderr by `--dry-run` and before a job that uses `--dpi` or `--job-budget` (that job asks once with a dry run first). In Python: `client.ocr(path, client.default_pipeline())`.
+
+## Command line
+
+```sh
+ocr-software --list-pipelines                         # available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
+ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   # page count and price in euros, nothing runs, nothing is billed
+ocr-software scan.pdf                                 # text to stdout, with the default pipeline (named on stderr)
+ocr-software scan.pdf --pipeline NAME@VERSION         # text to stdout
+ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
+ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
+ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf   # searchable PDF, -o is required
+ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
+ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080  # your own server
+python -m ocr_software ...                            # the same command without the script on PATH
+```
+
+Options:
+- `--format text` (default) `| md | json | hocr | pdf`
+- `--dpi 150|200|300` (PDF render resolution)
+- `--timeout SECONDS` (wait for the job, default 3600)
+- `--job-budget MILLICENTS` (cap; ignored where billing is off)
+- `-q`, `--dry-run`, `--version`
+
+Without `-o` the result goes to stdout as UTF-8 (not for pdf). With `-o` the file appears whole or not at all, an existing file is replaced, and the input file itself is refused as output.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done, every page read |
+| 1 | error from the service or the network (message on stderr with the API error code, for example 401 unauthorized); also an address that does not answer: a typo and an outage look the same, so a script may retry this |
+| 2 | wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https) |
+| 3 | the job is done but a page failed or did not run, or the job stopped early: the result is written anyway, stderr says what is missing and names the job; treat the file as incomplete |
+| 4 | the job did not finish within `--timeout`; it keeps running, stderr names the job |
+
+## Python
+
+```python
+from ocr_software import Client, PagesUnread
+client = Client()                                    # key and address from the environment
+text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes (text.decode("utf-8") for a string); raises PagesUnread (with .data) if a page was not read
+pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
+job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
+client.wait(job["job_id"]); client.result(job["job_id"], "json")
+q = client.quote("scan.pdf", "NAME@VERSION")         # dry run: page count and price, nothing runs
+from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
+```
+
+**Price:** the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001). Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits: [fair usage](https://ocr-software.com/legal/fair-usage/); for more volume write to info@ocr-software.com.
+
+**Word boxes (json):** `box = [x0, y0, x1, y1]` in pixels of the page image, origin top left; `width`, `height` and `dpi` of the page say which image. In PDF points: pixels * 72 / dpi. Per word, `verified` is true only where a second reader confirmed it (`scan-vlm-ctc@2`); `safe_ok` is always false today. Judge by `confidence` (0 to 1). Every field: [reference](https://ocr-software.com/docs/reference/).
+
+**Retries** follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or `Retry-After`). An upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A `Retry-After` over 60 s (`locked_out`) is not waited for. A submit carries an `Idempotency-Key`, so a retry never creates a second job.
+
+Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
+
+## Paperless-ngx
+
+Pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
+
+```sh
+#!/bin/sh
+ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
+```
+
+with `OCR_SOFTWARE_API_KEY` and `OCR_SOFTWARE_BASE_URL` set in the environment of the Paperless container.
+
+## Tests
+
+Fake local service, no network, no key:
+
+```sh
+python -m venv .venv
+.venv/bin/pip install pytest                          # Windows: .venv\Scripts\pip install pytest
+.venv/bin/python -m pytest -p no:cacheprovider .      # Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .
+```

{ocr_software-0.1.0 → ocr_software-0.1.2}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ocr-software"
-version = "0.1.0"
+version = "0.1.2"
 description = "Client and command line for the ocr-software.com OCR API: text, word boxes, layout, searchable PDF."
-readme = {file = "INSTALL.txt", content-type = "text/plain"}
+readme = {file = "INSTALL.txt", content-type = "text/markdown"}
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.9"
@@ -21,7 +21,7 @@ classifiers = [
 test = ["pytest==9.0.2"]
 
 [project.urls]
-Homepage = "https://ocr-software.com/"
+Homepage = "https://ocr-software.com/integrations/python/"
 Repository = "https://github.com/ocr-software/ocr-software-python"
 
 [project.scripts]

{ocr_software-0.1.0 → ocr_software-0.1.2}/tests/test_cli.py

@@ -221,3 +221,59 @@ def test_ctrl_c_ends_without_a_stack_trace(fake, doc, monkeypatch, capsysbinary)
     monkeypatch.setattr(cli.Client, "ocr", interrupted)
     code, out, errtext = run([doc, "--pipeline", "p@1"], capsysbinary)
     assert code == 130 and out == b"" and "interrupted" in errtext and "Traceback" not in errtext
+
+
+def test_quiet_drops_the_default_pipeline_line_only(fake, doc, capsysbinary):
+    fake.scripted[("GET", "/v1/catalog")] = [(200, {}, {"pipelines": [{"pipeline": "p@1", "available": True, "price_per_page_millicents": 100}]})]
+    job_flow(fake, result=b"x")
+    code, _, errtext = run([doc, "-q"], capsysbinary)
+    assert code == 0 and errtext == ""
+    job_flow(fake, result=b"x")
+    code, _, errtext = run([doc], capsysbinary)
+    assert code == 0 and "no --pipeline given, using p@1" in errtext
+
+
+def test_output_to_the_null_device_is_accepted_and_discards(fake, doc, capsysbinary):
+    job_flow(fake, result=b"gone")
+    code, out, errtext = run([doc, "--pipeline", "p@1", "-o", os.devnull], capsysbinary)
+    assert (code, out, errtext) == (0, b"", "")
+
+
+@pytest.mark.parametrize("target", [os.devnull, "/dev/null"])
+def test_both_null_device_spellings_discard_on_every_system(fake, doc, capsysbinary, target):
+    job_flow(fake, result=b"gone")
+    code, out, errtext = run([doc, "--pipeline", "p@1", "-o", target], capsysbinary)
+    assert (code, out, errtext) == (0, b"", "")
+
+
+DPI_WARNING = {"code": "dpi_ignored", "message": "dpi applies to the pages of a PDF."}
+DRY_WITH_WARNING = {"dry_run": True, "pages": 1, "price_per_page_millicents": 100, "price_millicents": 100, "max_charge_millicents": 0,
+                    "pages_covered": 1, "warnings": [DPI_WARNING]}
+
+
+def test_dry_run_shows_every_warning_as_its_own_stderr_line(fake, doc, capsysbinary):
+    fake.scripted[("POST", "/v1/jobs")] = [(200, {}, dict(DRY_WITH_WARNING, warnings=[DPI_WARNING, {"code": "job_budget", "message": "covers 1 of 2"}]))]
+    code, out, errtext = run([doc, "--pipeline", "a@1", "--dry-run", "--dpi", "300"], capsysbinary)
+    assert code == 0 and b"1 page with a@1" in out
+    assert errtext.splitlines() == ["ocr-software: warning dpi_ignored: dpi applies to the pages of a PDF.",
+                                    "ocr-software: warning job_budget: covers 1 of 2"]
+
+
+def test_a_real_job_shows_the_warnings_of_the_answer_in_one_upload(fake, doc, capsysbinary):
+    job_flow(fake, result=b"text")
+    fake.scripted[("POST", "/v1/jobs")] = [(202, {}, {"job_id": "j1", "state": "running", "warnings": [DPI_WARNING]})]
+    code, out, errtext = run([doc, "--pipeline", "a@1", "--dpi", "300", "--job-budget", "1"], capsysbinary)
+    assert code == 0 and out == b"text" and errtext == "ocr-software: warning dpi_ignored: dpi applies to the pages of a PDF.\n"
+    posts = [c for c in fake.log if c["method"] == "POST" and "/result" not in c["path"]]
+    assert len(posts) == 1 and "dry_run" not in posts[0]["query"]
+
+
+def test_an_older_service_without_warnings_breaks_nothing(fake, doc, capsysbinary):
+    job_flow(fake, result=b"text")
+    assert run([doc, "--pipeline", "a@1", "--dpi", "300"], capsysbinary) == (0, b"text", "")
+
+
+def test_a_plain_real_job_stays_one_upload(fake, doc, capsysbinary):
+    job_flow(fake)
+    run([doc, "--pipeline", "a@1"], capsysbinary)
+    assert sum(1 for c in fake.log if c["method"] == "POST" and "/result" not in c["path"]) == 1

{ocr_software-0.1.0 → ocr_software-0.1.2}/tests/test_client.py

@@ -510,3 +510,13 @@ def test_split_pages_text_and_markdown():
     md = "## Page 1\n\nfirst\n\n## Page 2\n\n## Page 7\n\nnot a page\n\n## Page 3\n\nlast\n"
     assert split_pages(md, "md") == [(1, "first\n"), (2, "## Page 7\n\nnot a page\n"), (3, "last\n")]
     assert split_pages("no headings", "md") == [(1, "no headings")]
+
+
+def test_both_names_set_the_ocr_software_name_wins_for_key_url_and_folder(monkeypatch):
+    for short, long_, bad, good in (("OCR_KEY", "OCR_SOFTWARE_API_KEY", "ocr_bogus", "ocr_good"),
+                                    ("OCR_BASE_URL", "OCR_SOFTWARE_BASE_URL", "http://bad:1", "http://good:1"),
+                                    ("OCR_ALLOWED_DIR", "OCR_SOFTWARE_ALLOWED_DIR", "/bad", "/good")):
+        monkeypatch.setenv(short, bad)
+        monkeypatch.setenv(long_, good)
+    c = Client()
+    assert (c._key, c.base_url, c.allowed_dir) == ("ocr_good", "http://good:1", "/good")

{ocr_software-0.1.0 → ocr_software-0.1.2}/tests/test_release_files.py

@@ -16,6 +16,8 @@ def test_readme_file_exists_and_no_runtime_dependencies():
     pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
     assert (ROOT / "INSTALL.txt").is_file() and 'file = "INSTALL.txt"' in pyproject
     assert "dependencies = []" in pyproject  # standard library only
+    # 13.11.2026: as text/plain PyPI showed one fixed-width block whose long lines ran off the page
+    assert 'content-type = "text/markdown"' in pyproject
 
 
 def test_readme_that_pypi_shows_has_no_draft_note():

ocr_software-0.1.0/INSTALL.txt

@@ -1,71 +0,0 @@
-ocr-software: Python client and command line for the ocr-software.com OCR API (MIT, standard library only, Python 3.9 or newer).
-
-Install:
-  pipx install ocr-software        command line only, in its own environment
-  pip install ocr-software         client library, inside a venv
-  uvx ocr-software --version       run once without installing (uv)
-First call (list the pipelines, then read one file):
-  ocr-software --list-pipelines
-  ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
-
-Settings (environment; the command line flag wins):
-  OCR_SOFTWARE_API_KEY        API key (starts with ocr_). OCR_KEY is read too, it is the name used in the API docs.
-  OCR_SOFTWARE_BASE_URL       default https://api.ocr-software.com ; own server e.g. http://127.0.0.1:8080 (also --base-url). OCR_BASE_URL is read too.
-  OCR_SOFTWARE_ALLOWED_DIR    optional: read documents only from below this folder (symlinks and .. do not escape)
-The key is never printed and never part of an error message. Without --pipeline the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr; --list-pipelines marks it. In Python: client.ocr(path, client.default_pipeline()).
-
-Command line:
-  ocr-software --list-pipelines                       available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
-  ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   page count and price in euros, nothing runs, nothing is billed
-  ocr-software scan.pdf                                text to stdout, with the default pipeline (named on stderr)
-  ocr-software scan.pdf --pipeline NAME@VERSION       text to stdout
-  ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
-  ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
-  ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf      searchable PDF, -o is required
-  ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
-  ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080     your own server
-  python -m ocr_software ...                          the same command without the script on PATH
-Options: --format text (default) | md | json | hocr | pdf ; --dpi 150|200|300 (PDF render resolution) ;
-  --timeout SECONDS (wait for the job, default 3600) ; --job-budget MILLICENTS (cap; ignored where billing is off) ; --dry-run ; --version
-Without -o the result goes to stdout as UTF-8 (not for pdf). With -o the file appears whole or not at all, an existing
-file is replaced, and the input file itself is refused as output.
-
-Exit codes:
-  0  done, every page read
-  1  error from the service or the network (message on stderr with the API error code, for example 401 unauthorized);
-     also an address that does not answer: a typo and an outage look the same, so a script may retry this
-  2  wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https)
-  3  the job is done but a page failed or did not run, or the job stopped early: the result is written anyway,
-     stderr says what is missing and names the job; treat the file as incomplete
-  4  the job did not finish within --timeout; it keeps running, stderr names the job
-
-Python:
-  from ocr_software import Client, PagesUnread
-  client = Client()                                    # key and address from the environment
-  text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes; raises PagesUnread (with .data) if a page was not read
-  pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
-  job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
-  client.wait(job["job_id"]); client.result(job["job_id"], "json")
-  client.quote("scan.pdf", "NAME@VERSION")             # dry run: page count and price, nothing runs
-  from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
-Price: the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001).
-Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits:
-https://ocr-software.com/legal/fair-usage/ ; for more volume write to info@ocr-software.com.
-Word boxes (json): box = [x0, y0, x1, y1] in pixels of the page image, origin top left; width, height and dpi of the page say which
-image. In PDF points: pixels * 72 / dpi. Per word, verified is true only where a second reader confirmed it (scan-vlm-ctc@2);
-safe_ok is always false today. Judge by confidence (0 to 1). Every field: https://ocr-software.com/docs/reference/
-Retries follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or Retry-After). An
-upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection
-can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on
-Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A Retry-After over 60 s (locked_out) is not waited for. A submit carries an Idempotency-Key, so a retry never creates a second job.
-Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
-
-Paperless-ngx, pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
-  #!/bin/sh
-  ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
-  with OCR_SOFTWARE_API_KEY and OCR_SOFTWARE_BASE_URL set in the environment of the Paperless container.
-
-Tests (fake local service, no network, no key):
-  python -m venv .venv
-  .venv/bin/pip install pytest             (Windows: .venv\Scripts\pip install pytest)
-  .venv/bin/python -m pytest -p no:cacheprovider .      (Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .)

ocr_software-0.1.0/PKG-INFO

@@ -1,88 +0,0 @@
-Metadata-Version: 2.4
-Name: ocr-software
-Version: 0.1.0
-Summary: Client and command line for the ocr-software.com OCR API: text, word boxes, layout, searchable PDF.
-License-Expression: MIT
-Project-URL: Homepage, https://ocr-software.com/
-Project-URL: Repository, https://github.com/ocr-software/ocr-software-python
-Keywords: ocr,pdf,searchable-pdf,hocr,markdown,document-ai
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Image Recognition
-Requires-Python: >=3.9
-Description-Content-Type: text/plain
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest==9.0.2; extra == "test"
-Dynamic: license-file
-
-ocr-software: Python client and command line for the ocr-software.com OCR API (MIT, standard library only, Python 3.9 or newer).
-
-Install:
-  pipx install ocr-software        command line only, in its own environment
-  pip install ocr-software         client library, inside a venv
-  uvx ocr-software --version       run once without installing (uv)
-First call (list the pipelines, then read one file):
-  ocr-software --list-pipelines
-  ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
-
-Settings (environment; the command line flag wins):
-  OCR_SOFTWARE_API_KEY        API key (starts with ocr_). OCR_KEY is read too, it is the name used in the API docs.
-  OCR_SOFTWARE_BASE_URL       default https://api.ocr-software.com ; own server e.g. http://127.0.0.1:8080 (also --base-url). OCR_BASE_URL is read too.
-  OCR_SOFTWARE_ALLOWED_DIR    optional: read documents only from below this folder (symlinks and .. do not escape)
-The key is never printed and never part of an error message. Without --pipeline the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr; --list-pipelines marks it. In Python: client.ocr(path, client.default_pipeline()).
-
-Command line:
-  ocr-software --list-pipelines                       available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
-  ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   page count and price in euros, nothing runs, nothing is billed
-  ocr-software scan.pdf                                text to stdout, with the default pipeline (named on stderr)
-  ocr-software scan.pdf --pipeline NAME@VERSION       text to stdout
-  ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
-  ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
-  ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf      searchable PDF, -o is required
-  ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
-  ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080     your own server
-  python -m ocr_software ...                          the same command without the script on PATH
-Options: --format text (default) | md | json | hocr | pdf ; --dpi 150|200|300 (PDF render resolution) ;
-  --timeout SECONDS (wait for the job, default 3600) ; --job-budget MILLICENTS (cap; ignored where billing is off) ; --dry-run ; --version
-Without -o the result goes to stdout as UTF-8 (not for pdf). With -o the file appears whole or not at all, an existing
-file is replaced, and the input file itself is refused as output.
-
-Exit codes:
-  0  done, every page read
-  1  error from the service or the network (message on stderr with the API error code, for example 401 unauthorized);
-     also an address that does not answer: a typo and an outage look the same, so a script may retry this
-  2  wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https)
-  3  the job is done but a page failed or did not run, or the job stopped early: the result is written anyway,
-     stderr says what is missing and names the job; treat the file as incomplete
-  4  the job did not finish within --timeout; it keeps running, stderr names the job
-
-Python:
-  from ocr_software import Client, PagesUnread
-  client = Client()                                    # key and address from the environment
-  text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes; raises PagesUnread (with .data) if a page was not read
-  pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
-  job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
-  client.wait(job["job_id"]); client.result(job["job_id"], "json")
-  client.quote("scan.pdf", "NAME@VERSION")             # dry run: page count and price, nothing runs
-  from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
-Price: the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001).
-Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits:
-https://ocr-software.com/legal/fair-usage/ ; for more volume write to info@ocr-software.com.
-Word boxes (json): box = [x0, y0, x1, y1] in pixels of the page image, origin top left; width, height and dpi of the page say which
-image. In PDF points: pixels * 72 / dpi. Per word, verified is true only where a second reader confirmed it (scan-vlm-ctc@2);
-safe_ok is always false today. Judge by confidence (0 to 1). Every field: https://ocr-software.com/docs/reference/
-Retries follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or Retry-After). An
-upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection
-can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on
-Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A Retry-After over 60 s (locked_out) is not waited for. A submit carries an Idempotency-Key, so a retry never creates a second job.
-Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
-
-Paperless-ngx, pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
-  #!/bin/sh
-  ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
-  with OCR_SOFTWARE_API_KEY and OCR_SOFTWARE_BASE_URL set in the environment of the Paperless container.
-
-Tests (fake local service, no network, no key):
-  python -m venv .venv
-  .venv/bin/pip install pytest             (Windows: .venv\Scripts\pip install pytest)
-  .venv/bin/python -m pytest -p no:cacheprovider .      (Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .)

ocr_software-0.1.0/README.md

@@ -1,71 +0,0 @@
-ocr-software: Python client and command line for the ocr-software.com OCR API (MIT, standard library only, Python 3.9 or newer).
-
-Install:
-  pipx install ocr-software        command line only, in its own environment
-  pip install ocr-software         client library, inside a venv
-  uvx ocr-software --version       run once without installing (uv)
-First call (list the pipelines, then read one file):
-  ocr-software --list-pipelines
-  ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
-
-Settings (environment; the command line flag wins):
-  OCR_SOFTWARE_API_KEY        API key (starts with ocr_). OCR_KEY is read too, it is the name used in the API docs.
-  OCR_SOFTWARE_BASE_URL       default https://api.ocr-software.com ; own server e.g. http://127.0.0.1:8080 (also --base-url). OCR_BASE_URL is read too.
-  OCR_SOFTWARE_ALLOWED_DIR    optional: read documents only from below this folder (symlinks and .. do not escape)
-The key is never printed and never part of an error message. Without --pipeline the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr; --list-pipelines marks it. In Python: client.ocr(path, client.default_pipeline()).
-
-Command line:
-  ocr-software --list-pipelines                       available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
-  ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   page count and price in euros, nothing runs, nothing is billed
-  ocr-software scan.pdf                                text to stdout, with the default pipeline (named on stderr)
-  ocr-software scan.pdf --pipeline NAME@VERSION       text to stdout
-  ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
-  ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
-  ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf      searchable PDF, -o is required
-  ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
-  ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080     your own server
-  python -m ocr_software ...                          the same command without the script on PATH
-Options: --format text (default) | md | json | hocr | pdf ; --dpi 150|200|300 (PDF render resolution) ;
-  --timeout SECONDS (wait for the job, default 3600) ; --job-budget MILLICENTS (cap; ignored where billing is off) ; --dry-run ; --version
-Without -o the result goes to stdout as UTF-8 (not for pdf). With -o the file appears whole or not at all, an existing
-file is replaced, and the input file itself is refused as output.
-
-Exit codes:
-  0  done, every page read
-  1  error from the service or the network (message on stderr with the API error code, for example 401 unauthorized);
-     also an address that does not answer: a typo and an outage look the same, so a script may retry this
-  2  wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https)
-  3  the job is done but a page failed or did not run, or the job stopped early: the result is written anyway,
-     stderr says what is missing and names the job; treat the file as incomplete
-  4  the job did not finish within --timeout; it keeps running, stderr names the job
-
-Python:
-  from ocr_software import Client, PagesUnread
-  client = Client()                                    # key and address from the environment
-  text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes; raises PagesUnread (with .data) if a page was not read
-  pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
-  job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
-  client.wait(job["job_id"]); client.result(job["job_id"], "json")
-  client.quote("scan.pdf", "NAME@VERSION")             # dry run: page count and price, nothing runs
-  from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
-Price: the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001).
-Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits:
-https://ocr-software.com/legal/fair-usage/ ; for more volume write to info@ocr-software.com.
-Word boxes (json): box = [x0, y0, x1, y1] in pixels of the page image, origin top left; width, height and dpi of the page say which
-image. In PDF points: pixels * 72 / dpi. Per word, verified is true only where a second reader confirmed it (scan-vlm-ctc@2);
-safe_ok is always false today. Judge by confidence (0 to 1). Every field: https://ocr-software.com/docs/reference/
-Retries follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or Retry-After). An
-upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection
-can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on
-Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A Retry-After over 60 s (locked_out) is not waited for. A submit carries an Idempotency-Key, so a retry never creates a second job.
-Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
-
-Paperless-ngx, pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
-  #!/bin/sh
-  ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
-  with OCR_SOFTWARE_API_KEY and OCR_SOFTWARE_BASE_URL set in the environment of the Paperless container.
-
-Tests (fake local service, no network, no key):
-  python -m venv .venv
-  .venv/bin/pip install pytest             (Windows: .venv\Scripts\pip install pytest)
-  .venv/bin/python -m pytest -p no:cacheprovider .      (Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .)

ocr_software-0.1.0/ocr_software.egg-info/PKG-INFO

@@ -1,88 +0,0 @@
-Metadata-Version: 2.4
-Name: ocr-software
-Version: 0.1.0
-Summary: Client and command line for the ocr-software.com OCR API: text, word boxes, layout, searchable PDF.
-License-Expression: MIT
-Project-URL: Homepage, https://ocr-software.com/
-Project-URL: Repository, https://github.com/ocr-software/ocr-software-python
-Keywords: ocr,pdf,searchable-pdf,hocr,markdown,document-ai
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Scientific/Engineering :: Image Recognition
-Requires-Python: >=3.9
-Description-Content-Type: text/plain
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest==9.0.2; extra == "test"
-Dynamic: license-file
-
-ocr-software: Python client and command line for the ocr-software.com OCR API (MIT, standard library only, Python 3.9 or newer).
-
-Install:
-  pipx install ocr-software        command line only, in its own environment
-  pip install ocr-software         client library, inside a venv
-  uvx ocr-software --version       run once without installing (uv)
-First call (list the pipelines, then read one file):
-  ocr-software --list-pipelines
-  ocr-software scan.pdf --pipeline scan-ctc@2 -o scan.txt
-
-Settings (environment; the command line flag wins):
-  OCR_SOFTWARE_API_KEY        API key (starts with ocr_). OCR_KEY is read too, it is the name used in the API docs.
-  OCR_SOFTWARE_BASE_URL       default https://api.ocr-software.com ; own server e.g. http://127.0.0.1:8080 (also --base-url). OCR_BASE_URL is read too.
-  OCR_SOFTWARE_ALLOWED_DIR    optional: read documents only from below this folder (symlinks and .. do not escape)
-The key is never printed and never part of an error message. Without --pipeline the default is used: the fastest and cheapest available pipeline (no previews). It is named on stderr; --list-pipelines marks it. In Python: client.ocr(path, client.default_pipeline()).
-
-Command line:
-  ocr-software --list-pipelines                       available pipelines, one per line: name@version, tab, what it delivers and costs; the default one on stderr (no key needed)
-  ocr-software scan.pdf --pipeline NAME@VERSION --dry-run   page count and price in euros, nothing runs, nothing is billed
-  ocr-software scan.pdf                                text to stdout, with the default pipeline (named on stderr)
-  ocr-software scan.pdf --pipeline NAME@VERSION       text to stdout
-  ocr-software scan.pdf -o scan.md --pipeline NAME@VERSION --format md
-  ocr-software scan.pdf -o scan.pdf.txt --pipeline NAME@VERSION
-  ocr-software scan.pdf -o searchable.pdf --pipeline NAME@VERSION --format pdf      searchable PDF, -o is required
-  ocr-software scan.pdf --pipeline NAME@VERSION --format json > scan.json
-  ocr-software scan.pdf --pipeline NAME@VERSION --base-url http://10.0.0.5:8080     your own server
-  python -m ocr_software ...                          the same command without the script on PATH
-Options: --format text (default) | md | json | hocr | pdf ; --dpi 150|200|300 (PDF render resolution) ;
-  --timeout SECONDS (wait for the job, default 3600) ; --job-budget MILLICENTS (cap; ignored where billing is off) ; --dry-run ; --version
-Without -o the result goes to stdout as UTF-8 (not for pdf). With -o the file appears whole or not at all, an existing
-file is replaced, and the input file itself is refused as output.
-
-Exit codes:
-  0  done, every page read
-  1  error from the service or the network (message on stderr with the API error code, for example 401 unauthorized);
-     also an address that does not answer: a typo and an outage look the same, so a script may retry this
-  2  wrong call: unreadable or unsupported input, output not writable, no key, malformed address (not http/https)
-  3  the job is done but a page failed or did not run, or the job stopped early: the result is written anyway,
-     stderr says what is missing and names the job; treat the file as incomplete
-  4  the job did not finish within --timeout; it keeps running, stderr names the job
-
-Python:
-  from ocr_software import Client, PagesUnread
-  client = Client()                                    # key and address from the environment
-  text = client.ocr("scan.pdf", "NAME@VERSION", "md")  # bytes; raises PagesUnread (with .data) if a page was not read
-  pdf = client.ocr("scan.pdf", "NAME@VERSION", "pdf")  # searchable PDF
-  job = client.submit("scan.pdf", "NAME@VERSION")      # step by step: submit, wait, result
-  client.wait(job["job_id"]); client.result(job["job_id"], "json")
-  client.quote("scan.pdf", "NAME@VERSION")             # dry run: page count and price, nothing runs
-  from ocr_software import price_sentence; price_sentence(q)   # the same sentence as --dry-run, in euros
-Price: the API counts money in millicents, 100,000 millicents = 1 EUR (a page of the cheapest pipeline costs 100 = EUR 0.001).
-Today nothing is charged ("you pay EUR 0.00 today"); the list price is shown for information. Free use has limits:
-https://ocr-software.com/legal/fair-usage/ ; for more volume write to info@ocr-software.com.
-Word boxes (json): box = [x0, y0, x1, y1] in pixels of the page image, origin top left; width, height and dpi of the page say which
-image. In PDF points: pixels * 72 / dpi. Per word, verified is true only where a second reader confirmed it (scan-vlm-ctc@2);
-safe_ok is always false today. Judge by confidence (0 to 1). Every field: https://ocr-software.com/docs/reference/
-Retries follow the API rules: 429, 500, 502, 503, 504 and network errors up to 5 times (waits 1, 2, 4, 8, 16 s or Retry-After). An
-upload the service cuts off (it does that beyond 2 uploads at once per key, instead of answering 429) counts like 429. If no connection
-can be made at all (wrong address, host down) it gives up after 2 retries and names the address: a few seconds, up to about 10 s on
-Windows, where a refused port itself takes 2 s per try (connect timeout 10 s). A Retry-After over 60 s (locked_out) is not waited for. A submit carries an Idempotency-Key, so a retry never creates a second job.
-Every document is checked locally first: PDF, PNG, JPEG or TIFF by its first bytes, at most 100 MiB.
-
-Paperless-ngx, pre-consume script (sketch, not tried against a real Paperless; a non-PDF input keeps its file name but becomes a PDF):
-  #!/bin/sh
-  ocr-software "$DOCUMENT_WORKING_PATH" --pipeline NAME@VERSION --format pdf -o "$DOCUMENT_WORKING_PATH.ocr" && mv "$DOCUMENT_WORKING_PATH.ocr" "$DOCUMENT_WORKING_PATH"
-  with OCR_SOFTWARE_API_KEY and OCR_SOFTWARE_BASE_URL set in the environment of the Paperless container.
-
-Tests (fake local service, no network, no key):
-  python -m venv .venv
-  .venv/bin/pip install pytest             (Windows: .venv\Scripts\pip install pytest)
-  .venv/bin/python -m pytest -p no:cacheprovider .      (Windows: .venv\Scripts\python -m pytest -p no:cacheprovider .)