onlinecompiler 0.1.0__py3-none-any.whl

onlinecompiler/__init__.py

@@ -0,0 +1,67 @@
+"""Python client for the OnlineCompiler.io code execution API: run and judge code in 46 languages."""
+
+from ._client import (
+    AuthenticationError,
+    Case,
+    CaseResult,
+    Checker,
+    Compiler,
+    InputFile,
+    JudgeResult,
+    Mode,
+    NotFoundError,
+    OnlineCompiler,
+    OnlineCompilerError,
+    OutputFile,
+    ProblemSession,
+    ProblemSessionCreated,
+    PublishResult,
+    Queued,
+    RateLimitError,
+    Receipt,
+    ReceiptKey,
+    RunResult,
+    RunTestsResult,
+    Scoring,
+    Submission,
+    SubmissionDeleted,
+    SubmissionProblem,
+    SubmissionQueued,
+    SubmissionResult,
+    __version__,
+)
+from ._verify import canonical_json, verify_receipt, verify_webhook
+
+__all__ = [
+    "AuthenticationError",
+    "Case",
+    "CaseResult",
+    "Checker",
+    "Compiler",
+    "InputFile",
+    "JudgeResult",
+    "Mode",
+    "NotFoundError",
+    "OnlineCompiler",
+    "OnlineCompilerError",
+    "OutputFile",
+    "ProblemSession",
+    "ProblemSessionCreated",
+    "PublishResult",
+    "Queued",
+    "RateLimitError",
+    "Receipt",
+    "ReceiptKey",
+    "RunResult",
+    "RunTestsResult",
+    "Scoring",
+    "Submission",
+    "SubmissionDeleted",
+    "SubmissionProblem",
+    "SubmissionQueued",
+    "SubmissionResult",
+    "__version__",
+    "canonical_json",
+    "verify_receipt",
+    "verify_webhook",
+]

onlinecompiler/_client.py

