ocr-software 0.1.0__tar.gz

ocr_software-0.1.0/INSTALL.txt

@@ -0,0 +1,71 @@
+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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ocr-software.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocr_software-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+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

@@ -0,0 +1,71 @@
+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/__init__.py

@@ -0,0 +1,6 @@
+"""ocr-software.com: client and command line for the OCR API."""
+from .advice import default_pipeline, price_sentence
+from .client import Client, OcrError, PagesUnread, split_pages, unread_message
+
+__version__ = "0.1.0"
+__all__ = ["Client", "OcrError", "PagesUnread", "split_pages", "unread_message", "default_pipeline", "price_sentence", "__version__"]

ocr_software-0.1.0/ocr_software/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ocr_software-0.1.0/ocr_software/advice.py

@@ -0,0 +1,86 @@
+"""Words for a human: price in euros, the default pipeline, a short pipeline line.
+
+One copy for the command line and the MCP server, so both say the same. Nothing here calls the network.
+Unit: 100,000 millicents = 1 EUR; factor 1 = 100 millicents = EUR 0.001 per page.
+"""
+from __future__ import annotations
+
+# The price rate lives here and nowhere else: showing pages of the base pipeline instead of euros changes eur() and price_sentence().
+MILLICENTS_PER_EUR = 100000
+MILLICENTS_PER_FACTOR = 100  # factor 1 = the base price per page
+FAIR_USE = "Free use has limits (https://ocr-software.com/legal/fair-usage/); for more volume write to info@ocr-software.com."
+SWITCH_HINTS = {
+    "hard_pages": "for hard pages (poor scans, doubtful words) use %s",
+    "turned_pages": "for turned pages use %s",
+    "no_tables": "without tables %s is cheaper",
+    "clean_bulk": "for clean bulk text %s is cheaper",
+}
+
+
+def eur(millicents):
+    """1 EUR = 100000 millicents; at least two decimals, as many as needed up to four."""
+    text = ("%.4f" % (millicents / MILLICENTS_PER_EUR)).rstrip("0")
+    return "EUR " + text + "0" * (2 - len(text.partition(".")[2]))
+
+
+def price_sentence(q, show_list_price=True):
+    """What the human reads before saying yes, from a dry run. Nothing is charged today (billing off or free pages): the price
+    is still shown, as information, with the fair-use link and the contact."""
+    pages, name = q["pages"], q["pipeline"]
+    price, charge, per_page = q.get("price_millicents") or 0, q.get("max_charge_millicents") or 0, q.get("price_per_page_millicents") or 0
+    start = "%d page%s with %s" % (pages, "" if pages == 1 else "s", name)
+    if not price:
+        text = "%s: nothing is charged (this service has no prices set)." % start
+    elif not charge:
+        text = "%s: you pay %s today." % (start, eur(0))
+        if show_list_price:
+            text += " List price %s in total (%s per page), shown for information only. %s" % (eur(price), eur(per_page), FAIR_USE)
+    else:
+        text = "%s: up to %s is charged (%s per page)." % (start, eur(charge), eur(per_page))
+    covered = q.get("pages_covered", pages)
+    if covered < pages:
+        text += " Only %d of %d pages would run." % (covered, pages)
+    return text
+
+
+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)."""
+    price = p.get("price_per_page_millicents")
+    if isinstance(price, (int, float)) and price > 0:
+        return price
+    factor = p.get("factor")
+    return factor * MILLICENTS_PER_FACTOR if isinstance(factor, (int, float)) else None
+
+
+def preview(p):
+    """A preview (preview: true, or version @0) has no long-term promise: never a default."""
+    return bool(p.get("preview")) or str(p.get("pipeline", "")).endswith("@0")
+
+
+def usable(p):
+    return p.get("available", True) and p.get("orderable", True) is not False and not preview(p)
+
+
+def default_pipeline(pipelines):
+    """name@version of the pipeline used when the caller names none: the fastest and cheapest usable one (rule in ziel.md).
+    Not ready and preview pipelines are out. Order: price, then not autoregressive (faster), then the name, so a tie never
+    depends on the order of the catalog. None if nothing is usable. The caller must say which one was chosen."""
+    best = min(((cost(p), bool(p.get("autoregressive")), p.get("pipeline", "")) for p in pipelines if usable(p) and cost(p) is not None),
+               default=None)
+    return best[2] if best else None
+
+
+def summary(p, default=None):
+    """One short line for a pipeline (without its name): what it delivers, what it costs, when to choose another one."""
+    feats = p.get("features") or []
+    parts = ["%s boxes" % p["level"] if p.get("level") else "", "tables" if "table_cells" in feats else "",
+             "layout" if "layout_classes" in feats else "", "slower" if p.get("autoregressive") else ""]
+    line = ", ".join(x for x in parts if x) or p.get("description", "")[:80]
+    price = cost(p)
+    if price is not None:
+        line += "; price %s per page" % eur(price)
+    if default and p.get("pipeline") == default:
+        line += "; the default (fastest and cheapest)"
+    hints = [SWITCH_HINTS[s["when"]] % s["pipeline"] for s in p.get("switch") or [] if s.get("when") in SWITCH_HINTS and s.get("pipeline")]
+    return line + ("; " + "; ".join(hints) if hints else "")

ocr_software-0.1.0/ocr_software/cli.py

@@ -0,0 +1,122 @@
+"""Command line: ocr-software IN [-o OUT] --pipeline NAME@VERSION [--format md|text|json|hocr|pdf].
+
+Exit codes: 0 done, every page read | 1 service or network error | 2 wrong call, unreadable input or output, no key
+| 3 job done but a page failed or did not run (the result is still written, the message says what is missing)
+| 4 the job did not finish within --timeout (it keeps running; the message names the job).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .advice import default_pipeline, price_sentence, summary
+from .client import DEFAULT_WAIT_TIMEOUT_S, FORMATS, Client, OcrError, PagesUnread
+
+EXIT_ERROR, EXIT_USAGE, EXIT_UNREAD, EXIT_TIMEOUT = 1, 2, 3, 4
+USAGE_CODES = ("bad_input", "no_key")
+
+
+def _parser():
+    p = argparse.ArgumentParser(prog="ocr-software", description="Read a PDF, PNG, JPEG or TIFF with the ocr-software.com API.")
+    p.add_argument("input", nargs="?", help="the document")
+    p.add_argument("-o", "--output", help="output file; without it the result goes to stdout (not for pdf)")
+    p.add_argument("--pipeline", help="name@version (default: the fastest and cheapest available one, named on stderr); --list-pipelines shows the choices")
+    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("--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)")
+    p.add_argument("--list-pipelines", action="store_true", help="print the available pipelines (name, tab, what it delivers and costs) and the default one, then exit")
+    p.add_argument("--version", action="version", version="ocr-software " + __version__)
+    return p
+
+
+def _write(path, data):
+    """Atomic: a half written output file never exists (a pre-consume hook may pick it up at once)."""
+    tmp = "%s.%d.part" % (path, os.getpid())
+    try:
+        with open(tmp, "xb") as f:  # normal file mode, unlike mkstemp
+            f.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def _same_file(a, b):
+    try:
+        return os.path.exists(b) and os.path.samefile(a, b)
+    except OSError:  # input missing: the client reports it with the right code
+        return False
+
+
+def _emit(data, output):
+    if output:
+        _write(output, data)
+    else:
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+
+
+def main(argv=None):
+    for stream in (sys.stderr, sys.stdout):  # a Windows console must not fail on a file name
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        client = Client(base_url=args.base_url)
+        if args.list_pipelines:
+            pipelines = client.catalog().get("pipelines", [])
+            default = default_pipeline(pipelines)
+            for p in pipelines:
+                if p.get("available"):
+                    print("%s	%s" % (p.get("pipeline"), summary(p, default)))
+            if default:
+                print("ocr-software: without --pipeline the default is %s (the fastest and cheapest available one)" % default, file=sys.stderr)
+            return 0
+        if not args.input:
+            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):
+            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))):
+            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 args.dry_run:
+            q = client.quote(args.input, pipeline, args.dpi)
+            q.setdefault("pipeline", pipeline)
+            print(price_sentence(q))
+            return 0
+        data = client.ocr(args.input, pipeline, args.format, timeout=args.timeout, dpi=args.dpi, job_budget=args.job_budget)
+        _emit(data, args.output)
+        return 0
+    except PagesUnread as e:
+        try:
+            _emit(e.data, args.output)
+        except OSError as w:
+            print("ocr-software: cannot write output: %s" % w, file=sys.stderr)
+        print("ocr-software: %s; the result is incomplete" % e, file=sys.stderr)
+        return EXIT_UNREAD
+    except OcrError as e:
+        print("ocr-software: %s" % e, file=sys.stderr)
+        return EXIT_USAGE if e.code in USAGE_CODES else EXIT_TIMEOUT if e.code == "timeout" else EXIT_ERROR
+    except OSError as e:
+        print("ocr-software: cannot write output: %s" % e, file=sys.stderr)
+        return EXIT_USAGE
+    except KeyboardInterrupt:  # Ctrl+C: no traceback; a job already submitted keeps running and is not billed twice on retry
+        print("ocr-software: interrupted; a job already submitted keeps running on the service", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())