ocr-software 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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())

ocr_software/client.py

@@ -0,0 +1,362 @@
+"""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),
+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.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import re
+import stat
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+from .advice import default_pipeline
+
+DEFAULT_BASE_URL = "https://api.ocr-software.com"
+MAX_RETRIES = 5  # retry rules of agents.md: 429, 500, 502, 503, 504 and network errors, waits 1, 2, 4, 8, 16 s
+RETRY_STATUS = (429, 500, 502, 503, 504)  # 502/504: proxy in front of a restarting service (seen 13.11.2026)
+BACKOFF_BASE_S = 1.0  # tests set it to 0
+RETRY_AFTER_LIMIT_S = 60  # longer: stop (locked_out has 900)
+HTTP_TIMEOUT_S = 90  # a status call waits up to 60 s on the server
+CONNECT_TIMEOUT_S = 10  # a wrong or unreachable address must fail fast, not after the read timeout
+PROBE_MIN_BODY = 64 * 1024  # an upload cut after this much may have been refused early (wrong key, pipeline, address): ask
+CONNECT_RETRIES = 2  # no connection at all (refused, unknown host, no route): 2 retries, not 5
+WAIT_SLICE_S = 30  # one long poll of wait()
+DEFAULT_WAIT_TIMEOUT_S = 3600
+FORMATS = ("json", "text", "md", "hocr", "pdf")
+MAX_DOCUMENT_BYTES = 100 * 1024 * 1024  # same as max_body_bytes of the service
+MAX_RESPONSE_BYTES = 256 * 1024 * 1024  # a larger result is refused, never held in memory
+DOCUMENT_MAGIC = (b"%PDF-", b"\x89PNG\r\n\x1a\n", b"\xff\xd8\xff", b"II*\x00", b"MM\x00*")  # PDF, PNG, JPEG, TIFF
+JOB_ID = re.compile(r"^[A-Za-z0-9_-]{1,100}$")
+KEY_CHARS = re.compile(r"^[\x21-\x7e]+$")
+
+
+class OcrError(Exception):
+    """Any failure. code is the API error code (unauthorized, busy, ...) or one of: no_key, bad_input, network, timeout."""
+
+    def __init__(self, message, code="error", http_status=0):
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status  # 0 if the failure was not an HTTP answer
+
+
+class PagesUnread(OcrError):
+    """The job is done but not every page was read. data is the result anyway, job the final job state."""
+
+    def __init__(self, message, job, data):
+        super().__init__(message, code="pages_unread")
+        self.job = job
+        self.data = data
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """The key must never follow a redirect to another host."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+class _ConnectTimeoutMixin:
+    """Connect with CONNECT_TIMEOUT_S, then read with the normal timeout (urllib has one timeout for both)."""
+
+    def connect(self):
+        read_timeout, self.timeout = self.timeout, CONNECT_TIMEOUT_S
+        try:
+            super().connect()
+        finally:
+            self.timeout = read_timeout
+        self.sock.settimeout(read_timeout)
+
+
+class _HTTPConnection(_ConnectTimeoutMixin, http.client.HTTPConnection):
+    pass
+
+
+class _HTTPSConnection(_ConnectTimeoutMixin, http.client.HTTPSConnection):
+    pass
+
+
+class _HTTPHandler(urllib.request.HTTPHandler):
+    def http_open(self, req):
+        return self.do_open(_HTTPConnection, req)
+
+
+class _HTTPSHandler(urllib.request.HTTPSHandler):
+    def https_open(self, req):
+        return self.do_open(_HTTPSConnection, req)
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect, _HTTPHandler, _HTTPSHandler)
+
+
+_CUT_OFF = (ConnectionResetError, ConnectionAbortedError, BrokenPipeError)  # Windows 10053/10054, Linux EPIPE/ECONNRESET
+
+
+def _int(text):
+    try:
+        return int(text)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _error_of(e):
+    """Code and message of an API error body {"error":{"code","message","details","missing","pipelines"}}."""
+    try:
+        err = json.loads(e.read(65536))["error"]  # bounded: an error body is short
+    except (ValueError, KeyError, TypeError, OSError, http.client.HTTPException):
+        return "http_error", str(e.reason)
+    message = err.get("message", "")
+    extra = {k: err[k] for k in ("details", "missing", "pipelines") if k in err}
+    details = extra.get("details")
+    if isinstance(details, list) and all(isinstance(d, str) and d in message for d in details):
+        del extra["details"]  # the service joins the details into the message: show them once
+    return err.get("code", "http_error"), message + (" " + json.dumps(extra) if extra else "")
+
+
+def _refusal(url, head):
+    """The real answer to an upload that was cut. The service (behind its proxy) answers a wrong key, pipeline or address
+    before it reads the body and closes; a client that is still sending gets a reset and never sees the answer (Windows
+    10053/10054, found 13.11.2026). The same request with an empty body is refused for the same reason at once, and
+    otherwise answers empty_document: then the key and the pipeline are fine and the cut was load. Returns an OcrError
+    to raise, or None if the cut is to be retried."""
+    probe_head = {k: v for k, v in head.items() if k != "Idempotency-Key"}  # the probe is not the upload
+    try:
+        with _OPENER.open(urllib.request.Request(url, data=b"", method="POST", headers=probe_head), timeout=CONNECT_TIMEOUT_S):
+            return None
+    except urllib.error.HTTPError as e:
+        code, message = _error_of(e)
+        if code == "empty_document" or (e.code in RETRY_STATUS and code != "locked_out"):
+            return None
+        return OcrError("%d %s: %s" % (e.code, code, message), code, e.code)
+    except (OSError, http.client.HTTPException):  # no answer to the probe either: the normal retry rules decide
+        return None
+
+
+_PAGE_HEADING = re.compile(r"^## Page (\d+)\n\n", re.M)
+
+
+def split_pages(text, format="text"):
+    """The pages of a result as [(number, text)]. format "text": pages are separated by a form feed (as pdftotext does), "md":
+    every page starts with the heading "## Page N" (the heading is not part of the page text). A result that does not look
+    like either format is one page, never an error."""
+    if format == "md":
+        starts, want = [], 1
+        for m in _PAGE_HEADING.finditer(text):  # a heading the model wrote inside a page does not count: numbers run 1, 2, 3 ...
+            if int(m.group(1)) == want:
+                starts.append(m)
+                want += 1
+        if starts:
+            ends = [m.start() for m in starts[1:]] + [len(text)]
+            return [(i + 1, text[m.end():end].rstrip("\n") + "\n") for i, (m, end) in enumerate(zip(starts, ends))]
+        return [(1, text)]
+    return [(i + 1, page) for i, page in enumerate(text.split("\f"))]
+
+
+def check_job_id(job_id):
+    if not isinstance(job_id, str) or not JOB_ID.match(job_id):
+        raise OcrError("invalid job_id", "bad_input")
+
+
+def read_document(path, allowed_dir=None):
+    """Read a local document: inside allowed_dir if set (realpath, so no escape by symlink or ..), a regular file of
+    at most 100 MiB, starting with the magic bytes of PDF, PNG, JPEG or TIFF."""
+    real = os.path.realpath(path)
+    if allowed_dir:
+        allowed = os.path.realpath(allowed_dir)
+        try:
+            inside = os.path.commonpath([real, allowed]) == allowed
+        except ValueError:  # other drive on Windows
+            inside = False
+        if not inside:
+            raise OcrError("file is outside the allowed folder: %s" % path, "bad_input")
+    try:
+        with open(real, "rb") as f:  # one open: the file that is checked is the file that is sent
+            st = os.fstat(f.fileno())
+            if not stat.S_ISREG(st.st_mode):
+                raise OcrError("not a file: %s" % path, "bad_input")
+            if st.st_size > MAX_DOCUMENT_BYTES:
+                raise OcrError("file is larger than %d MiB: %s" % (MAX_DOCUMENT_BYTES >> 20, path), "bad_input")
+            data = f.read(MAX_DOCUMENT_BYTES + 1)  # bounded even if the file grows meanwhile
+    except OSError:
+        raise OcrError("not a file: %s" % path, "bad_input")
+    if len(data) > MAX_DOCUMENT_BYTES:
+        raise OcrError("file is larger than %d MiB: %s" % (MAX_DOCUMENT_BYTES >> 20, path), "bad_input")
+    # like the service: a PDF may start with junk, "%PDF-" anywhere in the first 1024 bytes
+    if not data:
+        raise OcrError("file is empty: %s" % path, "bad_input")
+    if not (data.startswith(DOCUMENT_MAGIC) or b"%PDF-" in data[:1024]):
+        raise OcrError("not a PDF, PNG, JPEG or TIFF file: %s" % path, "bad_input")
+    return data
+
+
+def unread_message(job):
+    """None if every page was read, else one sentence saying what is missing."""
+    failed, not_run, stop = job.get("pages_failed", 0), job.get("pages_not_run", 0), job.get("stop")
+    if not (failed or not_run or stop):
+        return None
+    parts = []
+    if failed:
+        parts.append("%d page(s) failed" % failed)
+    if not_run:
+        parts.append("%d page(s) not run" % not_run)
+    if stop:
+        parts.append("stopped: %s" % stop)
+    return "job %s is done but not every page was read: %s" % (job.get("job_id", "?"), ", ".join(parts))
+
+
+class Client:
+    def __init__(self, api_key=None, base_url=None, allowed_dir=None):
+        env = os.environ
+        key = api_key if api_key is not None else env.get("OCR_SOFTWARE_API_KEY") or env.get("OCR_KEY", "")
+        self._key = key.strip()  # a key copied from a file or $(cat key) often ends in a newline
+        self.base_url = (base_url or env.get("OCR_SOFTWARE_BASE_URL") or env.get("OCR_BASE_URL") or DEFAULT_BASE_URL).strip().rstrip("/")
+        self.allowed_dir = allowed_dir if allowed_dir is not None else env.get("OCR_SOFTWARE_ALLOWED_DIR") or env.get("OCR_ALLOWED_DIR")
+        if urllib.parse.urlsplit(self.base_url).scheme not in ("http", "https"):
+            raise OcrError("base URL must start with http:// or https://", "bad_input")
+
+    def __repr__(self):
+        return "Client(base_url=%r)" % self.base_url  # never the key
+
+    def _call(self, method, path, query=None, body=None, key_needed=True, headers=None):
+        """One API call with the retry rules. Returns (bytes, headers). Raises OcrError carrying the API error code."""
+        url = self.base_url + path
+        query = {k: v for k, v in (query or {}).items() if v is not None}
+        if query:
+            url += "?" + urllib.parse.urlencode(query, safe=",@")
+        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")
+            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
+        probed = False
+        for attempt in range(MAX_RETRIES + 1):
+            req = urllib.request.Request(url, data=body, method=method, headers=head)
+            try:
+                with _OPENER.open(req, timeout=HTTP_TIMEOUT_S) as resp:
+                    data = resp.read(MAX_RESPONSE_BYTES + 1)
+                    if len(data) > MAX_RESPONSE_BYTES:
+                        raise OcrError("response larger than %d bytes, refused" % MAX_RESPONSE_BYTES, "too_large")
+                    return data, resp.headers
+            except urllib.error.HTTPError as e:
+                code, message = _error_of(e)
+                retry_after = _int(e.headers.get("Retry-After"))
+                if retry_after > RETRY_AFTER_LIMIT_S:
+                    raise OcrError("%d %s: %s (Retry-After %d s: not retried, ask the human)" % (e.code, code, message, retry_after), code, e.code)
+                if e.code not in RETRY_STATUS or attempt == MAX_RETRIES:
+                    raise OcrError("%d %s: %s" % (e.code, code, message), code, e.code)
+                delay = max(retry_after, BACKOFF_BASE_S * 2 ** attempt)
+            except urllib.error.URLError as e:  # urllib raises URLError only if the request could not be sent
+                if isinstance(e.reason, _CUT_OFF) and body and len(body) >= PROBE_MIN_BODY and not probed:
+                    probed = True
+                    refusal = _refusal(url, head)
+                    if refusal:
+                        raise refusal
+                if isinstance(e.reason, _CUT_OFF):  # connected, then cut: the service drops an upload beyond 2 per key instead of 429
+                    if attempt == MAX_RETRIES:
+                        raise OcrError("the service cut the connection %d times (more than 2 uploads at once with this key?): %s" % (attempt + 1, e.reason), "network")
+                    delay = BACKOFF_BASE_S * 2 ** attempt
+                elif attempt >= CONNECT_RETRIES:
+                    raise OcrError("cannot connect to %s: %s (check base_url, OCR_SOFTWARE_BASE_URL or --base-url)" % (self.base_url, e.reason), "network")
+                else:
+                    delay = BACKOFF_BASE_S * 2 ** attempt
+            except (OSError, http.client.HTTPException) as e:  # timeouts, timeouts (socket.timeout is no TimeoutError before 3.10), resets, cut bodies
+                if attempt == MAX_RETRIES:
+                    raise OcrError("network error: %s" % e, "network")
+                delay = BACKOFF_BASE_S * 2 ** attempt
+            time.sleep(delay)
+
+    def _json(self, method, path, **kw):
+        data, _ = self._call(method, path, **kw)
+        try:
+            answer = json.loads(data)
+        except ValueError:  # a proxy or captive portal answering 200 with a web page
+            answer = None
+        if not isinstance(answer, dict):
+            raise OcrError("%s did not answer like the OCR API (not JSON): check OCR_SOFTWARE_BASE_URL" % self.base_url, "bad_response")
+        return answer
+
+    def catalog(self):
+        """What the service offers (no key needed): pipelines, formats, features."""
+        return self._json("GET", "/v1/catalog", key_needed=False)
+
+    def default_pipeline(self):
+        """name@version used when the caller names none: the fastest and cheapest available one (advice.default_pipeline). Say
+        to the user which one it was."""
+        name = default_pipeline(self.catalog().get("pipelines", []))
+        if not name:
+            raise OcrError("no pipeline is available right now: try again later or see %s/v1/catalog" % self.base_url, "unavailable")
+        return name
+
+    def quote(self, path, pipeline, dpi=None):
+        """Dry run: nothing runs, nothing is billed. Returns the page count, price_per_page_millicents, price_millicents (100,000
+        millicents = 1 EUR) and warnings. ocr_software.advice.price_sentence(q) turns it into one sentence in euros."""
+        body = read_document(path, self.allowed_dir)
+        return self._json("POST", "/v1/jobs", query={"pipeline": pipeline, "dry_run": 1, "dpi": dpi}, body=body)
+
+    def submit(self, path, pipeline, formats=None, features=None, dpi=None, client_ref=None, job_budget=None):
+        """Submit one document. Returns the job state (job_id, state, pages ...); the job may still run."""
+        return self._submit(read_document(path, self.allowed_dir), pipeline, formats, features, dpi, client_ref, job_budget)
+
+    def _submit(self, data, pipeline, formats=None, features=None, dpi=None, client_ref=None, job_budget=None):
+        if not pipeline:
+            raise OcrError("pipeline is required (name@version, see catalog())", "bad_input")
+        query = {"pipeline": pipeline, "formats": formats, "features": features, "dpi": dpi, "client_ref": client_ref,
+                 "job_budget": job_budget}  # no wait here: POST /v1/jobs rejects it (400); status() long-polls
+        # The idempotency key makes the retries of the retry rules safe: no second job, no second charge.
+        return self._json("POST", "/v1/jobs", query=query, body=data, headers={"Idempotency-Key": str(uuid.uuid4())})
+
+    def status(self, job_id, wait=0):
+        """State and counts of a job. wait (0 to 60 s): hold until the job changes."""
+        check_job_id(job_id)
+        return self._json("GET", "/v1/jobs/" + job_id, query={"wait": max(0, min(60, int(wait)))})
+
+    def wait(self, job_id, timeout=DEFAULT_WAIT_TIMEOUT_S):
+        """Poll until state is done, return the last state. done does not mean every page worked: see unread_message()."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.status(job_id, wait=WAIT_SLICE_S)
+            if job.get("state") == "done":
+                return job
+            if time.monotonic() >= deadline:
+                raise OcrError("job %s still running after %d s" % (job_id, timeout), "timeout")
+
+    def result(self, job_id, format="json", source_path=None):
+        """Result bytes of a finished job. format pdf (searchable PDF) needs source_path, the original document."""
+        return self._result(job_id, format, read_document(source_path, self.allowed_dir) if source_path else None)
+
+    def _result(self, job_id, format, source):
+        check_job_id(job_id)
+        if format not in FORMATS:
+            raise OcrError("format must be one of %s" % ", ".join(FORMATS), "bad_input")
+        if format == "pdf":
+            if source is None:
+                raise OcrError("format pdf needs the original document (source_path)", "bad_input")
+            data, _ = self._call("POST", "/v1/jobs/%s/result" % job_id, query={"format": "pdf"}, body=source)
+        else:
+            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."""
+        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")
+        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)
+        data = self._result(job_id, format, source)
+        problem = unread_message(done)
+        if problem:
+            raise PagesUnread(problem, done, data)
+        return data