@@ -0,0 +1,622 @@
+"""The OnlineCompiler.io API client. Standard library only, so installing it adds nothing else."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any, Literal, TypedDict, overload
+from urllib.parse import quote
+
+from ._verify import _ed25519
+from ._verify import verify_receipt as _verify_receipt
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.onlinecompiler.io"
+# Long enough for a 30-second run or a 60-second run-tests request, plus queueing and network time.
+DEFAULT_TIMEOUT = 90.0
+SIGNUP_URL = "https://api.onlinecompiler.io/compilers/api-keys/"
+RECEIPT_KEYS_PATH = "/.well-known/receipt-keys.json"
+KEYS_MAX_AGE = 3600.0  # seconds the receipt key list is kept, as the API allows it to be cached
+KEYS_REFETCH_AFTER = 60.0  # seconds before an unknown key_id fetches the list again
+# The API answers 404 both for an unknown API key and for an id that is not the caller's.
+KEY_REFUSED = "Invalid or inactive API key"
+# What the API takes as an Idempotency-Key: 1 to 100 printable ASCII characters, space included.
+IDEMPOTENCY_KEY = re.compile(r"[ -~]{1,100}")
+REFUSED_ORIGINAL = ("The original request with this idempotency_key was refused, so it was not judged. Send it "
+                    "again.")
+
+Checker = Literal["trim", "exact", "tokens", "float", "rows"]
+Scoring = Literal["all_or_nothing", "percent", "weighted"]
+Mode = Literal["all", "samples"]
+
+
+class _InputFile(TypedDict):
+    name: str
+    content: str
+
+
+class InputFile(_InputFile, total=False):
+    """A file the program can read from its working directory. encoding is "utf8" (default) or "base64"."""
+
+    encoding: Literal["utf8", "base64"]
+
+
+class OutputFile(TypedDict):
+    """A file the program wrote to $OUTPUT_DIR. url is null when the file was not stored."""
+
+    name: str
+    mime: str
+    size: int
+    content_base64: str
+    url: str | None
+
+
+class RunResult(TypedDict, total=False):
+    """time, total (seconds) and memory (KB) are decimal strings, as the API sends them."""
+
+    output: str
+    error: str
+    status: str
+    exit_code: int | None
+    signal: int | None
+    time: str
+    total: str
+    memory: str
+    truncated: bool
+    time_limit: float
+    files: list[OutputFile]
+    files_truncated: bool
+
+
+class _Case(TypedDict):
+    expected_output: str
+
+
+class Case(_Case, total=False):
+    """One test case: stdin, the output it should print, and optionally hidden and weight.
+    Named Case rather than Test so pytest never tries to collect it from your test files."""
+
+    input: str
+    hidden: bool
+    weight: float
+
+
+class CaseResult(TypedDict, total=False):
+    """One test case's result. Hidden and skipped tests carry only verdict and hidden."""
+
+    verdict: str
+    hidden: bool
+    time: str
+    memory: str
+    exit_code: int | None
+    signal: int | None
+    output: str
+    error: str
+    truncated: bool
+    files: list[OutputFile]
+    files_truncated: bool
+
+
+class ReceiptKey(TypedDict):
+    """A published receipt signing key: the base64 of its raw 32-byte Ed25519 public key."""
+
+    key_id: str
+    algorithm: str
+    public_key: str
+
+
+class Receipt(TypedDict, total=False):
+    """A signed receipt (see https://onlinecompiler.io/docs/receipts). A stored problem's receipt has problem in
+    place of tests_sha256 and files_sha256. Check it with verify_receipt."""
+
+    receipt: str
+    format: int
+    submission: str
+    account: str
+    external_ref: str | None
+    issued: str
+    compiler: dict[str, Any]
+    code_sha256: str
+    tests_sha256: str
+    files_sha256: str | None
+    problem: dict[str, Any]
+    settings: dict[str, Any]
+    verdict: str
+    score: float
+    passed: int
+    total: int
+    tests: list[dict[str, Any]]
+    key_id: str
+    signature: str
+
+
+class _Judged(TypedDict):
+    verdict: str
+    score: float
+    passed: int
+    total: int
+    time_limit: float
+    compile_error: str | None
+    tests: list[CaseResult]
+    summary: str
+
+
+class RunTestsResult(_Judged):
+    """A judged submission: summary is the result in plain words; submission is its id; receipt is None when
+    none could be signed."""
+
+    submission: str
+    receipt: Receipt | None
+
+
+class JudgeResult(RunTestsResult, total=False):
+    """A stored problem's result: the run-tests result with the problem's id and the version judged."""
+
+    problem: str
+    version: int
+
+
+class SubmissionResult(_Judged, total=False):
+    """A finished submission's result, as GET /api/submissions/{id}/ and webhooks give it: the run-tests result
+    without submission and receipt (problem and version for a stored problem)."""
+
+    problem: str
+    version: int
+
+
+class SubmissionQueued(TypedDict):
+    """An async submission's answer: its id and status ("queued", or the original's status for a replayed
+    Idempotency-Key)."""
+
+    submission: str
+    status: str
+
+
+class SubmissionProblem(TypedDict):
+    id: str
+    version: int
+
+
+class Submission(TypedDict):
+    """A submission as its account sees it. status is queued, running, finished or failed; failed means it was not
+    judged, and error says why. hash_salt salts the receipt's tests and files hashes."""
+
+    submission: str
+    status: str
+    created: str
+    finished: str | None
+    external_ref: str | None
+    metadata: dict[str, Any] | None
+    problem: SubmissionProblem | None
+    result: SubmissionResult | None
+    receipt: Receipt | None
+    error: str | None
+    checker_log: str | None
+    hash_salt: str
+
+
+class SubmissionDeleted(TypedDict):
+    submission: str
+    deleted: bool
+
+
+class PublishResult(TypedDict, total=False):
+    """state is "published" (with warnings) or "checking" (with check, the reference check's submission id)."""
+
+    problem: str
+    version: int
+    state: str
+    warnings: list[str]
+    check: str
+
+
+class ProblemSession(TypedDict):
+    """A widget session as its owner sees it, never with its token."""
+
+    session: str
+    problem: str
+    version: int
+    external_ref: str
+    metadata: dict[str, Any] | None
+    callback_url: str
+    max_submits: int
+    submits_used: int
+    expires: str
+    revoked: str | None
+    created: str
+    submissions: list[str]
+
+
+class ProblemSessionCreated(ProblemSession):
+    """A new session with its token, which the API shows only this once: render it into the candidate's page as
+    the widget's data-session, and keep it out of logs."""
+
+    token: str
+
+
+class Queued(TypedDict):
+    status: str
+    id: int
+
+
+class Compiler(TypedDict, total=False):
+    id: str
+    name: str
+    packages: list[dict[str, str]]
+
+
+class OnlineCompilerError(Exception):
+    """The API refused or failed a request. status is the HTTP status, or 0 when no response arrived
+    (network error or timeout); body is the parsed error response, if any."""
+
+    def __init__(self, message: str, status: int = 0, body: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+
+
+class AuthenticationError(OnlineCompilerError):
+    """HTTP 401 or 403, or 404 for the key itself: the API key is missing, unknown, inactive, of the wrong kind, or
+    not allowed from this address, or the account may not make this request (a 403 such as a plan's problem limit;
+    the message says which)."""
+
+
+class NotFoundError(OnlineCompilerError):
+    """HTTP 404 for an id: the submission, problem or session does not exist or is not this account's."""
+
+
+class RateLimitError(OnlineCompilerError):
+    """HTTP 429: the monthly allowance, the per-minute rate, the pending runs or the account's
+    sandboxes are used up. The message says which, and when it is the plan, how to raise it."""
+
+
+def _error(status: int, raw: bytes) -> OnlineCompilerError:
+    try:
+        body = json.loads(raw)
+        message = body["error"] if isinstance(body, dict) and "error" in body else raw.decode("utf-8", "replace")
+    except ValueError:
+        body, message = None, raw.decode("utf-8", "replace")
+    message = message or f"HTTP {status}"
+    if status == 404 and message != KEY_REFUSED:
+        return NotFoundError(message, status, body)
+    if status in (401, 403, 404):
+        return AuthenticationError(message, status, body)
+    if status == 429:
+        return RateLimitError(message, status, body)
+    return OnlineCompilerError(message, status, body)
+
+
+def _without_none(**fields: Any) -> dict[str, Any]:
+    """Options left as None are left out, so the API applies its own defaults."""
+    return {key: value for key, value in fields.items() if value is not None}
+
+
+def _segment(value: str, what: str) -> str:
+    """value as one quoted path segment; an id or slug that could not be one is refused before any request."""
+    if not isinstance(value, str):
+        raise TypeError(f"{what} must be a string, not {type(value).__name__}")
+    if value in ("", ".", ".."):
+        raise ValueError(f"{what} must be a non-empty id")
+    return quote(value, safe="")
+
+
+def _judging_options(async_: bool | None, callback_url: str | None, external_ref: str | None,
+                     metadata: dict[str, Any] | None) -> dict[str, Any]:
+    if callback_url is not None and async_ is not True:
+        raise ValueError("callback_url needs async_=True: the result goes to the URL, not into the response")
+    return _without_none(callback_url=callback_url, external_ref=external_ref, metadata=metadata,
+                         **{"async": async_})
+
+
+class OnlineCompiler:
+    """A client for the OnlineCompiler.io code execution API.
+
+    api_key defaults to the ONLINECOMPILER_API_KEY environment variable. Get a free key at
+    https://api.onlinecompiler.io/compilers/api-keys/. Requests are never retried, since every
+    accepted run counts toward your allowance.
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = DEFAULT_TIMEOUT):
+        self.api_key = api_key or os.environ.get("ONLINECOMPILER_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._keys: list[ReceiptKey] | None = None
+        self._keys_fetched = 0.0
+
+    def run(self, compiler: str, code: str, input: str = "", *, time_limit: float | None = None,
+            files: list[InputFile] | None = None) -> RunResult:
+        """Run a program and wait for its result: output, error, exit_code, time, memory and any
+        files it wrote. compiler is an id such as "python-3.14" (see compilers())."""
+        body = _without_none(compiler=compiler, code=code, input=input, time_limit=time_limit, files=files)
+        return self._request("POST", "/api/run-code-sync/", body)
+
+    @overload
+    def run_tests(self, compiler: str, code: str, tests: list[Case], *, time_limit: float | None = None,
+                  checker: Checker | None = None, tolerance: float | None = None, scoring: Scoring | None = None,
+                  stop_on_failure: bool | None = None, files: list[InputFile] | None = None,
+                  async_: Literal[False] | None = None, external_ref: str | None = None,
+                  metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> RunTestsResult: ...
+
+    @overload
+    def run_tests(self, compiler: str, code: str, tests: list[Case], *, time_limit: float | None = None,
+                  checker: Checker | None = None, tolerance: float | None = None, scoring: Scoring | None = None,
+                  stop_on_failure: bool | None = None, files: list[InputFile] | None = None,
+                  async_: Literal[True], callback_url: str | None = None, external_ref: str | None = None,
+                  metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> SubmissionQueued: ...
+
+    @overload
+    def run_tests(self, compiler: str, code: str, tests: list[Case], *, time_limit: float | None = None,
+                  checker: Checker | None = None, tolerance: float | None = None, scoring: Scoring | None = None,
+                  stop_on_failure: bool | None = None, files: list[InputFile] | None = None,
+                  async_: bool | None = None, callback_url: str | None = None, external_ref: str | None = None,
+                  metadata: dict[str, Any] | None = None,
+                  idempotency_key: str | None = None) -> RunTestsResult | SubmissionQueued: ...
+
+    def run_tests(self, compiler: str, code: str, tests: list[Case], *, time_limit: float | None = None,
+                  checker: Checker | None = None, tolerance: float | None = None, scoring: Scoring | None = None,
+                  stop_on_failure: bool | None = None, files: list[InputFile] | None = None,
+                  async_: bool | None = None, callback_url: str | None = None, external_ref: str | None = None,
+                  metadata: dict[str, Any] | None = None,
+                  idempotency_key: str | None = None) -> RunTestsResult | SubmissionQueued:
+        """Judge a program against test cases: an overall verdict, a score, a verdict per test, the submission id
+        and a signed receipt. Each test counts as one run. time_limit is seconds per test (default 2).
+
+        async_=True answers at once with the submission id (async is a Python keyword); get the result with
+        wait_for_submission(), submission(), or a signed webhook to callback_url (which needs async_=True).
+        external_ref (your own id, signed into the receipt) and metadata (a JSON object, never in the receipt)
+        come back in lookups and webhooks. idempotency_key is sent as the Idempotency-Key header: repeating a
+        request with it answers with the original result instead of running again."""
+        headers = self._idempotency(idempotency_key)
+        body = _without_none(compiler=compiler, code=code, tests=tests, time_limit=time_limit, checker=checker,
+                             tolerance=tolerance, scoring=scoring, stop_on_failure=stop_on_failure, files=files)
+        body.update(_judging_options(async_, callback_url, external_ref, metadata))
+        answer = self._request("POST", "/api/run-tests/", body, headers=headers)
+        return answer if async_ else self._settled(answer)
+
+    def submit(self, compiler: str, code: str, input: str = "", *, time_limit: float | None = None,
+               files: list[InputFile] | None = None, extra_params: dict[str, Any] | None = None) -> Queued:
+        """Queue a run and return at once with its id. The result is POSTed to the callback URL
+        set on the API key in your dashboard, with extra_params echoed back."""
+        body = _without_none(compiler=compiler, code=code, input=input, time_limit=time_limit, files=files,
+                             extra_params=extra_params)
+        return self._request("POST", "/api/run-code/", body)
+
+    # Submissions
+
+    def submission(self, submission_id: str) -> Submission:
+        """A submission of this account: its status, and once it has ended its result and receipt (or error)."""
+        return self._request("GET", f"/api/submissions/{_segment(submission_id, 'submission_id')}/")
+
+    def delete_submission(self, submission_id: str) -> SubmissionDeleted:
+        """Delete a queued, finished or failed submission and what it kept; a running one is refused with 409.
+        Runs already counted stay counted. Frees its Idempotency-Key."""
+        return self._request("DELETE", f"/api/submissions/{_segment(submission_id, 'submission_id')}/")
+
+    def wait_for_submission(self, submission_id: str, *, interval: float = 2.0, timeout: float = 600.0) -> Submission:
+        """Look the submission up every interval seconds until it is finished or failed, and return it. A failed
+        one has error and no result. Raises OnlineCompilerError (status 0) if it is still queued or running after
+        timeout seconds; it is still judged, so look it up again later."""
+        deadline = time.monotonic() + timeout
+        while True:
+            current = self.submission(submission_id)
+            if current["status"] in ("finished", "failed"):
+                return current
+            if time.monotonic() + interval > deadline:
+                raise OnlineCompilerError(
+                    f"Submission {submission_id} is still {current['status']} after {timeout:g} seconds", 0, current)
+            time.sleep(interval)
+
+    # Stored problems: judging
+
+    @overload
+    def judge(self, problem: str, compiler: str, code: str, *, mode: Mode | None = None,
+              async_: Literal[False] | None = None, external_ref: str | None = None,
+              metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> JudgeResult: ...
+
+    @overload
+    def judge(self, problem: str, compiler: str, code: str, *, mode: Mode | None = None, async_: Literal[True],
+              callback_url: str | None = None, external_ref: str | None = None,
+              metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> SubmissionQueued: ...
+
+    @overload
+    def judge(self, problem: str, compiler: str, code: str, *, mode: Mode | None = None, async_: bool | None = None,
+              callback_url: str | None = None, external_ref: str | None = None,
+              metadata: dict[str, Any] | None = None,
+              idempotency_key: str | None = None) -> JudgeResult | SubmissionQueued: ...
+
+    def judge(self, problem: str, compiler: str, code: str, *, mode: Mode | None = None, async_: bool | None = None,
+              callback_url: str | None = None, external_ref: str | None = None,
+              metadata: dict[str, Any] | None = None,
+              idempotency_key: str | None = None) -> JudgeResult | SubmissionQueued:
+        """Judge code against a stored problem's current version. problem is its id (prob_...) or your slug for
+        it. mode "samples" judges only the visible tests. The result is the run-tests result with problem and
+        version; async_, callback_url, external_ref, metadata and idempotency_key work as in run_tests(). Send
+        async_=True for a problem with a custom checker."""
+        path = f"/api/problems/{_segment(problem, 'problem')}/submissions/"
+        headers = self._idempotency(idempotency_key)
+        body = _without_none(compiler=compiler, code=code, mode=mode)
+        body.update(_judging_options(async_, callback_url, external_ref, metadata))
+        answer = self._request("POST", path, body, headers=headers)
+        return answer if async_ else self._settled(answer)
+
+    # Stored problems: authoring. Specs and answers are plain dicts, as the API docs describe them.
+
+    def problems(self) -> list[dict[str, Any]]:
+        """This account's problems, newest first, without their tests."""
+        return self._request("GET", "/api/problems/")["problems"]
+
+    def problem(self, problem: str) -> dict[str, Any]:
+        """A problem by id or slug, with its draft and current version in full, hidden tests included."""
+        return self._request("GET", f"/api/problems/{_segment(problem, 'problem')}/")
+
+    def create_problem(self, spec: dict[str, Any]) -> dict[str, Any]:
+        """Create a problem from a title, an optional slug and public flag, and its first draft's fields (tests,
+        statement, checker, drivers, reference_solution...), sent as given."""
+        return self._request("POST", "/api/problems/", spec)
+
+    def update_problem(self, problem: str, fields: dict[str, Any]) -> dict[str, Any]:
+        """Change a problem's title, slug or public flag."""
+        return self._request("PATCH", f"/api/problems/{_segment(problem, 'problem')}/", fields)
+
+    def replace_draft(self, problem: str, draft: dict[str, Any]) -> dict[str, Any]:
+        """Replace the problem's draft with these fields (as create_problem takes, without title)."""
+        return self._request("PUT", f"/api/problems/{_segment(problem, 'problem')}/draft/", draft)
+
+    def publish_problem(self, problem: str) -> PublishResult:
+        """Publish the draft as the next version: at once without a reference solution (state "published"), else
+        once its reference check passes (state "checking"; problem() shows how the check went)."""
+        return self._request("POST", f"/api/problems/{_segment(problem, 'problem')}/publish/")
+
+    def archive_problem(self, problem: str) -> dict[str, Any]:
+        """Stop new submissions and free a problem slot."""
+        return self._request("POST", f"/api/problems/{_segment(problem, 'problem')}/archive/")
+
+    def restore_problem(self, problem: str) -> dict[str, Any]:
+        """Undo archive_problem, if the plan has a free problem slot."""
+        return self._request("POST", f"/api/problems/{_segment(problem, 'problem')}/restore/")
+
+    def public_problem(self, problem: str) -> dict[str, Any]:
+        """The current version as a candidate sees it: statement, languages, starter code and the visible tests.
+        A public problem answers by id with no API key; the key, when the client has one, also shows your own
+        private problems and works with a slug."""
+        return self._request("GET", f"/api/problems/{_segment(problem, 'problem')}/public/", auth=bool(self.api_key))
+
+    # Stored problems: sessions for the widget
+
+    def create_session(self, problem: str, external_ref: str, *, metadata: dict[str, Any] | None = None,
+                       callback_url: str | None = None, expires_in: int | None = None,
+                       max_submits: int | None = None) -> ProblemSessionCreated:
+        """Let one candidate's widget Submit to a problem's current version. Returns the session with its token,
+        shown only this once: render it into the candidate's page as data-session and keep it out of logs.
+        external_ref is your opaque reference for the candidate or attempt (the page sees it; never a name or
+        email). expires_in is seconds (60 to 86,400; default 3,600), max_submits 1 to 20 (default 1)."""
+        body = _without_none(external_ref=external_ref, metadata=metadata, callback_url=callback_url,
+                             expires_in=expires_in, max_submits=max_submits)
+        return self._request("POST", f"/api/problems/{_segment(problem, 'problem')}/sessions/", body, secret=True)
+
+    def session(self, problem: str, session_id: str) -> ProblemSession:
+        """A session: its Submits used, expiry and the ids of its submissions. Never the token."""
+        return self._request("GET", self._session_path(problem, session_id))
+
+    def revoke_session(self, problem: str, session_id: str) -> ProblemSession:
+        """End a session now: its next Submit is refused. Submissions already made are judged as usual."""
+        return self._request("DELETE", self._session_path(problem, session_id))
+
+    # Receipts
+
+    def receipt_keys(self, *, refresh: bool = False) -> list[ReceiptKey]:
+        """The published receipt signing keys. Needs no API key. Kept on the client for an hour; refresh=True
+        fetches them again."""
+        if refresh or self._keys is None or time.monotonic() - self._keys_fetched > KEYS_MAX_AGE:
+            self._keys = self._request("GET", RECEIPT_KEYS_PATH, auth=False)["keys"]
+            self._keys_fetched = time.monotonic()
+        return [key.copy() for key in self._keys]  # copies, so that changing them leaves the cache alone
+
+    def verify_receipt(self, receipt: Receipt | Mapping[str, Any] | None) -> bool:
+        """Whether a receipt's signature is valid, against the published keys (fetched once and kept; fetched
+        again, at most once a minute, for a key_id they lack). None (a submission without a receipt) is False.
+        Needs onlinecompiler[receipts], checked before any request; see onlinecompiler.verify_receipt to verify
+        with keys you already hold."""
+        _ed25519()
+        if not isinstance(receipt, Mapping):
+            return False
+        keys = self.receipt_keys()
+        key_id = receipt.get("key_id")
+        if (not any(key.get("key_id") == key_id for key in keys)
+                and time.monotonic() - self._keys_fetched > KEYS_REFETCH_AFTER):
+            keys = self.receipt_keys(refresh=True)
+        return _verify_receipt(receipt, keys)
+
+    # Account
+
+    def compilers(self) -> list[Compiler]:
+        """Every compiler id and its language name. Needs no API key."""
+        return self._request("GET", "/api/compilers/", auth=False)["compilers"]
+
+    def usage(self) -> dict[str, Any]:
+        """This month's runs and remaining allowance for the account, and for the key itself."""
+        return self._request("GET", "/api/usage/")
+
+    def limits(self) -> dict[str, Any]:
+        """Per-run limits (memory, time, output) and default account limits. Needs no API key."""
+        return self._request("GET", "/api/limits/", auth=False)
+
+    @staticmethod
+    def _idempotency(key: str | None) -> dict[str, str] | None:
+        if key is None:
+            return None
+        if not isinstance(key, str) or not IDEMPOTENCY_KEY.fullmatch(key):
+            raise ValueError("idempotency_key must be 1 to 100 printable ASCII characters")
+        return {"Idempotency-Key": key}
+
+    @staticmethod
+    def _session_path(problem: str, session_id: str) -> str:
+        return f"/api/problems/{_segment(problem, 'problem')}/sessions/{_segment(session_id, 'session_id')}/"
+
+    def _settled(self, answer: Any) -> Any:
+        """A sync judging answer. A retry whose Idempotency-Key finds the original still running answers 202 with
+        its id; wait for it and answer as the original would have."""
+        if not isinstance(answer, dict) or "verdict" in answer or "submission" not in answer:
+            return answer
+        try:
+            # Bounded by the client's own timeout: the original was a sync request, which ends well within it.
+            done = self.wait_for_submission(answer["submission"], interval=1.0, timeout=self.timeout)
+        except NotFoundError as exc:
+            # The 202 named a submission that was then refused (a 400 or 429 leaves none behind).
+            raise OnlineCompilerError(REFUSED_ORIGINAL, exc.status, exc.body) from None
+        if done["status"] != "finished" or done["result"] is None:
+            raise OnlineCompilerError(done["error"] or f"Submission {done['submission']} was not judged", 202, done)
+        return {**done["result"], "submission": done["submission"], "receipt": done["receipt"]}
+
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None, *, auth: bool = True,
+                 headers: dict[str, str] | None = None, secret: bool = False) -> Any:
+        """secret: the answer holds a secret (a session token), so no error quotes it."""
+        sent = {"Accept": "application/json", "User-Agent": f"onlinecompiler-python/{__version__}", **(headers or {})}
+        if auth:
+            if not self.api_key:
+                raise AuthenticationError(
+                    f"No API key: pass api_key or set ONLINECOMPILER_API_KEY. Get a free key at {SIGNUP_URL}")
+            sent["Authorization"] = self.api_key
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            sent["Content-Type"] = "application/json"
+        request = urllib.request.Request(self.base_url + path, data=data, headers=sent, method=method)
+        failed = ""
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:  # before URLError, which it subclasses
+            with exc:  # closes the error response
+                try:
+                    error_body = exc.read()
+                except (http.client.HTTPException, OSError):
+                    error_body = b""
+            raise _error(exc.code, error_body) from None
+        # OSError covers timeouts; HTTPException a reply cut off (IncompleteRead) or malformed.
+        except (urllib.error.URLError, http.client.HTTPException, OSError) as exc:
+            if not secret:
+                raise OnlineCompilerError(f"Could not reach {self.base_url}: {exc}") from exc
+            # An IncompleteRead holds the partial body, which may hold the secret: name only its kind, and raise
+            # below, outside this block, so that it is not attached as context either.
+            failed = f"Could not reach {self.base_url}: {type(exc).__name__}"
+        if failed:
+            raise OnlineCompilerError(failed)
+        try:
+            return json.loads(raw)
+        except ValueError:
+            pass
+        # Raised outside the except block, so that no exception context holds the text either.
+        if secret:
+            del raw  # not left in a frame that an error report could capture either
+            raise OnlineCompilerError(f"Expected JSON from {path}")
+        raise OnlineCompilerError(f"Expected JSON from {path}, got: {raw[:200]!r}")

