intosql 0.1.0__py3-none-any.whl

intosql/__init__.py

@@ -0,0 +1,103 @@
+"""Convert spreadsheets, CSV and JSON into SQL with the IntoSQL API."""
+
+from ._client import DEFAULT_BASE_URL, Conversions, IntoSQL, Upload
+from ._contract import (
+    CONTRACT_VERSION,
+    ColumnKind,
+    ColumnNames,
+    ColumnReport,
+    ColumnSpec,
+    DateOrder,
+    DetectedInput,
+    Dialect,
+    ErrorCode,
+    Fix,
+    FixCode,
+    InferenceSpec,
+    InputFormat,
+    InputSpec,
+    JobReport,
+    JobSpec,
+    OutputFormat,
+    OutputSpec,
+    OutputStyle,
+    Problem,
+    RowCounts,
+    Severity,
+    Timings,
+)
+from ._errors import (
+    ConversionCanceledError,
+    ConversionFailedError,
+    IntoSQLError,
+    WebhookSignatureError,
+)
+from ._spec import spec
+from ._types import (
+    Case,
+    Conversion,
+    ConversionErrorCode,
+    ConversionFailure,
+    ConversionOutput,
+    ConversionStatus,
+    ConversionUpload,
+    Page,
+    PageLinks,
+    PageMeta,
+    PingData,
+    Usage,
+    WebhookEvent,
+)
+from ._version import __version__
+from ._webhooks import parse_webhook, verify_webhook
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "DEFAULT_BASE_URL",
+    "Case",
+    "ColumnKind",
+    "ColumnNames",
+    "ColumnReport",
+    "ColumnSpec",
+    "Conversion",
+    "ConversionCanceledError",
+    "ConversionErrorCode",
+    "ConversionFailedError",
+    "ConversionFailure",
+    "ConversionOutput",
+    "ConversionStatus",
+    "ConversionUpload",
+    "Conversions",
+    "DateOrder",
+    "DetectedInput",
+    "Dialect",
+    "ErrorCode",
+    "Fix",
+    "FixCode",
+    "InferenceSpec",
+    "InputFormat",
+    "InputSpec",
+    "IntoSQL",
+    "IntoSQLError",
+    "JobReport",
+    "JobSpec",
+    "OutputFormat",
+    "OutputSpec",
+    "OutputStyle",
+    "Page",
+    "PageLinks",
+    "PageMeta",
+    "PingData",
+    "Problem",
+    "RowCounts",
+    "Severity",
+    "Timings",
+    "Upload",
+    "Usage",
+    "WebhookEvent",
+    "WebhookSignatureError",
+    "__version__",
+    "parse_webhook",
+    "spec",
+    "verify_webhook",
+]