ocr_software-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+ocr_software/__init__.py,sha256=JTRYcLC_n99LNPDG0mzIe7egHau8-IIcBChc8joRfAs,354
+ocr_software/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+ocr_software/advice.py,sha256=R4JCoJMCLtpRbo1I6Ga3Rim4taGFEQqBu-uJEeuegVc,4481
+ocr_software/cli.py,sha256=5TWkJp63Uzb-6XsC1m8YXpWdLt3rjhI9kfJKui8rGks,6121
+ocr_software/client.py,sha256=Zr_mAQ_5afCtD-Eb60DHSzXPXzCoBj1r05l4rjYzpGU,18788
+ocr_software-0.1.0.dist-info/licenses/LICENSE,sha256=E_lY7BQrEo1ekTWu4ZrM1nXk9oe7Lcoye3TqknyW0DI,1073
+ocr_software-0.1.0.dist-info/METADATA,sha256=kBkvqg0PfM0_d7tplBf-cJrg1csZsDs5qDZYElntEl8,6785
+ocr_software-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ocr_software-0.1.0.dist-info/entry_points.txt,sha256=CtQxrFjWhf9uMiIWmGCORvgBLVLvuod4qQT7i38iJFo,55
+ocr_software-0.1.0.dist-info/top_level.txt,sha256=I9VcBBNNYq0d22lG1zSeBdPZp-ilw7bbm3ZmoWaHxI8,13
+ocr_software-0.1.0.dist-info/RECORD,,

ocr_software-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ocr_software-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ocr-software = ocr_software.cli:main

ocr_software-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ocr_software