graph2table 0.1.0__tar.gz

graph2table-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+build/

graph2table-0.1.0/LICENSE

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

graph2table-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: graph2table
+Version: 0.1.0
+Summary: Client for the graph2table API: send a chart image, get the data table.
+Project-URL: Homepage, https://graph2table.com
+Project-URL: Documentation, https://graph2table.com/docs/api
+Project-URL: Benchmark, https://graph2table.com/blog/chartx-technical-report
+Author: graph2table
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chart,chart to table,csv,data extraction,graph,plot digitizer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# graph2table
+
+Python client for the [graph2table](https://graph2table.com) API. Send a chart image, get the data table.
+
+graph2table automatically extracts the data table from a chart image.
+
+## Install
+
+```
+pip install graph2table
+```
+
+## Use
+
+```python
+from graph2table import convert
+
+result = convert("figure.png", api_key="YOUR_API_KEY")
+
+result.headers          # ['x', 'Series A', 'Series B']
+result.rows[0]          # {'x': 0.0, 'Series A': 12.4, 'Series B': 9.1}
+result.to_csv("figure.csv")
+result.to_dataframe()   # pandas, if installed
+```
+
+Get an API key at https://graph2table.com/app/keys. Each call costs 10 credits. Set the `GRAPH2TABLE_API_KEY` environment variable to skip the `api_key` argument.
+
+The image can be a file path, raw bytes, or an open file. PNG, JPG and WebP up to 10 MB.
+
+To focus the extraction, pass `custom_instructions="Extract only the red series"`.
+
+Errors raise `Graph2TableError` with the HTTP status and the API message.
+
+## Check the result
+
+Open the same image at https://graph2table.com/converter to see every extracted point drawn on the chart, and correct a point before you export.
+
+## Links
+
+- API reference: https://graph2table.com/docs/api
+- Accuracy and released data: https://graph2table.com/blog/chartx-technical-report

graph2table-0.1.0/README.md

@@ -0,0 +1,41 @@
+# graph2table
+
+Python client for the [graph2table](https://graph2table.com) API. Send a chart image, get the data table.
+
+graph2table automatically extracts the data table from a chart image.
+
+## Install
+
+```
+pip install graph2table
+```
+
+## Use
+
+```python
+from graph2table import convert
+
+result = convert("figure.png", api_key="YOUR_API_KEY")
+
+result.headers          # ['x', 'Series A', 'Series B']
+result.rows[0]          # {'x': 0.0, 'Series A': 12.4, 'Series B': 9.1}
+result.to_csv("figure.csv")
+result.to_dataframe()   # pandas, if installed
+```
+
+Get an API key at https://graph2table.com/app/keys. Each call costs 10 credits. Set the `GRAPH2TABLE_API_KEY` environment variable to skip the `api_key` argument.
+
+The image can be a file path, raw bytes, or an open file. PNG, JPG and WebP up to 10 MB.
+
+To focus the extraction, pass `custom_instructions="Extract only the red series"`.
+
+Errors raise `Graph2TableError` with the HTTP status and the API message.
+
+## Check the result
+
+Open the same image at https://graph2table.com/converter to see every extracted point drawn on the chart, and correct a point before you export.
+
+## Links
+
+- API reference: https://graph2table.com/docs/api
+- Accuracy and released data: https://graph2table.com/blog/chartx-technical-report

graph2table-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "graph2table"
+version = "0.1.0"
+description = "Client for the graph2table API: send a chart image, get the data table."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "graph2table" }]
+keywords = ["chart", "graph", "plot digitizer", "data extraction", "chart to table", "csv"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://graph2table.com"
+Documentation = "https://graph2table.com/docs/api"
+Benchmark = "https://graph2table.com/blog/chartx-technical-report"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/graph2table"]

graph2table-0.1.0/src/graph2table/__init__.py

@@ -0,0 +1,14 @@
+"""graph2table Python client. Send a chart image, get the data table.
+
+    from graph2table import convert
+
+    result = convert("figure.png", api_key="YOUR_API_KEY")
+    result.headers
+    result.rows
+    result.to_csv("figure.csv")
+"""
+
+from .client import Client, ConversionResult, Graph2TableError, convert
+
+__all__ = ["Client", "ConversionResult", "Graph2TableError", "convert"]
+__version__ = "0.1.0"

graph2table-0.1.0/src/graph2table/client.py

@@ -0,0 +1,155 @@
+"""HTTP client for the graph2table API (POST /api/v1/convert)."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO, Any, Dict, List, Optional, Union
+
+import requests
+
+DEFAULT_BASE_URL = "https://graph2table.com"
+DEFAULT_TIMEOUT = 180
+ENV_API_KEY = "GRAPH2TABLE_API_KEY"
+
+ImageInput = Union[str, "os.PathLike[str]", bytes, IO[bytes]]
+
+
+class Graph2TableError(Exception):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"graph2table API error {status}: {message}")
+        self.status = status
+        self.message = message
+
+
+@dataclass
+class ConversionResult:
+    """The extracted table. `rows` are dicts keyed by column header."""
+
+    headers: List[str]
+    rows: List[Dict[str, Any]] = field(default_factory=list)
+
+    def to_csv(self, path: Optional[Union[str, "os.PathLike[str]"]] = None) -> str:
+        """Return the table as CSV text. If `path` is given, also write it there."""
+        buf = io.StringIO()
+        writer = csv.DictWriter(buf, fieldnames=self.headers, extrasaction="ignore")
+        writer.writeheader()
+        for row in self.rows:
+            writer.writerow(row)
+        text = buf.getvalue()
+        if path is not None:
+            Path(path).write_text(text, encoding="utf-8", newline="")
+        return text
+
+    def to_dataframe(self):  # type: ignore[no-untyped-def]
+        """Return a pandas DataFrame (pandas is an optional dependency)."""
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError("pandas is required: pip install graph2table[pandas]") from exc
+        return pd.DataFrame(self.rows, columns=self.headers)
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+
+def _parse_data(data: Any) -> ConversionResult:
+    """The API returns `data` as a JSON string holding a list of row objects."""
+    rows = json.loads(data) if isinstance(data, str) else data
+    if not isinstance(rows, list):
+        raise Graph2TableError(200, "Unexpected response shape: data is not a list")
+    headers: List[str] = []
+    for row in rows:
+        for key in row:
+            if key not in headers:
+                headers.append(key)
+    return ConversionResult(headers=headers, rows=rows)
+
+
+def _open_image(image: ImageInput, filename: Optional[str]):
+    """Return (filename, bytes-or-file) for the multipart upload."""
+    if isinstance(image, (bytes, bytearray)):
+        return filename or "image.png", bytes(image)
+    if hasattr(image, "read"):
+        name = filename or getattr(image, "name", None) or "image.png"
+        return os.path.basename(str(name)), image
+    path = Path(image)
+    return filename or path.name, path.read_bytes()
+
+
+class Client:
+    """Client for the graph2table API.
+
+    The API key comes from the `api_key` argument or the GRAPH2TABLE_API_KEY
+    environment variable. Create keys at https://graph2table.com/app/keys.
+    Every request costs 10 credits.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ):
+        key = api_key or os.environ.get(ENV_API_KEY)
+        if not key:
+            raise ValueError(
+                f"No API key. Pass api_key=... or set the {ENV_API_KEY} environment variable."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    def convert(
+        self,
+        image: ImageInput,
+        custom_instructions: Optional[str] = None,
+        filename: Optional[str] = None,
+    ) -> ConversionResult:
+        """Extract the data table from one chart image.
+
+        `image` is a file path, raw bytes, or an open binary file. PNG, JPG and
+        WebP up to 10 MB are accepted. `custom_instructions` (500 characters or
+        fewer) tells the extractor what to focus on, for example
+        "Extract only the red series".
+        """
+        name, payload = _open_image(image, filename)
+        files = {"file": (name, payload)}
+        data = {}
+        if custom_instructions:
+            data["custom_instructions"] = custom_instructions
+        response = self.session.post(
+            f"{self.base_url}/api/v1/convert",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            files=files,
+            data=data,
+            timeout=self.timeout,
+        )
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if response.status_code != 200 or not body.get("success"):
+            message = body.get("error") if isinstance(body, dict) else None
+            raise Graph2TableError(response.status_code, message or response.text[:200])
+        return _parse_data(body.get("data"))
+
+
+def convert(
+    image: ImageInput,
+    api_key: Optional[str] = None,
+    custom_instructions: Optional[str] = None,
+    **client_kwargs: Any,
+) -> ConversionResult:
+    """One-call convenience wrapper around `Client.convert`."""
+    return Client(api_key=api_key, **client_kwargs).convert(
+        image, custom_instructions=custom_instructions
+    )

graph2table-0.1.0/tests/test_client.py

@@ -0,0 +1,79 @@
+import json
+
+import pytest
+
+from graph2table import Client, Graph2TableError, convert
+from graph2table.client import _parse_data
+
+
+class FakeResponse:
+    def __init__(self, status_code, body, text=""):
+        self.status_code = status_code
+        self._body = body
+        self.text = text or json.dumps(body)
+
+    def json(self):
+        return self._body
+
+
+class FakeSession:
+    def __init__(self, response):
+        self.response = response
+        self.calls = []
+
+    def post(self, url, **kwargs):
+        self.calls.append((url, kwargs))
+        return self.response
+
+
+def legacy_data(rows):
+    # The API returns `data` as a pretty-printed JSON string of row objects.
+    return json.dumps(rows, indent=4)
+
+
+def test_convert_parses_legacy_data(tmp_path):
+    rows = [{"x": 1, "Series A": 2.5}, {"x": 2, "Series A": 3.0}]
+    session = FakeSession(FakeResponse(200, {"success": True, "data": legacy_data(rows)}))
+    img = tmp_path / "chart.png"
+    img.write_bytes(b"\x89PNG fake")
+
+    result = Client(api_key="k", session=session).convert(img, custom_instructions="red only")
+
+    assert result.headers == ["x", "Series A"]
+    assert result.rows == rows
+    assert len(result) == 2
+    url, kwargs = session.calls[0]
+    assert url == "https://graph2table.com/api/v1/convert"
+    assert kwargs["headers"]["Authorization"] == "Bearer k"
+    assert kwargs["files"]["file"][0] == "chart.png"
+    assert kwargs["data"] == {"custom_instructions": "red only"}
+
+
+def test_to_csv_writes_file(tmp_path):
+    result = _parse_data(legacy_data([{"x": 1, "y": 2}, {"x": 3, "y": 4}]))
+    out = tmp_path / "t.csv"
+    text = result.to_csv(out)
+    assert text.splitlines() == ["x,y", "1,2", "3,4"]
+    assert out.read_text(encoding="utf-8").splitlines() == ["x,y", "1,2", "3,4"]
+
+
+def test_error_response_raises():
+    session = FakeSession(FakeResponse(402, {"error": "Insufficient credits."}))
+    with pytest.raises(Graph2TableError) as exc:
+        Client(api_key="k", session=session).convert(b"bytes")
+    assert exc.value.status == 402
+    assert "Insufficient credits" in str(exc.value)
+
+
+def test_missing_api_key(monkeypatch):
+    monkeypatch.delenv("GRAPH2TABLE_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        Client()
+
+
+def test_env_api_key(monkeypatch):
+    monkeypatch.setenv("GRAPH2TABLE_API_KEY", "from-env")
+    session = FakeSession(FakeResponse(200, {"success": True, "data": "[]"}))
+    result = convert(b"bytes", session=session)
+    assert result.rows == []
+    assert session.calls[0][1]["headers"]["Authorization"] == "Bearer from-env"