intosql/_client.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from collections.abc import Iterator
+from types import TracebackType
+from typing import (
+    IO,
+    Any,
+    Callable,
+    Literal,
+    Union,
+    cast,
+)
+from urllib.parse import quote, urlencode, urlsplit
+
+import httpx
+
+from ._contract import JobSpec
+from ._errors import ConversionCanceledError, ConversionFailedError, IntoSQLError
+from ._types import Case, Conversion, Page, Usage
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://intosql.com/api/v1"
+
+Upload = Union[bytes, bytearray, memoryview, str, "os.PathLike[str]", IO[bytes]]
+"""A file to upload: its bytes, a path to it, or a binary file object open for reading."""
+
+_RETRYABLE_CODES = frozenset({"rate_limited", "too_many_active", "request_in_progress"})
+"""Codes worth sending again: waiting fixes them. Never `already_started`: it is on its way."""
+
+_RETRYABLE_STATUSES = frozenset({408, 425})
+"""Statuses from the network in between, which carry no code of ours. Every 5xx is retried too."""
+
+
+class IntoSQL:
+    """The IntoSQL API: convert spreadsheets, CSV and JSON into SQL on IntoSQL's machines."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        http_client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if api_key == "":
+            raise ValueError("An API key is required: make one in Settings, API keys.")
+
+        self._api_key = api_key
+        self._base_url = base_url[:-1] if base_url.endswith("/") else base_url
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._sleep = sleep
+        self.conversions = Conversions(self)
+
+    def close(self) -> None:
+        """Closes the HTTP client, unless it was passed in."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> IntoSQL:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def convert(
+        self,
+        file: Upload,
+        *,
+        name: str,
+        spec: JobSpec,
+        size: int | None = None,
+        timeout: float = 3600.0,
+        interval: float | None = None,
+    ) -> Conversion:
+        """Uploads `file`, converts it and waits for the result.
+
+        `size` is the file's size in bytes, needed only for a file object that can't seek.
+        """
+        size = _size_of(file) if size is None else size
+        opened = self.conversions.create(name=name, size=size, spec=spec)
+        self.conversions.upload(opened, file, size=size)
+        self.conversions.start(opened["id"])
+
+        return self.conversions.wait(opened["id"], timeout=timeout, interval=interval)
+
+    def convert_url(
+        self,
+        url: str,
+        *,
+        spec: JobSpec,
+        name: str | None = None,
+        timeout: float = 3600.0,
+        interval: float | None = None,
+    ) -> Conversion:
+        """Converts the file at a public HTTPS address and waits for the result."""
+        queued = self.conversions.create_from_url(url=url, spec=spec, name=name)
+
+        return self.conversions.wait(queued["id"], timeout=timeout, interval=interval)
+
+    def usage(self) -> Usage:
+        """Bytes of conversions the plan includes this month, used and left."""
+        return cast(Usage, self._request("GET", "/usage")["data"])
+
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:  # noqa: ANN401
+        url = self._url(path)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"intosql-python/{__version__}",
+        }
+
+        if method == "POST":
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+
+        attempt = 0
+
+        while True:
+            try:
+                response = self._http.request(
+                    method, url, headers=headers, json=body, timeout=self._timeout
+                )
+            except httpx.TransportError:
+                if attempt >= self._max_retries:
+                    raise
+
+                self._sleep(_backoff(attempt, None))
+                attempt += 1
+                continue
+
+            if response.is_success:
+                return None if response.status_code == 204 else response.json()
+
+            error = _to_error(response)
+
+            if _retryable(error) and attempt < self._max_retries:
+                self._sleep(_backoff(attempt, response.headers.get("Retry-After")))
+                attempt += 1
+                continue
+
+            raise error
+
+    def _url(self, path: str) -> str:
+        """A path under the API, or one of its own absolute addresses (pagination links)."""
+        if not path.startswith("http"):
+            return f"{self._base_url}{path}"
+
+        if _origin(path) != _origin(self._base_url):
+            raise ValueError(f"Refusing to send the API key to {_origin(path)}.")
+
+        return path
+
+
+class Conversions:
+    """Each step of a conversion on its own: `client.conversions`."""
+
+    def __init__(self, client: IntoSQL) -> None:
+        self._client = client
+
+    def create(self, *, name: str, size: int, spec: JobSpec) -> Conversion:
+        """Opens a conversion; the answer has the address to upload the file to."""
+        body = {"name": name, "bytes": size, "spec": spec}
+
+        return cast(Conversion, self._client._request("POST", "/conversions", body)["data"])
+
+    def create_from_url(self, *, url: str, spec: JobSpec, name: str | None = None) -> Conversion:
+        """Queues a conversion of the file at a public HTTPS address."""
+        body: dict[str, Any] = {"url": url, "spec": spec}
+
+        if name is not None:
+            body["name"] = name
+
+        return cast(Conversion, self._client._request("POST", "/conversions", body)["data"])
+
+    def upload(self, conversion: Conversion, file: Upload, *, size: int | None = None) -> None:
+        """Sends the file to the address `create` answered with, streamed. Never retried."""
+        upload = conversion["upload"]
+
+        if upload is None:
+            raise ValueError(
+                f"Conversion {conversion['id']} has no upload address: open it with create()."
+            )
+
+        headers = httpx.Headers()
+
+        for header, value in upload["headers"].items():
+            headers[header] = ", ".join(value) if isinstance(value, list) else value
+
+        if isinstance(file, (str, os.PathLike)):
+            with open(file, "rb") as opened:
+                response = self._put(upload["url"], headers, opened, size)
+        else:
+            response = self._put(upload["url"], headers, file, size)
+
+        if not response.is_success:
+            raise IntoSQLError(
+                response.status_code,
+                "upload_failed",
+                f"The upload answered {response.status_code}.",
+            )
+
+    def _put(
+        self,
+        url: str,
+        headers: httpx.Headers,
+        file: bytes | bytearray | memoryview | IO[bytes],
+        size: int | None,
+    ) -> httpx.Response:
+        if isinstance(file, (bytes, bytearray, memoryview)):
+            content: Any = bytes(file)
+        else:
+            content = file
+            known = _size_of(file) if size is None else size
+            headers.setdefault("Content-Length", str(known))
+
+        return self._client._http.request(
+            "PUT", url, headers=headers, content=content, timeout=self._client._timeout
+        )
+
+    def start(self, id: str) -> Conversion:  # noqa: A002
+        """Starts a conversion once its file is uploaded whole."""
+        return cast(
+            Conversion, self._client._request("POST", f"/conversions/{_quote(id)}/start")["data"]
+        )
+
+    def retrieve(self, id: str) -> Conversion:  # noqa: A002
+        """Reads a conversion."""
+        return cast(Conversion, self._client._request("GET", f"/conversions/{_quote(id)}")["data"])
+
+    def list(self, *, limit: int | None = None, status: str | None = None) -> Iterator[Conversion]:
+        """Every conversion, newest first, a page at a time; `status` keeps only those in it."""
+        query: dict[str, str] = {}
+
+        if limit is not None:
+            query["limit"] = str(limit)
+
+        if status is not None:
+            query["status"] = status
+
+        path: str | None = f"/conversions?{urlencode(query)}" if query else "/conversions"
+
+        while path is not None:
+            page = cast(Page, self._client._request("GET", path))
+
+            yield from page["data"]
+            path = page["links"].get("next")
+
+    def cancel(self, id: str) -> Conversion:  # noqa: A002
+        """Stops a conversion that hasn't ended; canceling it again answers the same."""
+        return cast(
+            Conversion, self._client._request("POST", f"/conversions/{_quote(id)}/cancel")["data"]
+        )
+
+    def create_case(
+        self,
+        id: str,  # noqa: A002
+        *,
+        consent: Literal[True],
+        share: Literal["file", "report"] | None = None,
+        email: str | None = None,
+        note: str | None = None,
+    ) -> Case:
+        """Sends a conversion that didn't come out right to IntoSQL, so support for it gets added.
+
+        `consent` must be True: the person agrees to send it. `share="file"` sends the file too.
+        """
+        body: dict[str, Any] = {"consent": consent}
+
+        for key, value in (("share", share), ("email", email), ("note", note)):
+            if value is not None:
+                body[key] = value
+
+        return cast(
+            Case, self._client._request("POST", f"/conversions/{_quote(id)}/cases", body)["data"]
+        )
+
+    def delete(self, id: str) -> None:  # noqa: A002
+        """Deletes its files now instead of after 24 hours."""
+        self._client._request("DELETE", f"/conversions/{_quote(id)}")
+
+    def wait(
+        self,
+        id: str,  # noqa: A002
+        *,
+        timeout: float = 3600.0,
+        interval: float | None = None,
+    ) -> Conversion:
+        """Reads the conversion until it is done.
+
+        Raises `ConversionFailedError` if it fails, `ConversionCanceledError` if it is canceled and
+        `TimeoutError` after `timeout` seconds. Pauses grow from half a second to 5 seconds, or
+        are `interval` seconds each when given.
+        """
+        deadline = time.monotonic() + timeout
+        attempt = 0
+
+        while True:
+            conversion = self.retrieve(id)
+            status = conversion["status"]
+
+            if status == "done":
+                return conversion
+
+            if status == "failed":
+                raise ConversionFailedError(id, conversion["error"])
+
+            if status == "canceled":
+                raise ConversionCanceledError(id)
+
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Conversion {id} is still {status}.")
+
+            self._client._sleep(min(0.5 * 2.0**attempt, 5.0) if interval is None else interval)
+            attempt += 1
+
+
+def _quote(id: str) -> str:  # noqa: A002
+    return quote(id, safe="")
+
+
+def _origin(url: str) -> str:
+    parts = urlsplit(url)
+
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def _size_of(file: Upload) -> int:
+    if isinstance(file, (bytes, bytearray)):
+        return len(file)
+
+    if isinstance(file, memoryview):
+        return file.nbytes
+
+    if isinstance(file, (str, os.PathLike)):
+        return os.path.getsize(file)
+
+    try:
+        position = file.tell()
+        end = file.seek(0, os.SEEK_END)
+        file.seek(position)
+    except (OSError, ValueError) as error:
+        raise TypeError("Pass size= for a file object that can't seek.") from error
+
+    return end - position
+
+
+def _backoff(attempt: int, retry_after: str | None) -> float:
+    try:
+        seconds = float(retry_after) if retry_after is not None else 0.0
+    except ValueError:
+        seconds = 0.0
+
+    if seconds > 0 and seconds != float("inf"):
+        return seconds
+
+    return min(0.5 * 2.0**attempt, 8.0)
+
+
+def _to_error(response: httpx.Response) -> IntoSQLError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    error = body.get("error") if isinstance(body, dict) else None
+    error = error if isinstance(error, dict) else {}
+
+    return IntoSQLError(
+        response.status_code,
+        error.get("code") or "http_error",
+        error.get("message") or f"The API answered {response.status_code}.",
+        error.get("fields") or {},
+        error.get("request_id") or response.headers.get("X-Request-Id"),
+    )
+
+
+def _retryable(error: IntoSQLError) -> bool:
+    return (
+        error.code in _RETRYABLE_CODES or error.status in _RETRYABLE_STATUSES or error.status >= 500
+    )

