Overview

The Judge0 Python SDK has two layers:

  • a high-level API that creates submissions, expands test cases, batches requests, and optionally waits for results;

  • a low-level API on Client that maps one-to-one to Judge0 HTTP routes.

Most applications should start with judge0.run(). Use the client methods when you need a single HTTP call, custom polling, or server metadata.

High-level and low-level API

High-level functions live in judge0.api. The entry-point functions (judge0.run(), judge0.async_run(), judge0.wait(), and judge0.get_client()) are re-exported from the judge0 package. They accept either source code, a Submission, or a sequence of submissions. If you omit client, the SDK resolves one from the environment. See Client Resolution.

Function

Role

judge0.run() / judge0.execute() / judge0.sync_run()

Create submission(s) and wait until they finish. These names are aliases of judge0.api.sync_execute().

judge0.async_run() / judge0.async_execute()

Create submission(s) and return immediately. These are not asyncio coroutines.

judge0.wait()

Poll existing submission(s) until they finish or the retry strategy stops.

judge0.get_client()

Resolve the implicit client for CE (Flavor.CE) or Extra CE (Flavor.EXTRA_CE).

judge0.api.create_submissions()

Send already-built submissions, splitting them into batches that fit the server limit.

judge0.api.get_submissions()

Refresh status and result fields on existing submissions.

judge0.api.create_submissions_from_test_cases()

Expand one or more submissions across test cases. Used internally by judge0.run().

The low-level API is the methods on Client:

Low-level calls do not wait for execution, do not expand test cases, and do not pick a client for you. create_submissions and get_submissions on the client cannot send more items than client.config.max_submission_batch_size. The high-level helpers batch automatically.

async_run versus run

judge0.run() blocks until Judge0 reports a terminal status or the client’s retry strategy is exhausted, which may return a queued or processing submission. judge0.async_run() only creates the submission(s) and returns the submission objects with their token fields populated. Call judge0.wait() later, or poll with judge0.api.get_submissions().

import judge0

submission = judge0.async_run(source_code="print('hello, world')")
print(submission.stdout)  # None; the job is not finished yet.

judge0.wait(submissions=submission)
print(submission.stdout)  # hello, world

Important classes

  • Client: HTTP client for one Judge0 server. Provider subclasses include Judge0CloudCE, RapidJudge0CE, and ATDJudge0CE, plus the Extra CE variants.

  • Submission: request and response for one program run. Set source_code, language, stdin, and optional limits before sending. After execution, read stdout, stderr, status, time, and memory.

  • TestCase: pair of input and expected_output. judge0.run() also accepts tuples, lists, and dicts and normalizes them to this type.

  • LanguageAlias and Flavor: language aliases such as judge0.PYTHON or judge0.C, and the CE / Extra CE flavors used for client resolution.

  • Status: submission status, including Accepted, compile errors, and runtime errors.

  • File and Filesystem: extra files sent with a submission, or files produced after execution.

  • RegularPeriodRetry, MaxRetries, and MaxWaitTime: polling strategies used by judge0.wait().

Typical flow

  1. Build source code or a Submission.

  2. Optionally attach test cases or extra files.

  3. Call judge0.run(), or judge0.async_run() plus judge0.wait().

  4. Inspect stdout, status, and other result fields.

import judge0

result = judge0.run(
    source_code="print(f'Hello, {input()}!')",
    language=judge0.PYTHON,
    test_cases=[
        ("Ada", "Hello, Ada!"),
        {"input": "Bob", "expected_output": "Hello, Bob!"},
    ],
)

for case in result:
    print(case.status, case.stdout)

Pass an explicit client when you do not want implicit resolution:

import judge0

client = judge0.RapidJudge0CE(api_key="xxx")
result = judge0.run(client=client, source_code="print(42)")
print(result.stdout)

For the full parameter lists, see the API Module reference, the Clients Module reference, and the Submission Module reference.