kovapdf 0.1.0__py3-none-any.whl

kovapdf/__init__.py

@@ -0,0 +1,34 @@
+"""KovaPDF for Python: compress, merge, split, convert, read scans, redact,
+check signatures and send documents for signature.
+
+    from kovapdf import KovaPDF
+    kova = KovaPDF()  # the key comes from KOVAPDF_API_KEY
+    result = kova.compress("in.pdf", level="strong", save_to="out.pdf")
+    print(result.attribution)  # Done with KovaPDF (kovapdf.com).
+"""
+
+from ._generated import API_BASE, ATTRIBUTION, ENDPOINTS, SDK_VERSION, SITE_URL, TOOL_IDS, TOOLS
+from ._http import ClientIdentity, Transport, parse_retry_after
+from .client import KovaPDF, ResultFile, RunResult
+from .errors import FRIENDLY, KovaPDFError
+from .webhooks import verify_webhook
+
+__version__ = SDK_VERSION
+__all__ = [
+    "API_BASE",
+    "ATTRIBUTION",
+    "ENDPOINTS",
+    "FRIENDLY",
+    "SDK_VERSION",
+    "SITE_URL",
+    "TOOLS",
+    "TOOL_IDS",
+    "ClientIdentity",
+    "KovaPDF",
+    "KovaPDFError",
+    "ResultFile",
+    "RunResult",
+    "Transport",
+    "parse_retry_after",
+    "verify_webhook",
+]

kovapdf/__main__.py

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

kovapdf/_generated.py