intosql/_contract.py

@@ -0,0 +1,248 @@
+"""The engine's conversion contract: what a spec accepts and what a report holds.
+
+Mirrors the contract generated from engine/crates/intosql-core (CONTRACT_VERSION 1). The string
+unions list the values known today; the server may add more, so code should not assume a value
+is one of them.
+"""
+
+from typing import Literal, Optional, TypedDict
+
+CONTRACT_VERSION = 1
+
+ColumnKind = Literal[
+    "boolean",
+    "float",
+    "date",
+    "timestamp",
+    "integer",
+    "bigint",
+    "decimal",
+    "time",
+    "timestamptz",
+    "text",
+]
+"""The kind of value a column holds, before it is mapped to a dialect's type."""
+
+ColumnNames = Literal["snake_case", "as_written"]
+"""How column names are written."""
+
+DateOrder = Literal["day_first", "month_first", "year_first", "auto"]
+"""How ambiguous dates such as 03/02/2024 are read."""
+
+Dialect = Literal["postgresql", "mysql", "mariadb", "sqlite", "sql_server", "oracle"]
+"""The databases IntoSQL writes SQL for."""
+
+ErrorCode = Literal[
+    "unsupported_version",
+    "batch_rows_out_of_range",
+    "sample_rows_too_small",
+    "table_name_empty",
+    "table_name_too_long",
+    "column_name_empty",
+    "column_name_too_long",
+    "column_not_found",
+    "no_columns",
+    "unsupported_format",
+    "encrypted_file",
+    "corrupt_file",
+    "empty_file",
+    "sheet_not_found",
+    "invalid_date",
+    "invalid_number",
+    "invalid_time",
+    "invalid_boolean",
+    "value_too_long",
+    "ambiguous_reading",
+    "mixed_number_formats",
+    "other_table_skipped",
+    "invalid_json_row",
+    "ragged_row",
+]
+"""Problems: what stopped a conversion, left a row out or needs a look."""
+
+FixCode = Literal[
+    "leading_zeros_kept",
+    "dates_day_first",
+    "dates_month_first",
+    "decimal_comma_read",
+    "column_renamed",
+    "unnamed_column_named",
+    "duplicate_column_renamed",
+    "reserved_word_renamed",
+    "text_transcoded",
+    "boolean_words_read",
+    "null_markers_read",
+    "formatted_numbers_read",
+    "code_kept_as_text",
+    "read_by_locale",
+    "unclosed_quote_read",
+    "header_found",
+    "no_header_found",
+    "total_row_skipped",
+    "note_row_skipped",
+    "excel1904_dates",
+]
+"""Corrections the engine made, each with its evidence."""
+
+InputFormat = Literal["xlsx", "xls", "xlsb", "ods", "csv", "tsv", "json", "ndjson", "sql_dump"]
+"""What a file can be read as."""
+
+OutputFormat = Literal["sql", "csv", "json"]
+"""What a conversion writes."""
+
+OutputStyle = Literal["inserts", "bulk"]
+"""How rows are written."""
+
+Severity = Literal["error", "rejected", "warning"]
+"""How serious a problem is."""
+
+
+class _ColumnReportRequired(TypedDict):
+    source_name: str
+    name: str
+    sql_type: str
+    kind: ColumnKind
+    nullable: bool
+    fixes: list[int]
+
+
+class ColumnReport(_ColumnReportRequired, total=False):
+    """One column as it was read and as it was written."""
+
+    precision: Optional[int]
+    scale: Optional[int]
+    max_chars: Optional[int]
+    excluded: bool
+    as_text: bool
+
+
+class _ColumnSpecRequired(TypedDict):
+    index: int
+
+
+class ColumnSpec(_ColumnSpecRequired, total=False):
+    """What to do with one column of the file, found by its 0-based position."""
+
+    name: Optional[str]
+    as_text: bool
+    exclude: bool
+
+
+class _DetectedInputRequired(TypedDict):
+    format: InputFormat
+    encoding: str
+    bytes: int
+
+
+class DetectedInput(_DetectedInputRequired, total=False):
+    """What was detected about the input."""
+
+    delimiter: Optional[str]
+    sheet: Optional[str]
+
+
+class _FixRequired(TypedDict):
+    number: int
+    code: FixCode
+    args: dict[str, str]
+
+
+class Fix(_FixRequired, total=False):
+    """A correction the engine made, numbered like a proofreader's mark."""
+
+    column: Optional[str]
+    row: Optional[int]
+
+
+class _InferenceSpecRequired(TypedDict):
+    sample_rows: int
+    date_order: DateOrder
+    keep_leading_zeros: bool
+
+
+class InferenceSpec(_InferenceSpecRequired, total=False):
+    """How column types are inferred."""
+
+    locale: Optional[str]
+
+
+class InputSpec(TypedDict, total=False):
+    """How to read the input. Absent values are detected from the file."""
+
+    format: Optional[InputFormat]
+    encoding: Optional[str]
+    delimiter: Optional[str]
+    sheet: Optional[str]
+    header_row: Optional[int]
+
+
+class _OutputSpecRequired(TypedDict):
+    format: OutputFormat
+    dialect: Dialect
+    create_table: bool
+    column_names: ColumnNames
+    style: OutputStyle
+    batch_rows: int
+
+
+class OutputSpec(_OutputSpecRequired, total=False):
+    """What to write."""
+
+    table: Optional[str]
+    schema: Optional[str]
+
+
+class _JobSpecRequired(TypedDict):
+    version: int
+    input: InputSpec
+    output: OutputSpec
+    inference: InferenceSpec
+
+
+class JobSpec(_JobSpecRequired, total=False):
+    """A conversion request, the same for the browser, the CLI, the API and MCP."""
+
+    columns: list[ColumnSpec]
+
+
+class _ProblemRequired(TypedDict):
+    code: ErrorCode
+    severity: Severity
+    args: dict[str, str]
+
+
+class Problem(_ProblemRequired, total=False):
+    """Something that stopped the conversion, left a row out or needs a look."""
+
+    column: Optional[str]
+    row: Optional[int]
+
+
+class RowCounts(TypedDict):
+    """Row totals."""
+
+    read: int
+    converted: int
+    rejected: int
+
+
+class Timings(TypedDict):
+    """How long each stage took."""
+
+    read_ms: int
+    convert_ms: int
+    total_ms: int
+
+
+class JobReport(TypedDict):
+    """What a conversion did, the same on every surface."""
+
+    version: int
+    input: DetectedInput
+    dialect: Dialect
+    table: str
+    columns: list[ColumnReport]
+    rows: RowCounts
+    fixes: list[Fix]
+    problems: list[Problem]
+    timings: Timings

