Package piston_rspy

piston_rspy - Python bindings for piston_rs.

Classes

class Client

–

A client used to send requests to Piston.

NOTE:

• The client is immutable, and by extension its properties are also immutable.

Static methods

def with_key(key: str, /) ‑> Client

–

Creates a new client, with an api key.

Args:

• key str: The api key to use.

Returns:

• Client: The new client.

def with_url(key: str, /) ‑> Client

–

Creates a new Client with a custom url.

Args:

• url str: The url to use as the underlying piston backend.

Returns:

• Client: The new client.

def with_url_and_key(key: str, /) ‑> Client

–

Creates a new Client with a custom url and an api key.

Args:

• url str: The url to use as the underlying piston backend.

• key str: The api key to use.

Returns:

• Client: The new client.

Instance variables

var headers

dict[str, str]: The headers being sent with requests.

var url

str: The base url for the Piston v2 api.

Methods

def execute(self, executor: Executor, /) ‑> ExecResponse

–

async: Executes code using a given executor. This is an http request.

Args:

• executor Executor: The executor to use for the request.

Returns:

• ExecResponse: The response from Piston.

Raises:

• RuntimeError: If the request to Piston failed.

def fetch_runtimes(self) ‑> list[Runtime]

–

async: Fetches the runtimes from Piston. This is an http request.

Returns:

• list[Runtime]: The available Piston runtimes.

Raises:

• RuntimeError: If the request to Piston failed.

class ExecResponse (...)

A response from the Piston api when sending a request to execute code.

NOTE:

• This object cannot be instantiated, and is immutable.
• It can only be created with a call to Client.execute().

Instance variables

var compile

ExecResult | None: The optional result Piston sends detailing compilation. This will be None for non-compiled languages.

var language

str: The language that was used.

var run

ExecResult: The result Piston sends detailing execution.

var status

int: The response status returned by Piston.

var version

str: The version of the language that was used.

Methods

def is_err(self) ‑> bool

–

Whether or not the request to Piston failed.

Returns:

• bool: True if a non 200 status code was received.

def is_ok(self) ‑> bool

–

Whether or not the request to Piston succeeded.

Returns:

• bool: True if a 200 status code was received.

class ExecResult (...)

The result of code execution returned by Piston.

NOTE:

• This object cannot be instantiated, and is immutable.
• It can only be created with a call to Client.execute().

Instance variables

var code

int | None: The optional exit code returned by the process.

var output

str: The text sent to both stdout, and stderr during execution.

var signal

str | None: The optional signal sent to the process. (SIGKILL etc)

var stderr

str: The text sent to stderr during execution.

var stdout

str: The text sent to stdout during execution.

Methods

def is_err(self) ‑> bool

–

Whether or not the execution produced errors.

Returns:

• bool: True if the execution returned a non zero exit code.

def is_ok(self) ‑> bool

–

Whether or not the execution was ok.

Returns:

• bool: True if the execution returned a zero exit code.

class Executor (language: str = '', version: str = '*', files: list[File] = [], stdin: str = '', args: list[str] = [], compile_timeout: int = 10000, run_timeout: int = 3000, compile_memory_limit: int = -1, run_memory_limit: int = -1, /)

–

An object containing information about the code being executed.

A convenient builder flow is provided by the methods associated with the Executor. These consume self and return self for chained calls.

• For compile_memory_limit and run_memory_limit -1 can be used to signify no limit.

Instance variables

var args

list[str]: The command line arguments to pass to the program.

var compile_memory_limit

int: The maximum allowed memory usage for compilation in bytes.

var compile_timeout

int: The maximum allowed time for compilation in milliseconds.

var files

list[File]: A list of files to send to Piston. The first file in the list is considered the main file.

var language

str: The language to use for execution.

var run_memory_limit

int: The maximum allowed memory usage for execution in bytes.

var run_timeout

int: The maximum allowed time for execution in milliseconds.

var stdin

str: The text to pass as stdin to the program.

var version

str: The version of the language to use for execution.

Methods

def add_arg(self, arg: str, /) ‑> Executor

–

Adds an arg to be passed as a command line argument.

Does not overwrite any existing args.

Args:

• arg str: The arg to add.

Returns:

• Executor: The executor, for chained method calls.

def add_args(self, args: list[str], /) ‑> Executor

–

Adds multiple args to be passed as a command line argument.

Does not overwrite any existing args.

Args:

• args list[str]: The args to add.

Returns:

• Executor: The executor, for chained method calls.

