At minimum, a Session requires a Core, an AudioDriver, an InputDriver, and a VideoDriver; each with_ method sets an argument (mostly drivers) for the Session.

__init__()[source]¶

Initialize a new SessionBuilder with no arguments, not even the required ones.

Calling build() before setting any of the required arguments will raise a RequiredError.

classmethod defaults(core)[source]¶

Alias to defaults().

Return type:: SessionBuilder

with_core(core)[source]¶

Set the core to use for the session.

Parameters:

The core to use for the session. May be one of the following:

Core: Will be used as-is.
str, PathLike: Will load a Core from this path in build().
CDLL: Will load a Core from this library in build().
Callable () -> Core: Zero-argument function that returns a Core. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If core is not one of the permitted types.

with_content(content)[source]¶

Set the content to use for this session.

Will be loaded and managed by this builder’s assigned ContentDriver.

Parameters:

content (TypeAliasType) –

The content to use for this session. May be one of the following:

str, PathLike: Will load a single content file without enabling a subsystem.
zipfile.Path: Will load a single content file within a ZIP archive without enabling a subsystem.
bytes, bytearray, memoryview, Buffer: Will expose a single unnamed content buffer without enabling a subsystem.
SubsystemContent: Will enable a subsystem and load multiple associated content files.
retro_game_info: Will be passed to the core as-is without enabling a subsystem.
None: Will load the core without using any content or enabling a subsystem; if not supported by the core, this will raise an error in build(). Note that retro_load_game will be called.
Callable () -> Content | SubsystemContent | None: Zero-argument function that returns one of the above. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If content is not one of the permitted types.

See:

ContentDriver.load() for details on how loaded content is exposed to the core.

with_audio(audio)[source]¶

Set the audio driver for this session.

Parameters:

audio (TypeAliasType) –

The audio driver to use for this session. May be one of the following:

AudioDriver: Will be used by the built Session as-is.
DEFAULT: Will use an ArrayAudioDriver with its default configuration.
Callable () -> AudioDriver: Zero-argument function that returns an AudioDriver. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If audio is not one of the permitted types.
ValueError – If audio is None.

with_input(input)[source]¶

Set the input driver for this session.

Parameters:

input (TypeAliasType) –

The input driver to use for this session. May be one of the following:

InputDriver: Will be used by the built Session as-is.
Generator, Iterable, Iterator: Will be wrapped in an IterableInputDriver that yields InputPollResult values.
DEFAULT: Will use an IterableInputDriver with its default configuration.
Callable () -> InputDriver | iterable: Zero-argument function that returns either an InputDriver or an iterable/iterator/generator of InputPollResult values. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If input (or the value returned by a callable input) is not one of the permitted types.
ValueError – If input is None.

with_rumble(rumble)[source]¶

Configure the rumble driver for this session’s input driver.

Parameters:

rumble (TypeAliasType) –

The rumble driver to use for this session. May be one of the following:

RumbleDriver: Will be used by the built Session as-is.
None: No rumble driver will be used, and any rumble interfaces that the core exposes will not function.
DEFAULT: Will use a DictRumbleDriver with no initial state.
Callable () -> RumbleDriver | None: Zero-argument function that returns a RumbleDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If rumble is not one of the aforementioned types.

with_video(video)[source]¶

Set the video driver for this session.

Parameters:

video (TypeAliasType) –

The video driver to use for this session. May be one of the following:

VideoDriver: Used by the built Session as-is.
DEFAULT: Uses a MultiVideoDriver with its default configuration. See its documentation for more details.
Mapping [HardwareContext, Callable () -> VideoDriver]: Uses a MultiVideoDriver with the provided driver map.
Callable () -> VideoDriver: Zero-argument function that returns a VideoDriver. Called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If video is not one of the aforementioned types.
ValueError – If video does not contain a mapping for HardwareContext.NONE.

with_content_driver(content)[source]¶

Set the content driver for this session.

Parameters:

content (TypeAliasType) –

The content driver to use for this session. May be one of the following:

ContentDriver: Will be used by the built Session as-is.
DEFAULT: Will use a StandardContentDriver with its default configuration.
None: No content driver will be used; content set via with_content() will not be loaded.
Callable () -> ContentDriver | None: Zero-argument function that returns a ContentDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If content is not one of the permitted types.

with_overscan(overscan)[source]¶

Set whether the loaded core should render overscan regions.

Parameters:

overscan (TypeAliasType) –

The overscan flag to expose to the core. May be one of the following:

bool: Will be reported to the core as-is.
DEFAULT: Reports False to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> bool | None: Zero-argument function that returns a bool or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If overscan is not one of the permitted types.

with_message(message)[source]¶

Set the message driver for this session.

Parameters:

message (TypeAliasType) –

The message driver to use for this session. May be one of the following:

MessageDriver: Will be used by the built Session as-is.
Logger: Will be wrapped in a LoggerMessageDriver that forwards messages to the given logger.
DEFAULT: Will use a LoggerMessageDriver with its default configuration.
None: The environment calls that MessageDriver normally implements will be unavailable to the loaded Core.
Callable () -> MessageDriver | None: Zero-argument function that returns a MessageDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If message is not one of the permitted types.

with_options(options)[source]¶

Configure the options driver for this session.

Parameters:

options (TypeAliasType) –

May be one of the following:

OptionDriver: Will be used by the built Session as-is.
Mapping [AnyStr, AnyStr]: Will be used to initialize a DictOptionDriver with the provided options and with API version 2. All keys and values must be either str or bytes; mixing the two is not allowed.
0, 1, or 2: Will be used to initialize a DictOptionDriver with no initial options using the provided API version.
DEFAULT: Will use a DictOptionDriver with API version 2 and no initial options.
None: All environment calls that OptionDriver normally implements will be unavailable to the loaded Core.
Callable () -> OptionDriver | None: Zero-argument function that returns an OptionDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If options is not one of the aforementioned types.
ValueError – If options is a Mapping whose keys and values are not all str or bytes.

with_paths(path)[source]¶

Configure the path driver for this session.

Parameters:

path (TypeAliasType) –

May be one of the following:

PathDriver: Will be used by the built Session as-is.
DEFAULT: Will use a TempDirPathDriver configured with an unspecified temporary directory and the provided Core’s path.
Callable (Core) -> PathDriver | None: One-argument function that accepts a Core and returns a PathDriver or None. Will be called in build() with the configured Core as the argument.
None: All environment calls that PathDriver normally implements will be unavailable to the loaded Core.

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If path is not one of the aforementioned types.

with_sensor(sensor)[source]¶

Configure the sensor driver for this session.

Parameters:

sensor (TypeAliasType) –

May be one of the following:

SensorDriver: Will be used by the built Session as-is.
None: All environment calls and interfaces that SensorDriver normally implements will be unavailable to the loaded Core.
DEFAULT: Will use an IterableSensorDriver whose sensor state can be configured, but does not produce any nonzero readings.
Callable () -> SensorDriver: Zero-argument function that returns the SensorDriver that the built Session will use.
Callable () -> Iterable | Iterator: Zero-argument function that returns an iterator or generator that yields elements as described in IterableSensorDriver. An IterableSensorDriver will be created from this iterator.
Iterable | Iterator: An iterator, iterable, or generator function that yields elements as described in IterableSensorDriver. An IterableSensorDriver will be created from this iterator.

Return type:

Self

Returns:

This SessionBuilder object.

with_log(log)[source]¶

Set the log driver for this session.

Parameters:

log (TypeAliasType) –

The log driver to use for this session. May be one of the following:

LogDriver: Will be used by the built Session as-is.
Logger: Will be wrapped in an UnformattedLogDriver that forwards core log messages to the given logger.
DEFAULT: Will use an UnformattedLogDriver with its default configuration.
None: The log interface will be unavailable to the loaded Core.
Callable () -> LogDriver | None: Zero-argument function that returns a LogDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If log is not one of the permitted types.

with_perf(perf)[source]¶

Set the performance driver for this session.

Parameters:

perf (TypeAliasType) –