intosql/_errors.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from ._contract import Problem
+from ._types import ConversionFailure
+
+
+class IntoSQLError(Exception):
+    """An answer from the API that wasn't a success. `code` doesn't change between versions."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        fields: dict[str, list[str]] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.fields: dict[str, list[str]] = fields if fields is not None else {}
+        self.request_id = request_id
+        """The answer's X-Request-Id; quote it when you write to IntoSQL."""
+
+
+class ConversionFailedError(Exception):
+    """A conversion that ended as `failed`, with the stable code and the engine's problems."""
+
+    def __init__(self, id: str, failure: ConversionFailure | None) -> None:  # noqa: A002
+        message = failure["message"] if failure is not None else f"Conversion {id} failed."
+        super().__init__(message)
+        self.id = id
+        self.code = failure["code"] if failure is not None else "internal_error"
+        self.problems: list[Problem] = failure["problems"] if failure is not None else []
+        self.message = message
+
+
+class ConversionCanceledError(Exception):
+    """A conversion that was canceled while it was awaited."""
+
+    def __init__(self, id: str) -> None:  # noqa: A002
+        message = f"Conversion {id} was canceled."
+        super().__init__(message)
+        self.id = id
+        self.message = message
+
+
+class WebhookSignatureError(ValueError):
+    """A webhook call whose IntoSQL-Signature doesn't match its body, or is too old."""