def add_file(self, file: File, /) ‑> Executor

–

Adds a File containing the code to be executed.

Does not overwrite any existing files.

Args:

• file File: The file to add.

Returns:

• Executor: The executor, for chained method calls.

def add_files(self, files: list[File], /) ‑> Executor

–

Adds multiple File's containing code to be executed.

Does not overwrite any existing files.

Args:

• files list[File]: The file to add.

Returns:

• Executor: The executor, for chained method calls.

def copy(self) ‑> Executor

–

Copies the executor, leaving the existing one unchanged.

Returns:

• Executor: A copy of the executor.

def reset(self)

–

Resets the executor back to a new state, ready to be configured again and sent to Piston after metadata is added.

This method mutates the executor in place.

def set_args(self, args: list[str], /)

–

Adds multiple args to be passed as command line arguments.

This method mutates the executor in place. Overwrites any existing args.

Args:

• args list[str]: The args to replace existing args with.

def set_compile_memory_limit(self, limit: int, /) ‑> Executor

–

Sets the maximum allowed memory usage for compilation in bytes.

Args:

• limit int: The limit to set.

Returns:

• Executor: The executor, for chained method calls.

def set_compile_timeout(self, timeout: int, /) ‑> Executor

–

Sets the maximum allowed time for compilation in milliseconds.

Args:

• timeout int: The timeout to set.

Returns:

• Executor: The executor, for chained method calls.

def set_files(self, files: list[File], /)

–

Adds multiple File's containing the code to be executed.

This method mutates the executor in place. Overwrites any existing files.

Args:

• files list[File]: The files to replace existing files with.

def set_language(self, language: str, /) ‑> Executor

–

Sets the language to use for execution.

Args:

• language str: The language to use.

Returns:

• Executor: The executor, for chained method calls.

def set_run_memory_limit(self, limit: int, /) ‑> Executor

–

Sets the maximum allowed memory usage for execution in bytes.

Args:

• limit int: The limit to set.

Returns:

• Executor: The executor, for chained method calls.

def set_run_timeout(self, timeout: int, /) ‑> Executor

–

Sets the maximum allowed time for execution in milliseconds.

Args:

• timeout int: The timeout to set.

Returns:

• Executor: The executor, for chained method calls.

def set_stdin(self, stdin: str, /) ‑> Executor

–

Sets the text to pass as stdin to the program.

Args:

• stdin str: The text to set.

Returns:

• Executor: The executor, for chained method calls.

def set_version(self, version: str, /) ‑> Executor

–

Sets the version of the language to use for execution.

Args:

• version str: The version to use.

Returns:

• Executor: The executor, for chained method calls.

class File (name: str = '', content: str = '', encoding: str = 'utf8', /)

–

A file that contains the source code to be executed.

Instance variables

var content

str: Required by Piston The content of the file.

var encoding

str: The encoding of the file.

var name

str: The name of the file.

Methods

def copy(self) ‑> File

–

Copies the file, leaving the existing one unchanged.

Returns:

• File: A copy of the file.

def load_content_from(self, path: str, /) ‑> File

–

Sets the content of the file to the contents of an existing file on disk.

Args:

• path str: The path to the file.

Returns:

• File: The file, for chained method calls.

def load_from(cls, path: str, /) ‑> File

–

Creates a new File from an existing file on disk.

Args:

• path str: The path to the file.

Returns:

• File: The new file.

def set_content(self, content: str, /) ‑> File

–

Sets the content of the file.

Args:

• content str: The content to use.

Returns:

• File: The file, for chained method calls.

def set_encoding(self, encoding: str, /) ‑> File

–

Sets the encoding of the file.

Args:

• encoding str: The encoding to use.

Returns:

• File: The file, for chained method calls.

def set_name(self, name: str, /) ‑> File

–

Sets the name of the file.

Args:

• name str: The name to use.

Returns:

• File: The file, for chained method calls.

class Runtime (language: str, version: str, aliases: list[str], /)

–

A runtime available to be used by Piston.

Note:

Runtimes are not meant to be created manually. Instead, they should be fetched from Piston using Client.fetch_runtimes() and stored. The Python bindings for piston_rs do allow you to instantiate the class, however.

Instance variables

var aliases

list[str]: The aliases of the language.

var language

str: The language.

var version

str: The version of the language.

Methods

def copy(self) ‑> Runtime

–

Copies the runtime, leaving the existing one unchanged.

Returns:

• Runtime: A copy of the runtime.