onlinecompiler/_verify.py

@@ -0,0 +1,206 @@
+"""Checks that need no client and no network: webhook signatures, receipt signatures and the canonical JSON
+receipts are signed over. Webhooks use only the standard library; receipts need the optional cryptography
+package (pip install "onlinecompiler[receipts]")."""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import json
+import re
+import time
+from collections.abc import Iterable, Mapping, Sequence
+from decimal import Decimal
+from hashlib import sha256
+from typing import Any, Protocol, Union
+
+RECEIPTS_EXTRA = 'pip install "onlinecompiler[receipts]"'
+_TIMESTAMP = re.compile(r"[0-9]{1,15}")
+_SIGNATURE = re.compile(r"[0-9a-f]{64}")
+
+
+class _SupportsItems(Protocol):
+    def items(self) -> Iterable[tuple[Any, Any]]: ...
+
+
+# Request headers: anything with items(), as dicts and the request headers of Django, Flask (werkzeug), FastAPI and
+# Starlette have, or (name, value) pairs as an ASGI scope holds them.
+HeadersLike = Union[_SupportsItems, Iterable[tuple[Any, Any]]]
+MAX_SIGNATURES = 8  # X-OC-Signature entries looked at; the API sends one, or two during a secret rotation
+
+
+# Canonical JSON (RFC 8785 style), written to match the API's own (backend/judge/canonical.py) byte for byte:
+# object keys sorted by their UTF-16 code units, no whitespace, non-ASCII text left as it is, and numbers as
+# ECMAScript writes them.
+
+def _number(x: float) -> str:
+    if x != x or x in (float("inf"), float("-inf")):
+        raise ValueError("NaN and Infinity cannot be canonicalized")
+    if x == 0:
+        return "0"
+    sign = "-" if x < 0 else ""
+    _sign, digits_t, exp = Decimal(repr(abs(x))).as_tuple()
+    digits = "".join(map(str, digits_t)).rstrip("0") or "0"
+    n = len(digits_t) + int(exp)  # where the decimal point falls, counted from the first digit
+    k = len(digits)
+    if k <= n <= 21:
+        out = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        out = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        out = "0." + "0" * -n + digits
+    else:
+        e = n - 1
+        out = digits[0] + ("." + digits[1:] if k > 1 else "") + "e" + ("-" if e < 0 else "+") + str(abs(e))
+    return sign + out
+
+
+def _write(value: object, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, int):
+        out.append(str(value))
+    elif isinstance(value, float):
+        out.append(_number(value))
+    elif isinstance(value, str):
+        out.append(json.dumps(value, ensure_ascii=False))
+    elif isinstance(value, (list, tuple)):
+        out.append("[")
+        for i, item in enumerate(value):
+            if i:
+                out.append(",")
+            _write(item, out)
+        out.append("]")
+    elif isinstance(value, Mapping):
+        if not all(isinstance(key, str) for key in value):
+            raise TypeError("canonical JSON object keys must be strings")
+        out.append("{")
+        for i, key in enumerate(sorted(value, key=lambda k: k.encode("utf-16-be"))):
+            if i:
+                out.append(",")
+            out.append(json.dumps(key, ensure_ascii=False))
+            out.append(":")
+            _write(value[key], out)
+        out.append("}")
+    else:
+        raise TypeError(f"cannot canonicalize {type(value).__name__}")
+
+
+def canonical_json(value: Any) -> bytes:
+    """The canonical JSON of value as UTF-8 bytes: what receipts are signed over, and what their tests and
+    files hashes are taken of. The same bytes as the API's own canonical form for any value the API signs.
+    Raises ValueError for NaN, Infinity or a string holding a lone surrogate (which the API never signs) and
+    TypeError for anything JSON cannot hold. Python ints of any size are written exactly; JavaScript cannot hold
+    integers beyond 2**53, so the Node client's canonical form differs from this one there."""
+    out: list[str] = []
+    _write(value, out)
+    return "".join(out).encode("utf-8")
+
+
+# Webhooks
+
+def _text(value: Any) -> str | None:
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).decode("latin-1")
+    if isinstance(value, (list, tuple)) and all(isinstance(item, str) for item in value):
+        return ",".join(value)
+    return value if isinstance(value, str) else None
+
+
+def _header(headers: Any, name: str) -> str | None:
+    """The first value of the header called name (lower case) in a mapping, or in pairs as an ASGI scope holds them."""
+    pairs: Iterable = headers.items() if hasattr(headers, "items") else headers
+    for key, value in pairs:
+        key = _text(key)
+        if key is not None and key.lower() == name:
+            return _text(value)
+    return None
+
+
+def verify_webhook(secret: str | Sequence[str], raw_body: bytes | str, headers: HeadersLike,
+                   tolerance: float = 300) -> bool:
+    """Whether a webhook delivery is genuine: True when X-OC-Signature holds a v1= HMAC-SHA256 of
+    "{X-OC-Timestamp}.{raw_body}" made with secret (the whole whsec_ string), and the timestamp is within
+    tolerance seconds (default 300) of now. Only the first 8 entries of X-OC-Signature are looked at.
+
+    raw_body is the request body exactly as received, before any JSON parsing (bytes; a str is encoded as
+    UTF-8). headers is the request's headers (Django's, Flask's or FastAPI's request.headers, a dict, or
+    (name, value) pairs), matched case-insensitively. secret may be a list, for while you rotate it on your side; during a rotation on
+    ours the header holds two signatures, and one match is enough. Compared in constant time. Any missing,
+    malformed or wrong input returns False; it never raises."""
+    try:
+        given: list[object] = [secret] if isinstance(secret, str) else list(secret)
+        secrets = [item for item in given if isinstance(item, str) and item]
+        if not secrets or len(secrets) != len(given):
+            return False
+        if isinstance(raw_body, str):
+            raw_body = raw_body.encode("utf-8")
+        if not isinstance(raw_body, (bytes, bytearray, memoryview)):
+            return False
+        timestamp = _header(headers, "x-oc-timestamp")
+        signature = _header(headers, "x-oc-signature")
+        if timestamp is None or signature is None or not _TIMESTAMP.fullmatch(timestamp):
+            return False
+        if not abs(time.time() - int(timestamp)) <= tolerance:  # written so that a NaN tolerance fails
+            return False
+        entries = [value.strip() for value in signature.split(",", MAX_SIGNATURES)[:MAX_SIGNATURES]]
+        values = [value[3:] for value in entries if value.startswith("v1=")]
+        sent = [value.encode("ascii") for value in values if _SIGNATURE.fullmatch(value)]
+        message = timestamp.encode("ascii") + b"." + bytes(raw_body)
+        matched = False
+        for item in secrets:
+            expected = hmac.new(item.encode("utf-8"), message, sha256).hexdigest().encode("ascii")
+            for value in sent:
+                matched |= hmac.compare_digest(expected, value)
+        return matched
+    except Exception:  # bad input of any kind is a failed check, never an error
+        return False
+
+
+# Receipts
+
+def _ed25519():
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    except ImportError:
+        raise ModuleNotFoundError(f"Verifying receipts needs the cryptography package: {RECEIPTS_EXTRA}",
+                                  name="cryptography") from None
+    return Ed25519PublicKey, InvalidSignature
+
+
+def _b64(value: Any) -> bytes:
+    if not isinstance(value, str):
+        raise TypeError("expected base64 text")
+    return base64.b64decode(value, validate=True)
+
+
+def verify_receipt(receipt: Mapping[str, Any] | None,
+                   keys: Sequence[Mapping[str, Any]] | Mapping[str, Any] | None) -> bool:
+    """Whether a receipt's Ed25519 signature is valid: over the canonical JSON of every field but signature, with
+    the key the receipt names in key_id. keys is the published key list, as client.receipt_keys() returns it or the
+    whole {"keys": [...]} document from https://api.onlinecompiler.io/.well-known/receipt-keys.json. No network.
+
+    Returns False for a changed field, an unknown key_id, a malformed signature, None (a submission without a
+    receipt) or any other bad input. Needs the cryptography package: without it this raises ModuleNotFoundError
+    saying what to install."""
+    public_key_class, _invalid_signature = _ed25519()  # outside the try, so a missing extra is never a False
+    try:
+        if isinstance(keys, Mapping):
+            keys = keys["keys"]
+        if not isinstance(receipt, Mapping) or keys is None or isinstance(keys, (str, bytes)):
+            return False
+        key_id = receipt["key_id"]
+        signature = _b64(receipt["signature"])
+        entry = next((key for key in keys if isinstance(key, Mapping) and key.get("key_id") == key_id), None)
+        if entry is None or entry.get("algorithm", "Ed25519") != "Ed25519":
+            return False
+        message = canonical_json({name: value for name, value in receipt.items() if name != "signature"})
+        public_key_class.from_public_bytes(_b64(entry["public_key"])).verify(signature, message)
+    except Exception:  # InvalidSignature, and any bad input (hostile nesting deep enough for RecursionError too)
+        return False
+    return True  # only once verify() has passed