intosql/_spec.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from ._contract import Dialect, JobSpec, OutputFormat
+
+
+def spec(
+    dialect: Dialect,
+    *,
+    format: OutputFormat = "sql",  # noqa: A002
+    table: str | None = None,
+    schema: str | None = None,
+    sheet: str | None = None,
+    create_table: bool = True,
+    batch_rows: int = 500,
+) -> JobSpec:
+    """A conversion request with IntoSQL's defaults: types inferred, snake_case, batched inserts."""
+    return {
+        "version": 1,
+        "input": {
+            "sheet": sheet,
+            "header_row": None,
+            "delimiter": None,
+            "encoding": None,
+        },
+        "output": {
+            "format": format,
+            "dialect": dialect,
+            "table": table,
+            "schema": schema,
+            "create_table": create_table,
+            "column_names": "snake_case",
+            "style": "inserts",
+            "batch_rows": batch_rows,
+        },
+        "inference": {
+            "sample_rows": 10_000,
+            "date_order": "auto",
+            "keep_leading_zeros": True,
+            "locale": None,
+        },
+        "columns": [],
+    }

intosql/_types.py

@@ -0,0 +1,117 @@
+"""What the API answers with: decoded JSON, so new fields and values pass through."""
+
+from typing import Literal, Optional, TypedDict, Union
+
+from ._contract import JobReport, JobSpec, Problem
+
+ConversionStatus = Literal["awaiting_upload", "queued", "running", "done", "failed", "canceled"]
+"""Where a conversion is. The server may add statuses, so compare against these, don't assume."""
+
+ConversionErrorCode = Literal[
+    "not_uploaded",
+    "unreachable",
+    "download_stalled",
+    "too_big",
+    "over_quota",
+    "timed_out",
+    "account_suspended",
+    "internal_error",
+]
+"""Codes a conversion fails with on IntoSQL's side; a refused file carries an ErrorCode."""
+
+
+class ConversionFailure(TypedDict):
+    """Why a conversion failed. `code` is stable; new codes may be added within v1."""
+
+    code: str
+    message: str
+    problems: list[Problem]
+
+
+class ConversionOutput(TypedDict):
+    """The result of a done conversion, downloadable for ten minutes."""
+
+    bytes: int
+    url: str
+
+
+class ConversionUpload(TypedDict):
+    """Where to PUT the file, right after `create`."""
+
+    method: Literal["PUT"]
+    url: str
+    headers: dict[str, Union[str, list[str]]]
+
+
+class Conversion(TypedDict):
+    """A conversion as the API answers it."""
+
+    id: str
+    status: str
+    name: str
+    bytes: int
+    spec: JobSpec
+    report: Optional[JobReport]
+    error: Optional[ConversionFailure]
+    output: Optional[ConversionOutput]
+    upload: Optional[ConversionUpload]
+    created_at: Optional[str]
+    started_at: Optional[str]
+    finished_at: Optional[str]
+    expires_at: str
+
+
+class Case(TypedDict):
+    """A conversion sent to IntoSQL because it didn't come out right."""
+
+    id: str
+    conversion_id: Optional[str]
+    share: Literal["file", "report"]
+    status: Literal["open", "fixed", "closed"]
+    created_at: Optional[str]
+    expires_at: str
+
+
+class Usage(TypedDict):
+    """Bytes of conversions the plan includes this month, used and left."""
+
+    limit: int
+    used: int
+    left: int
+    period_start: str
+
+
+class PageLinks(TypedDict, total=False):
+    next: Optional[str]
+    prev: Optional[str]
+
+
+class PageMeta(TypedDict):
+    per_page: int
+    next_cursor: Optional[str]
+    prev_cursor: Optional[str]
+
+
+class Page(TypedDict):
+    """One page of `GET /conversions`."""
+
+    data: list[Conversion]
+    links: PageLinks
+    meta: PageMeta
+
+
+class PingData(TypedDict):
+    sent_at: str
+
+
+class WebhookEvent(TypedDict):
+    """What a webhook call carries. `id` is the same on every retry: handle each event once.
+
+    `type` is `conversion.done`, `conversion.failed`, `conversion.canceled` or `ping`. `data` is
+    the conversion, or `{"sent_at": ...}` for `ping`.
+    """
+
+    id: str
+    type: str
+    created_at: str
+    data: Union[Conversion, PingData]