The performance driver to use for this session. May be one of the following:

PerfDriver: Will be used by the built Session as-is.
DEFAULT: Will use a DefaultPerfDriver with its default configuration.
None: The performance interface will be unavailable to the loaded Core.
Callable () -> PerfDriver | None: Zero-argument function that returns a PerfDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If perf is not one of the permitted types.

with_location(location)[source]¶

Set the location driver for this session.

Parameters:

location (TypeAliasType) –

The location driver to use for this session. May be one of the following:

LocationDriver: Will be used by the built Session as-is.
DEFAULT: No location driver will be used; equivalent to passing None.
None: The location interface will be unavailable to the loaded Core.
Callable () -> LocationDriver | None: Zero-argument function that returns a LocationDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If location is not one of the permitted types.

with_user(user)[source]¶

Set the user driver for this session.

Parameters:

user (TypeAliasType) –

The user driver to use for this session. May be one of the following:

UserDriver: Will be used by the built Session as-is.
DEFAULT: Will use a DefaultUserDriver with its default configuration.
None: The environment calls that UserDriver normally implements will be unavailable to the loaded Core.
Callable () -> UserDriver | None: Zero-argument function that returns a UserDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If user is not one of the permitted types.

with_vfs(vfs)[source]¶

Set the virtual filesystem driver for this session.

Parameters:

vfs (TypeAliasType) –

The filesystem driver to use for this session. May be one of the following:

FileSystemDriver: Will be used by the built Session as-is.
1, 2, or 3: Will use a DefaultFileSystemDriver with the given API version.
DEFAULT: Will use a DefaultFileSystemDriver with its default configuration.
None: The VFS interface will be unavailable to the loaded Core.
Callable () -> FileSystemDriver | None: Zero-argument function that returns a FileSystemDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If vfs is not one of the permitted types.

with_led(led)[source]¶

Set the LED driver for this session.

Parameters:

led (TypeAliasType) –

The LED driver to use for this session. May be one of the following:

LedDriver: Will be used by the built Session as-is.
DEFAULT: Will use a DictLedDriver with its default configuration.
None: The LED interface will be unavailable to the loaded Core.
Callable () -> LedDriver | None: Zero-argument function that returns a LedDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If led is not one of the permitted types.

with_av_mask(av_mask)[source]¶

Set the audio/video enable mask for this session.

Parameters:

av_mask (TypeAliasType) –

The AvEnableFlags to expose to the core. May be one of the following:

AvEnableFlags: Will be reported to the core as-is.
DEFAULT: Reports AvEnableFlags.ALL to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> AvEnableFlags | None: Zero-argument function that returns an AvEnableFlags or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If av_mask is not one of the permitted types.

with_midi(midi)[source]¶

Set the MIDI driver for this session.

Parameters:

midi (TypeAliasType) –

The MIDI driver to use for this session. May be one of the following:

MidiDriver: Will be used by the built Session as-is.
DEFAULT: Will use a GeneratorMidiDriver with its default configuration.
None: The MIDI interface will be unavailable to the loaded Core.
Callable () -> MidiDriver | None: Zero-argument function that returns a MidiDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If midi is not one of the permitted types.

with_timing(timing)[source]¶

Set the timing driver for this session.

Parameters:

timing (TypeAliasType) –

The timing driver to use for this session. May be one of the following:

TimingDriver: Will be used by the built Session as-is.
DEFAULT: Will use a DefaultTimingDriver running unblocked at 60 FPS.
None: The corresponding environment calls will be unavailable to the core.
Callable () -> TimingDriver | None: Zero-argument function that returns a TimingDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If timing is not one of the permitted types.

with_preferred_hw(hw)[source]¶

Set the preferred hardware context to report to the core.

Parameters:

hw (TypeAliasType) –

The preferred hardware context to expose to the core. May be one of the following:

HardwareContext: Will be reported to the core as-is.
DEFAULT: The corresponding environment call will be unavailable to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> HardwareContext | None: Zero-argument function that returns a HardwareContext or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If hw is not one of the permitted types.