onlinecompiler-0.1.0.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.5
+Name: onlinecompiler
+Version: 0.1.0
+Summary: Python client for the OnlineCompiler.io code execution API: run and judge code in 46 languages in a sandbox
+Project-URL: Homepage, https://onlinecompiler.io
+Project-URL: Documentation, https://onlinecompiler.io/docs
+Project-URL: Pricing, https://onlinecompiler.io/pricing
+Project-URL: Changelog, https://onlinecompiler.io/changelog
+Author: RunCode Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code execution,code judge,compiler api,judge0,online compiler,online judge,onlinecompiler,sandbox,signed receipts,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: receipts
+Requires-Dist: cryptography>=42; extra == 'receipts'
+Description-Content-Type: text/markdown
+
+# OnlineCompiler.io Python client
+
+Run code in 46 languages from Python, or judge it against test cases, through the
+[OnlineCompiler.io](https://onlinecompiler.io/?utm_source=pypi) code execution API. Every run gets a
+fresh gVisor sandbox with no network, 512 MB of memory and a 30-second limit. Free up to 100,000 runs
+a month, commercial use included.
+
+No dependencies beyond the standard library. Python 3.10 or newer. Verifying signed receipts needs
+one optional extra, `pip install "onlinecompiler[receipts]"` (it adds `cryptography`).
+
+```bash
+pip install onlinecompiler
+```
+
+Get a free API key at https://api.onlinecompiler.io/compilers/api-keys/ and set it as
+`ONLINECOMPILER_API_KEY`, or pass it to the client.
+
+## Run a program
+
+```python
+from onlinecompiler import OnlineCompiler
+
+client = OnlineCompiler()  # reads ONLINECOMPILER_API_KEY
+
+result = client.run("python-3.14", "name = input()\nprint(f'Hello, {name}!')", input="Ada")
+print(result["output"])                          # Hello, Ada!
+print(result["exit_code"], result["time"], result["memory"])
+```
+
+The result has `output` (stdout), `error` (stderr or compiler errors), `exit_code`, `signal`, `time`
+and `total` (seconds), `memory` (KB), `truncated`, `time_limit` and `files`. `time`, `total` and
+`memory` are decimal strings, as the API sends them. Compiler ids such as `gcc-15`, `openjdk-25` and
+`nodejs-24` come from `client.compilers()`. Pass `time_limit` (seconds, up to 30) to stop a run sooner.
+
+## Judge a solution against test cases
+
+```python
+result = client.run_tests(
+    "python-3.14",
+    "a, b = map(int, input().split())\nprint(a + b)",
+    tests=[
+        {"input": "1 2", "expected_output": "3"},
+        {"input": "10 20", "expected_output": "30", "hidden": True},
+    ],
+)
+print(result["verdict"], result["score"], f"{result['passed']}/{result['total']}")
+for case in result["tests"]:
+    print(case["verdict"])
+```
+
+Each test counts as one run. Hidden tests return only their verdict. `checker` picks how output is
+compared (`trim` by default, `exact`, `tokens`, `float` or `rows`), `scoring` is `all_or_nothing`
+(default), `percent` or `weighted` (with a `weight` per test), and `time_limit` is seconds per test
+(default 2). See the [run-tests docs](https://onlinecompiler.io/docs/run-tests?utm_source=pypi).
+
+Every run-tests result also has `summary` (the result in plain words), `submission` (its id) and a
+signed `receipt`.
+
+## Judge in the background
+
+```python
+queued = client.run_tests(
+    "python-3.14",
+    "a, b = map(int, input().split())\nprint(a + b)",
+    tests=[{"input": "1 2", "expected_output": "3"}, {"input": "10 20", "expected_output": "30", "hidden": True}],
+    async_=True,
+    external_ref="attempt-4821",
+    idempotency_key="attempt-4821",
+)
+done = client.wait_for_submission(queued["submission"])  # looks it up every 2 seconds
+result = done["result"]  # None when it failed, which means it was not judged
+if result is not None:
+    print(result["verdict"], result["score"])
+else:
+    print("Not judged:", done["error"])  # send it again
+client.delete_submission(done["submission"])  # optional: drop the stored code and output
+```
+
+`async_=True` (`async` is a Python keyword) answers at once with the submission id, and the submission
+waits in your account's queue instead of getting 429 in a burst. Add `callback_url` to have the result
+POSTed to your server as a signed webhook (see below); it needs `async_=True`, and the client refuses it
+without. `external_ref` is your own id, signed into the receipt; `metadata` is any JSON object, returned in
+lookups and webhooks. `idempotency_key` (1 to 100 printable ASCII characters, checked before sending) is
+sent as the `Idempotency-Key` header, so a retry after a timeout answers with the original result instead
+of running again. `client.submission(id)` looks a submission up once.
+
+## Judge against a stored problem
+
+A stored problem keeps its tests, checker and limits on the server, so you send only the candidate's
+code and the hidden tests never leave it.
+
+```python
+client.create_problem({
+    "title": "Sum of two numbers",
+    "slug": "sum",
+    "languages": ["python-3.14"],
+    "tests": [
+        {"name": "sample", "input": "1 2\n", "expected_output": "3\n", "hidden": False},
+        {"input": "5 7\n", "expected_output": "12\n"},  # tests are hidden unless you say otherwise
+    ],
+})
+client.publish_problem("sum")  # no reference solution, so it is published at once
+
+result = client.judge("sum", "python-3.14", "a, b = map(int, input().split())\nprint(a + b)")
+print(result["verdict"], result["score"], result["problem"], result["version"])
+```
+
+`judge` takes the problem's id (`prob_...`) or your slug for it. `mode="samples"` judges only the
+visible tests, and `async_`, `callback_url`, `external_ref`, `metadata` and `idempotency_key` work as
+above. Problems are plain dicts, as the
+[stored problems docs](https://onlinecompiler.io/docs/problems?utm_source=pypi) describe them:
+`problems()`, `problem()`, `create_problem()`, `update_problem()`, `replace_draft()`,
+`publish_problem()`, `archive_problem()`, `restore_problem()` and `public_problem()`.
+
+## Sessions for the widget
+
+A session lets one candidate's [embedded editor](https://onlinecompiler.io/docs/widget?utm_source=pypi)
+Submit to a stored problem without your API key ever reaching the browser. Create it on your server and
+put only its token in the page:
+
+```python
+problem_id = client.problem("sum")["problem"]  # the widget takes the id, never the slug
+session = client.create_session(problem_id, "attempt-4821", max_submits=2, expires_in=3600)
+
+html = (f'<div class="runcode" data-key="YOUR_WIDGET_KEY" data-problem="{problem_id}" '
+        f'data-session="{session["token"]}"></div>\n'
+        '<script src="https://onlinecompiler.io/widget.js"></script>')
+```
+
+The token is shown only this once and the client never logs it or puts it in an error, so keep it out
+of your own logs too. `external_ref` should be an opaque id: the candidate's page sees it. Record the
+score from the webhook or `client.submission(id)`, never from the browser.
+`client.session(problem_id, session["session"])` shows the Submits used and the submission ids, and
+`client.revoke_session(problem_id, session["session"])` ends it at once.
+
+## Verify webhooks
+
+An async submission with a `callback_url` (or a callback URL on the API key) gets one signed
+`submission.finished` event. Check it before you trust it.
+
+Verify the raw request body exactly as received: a body that was parsed and serialized again never
+matches. In Flask that is `request.get_data()`, in Django `request.body`, in FastAPI
+`await request.body()`.
+
+```python
+import os
+
+from flask import Flask, abort, request
+from onlinecompiler import verify_webhook
+
+app = Flask(__name__)
+SECRET = os.environ["ONLINECOMPILER_WEBHOOK_SECRET"]  # whsec_..., shown with the API key in your dashboard
+
+@app.post("/hooks/oc")
+def webhook():
+    if not verify_webhook(SECRET, request.get_data(), request.headers):
+        abort(400)
+    event = request.get_json()
+    print(event["submission"], event["status"], event["result"] and event["result"]["verdict"])
+    return "", 204  # answer quickly; deduplicate on event["delivery"]
+```
+
+`verify_webhook(secret, raw_body, headers, tolerance=300)` needs no client and no network. It takes any
+mapping of headers (Django's, Flask's, FastAPI's or a dict), compares in constant time, accepts either
+signature while a secret is being rotated, takes a list of secrets while you rotate yours, and rejects a
+timestamp more than `tolerance` seconds (default 300) from now. Anything missing or malformed returns
+`False`. See the [webhooks docs](https://onlinecompiler.io/docs/webhooks?utm_source=pypi).
+
+## Verify receipts
+
+Every judged submission comes with a receipt signed with Ed25519: proof of what ran, against which
+tests, and what came out. Anyone can check it with the published keys.
+
+```bash
+pip install "onlinecompiler[receipts]"
+```
+
+```python
+from onlinecompiler import verify_receipt
+
+receipt = client.submission("sub_8f2Kq7LmT3xR9vWb1cYd4hNe")["receipt"]
+print(client.verify_receipt(receipt))  # fetches the published keys once, no API key needed
+
+keys = client.receipt_keys()           # or save them and verify offline later
+print(verify_receipt(receipt, keys))   # False once any field has been changed
+```
+
+Both return `False` for `None`, which a submission that was not judged has as its receipt. Without the
+extra, verifying raises an error that says what to install. Store and deduplicate receipts by their
+`submission` id (or the whole receipt), not by the signature string. `canonical_json(value)` returns
+the canonical bytes receipts are signed over, for reproducing their hashes as the
+[receipts docs](https://onlinecompiler.io/docs/receipts?utm_source=pypi) describe.
+
+## Files in and out
+
+```python
+import base64
+
+code = """
+import pandas as pd
+import matplotlib.pyplot as plt
+df = pd.read_csv("sales.csv")
+df.plot(x="month", y="units")
+plt.show()   # saved as figure-1.png in $OUTPUT_DIR
+"""
+result = client.run("python-3.14", code, files=[{"name": "sales.csv", "content": open("sales.csv").read()}])
+for f in result["files"]:
+    with open(f["name"], "wb") as out:
+        out.write(base64.b64decode(f["content_base64"]))
+```
+
+Input files sit in the program's working directory; send binary ones with `"encoding": "base64"`.
+Files the program writes to `$OUTPUT_DIR` come back in `files`.
+
+## Queue runs and get results by callback
+
+```python
+queued = client.submit("g++-15", source, input="3\n", extra_params={"submission_id": 981})
+print(queued["id"])
+```
+
+`submit` returns at once. When the run finishes, its result is POSTed to the callback URL set on your
+API key in the dashboard, with your `extra_params` echoed back.
+
+## Other calls
+
+- `client.compilers()`: every compiler id and language name (no key needed).
+- `client.usage()`: this month's runs and what's left, for the account and for the key.
+- `client.limits()`: per-run limits and default account limits (no key needed).
+
+## Errors
+
+```python
+from onlinecompiler import OnlineCompilerError, RateLimitError
+
+try:
+    client.run("python-3.14", "print(1)")
+except RateLimitError as e:          # HTTP 429
+    print(e.message)                 # which limit was hit, and how to raise it
+except OnlineCompilerError as e:     # anything else, including AuthenticationError
+    print(e.status, e.message)       # status is 0 when the API could not be reached
+```
+
+`AuthenticationError` covers a missing, unknown or unauthorized key; `NotFoundError` a submission,
+problem or session that does not exist or is not yours. A conflict, such as an archived problem or an
+`Idempotency-Key` reused with another body, is an `OnlineCompilerError` with status 409 and the API's
+message.
+
+The client never retries a request by itself, because every run the API accepts counts toward your
+allowance. `OnlineCompiler(api_key=None, *, base_url="https://api.onlinecompiler.io", timeout=90.0)`
+takes the key, the API address and a timeout in seconds.
+
+## Links
+
+[Docs](https://onlinecompiler.io/docs?utm_source=pypi) ·
+[Languages](https://onlinecompiler.io/languages?utm_source=pypi) ·
+[Limits](https://onlinecompiler.io/docs/limits?utm_source=pypi) ·
+[Pricing](https://onlinecompiler.io/pricing?utm_source=pypi) ·
+[Security](https://onlinecompiler.io/security?utm_source=pypi) ·
+[Changelog](https://onlinecompiler.io/changelog?utm_source=pypi)
+
+MIT licensed. OnlineCompiler.io is a product of RunCode Inc.

onlinecompiler-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+onlinecompiler/__init__.py,sha256=MLAxBiuLqizMyRK_qewa_pN7azVU0Eg4w1vOgmE4MpM,1329
+onlinecompiler/_client.py,sha256=o6xLIS2EFXVFFJjymRdGlf2BfWCVcM02BdSMJQ98UMo,28897
+onlinecompiler/_verify.py,sha256=tEVxpKtFRsAHzD85pFyQ6YQOOX96_maqEc4FXvVMA70,9522
+onlinecompiler/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onlinecompiler-0.1.0.dist-info/METADATA,sha256=RJoUm1uPP_KIyvG40crStoFpOmZZ-gzyNVrzy9Kjz4s,12526
+onlinecompiler-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+onlinecompiler-0.1.0.dist-info/licenses/LICENSE,sha256=ewJ8Ho-t36T048PVcYWDREgjhelKO_i5q2cH8pafvU0,1069
+onlinecompiler-0.1.0.dist-info/RECORD,,

onlinecompiler-0.1.0.dist-info/WHEEL

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

onlinecompiler-0.1.0.dist-info/licenses/LICENSE

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