parserbee 0.1.0__py3-none-any.whl

parserbee/__init__.py

@@ -0,0 +1,27 @@
+"""Python client for the ParserBee document extraction API."""
+
+__version__ = "0.1.0"
+
+from .client import ParserBee  # noqa: E402
+from .errors import (  # noqa: E402
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    NotFoundError,
+    ParserBeeError,
+    PermissionDeniedError,
+)
+
+__all__ = [
+    "ParserBee",
+    "ParserBeeError",
+    "APIError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+]

parserbee/client.py

@@ -0,0 +1,149 @@
+"""HTTP client for the ParserBee API."""
+
+import mimetypes
+import os
+from pathlib import Path
+from typing import IO, Any, Dict, List, Optional, Union
+from urllib.parse import quote
+
+import requests
+
+from . import __version__
+from .errors import APIConnectionError, APIError, error_for_status
+
+DEFAULT_BASE_URL = "https://app.parserbee.com"
+DEFAULT_TIMEOUT = 120.0
+
+FileInput = Union[str, os.PathLike, IO[bytes]]
+
+
+class ParserBee:
+    """Client for the ParserBee REST API.
+
+    The API key is read from the ``api_key`` argument or, if that is not
+    given, from the ``PARSERBEE_API_KEY`` environment variable. Generate a
+    key from Settings in the ParserBee dashboard; it starts with ``pk_``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("PARSERBEE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "No API key given. Pass api_key=... or set PARSERBEE_API_KEY."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "x-api-key": api_key,
+                "User-Agent": f"parserbee-python/{__version__}",
+                "Accept": "application/json",
+            }
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        kwargs.setdefault("timeout", self.timeout)
+        try:
+            response = self._session.request(method, url, **kwargs)
+        except requests.RequestException as exc:
+            raise APIConnectionError(f"Could not reach the ParserBee API: {exc}") from exc
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+
+        if response.status_code >= 400:
+            raise error_for_status(response.status_code, body)
+        if not isinstance(body, dict):
+            raise APIError(
+                "Unexpected response from the ParserBee API",
+                status=response.status_code,
+            )
+        return body
+
+    def extract(
+        self,
+        template_id: str,
+        file: Optional[FileInput] = None,
+        *,
+        file_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Extract structured data from a document with a Parser Template.
+
+        Pass either ``file`` (a path or an open binary file) or ``file_url``
+        (a public link to the document). Each extraction costs 1 page credit
+        per page processed.
+
+        Returns the full API response. The extracted fields are in
+        ``result["data"]``; ``result["usage"]`` holds the page count and the
+        page credits charged.
+        """
+        if not template_id:
+            raise ValueError("template_id is required")
+        if (file is None) == (file_url is None):
+            raise ValueError("Pass exactly one of file or file_url")
+
+        if file_url is not None:
+            return self._request(
+                "POST",
+                "/api/v1/extract",
+                json={"template_id": template_id, "file_url": file_url},
+            )
+
+        if isinstance(file, (str, os.PathLike)):
+            path = Path(file)
+            with path.open("rb") as handle:
+                return self._upload(template_id, handle, path.name)
+
+        name = Path(getattr(file, "name", "document")).name
+        return self._upload(template_id, file, name)
+
+    def _upload(self, template_id: str, handle: IO[bytes], name: str) -> Dict[str, Any]:
+        content_type = mimetypes.guess_type(name)[0] or "application/octet-stream"
+        return self._request(
+            "POST",
+            "/api/v1/extract",
+            data={"template_id": template_id},
+            files={"file": (name, handle, content_type)},
+        )
+
+    def list_templates(self) -> List[Dict[str, Any]]:
+        """Return every Parser Template in the account, newest first."""
+        return self._request("GET", "/api/v1/templates").get("items", [])
+
+    def get_template(self, template_id: str) -> Dict[str, Any]:
+        """Return one Parser Template, with its fields."""
+        return self._request("GET", f"/api/v1/templates/{quote(template_id, safe='')}")
+
+    def get_credits(self) -> Dict[str, Any]:
+        """Return the page credit balance and the subscription plan."""
+        return self._request("GET", "/api/v1/credits")
+
+    def list_activity(self) -> List[Dict[str, Any]]:
+        """Return the last 10 extraction requests, newest first."""
+        return self._request("GET", "/api/v1/activity").get("items", [])
+
+    def get_activity(self, request_id: str) -> Dict[str, Any]:
+        """Return one extraction request, including the extracted data."""
+        return self._request("GET", f"/api/v1/activity/{quote(request_id, safe='')}")
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "ParserBee":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

parserbee/errors.py

@@ -0,0 +1,77 @@
+"""Exceptions raised by the ParserBee client."""
+
+from typing import Any, Dict, Optional
+
+
+class ParserBeeError(Exception):
+    """Base class for every error the client raises."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.body = body or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"(code: {self.code})")
+        if self.status:
+            parts.append(f"[HTTP {self.status}]")
+        return " ".join(parts)
+
+
+class AuthenticationError(ParserBeeError):
+    """The API key is missing or invalid (HTTP 401)."""
+
+
+class InsufficientCreditsError(ParserBeeError):
+    """The account has no page credits left (HTTP 402)."""
+
+    @property
+    def credits_remaining(self) -> Optional[int]:
+        return self.body.get("credits_remaining")
+
+
+class PermissionDeniedError(ParserBeeError):
+    """No active subscription, or the account is locked (HTTP 403)."""
+
+
+class NotFoundError(ParserBeeError):
+    """The template or activity record does not exist (HTTP 404)."""
+
+
+class InvalidRequestError(ParserBeeError):
+    """The request is missing a field or the file is not accepted (HTTP 400)."""
+
+
+class APIError(ParserBeeError):
+    """Any other error returned by the API, including server errors."""
+
+
+class APIConnectionError(ParserBeeError):
+    """The request did not reach the API (network error or timeout)."""
+
+
+_STATUS_ERRORS = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+}
+
+
+def error_for_status(status: int, body: Dict[str, Any]) -> ParserBeeError:
+    """Build the right exception for an error response."""
+    cls = _STATUS_ERRORS.get(status, APIError)
+    message = body.get("error") or f"ParserBee API returned HTTP {status}"
+    return cls(message, code=body.get("code"), status=status, body=body)

parserbee-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: parserbee
+Version: 0.1.0
+Summary: Python client for the ParserBee document extraction API
+Project-URL: Homepage, https://parserbee.com
+Project-URL: Documentation, https://app.parserbee.com/docs
+Project-URL: Source, https://github.com/ParserBee/parserbee-python
+Author-email: ParserBee <support@parserbee.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data extraction,document extraction,invoice,ocr,parserbee,pdf
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parserbee-python
+
+Python client for the [ParserBee](https://parserbee.com) API. Send a PDF, scan or phone photo of an invoice, purchase order, receipt or bank statement, and get back structured JSON that matches your Parser Template.
+
+## Install
+
+```bash
+pip install parserbee
+```
+
+Requires Python 3.9 or later.
+
+## Before you start
+
+1. Create a free account at [app.parserbee.com](https://app.parserbee.com/create-account). New accounts get 25 free pages, no credit card.
+2. Create a Parser Template: upload one sample document and the AI builds the fields for you, or pick a ready-made one from the [template library](https://parserbee.com/templates/).
+3. Copy your API key from **Settings** (it starts with `pk_`) and the template ID from the template page.
+
+```bash
+export PARSERBEE_API_KEY=pk_your_api_key
+```
+
+## Quick start
+
+```python
+from parserbee import ParserBee
+
+client = ParserBee()  # reads PARSERBEE_API_KEY
+
+result = client.extract("your_template_id", "invoice.pdf")
+print(result["data"])
+# {'invoice_number': 'INV-2026-001', 'vendor_name': 'Acme Corp', 'total_amount': 1500.0, ...}
+```
+
+Extract from a public link instead of a local file:
+
+```python
+result = client.extract("your_template_id", file_url="https://example.com/invoice.pdf")
+```
+
+An open binary file works too:
+
+```python
+with open("receipt.jpg", "rb") as f:
+    result = client.extract("your_template_id", f)
+```
+
+## The response
+
+`extract()` returns the API response as a dict:
+
+| Key | What it holds |
+|---|---|
+| `data` | The extracted fields, shaped like your Parser Template |
+| `request_id` | The request ID (also in Activity in the dashboard) |
+| `credits_remaining` | Page credits left after this call |
+| `usage` | `pages_processed`, `credits_charged`, `doc_size_bytes` |
+| `processing_time_ms` | Time taken |
+
+Each extraction costs 1 page credit per page processed, with a minimum of 1.
+
+## Other methods
+
+```python
+client.list_templates()          # every Parser Template in the account
+client.get_template("tpl_id")    # one template with its fields
+client.get_credits()             # balance, plan and subscription status
+client.list_activity()           # the last 10 extractions
+client.get_activity("req_id")    # one extraction, with its data
+```
+
+## Errors
+
+Every error is a subclass of `parserbee.ParserBeeError`, with `.code` and `.status`:
+
+| Exception | When |
+|---|---|
+| `InvalidRequestError` | 400: missing field, or a file type that is not accepted |
+| `AuthenticationError` | 401: missing or invalid API key |
+| `InsufficientCreditsError` | 402: no page credits left (`.credits_remaining`) |
+| `PermissionDeniedError` | 403: no active subscription |
+| `NotFoundError` | 404: template or request not found |
+| `APIError` | Any other API error |
+| `APIConnectionError` | The request did not reach the API |
+
+```python
+from parserbee import InsufficientCreditsError
+
+try:
+    client.extract("your_template_id", "invoice.pdf")
+except InsufficientCreditsError:
+    print("Top up page credits in the dashboard")
+```
+
+## Examples
+
+The [examples](https://github.com/ParserBee/parserbee-python/tree/main/examples) folder has scripts you can run as they are:
+
+- `extract_invoice.py`: one file, printed as JSON
+- `extract_from_url.py`: a document that is already online
+- `folder_to_csv.py`: every PDF and image in a folder, one CSV row each
+- `check_credits.py`: balance and template IDs
+
+## Supported files
+
+PDF, PNG, JPG, WebP and HEIC, up to 50 MB. The API also reads DOC, PPT, PPTX, XLSX, CSV, TXT, RTF, ODT, HTML and EML; see the [API reference](https://app.parserbee.com/docs) for details. Scans and phone photos work, and there is no need to run OCR first. DOCX is not accepted: save it as PDF first.
+
+## No code needed?
+
+If you only need the data in a spreadsheet, you do not need this library. [Data Lab](https://parserbee.com/tools/bank-statement-converter/#data-lab) in the dashboard takes a batch of documents and exports one combined Excel, CSV or Google Sheets file. To try a single invoice in the browser, use the free [invoice parser](https://parserbee.com/tools/invoice-parser/).
+
+Choosing a tool for invoices? Our comparison of [invoice OCR software](https://parserbee.com/blog/best-invoice-ocr-software/) covers 10 options, tested on real invoices, scans and phone photos.
+
+## Links
+
+- [ParserBee](https://parserbee.com)
+- [API reference](https://app.parserbee.com/docs)
+- [Pricing](https://parserbee.com/pricing/)
+- Support: support@parserbee.com
+
+## License
+
+MIT

parserbee-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+parserbee/__init__.py,sha256=DdP2GEvaMpMjZWfmRLlPf951_Yei4pHcEwHWFjXKRQg,585
+parserbee/client.py,sha256=ieYHwaYYVvQzH3fo_Z56uKcnvHri148IHjt2C2BWwOU,5293
+parserbee/errors.py,sha256=VV854RlMVrqta5kiYpIPzJh-Q1NaBblBav8pzuRW4HA,2174
+parserbee-0.1.0.dist-info/METADATA,sha256=LjToRLDrGAfqZ3dvCvkY9oXWgYf40qVJlgKRzKl5yak,5347
+parserbee-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+parserbee-0.1.0.dist-info/licenses/LICENSE,sha256=WMylYQd76UfonebFez-VIVw180ftkAN4PUC_Kc-rYVM,1066
+parserbee-0.1.0.dist-info/RECORD,,

parserbee-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

parserbee-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ParserBee
+
+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.