with_driver_switch_enable(enable)[source]¶

Set whether the core may switch hardware rendering drivers at runtime.

Parameters:

enable (TypeAliasType) –

The driver-switch flag to expose to the core. May be one of the following:

bool: Will be reported to the core as-is.
DEFAULT: Reports False to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> bool | None: Zero-argument function that returns a bool or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If enable is not one of the permitted types.

with_savestate_context(context)[source]¶

Set the savestate context to report to the core.

Parameters:

context (TypeAliasType) –

The SavestateContext to expose to the core. May be one of the following:

SavestateContext: Will be reported to the core as-is.
DEFAULT: Reports SavestateContext.NORMAL to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> SavestateContext | None: Zero-argument function that returns a SavestateContext or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If context is not one of the permitted types.

with_jit_capable(capable)[source]¶

Set whether the host environment is JIT-capable.

Parameters:

capable (TypeAliasType) –

The JIT-capable flag to expose to the core. May be one of the following:

bool: Will be reported to the core as-is.
DEFAULT: Reports True to the core.
None: The corresponding environment call will be unavailable to the core.
Callable () -> bool | None: Zero-argument function that returns a bool or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If capable is not one of the permitted types.

with_mic(mic)[source]¶

Set the microphone driver for this session.

Parameters:

mic (TypeAliasType) –

The microphone driver to use for this session. May be one of the following:

MicrophoneDriver: Will be used by the built Session as-is.
DEFAULT: Will use a GeneratorMicrophoneDriver with its default configuration.
None: The microphone interface will be unavailable to the loaded Core.
Callable () -> MicrophoneDriver | None: Zero-argument function that returns a MicrophoneDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If mic is not one of the permitted types.

with_power(power)[source]¶

Set the power driver for this session.

Parameters:

power (TypeAliasType) –

The power driver to use for this session. May be one of the following:

PowerDriver: Will be used by the built Session as-is.
retro_device_power: Will be wrapped in a ConstantPowerDriver that always reports this state.
DEFAULT: Will use a ConstantPowerDriver reporting a fully charged, plugged-in device.
None: The power interface will be unavailable to the loaded Core.
Callable () -> PowerDriver | None: Zero-argument function that returns a PowerDriver or None. Will be called in build().

Return type:

Self

Returns:

This SessionBuilder object.

Raises:

TypeError – If power is not one of the permitted types.

build()[source]¶

Construct a Session with the provided arguments.

Raises:

RequiredError – If a Core, AudioDriver, InputDriver, or VideoDriver is not set.
Exception – Any exception raised by a registered driver factory or initializer.

Return type:

TypeAliasType

Returns:

A Session object.

static __new__(*args, **kwargs)¶

DEFAULT = _DefaultType.DEFAULT¶: A placeholder that indicates the default value for one of SessionBuilder’s arguments. When passed to one of SessionBuilder’s with_ methods, it will use the default driver or argument configuration unless otherwise noted.

defaults(core)[source]¶

Construct a SessionBuilder with the recommended drivers and their default values.

Does not build the session, so these defaults may still be overridden.

Parameters:: core (Core | str | PathLike[str] | PathLike[bytes] | CDLL | GenericAlias[Core]) – The core to use for the session.
Return type:: SessionBuilder

Examples:

builder = SessionBuilder.defaults(core)
with builder.with_log(None).build() as session:
    pass

exception RequiredError[source]¶

Bases: RuntimeError

Raised by SessionBuilder.build() when a required argument has not been set.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

add_note(note, /)¶: Add a note to the exception

args¶

with_traceback(tb, /)¶: Set self.__traceback__ to tb and return self.

type AnySession = Session[AudioDriver, InputDriver, VideoDriver, ContentDriver | None, MessageDriver | None, OptionDriver | None, PathDriver | None, RumbleDriver | None, SensorDriver | None, CameraDriver | None, LogDriver | None, PerfDriver | None, LocationDriver | None, UserDriver | None, FileSystemDriver | None, LedDriver | None, MidiDriver | None, TimingDriver | None, MicrophoneDriver | None, PowerDriver | None]¶