parserbee 0.1.0__tar.gz

parserbee-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python -c "import re;print(re.search(r'__version__ = \"(.+)\"', open('src/parserbee/__init__.py').read()).group(1))")
+          if [ "v$version" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match __version__ $version"
+            exit 1
+          fi
+      - run: pip install -e ".[dev]" build
+      - run: pytest -q
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/parserbee
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

parserbee-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

parserbee-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store

parserbee-0.1.0/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.

parserbee-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,123 @@
+# 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/examples/check_credits.py

@@ -0,0 +1,18 @@
+"""Print the page credit balance and the Parser Templates in the account."""
+
+from parserbee import ParserBee
+
+
+def main() -> None:
+    with ParserBee() as client:
+        credits = client.get_credits()
+        print(f"Plan: {credits['subscription_plan']} ({credits['subscription_status']})")
+        print(f"Page credits: {credits['credits_remaining']} of {credits['credits_total']}")
+
+        print("\nParser Templates:")
+        for template in client.list_templates():
+            print(f"  {template['id']}  {template['name']}")
+
+
+if __name__ == "__main__":
+    main()

parserbee-0.1.0/examples/extract_from_url.py

@@ -0,0 +1,26 @@
+"""Extract data from a document that is already online.
+
+The link must open without a login.
+
+Usage:
+    python examples/extract_from_url.py <template_id> https://example.com/invoice.pdf
+"""
+
+import json
+import sys
+
+from parserbee import ParserBee
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        sys.exit("Usage: python extract_from_url.py <template_id> <url>")
+
+    with ParserBee() as client:
+        result = client.extract(sys.argv[1], file_url=sys.argv[2])
+
+    print(json.dumps(result["data"], indent=2))
+
+
+if __name__ == "__main__":
+    main()

parserbee-0.1.0/examples/extract_invoice.py

@@ -0,0 +1,28 @@
+"""Extract the fields of one invoice and print them.
+
+Usage:
+    export PARSERBEE_API_KEY=pk_...
+    python examples/extract_invoice.py <template_id> invoice.pdf
+"""
+
+import json
+import sys
+
+from parserbee import ParserBee
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        sys.exit("Usage: python extract_invoice.py <template_id> <file>")
+    template_id, path = sys.argv[1], sys.argv[2]
+
+    with ParserBee() as client:
+        result = client.extract(template_id, path)
+
+    print(json.dumps(result["data"], indent=2))
+    usage = result.get("usage") or {}
+    print(f"\nPages: {usage.get('pages_processed')}, credits left: {result.get('credits_remaining')}")
+
+
+if __name__ == "__main__":
+    main()

parserbee-0.1.0/examples/folder_to_csv.py

@@ -0,0 +1,61 @@
+"""Extract every document in a folder and write one CSV row per document.
+
+Top-level fields become columns. Lists and groups (such as invoice line
+items) are written as JSON text in their column.
+
+Usage:
+    python examples/folder_to_csv.py <template_id> ./invoices output.csv
+"""
+
+import csv
+import json
+import sys
+from pathlib import Path
+
+from parserbee import InsufficientCreditsError, ParserBee, ParserBeeError
+
+EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".webp", ".heic"}
+
+
+def cell(value):
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    return value
+
+
+def main() -> None:
+    if len(sys.argv) != 4:
+        sys.exit("Usage: python folder_to_csv.py <template_id> <folder> <output.csv>")
+    template_id, folder, output = sys.argv[1], Path(sys.argv[2]), Path(sys.argv[3])
+
+    files = sorted(p for p in folder.iterdir() if p.suffix.lower() in EXTENSIONS)
+    if not files:
+        sys.exit(f"No PDF or image files in {folder}")
+
+    rows = []
+    with ParserBee() as client:
+        for path in files:
+            try:
+                data = client.extract(template_id, path)["data"]
+            except InsufficientCreditsError:
+                print("Out of page credits; stopping.")
+                break
+            except ParserBeeError as exc:
+                print(f"{path.name}: failed ({exc})")
+                continue
+            rows.append({"source_file": path.name, **{k: cell(v) for k, v in data.items()}})
+            print(f"{path.name}: done")
+
+    if not rows:
+        sys.exit("Nothing was extracted.")
+
+    columns = list(dict.fromkeys(key for row in rows for key in row))
+    with output.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=columns)
+        writer.writeheader()
+        writer.writerows(rows)
+    print(f"Wrote {len(rows)} rows to {output}")
+
+
+if __name__ == "__main__":
+    main()