intosql/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

intosql/_webhooks.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import cast
+
+from ._errors import WebhookSignatureError
+from ._types import WebhookEvent
+
+
+def verify_webhook(
+    body: str | bytes,
+    header: str,
+    secret: str,
+    *,
+    tolerance: int = 300,
+    now: int | None = None,
+) -> bool:
+    """Whether a webhook call came from IntoSQL.
+
+    `body` is the raw request body, `header` the IntoSQL-Signature header and `secret` the signing
+    secret from Settings, API keys. Calls signed more than `tolerance` seconds from `now` (Unix
+    seconds, the current time by default) are refused.
+    """
+    parts = {}
+
+    for part in header.split(","):
+        key, _, value = part.strip().partition("=")
+        parts[key] = value
+
+    try:
+        timestamp = int(parts.get("t", ""))
+    except ValueError:
+        return False
+
+    signature = parts.get("v1")
+    current = int(time.time()) if now is None else now
+
+    if signature is None or abs(current - timestamp) > tolerance:
+        return False
+
+    raw = body.encode() if isinstance(body, str) else body
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw, hashlib.sha256)
+
+    return hmac.compare_digest(expected.hexdigest().encode(), signature.encode())
+
+
+def parse_webhook(
+    body: str | bytes,
+    header: str,
+    secret: str,
+    *,
+    tolerance: int = 300,
+    now: int | None = None,
+) -> WebhookEvent:
+    """The event of a webhook call, once its signature checks out.
+
+    Raises `WebhookSignatureError` when it doesn't, so a forged or replayed call never reaches
+    your code.
+    """
+    if not verify_webhook(body, header, secret, tolerance=tolerance, now=now):
+        raise WebhookSignatureError("The IntoSQL-Signature does not match this body.")
+
+    return cast(WebhookEvent, json.loads(body))