@@ -0,0 +1,598 @@
+# Generated by packages/sdk-js/scripts/generate.mjs from integrations/generated/manifest.json and frontend/public/developers/openapi.json. Do not edit.
+# fmt: off
+"""The generated part of the KovaPDF SDK: tools, their options and the API's endpoints."""
+
+from typing import Any, Dict, List, Literal, Optional, Sequence, TypedDict, Union
+
+SDK_VERSION = "0.1.0"
+ATTRIBUTION = "Done with KovaPDF (kovapdf.com)."
+SITE_URL = "https://www.kovapdf.com"
+API_BASE = "https://api.kovapdf.com/api/v1"
+
+TOOL_IDS = ("verify", "compress", "merge", "split", "organize", "convert", "ocr", "redact", "bijoy_to_unicode", "unicode_to_bijoy", "kruti_to_unicode",)
+ToolId = Literal["verify", "compress", "merge", "split", "organize", "convert", "ocr", "redact", "bijoy_to_unicode", "unicode_to_bijoy", "kruti_to_unicode"]
+
+
+class VerifyOptions(TypedDict, total=False):
+    """Options of verify (Check PDF signatures): No options. Needs the verify permission."""
+
+    pass
+
+
+class CompressOptions(TypedDict, total=False):
+    """Options of compress (Compress PDF): level (basic, strong or quality) or targetKb."""
+
+    level: Literal["basic", "strong", "quality"]
+    targetKb: int
+
+
+class MergeOptions(TypedDict, total=False):
+    """Options of merge (Merge PDFs): Two or more PDFs, in order."""
+
+    pass
+
+
+class SplitOptions(TypedDict, total=False):
+    """Options of split (Split PDF): mode all, range (with pages), every (with pagesPerPart) or size (with maxMb)."""
+
+    mode: Literal["all", "range", "every", "size"]
+    pages: str
+    pagesPerPart: int
+    maxMb: float
+
+
+class OrganizeOptions(TypedDict, total=False):
+    """Options of organize (Reorder, rotate or delete pages): pages: the new order, each a number or { page, rotate }."""
+
+    pages: List[Union[int, Dict[str, Any]]]
+
+
+class ConvertOptions(TypedDict, total=False):
+    """Options of convert (Convert files): to word, excel, jpg or png for a PDF; to pdf for an office file or pictures."""
+
+    to: Literal["word", "excel", "jpg", "png", "pdf"]
+    pages: str
+    dpi: Literal[72, 150, 300]
+
+
+class OcrOptions(TypedDict, total=False):
+    """Options of ocr (Read text from a scan): language and pages."""
+
+    language: str
+    pages: str
+
+
+class RedactOptions(TypedDict, total=False):
+    """Options of redact (Redact a PDF): terms and or patterns, matchCase, wholeWord, label. The report lists every removal."""
+
+    terms: List[str]
+    patterns: List[Literal["email", "phone", "card", "date", "url", "iban", "ssn"]]
+    matchCase: bool
+    wholeWord: bool
+    label: str
+
+
+class BijoyToUnicodeOptions(TypedDict, total=False):
+    """Options of bijoy_to_unicode (Bijoy to Unicode): text, or one .txt file; keepEnglish."""
+
+    text: str
+    keepEnglish: bool
+
+
+class UnicodeToBijoyOptions(TypedDict, total=False):
+    """Options of unicode_to_bijoy (Unicode to Bijoy): text, or one .txt file."""
+
+    text: str
+
+
+class KrutiToUnicodeOptions(TypedDict, total=False):
+    """Options of kruti_to_unicode (Kruti Dev to Unicode): text, or one .txt file; keepEnglish."""
+
+    text: str
+    keepEnglish: bool
+
+
+TOOLS: List[Dict[str, Any]] = [
+    {
+        "id": "verify",
+        "command": "verify",
+        "method": "verify_job",
+        "title": "Check PDF signatures",
+        "description": "Checks every digital signature in a PDF: who signed, when, whether the document changed after signing, and whether the certificate is trusted. Returns a report. The file is not changed.",
+        "scope": "verify",
+        "limitsClass": "light",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "No options. Needs the verify permission.",
+        "options": [],
+    },
+    {
+        "id": "compress",
+        "command": "compress",
+        "method": "compress",
+        "title": "Compress PDF",
+        "description": "Makes a PDF smaller. Choose a level, or a target size in KB. Returns a link to the smaller PDF; the original is not changed.",
+        "scope": "tools:run",
+        "limitsClass": "light",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "level (basic, strong or quality) or targetKb.",
+        "options": [
+            {
+                "name": "level",
+                "flag": "level",
+                "kind": "string",
+                "choices": ["basic", "strong", "quality"],
+                "required": False,
+                "description": "basic (the usual) keeps good quality, strong makes it smallest, quality changes the least.",
+                "default": "basic",
+            },
+            {
+                "name": "targetKb",
+                "flag": "target-kb",
+                "kind": "integer",
+                "required": False,
+                "description": "Aim for this size in KB instead of a level.",
+            },
+        ],
+    },
+    {
+        "id": "merge",
+        "command": "merge",
+        "method": "merge",
+        "title": "Merge PDFs",
+        "description": "Joins two or more PDFs into one, in the order given. Returns a link to the merged PDF.",
+        "scope": "tools:run",
+        "limitsClass": "light",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 2,
+            "max": 20,
+            "multi": True,
+        },
+        "optionsNote": "Two or more PDFs, in order.",
+        "options": [],
+    },
+    {
+        "id": "split",
+        "command": "split",
+        "method": "split",
+        "title": "Split PDF",
+        "description": "Splits a PDF: every page on its own (all), chosen pages into one PDF (range), every N pages (every), or into parts under a size (size). Returns a link to a PDF or a ZIP of PDFs.",
+        "scope": "tools:run",
+        "limitsClass": "heavy",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "mode all, range (with pages), every (with pagesPerPart) or size (with maxMb).",
+        "options": [
+            {
+                "name": "mode",
+                "flag": "mode",
+                "kind": "string",
+                "choices": ["all", "range", "every", "size"],
+                "required": False,
+                "description": "all, range, every or size.",
+                "default": "all",
+            },
+            {
+                "name": "pages",
+                "flag": "pages",
+                "kind": "string",
+                "required": False,
+                "description": "For range: pages like 1-3,5.",
+            },
+            {
+                "name": "pagesPerPart",
+                "flag": "pages-per-part",
+                "kind": "integer",
+                "required": False,
+                "description": "For every: pages in each part.",
+            },
+            {
+                "name": "maxMb",
+                "flag": "max-mb",
+                "kind": "number",
+                "required": False,
+                "description": "For size: the most MB in each part.",
+            },
+        ],
+    },
+    {
+        "id": "organize",
+        "command": "organize",
+        "method": "organize",
+        "title": "Reorder, rotate or delete pages",
+        "description": "Builds a new PDF from the pages listed, in that order. Each item is a page number, or { page, rotate } with rotate 90, 180 or 270. Pages left out are deleted. The original is not changed.",
+        "scope": "tools:run",
+        "limitsClass": "heavy",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "pages: the new order, each a number or { page, rotate }.",
+        "options": [
+            {
+                "name": "pages",
+                "flag": "pages",
+                "kind": "json",
+                "required": True,
+                "description": "The new document's pages in order: page numbers, or { page, rotate }.",
+            },
+        ],
+    },
+    {
+        "id": "convert",
+        "command": "convert",
+        "method": "convert",
+        "title": "Convert files",
+        "description": "Converts a PDF to Word (word), Excel (excel) or pictures (jpg, png); or a Word, Excel, PowerPoint or OpenDocument file, or pictures, to PDF (pdf). Returns a link to the result.",
+        "scope": "tools:run",
+        "limitsClass": "heavy",
+        "inputs": {
+            "kinds": ["pdf", "image", "office"],
+            "min": 1,
+            "max": 20,
+            "multi": True,
+        },
+        "optionsNote": "to word, excel, jpg or png for a PDF; to pdf for an office file or pictures.",
+        "options": [
+            {
+                "name": "to",
+                "flag": "to",
+                "kind": "string",
+                "choices": ["word", "excel", "jpg", "png", "pdf"],
+                "required": True,
+                "description": "What to make: word, excel, jpg, png or pdf.",
+            },
+            {
+                "name": "pages",
+                "flag": "pages",
+                "kind": "string",
+                "required": False,
+                "description": "For pictures: pages like 1-3.",
+            },
+            {
+                "name": "dpi",
+                "flag": "dpi",
+                "kind": "number",
+                "choices": [72, 150, 300],
+                "required": False,
+                "description": "For pictures: 72, 150 or 300.",
+            },
+        ],
+    },
+    {
+        "id": "ocr",
+        "command": "ocr",
+        "method": "ocr",
+        "title": "Read text from a scan",
+        "description": "Reads the text in a scanned PDF or a picture with text recognition. Returns the text and a link to a .txt file. Up to 30 pages per call; use pages to choose.",
+        "scope": "tools:run",
+        "limitsClass": "heavy",
+        "inputs": {
+            "kinds": ["pdf", "image"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "language and pages.",
+        "options": [
+            {
+                "name": "language",
+                "flag": "language",
+                "kind": "string",
+                "required": False,
+                "description": "A language code such as eng, ben or hin; left out, it is detected.",
+            },
+            {
+                "name": "pages",
+                "flag": "pages",
+                "kind": "string",
+                "required": False,
+                "description": "Pages like 1-3,5.",
+            },
+        ],
+    },
+    {
+        "id": "redact",
+        "command": "redact",
+        "method": "redact",
+        "title": "Redact a PDF",
+        "description": "Permanently removes words or kinds of details (email, phone, card, date, url, iban, ssn) from a copy of the PDF, and lists every place something was removed as proof. The original is not changed.",
+        "scope": "tools:run",
+        "limitsClass": "heavy",
+        "inputs": {
+            "kinds": ["pdf"],
+            "min": 1,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "terms and or patterns, matchCase, wholeWord, label. The report lists every removal.",
+        "options": [
+            {
+                "name": "terms",
+                "flag": "terms",
+                "kind": "string[]",
+                "required": False,
+                "description": "Words or phrases to remove.",
+            },
+            {
+                "name": "patterns",
+                "flag": "patterns",
+                "kind": "string[]",
+                "choices": ["email", "phone", "card", "date", "url", "iban", "ssn"],
+                "required": False,
+                "description": "Kinds of details to remove.",
+            },
+            {
+                "name": "matchCase",
+                "flag": "match-case",
+                "kind": "boolean",
+                "required": False,
+                "description": "Match capital letters exactly.",
+            },
+            {
+                "name": "wholeWord",
+                "flag": "whole-word",
+                "kind": "boolean",
+                "required": False,
+                "description": "Match whole words only.",
+            },
+            {
+                "name": "label",
+                "flag": "label",
+                "kind": "string",
+                "required": False,
+                "description": "Words printed in each box, such as REDACTED.",
+            },
+        ],
+    },
+    {
+        "id": "bijoy_to_unicode",
+        "command": "bijoy-to-unicode",
+        "method": "bijoy_to_unicode",
+        "title": "Bijoy to Unicode",
+        "description": "Converts Bangla text typed in Bijoy (SutonnyMJ and similar fonts) to Unicode Bangla. English words are kept as they are. Pass the text, or a .txt file.",
+        "scope": "tools:run",
+        "limitsClass": "text",
+        "inputs": {
+            "kinds": ["text"],
+            "min": 0,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "text, or one .txt file; keepEnglish.",
+        "options": [
+            {
+                "name": "text",
+                "flag": "text",
+                "kind": "string",
+                "required": False,
+                "description": "The text to convert.",
+            },
+            {
+                "name": "keepEnglish",
+                "flag": "keep-english",
+                "kind": "boolean",
+                "required": False,
+                "description": "Keep English words as they are (the usual).",
+            },
+        ],
+    },
+    {
+        "id": "unicode_to_bijoy",
+        "command": "unicode-to-bijoy",
+        "method": "unicode_to_bijoy",
+        "title": "Unicode to Bijoy",
+        "description": "Converts Unicode Bangla text to Bijoy, for SutonnyMJ and similar fonts. Pass the text, or a .txt file.",
+        "scope": "tools:run",
+        "limitsClass": "text",
+        "inputs": {
+            "kinds": ["text"],
+            "min": 0,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "text, or one .txt file.",
+        "options": [
+            {
+                "name": "text",
+                "flag": "text",
+                "kind": "string",
+                "required": False,
+                "description": "The text to convert.",
+            },
+        ],
+    },
+    {
+        "id": "kruti_to_unicode",
+        "command": "kruti-to-unicode",
+        "method": "kruti_to_unicode",
+        "title": "Kruti Dev to Unicode",
+        "description": "Converts Hindi text typed in Kruti Dev to Unicode Hindi. English words are kept as they are. Pass the text, or a .txt file.",
+        "scope": "tools:run",
+        "limitsClass": "text",
+        "inputs": {
+            "kinds": ["text"],
+            "min": 0,
+            "max": 1,
+            "multi": False,
+        },
+        "optionsNote": "text, or one .txt file; keepEnglish.",
+        "options": [
+            {
+                "name": "text",
+                "flag": "text",
+                "kind": "string",
+                "required": False,
+                "description": "The text to convert.",
+            },
+            {
+                "name": "keepEnglish",
+                "flag": "keep-english",
+                "kind": "boolean",
+                "required": False,
+                "description": "Keep English words as they are (the usual).",
+            },
+        ],
+    },
+]
+
+ENDPOINTS: Dict[str, Dict[str, Any]] = {
+    "cancelSignRequest": {
+        "method": "POST",
+        "path": "/sign-requests/{id}/cancel",
+        "scope": "sign-requests:write",
+    },
+    "createJob": {
+        "method": "POST",
+        "path": "/jobs",
+        "scope": "tools",
+    },
+    "createSignRequest": {
+        "method": "POST",
+        "path": "/sign-requests",
+        "scope": "sign-requests:write",
+    },
+    "digitalSign": {
+        "method": "POST",
+        "path": "/digital-sign",
+        "scope": "digital-sign",
+    },
+    "downloadResult": {
+        "method": "GET",
+        "path": "/downloads/{token}",
+        "scope": None,
+    },
+    "getFile": {
+        "method": "GET",
+        "path": "/files/{id}",
+        "scope": "tools",
+    },
+    "getJob": {
+        "method": "GET",
+        "path": "/jobs/{id}",
+        "scope": "tools",
+    },
+    "getMe": {
+        "method": "GET",
+        "path": "/me",
+        "scope": None,
+    },
+    "getOpenApi": {
+        "method": "GET",
+        "path": "/openapi.json",
+        "scope": None,
+    },
+    "getSignRequest": {
+        "method": "GET",
+        "path": "/sign-requests/{id}",
+        "scope": "sign-requests:read",
+    },
+    "getSignRequestDocument": {
+        "method": "GET",
+        "path": "/sign-requests/{id}/document",
+        "scope": "sign-requests:read",
+    },
+    "listSignRequests": {
+        "method": "GET",
+        "path": "/sign-requests",
+        "scope": "sign-requests:read",
+    },
+    "listTools": {
+        "method": "GET",
+        "path": "/tools",
+        "scope": None,
+    },
+    "remindSigners": {
+        "method": "POST",
+        "path": "/sign-requests/{id}/remind",
+        "scope": "sign-requests:write",
+    },
+    "uploadFile": {
+        "method": "POST",
+        "path": "/files",
+        "scope": "tools",
+    },
+    "verifyPdf": {
+        "method": "POST",
+        "path": "/verify",
+        "scope": "verify",
+    },
+}
+
+
+class ToolMethods:
+    """One method per tool, made from the manifest. Each uploads, runs the job, waits and returns the result."""
+
+    def run(self, tool: str, inputs: Sequence[Any] = (), options: Optional[Dict[str, Any]] = None, *, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:  # pragma: no cover
+        raise NotImplementedError
+
+    def verify_job(self, file: Any, *, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Check PDF signatures. Checks every digital signature in a PDF: who signed, when, whether the document changed after signing, and whether the certificate is trusted. Returns a report. The file is not changed."""
+        options = {k: v for k, v in {}.items() if v is not None}
+        return self.run("verify", [file], options, timeout=timeout, save_to=save_to)
+
+    def compress(self, file: Any, *, level: Optional[Literal["basic", "strong", "quality"]] = None, target_kb: Optional[int] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Compress PDF. Makes a PDF smaller. Choose a level, or a target size in KB. Returns a link to the smaller PDF; the original is not changed."""
+        options = {k: v for k, v in {"level": level, "targetKb": target_kb}.items() if v is not None}
+        return self.run("compress", [file], options, timeout=timeout, save_to=save_to)
+
+    def merge(self, files: Sequence[Any], *, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Merge PDFs. Joins two or more PDFs into one, in the order given. Returns a link to the merged PDF."""
+        options = {k: v for k, v in {}.items() if v is not None}
+        return self.run("merge", list(files), options, timeout=timeout, save_to=save_to)
+
+    def split(self, file: Any, *, mode: Optional[Literal["all", "range", "every", "size"]] = None, pages: Optional[str] = None, pages_per_part: Optional[int] = None, max_mb: Optional[float] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Split PDF. Splits a PDF: every page on its own (all), chosen pages into one PDF (range), every N pages (every), or into parts under a size (size). Returns a link to a PDF or a ZIP of PDFs."""
+        options = {k: v for k, v in {"mode": mode, "pages": pages, "pagesPerPart": pages_per_part, "maxMb": max_mb}.items() if v is not None}
+        return self.run("split", [file], options, timeout=timeout, save_to=save_to)
+
+    def organize(self, file: Any, *, pages: List[Union[int, Dict[str, Any]]], timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Reorder, rotate or delete pages. Builds a new PDF from the pages listed, in that order. Each item is a page number, or { page, rotate } with rotate 90, 180 or 270. Pages left out are deleted. The original is not changed."""
+        options = {k: v for k, v in {"pages": pages}.items() if v is not None}
+        return self.run("organize", [file], options, timeout=timeout, save_to=save_to)
+
+    def convert(self, files: Sequence[Any], *, to: Literal["word", "excel", "jpg", "png", "pdf"], pages: Optional[str] = None, dpi: Optional[Literal[72, 150, 300]] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Convert files. Converts a PDF to Word (word), Excel (excel) or pictures (jpg, png); or a Word, Excel, PowerPoint or OpenDocument file, or pictures, to PDF (pdf). Returns a link to the result."""
+        options = {k: v for k, v in {"to": to, "pages": pages, "dpi": dpi}.items() if v is not None}
+        return self.run("convert", list(files), options, timeout=timeout, save_to=save_to)
+
+    def ocr(self, file: Any, *, language: Optional[str] = None, pages: Optional[str] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Read text from a scan. Reads the text in a scanned PDF or a picture with text recognition. Returns the text and a link to a .txt file. Up to 30 pages per call; use pages to choose."""
+        options = {k: v for k, v in {"language": language, "pages": pages}.items() if v is not None}
+        return self.run("ocr", [file], options, timeout=timeout, save_to=save_to)
+
+    def redact(self, file: Any, *, terms: Optional[List[str]] = None, patterns: Optional[List[Literal["email", "phone", "card", "date", "url", "iban", "ssn"]]] = None, match_case: Optional[bool] = None, whole_word: Optional[bool] = None, label: Optional[str] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Redact a PDF. Permanently removes words or kinds of details (email, phone, card, date, url, iban, ssn) from a copy of the PDF, and lists every place something was removed as proof. The original is not changed."""
+        options = {k: v for k, v in {"terms": terms, "patterns": patterns, "matchCase": match_case, "wholeWord": whole_word, "label": label}.items() if v is not None}
+        return self.run("redact", [file], options, timeout=timeout, save_to=save_to)
+
+    def bijoy_to_unicode(self, file: Any = None, *, text: Optional[str] = None, keep_english: Optional[bool] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Bijoy to Unicode. Converts Bangla text typed in Bijoy (SutonnyMJ and similar fonts) to Unicode Bangla. English words are kept as they are. Pass the text, or a .txt file."""
+        options = {k: v for k, v in {"text": text, "keepEnglish": keep_english}.items() if v is not None}
+        return self.run("bijoy_to_unicode", [] if file is None else [file], options, timeout=timeout, save_to=save_to)
+
+    def unicode_to_bijoy(self, file: Any = None, *, text: Optional[str] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Unicode to Bijoy. Converts Unicode Bangla text to Bijoy, for SutonnyMJ and similar fonts. Pass the text, or a .txt file."""
+        options = {k: v for k, v in {"text": text}.items() if v is not None}
+        return self.run("unicode_to_bijoy", [] if file is None else [file], options, timeout=timeout, save_to=save_to)
+
+    def kruti_to_unicode(self, file: Any = None, *, text: Optional[str] = None, keep_english: Optional[bool] = None, timeout: Optional[float] = None, save_to: Optional[str] = None) -> Any:
+        """Kruti Dev to Unicode. Converts Hindi text typed in Kruti Dev to Unicode Hindi. English words are kept as they are. Pass the text, or a .txt file."""
+        options = {k: v for k, v in {"text": text, "keepEnglish": keep_english}.items() if v is not None}
+        return self.run("kruti_to_unicode", [] if file is None else [file], options, timeout=timeout, save_to=save_to)