parserbee-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parserbee"
+dynamic = ["version"]
+description = "Python client for the ParserBee document extraction API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "ParserBee", email = "support@parserbee.com" }]
+keywords = ["parserbee", "ocr", "invoice", "pdf", "document extraction", "data extraction"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = ["requests>=2.28"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://parserbee.com"
+Documentation = "https://app.parserbee.com/docs"
+Source = "https://github.com/ParserBee/parserbee-python"
+
+[tool.hatch.version]
+path = "src/parserbee/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parserbee"]

parserbee-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,163 @@
+import io
+
+import pytest
+import requests
+
+from parserbee import (
+    APIConnectionError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    NotFoundError,
+    ParserBee,
+)
+
+
+class FakeResponse:
+    def __init__(self, status_code, body):
+        self.status_code = status_code
+        self._body = body
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no json")
+        return self._body
+
+
+class FakeSession:
+    def __init__(self, response=None, error=None):
+        self.headers = {}
+        self.calls = []
+        self.response = response or FakeResponse(200, {})
+        self.error = error
+
+    def request(self, method, url, **kwargs):
+        self.calls.append((method, url, kwargs))
+        if self.error:
+            raise self.error
+        return self.response
+
+    def close(self):
+        pass
+
+
+def make_client(response=None, error=None):
+    session = FakeSession(response, error)
+    return ParserBee("pk_test", session=session), session
+
+
+def test_api_key_from_environment(monkeypatch):
+    monkeypatch.setenv("PARSERBEE_API_KEY", "pk_env")
+    client = ParserBee(session=FakeSession())
+    assert client.api_key == "pk_env"
+
+
+def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv("PARSERBEE_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        ParserBee(session=FakeSession())
+
+
+def test_sends_api_key_header():
+    client, session = make_client()
+    assert session.headers["x-api-key"] == "pk_test"
+    assert session.headers["User-Agent"].startswith("parserbee-python/")
+
+
+def test_extract_uploads_file_from_path(tmp_path):
+    pdf = tmp_path / "invoice.pdf"
+    pdf.write_bytes(b"%PDF-1.4")
+    body = {"success": True, "data": {"invoice_number": "INV-001"}}
+    client, session = make_client(FakeResponse(200, body))
+
+    result = client.extract("tpl_123", pdf)
+
+    method, url, kwargs = session.calls[0]
+    assert (method, url) == ("POST", "https://app.parserbee.com/api/v1/extract")
+    assert kwargs["data"] == {"template_id": "tpl_123"}
+    name, _, content_type = kwargs["files"]["file"]
+    assert (name, content_type) == ("invoice.pdf", "application/pdf")
+    assert result["data"]["invoice_number"] == "INV-001"
+
+
+def test_extract_accepts_open_file():
+    handle = io.BytesIO(b"\x89PNG")
+    handle.name = "/tmp/receipt.png"
+    client, session = make_client(FakeResponse(200, {"success": True}))
+
+    client.extract("tpl_123", handle)
+
+    name, _, content_type = session.calls[0][2]["files"]["file"]
+    assert (name, content_type) == ("receipt.png", "image/png")
+
+
+def test_extract_from_url_sends_json():
+    client, session = make_client(FakeResponse(200, {"success": True}))
+
+    client.extract("tpl_123", file_url="https://example.com/invoice.pdf")
+
+    kwargs = session.calls[0][2]
+    assert kwargs["json"] == {"template_id": "tpl_123", "file_url": "https://example.com/invoice.pdf"}
+    assert "files" not in kwargs
+
+
+@pytest.mark.parametrize("args", [{}, {"file": "a.pdf", "file_url": "https://x.y/a.pdf"}])
+def test_extract_needs_exactly_one_source(args):
+    client, _ = make_client()
+    with pytest.raises(ValueError):
+        client.extract("tpl_123", **args)
+
+
+def test_list_templates_returns_items():
+    client, session = make_client(FakeResponse(200, {"items": [{"id": "tpl_1"}], "total": 1}))
+    assert client.list_templates() == [{"id": "tpl_1"}]
+    assert session.calls[0][1].endswith("/api/v1/templates")
+
+
+def test_get_template_escapes_id():
+    client, session = make_client(FakeResponse(200, {"id": "a/b"}))
+    client.get_template("a/b")
+    assert session.calls[0][1].endswith("/api/v1/templates/a%2Fb")
+
+
+def test_get_credits():
+    client, _ = make_client(FakeResponse(200, {"credits_remaining": 42}))
+    assert client.get_credits()["credits_remaining"] == 42
+
+
+def test_activity_endpoints():
+    client, session = make_client(FakeResponse(200, {"items": [], "total": 0}))
+    assert client.list_activity() == []
+    client.get_activity("req_1")
+    assert session.calls[1][1].endswith("/api/v1/activity/req_1")
+
+
+@pytest.mark.parametrize(
+    "status,exc",
+    [
+        (400, InvalidRequestError),
+        (401, AuthenticationError),
+        (402, InsufficientCreditsError),
+        (404, NotFoundError),
+    ],
+)
+def test_error_statuses_map_to_exceptions(status, exc):
+    client, _ = make_client(FakeResponse(status, {"error": "nope", "code": "SOME_CODE"}))
+    with pytest.raises(exc) as info:
+        client.get_credits()
+    assert info.value.code == "SOME_CODE"
+    assert info.value.status == status
+
+
+def test_insufficient_credits_exposes_balance():
+    body = {"error": "Insufficient page credits", "code": "INSUFFICIENT_CREDITS", "credits_remaining": 0}
+    client, _ = make_client(FakeResponse(402, body))
+    with pytest.raises(InsufficientCreditsError) as info:
+        client.extract("tpl_123", file_url="https://example.com/a.pdf")
+    assert info.value.credits_remaining == 0
+
+
+def test_network_error_is_wrapped():
+    client, _ = make_client(error=requests.ConnectionError("boom"))
+    with pytest.raises(APIConnectionError):
+        client.get_credits()