intosql-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: intosql
+Version: 0.1.0
+Summary: Convert spreadsheets, CSV and JSON into SQL with the IntoSQL API.
+Project-URL: Homepage, https://intosql.com/docs/sdks/python
+Project-URL: Documentation, https://intosql.com/docs/sdks/python
+Project-URL: Repository, https://github.com/alfonsobries/intosql
+Project-URL: Changelog, https://github.com/alfonsobries/intosql/blob/main/sdks/python/CHANGELOG.md
+Author-email: IntoSQL <hello@intosql.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: converter,csv,excel,mysql,postgresql,sql,sqlite,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# IntoSQL for Python
+
+Convert spreadsheets (XLSX, XLS, ODS), CSV and JSON into SQL for PostgreSQL, MySQL, MariaDB, SQLite, SQL Server or Oracle with the [IntoSQL API](https://intosql.com/developers). Column types are inferred and dirty values fixed, so the script loads on the first try.
+
+```sh
+pip install intosql
+```
+
+Python 3.9 or newer. The API is part of IntoSQL Pro; make a key in Settings, API keys.
+
+## Convert a file
+
+```python
+import os
+from intosql import IntoSQL, spec
+
+intosql = IntoSQL(os.environ["INTOSQL_API_KEY"])
+
+conversion = intosql.convert(
+    "ventas.xlsx",
+    name="ventas.xlsx",
+    spec=spec("postgresql", table="ventas"),
+)
+
+print(conversion["report"]["rows"]["converted"], conversion["output"]["url"])
+```
+
+The file streams to storage as it is; the output URL downloads the script for ten minutes. Read the conversion again (`intosql.conversions.retrieve(id)`) for a fresh one.
+
+## Convert a file by URL
+
+```python
+conversion = intosql.convert_url(
+    "https://example.com/exports/ventas.csv",
+    spec=spec("mysql"),
+)
+```
+
+## Check a webhook
+
+Save a webhook address in Settings, API keys, and IntoSQL calls it when a conversion is done, failed or canceled.
+
+```python
+from intosql import parse_webhook
+
+# Raises WebhookSignatureError when the signature doesn't match.
+event = parse_webhook(
+    request.get_data(),
+    request.headers.get("IntoSQL-Signature", ""),
+    os.environ["INTOSQL_WEBHOOK_SECRET"],
+)
+```
+
+## Errors and retries
+
+Failed requests raise `IntoSQLError` with the HTTP `status`, a `code` that doesn't change (`needs_pro`, `over_quota`, `too_big`, `invalid_spec`, `invalid_url` and more) and the `request_id`. A conversion that ends as failed raises `ConversionFailedError` with its `code` and the engine's `problems`. Rate limits, a full account, server errors and lost connections are retried twice with the same idempotency key (`max_retries` changes it); `already_started` never is.
+
+Every endpoint: [intosql.com/developers](https://intosql.com/developers). This SDK: [intosql.com/docs/sdks/python](https://intosql.com/docs/sdks/python).

intosql-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+intosql/__init__.py,sha256=TBp76mjNGCUfMmUakqCjG0cs0Ooq8ZkmBa8_ZPjibik,1931
+intosql/_client.py,sha256=LghUfjzP4X48QEnxMbW6HiAWeeiwyeK_wZKXSTUOoEk,13035
+intosql/_contract.py,sha256=77NdKJa7isev6G-9W_pATALLgF-OA9BrYcP5_65eKmY,5654
+intosql/_errors.py,sha256=NxxVzgNU8Jw7DkCXze_fU-plkLkVouFnAppbnRIDWUk,1757
+intosql/_spec.py,sha256=sxQTvSl02-Ruda0PldoAaEKiVmFPBHlOHwA_RAw3Zso,1134
+intosql/_types.py,sha256=X_Gtx74HKvDH2XTqzRnFZaEoEo53rS2ASrCCKTUmkiI,2790
+intosql/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+intosql/_webhooks.py,sha256=oLbKS3wDxl3JUotXNiIKTdgDK4WHIPb_YuyASiHKbd8,1842
+intosql/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intosql-0.1.0.dist-info/METADATA,sha256=v3nbv23g9qvDX91XET4e7x2GLg_e086xvWWIKX9AonA,3048
+intosql-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+intosql-0.1.0.dist-info/licenses/LICENSE,sha256=7-YghfHK2R7-j_AcB_VVurxAn4brtCXq1CXFRIkSlk8,1064
+intosql-0.1.0.dist-info/RECORD,,

intosql-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

intosql-0.1.0.dist-info/licenses/LICENSE

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