Table of Contents

Class Wrapper<TWObs, TWAct, TObs, TAct>

Namespace
Gym.Envs
Assembly
Gym.dll

Wraps an env to change parts of its behaviour while forwarding the rest. Every member forwards to Env unless the wrapper overrides it; spaces and metadata can be replaced on the wrapper alone, without touching the env beneath.

public class Wrapper<TWObs, TWAct, TObs, TAct> : Env<TWObs, TWAct>, IDynamicAttributes, IWrapper, IEnv, IDisposable

Type Parameters

TWObs

The observation type the wrapper returns.

TWAct

The action type the wrapper takes.

TObs

The wrapped env's observation type.

TAct

The wrapped env's action type.

Inheritance
Env<TWObs, TWAct>
Wrapper<TWObs, TWAct, TObs, TAct>
Implements
Derived
ActionWrapper<TObs, TWAct, TAct>
ObservationWrapper<TWObs, TObs, TAct>
Inherited Members
Extension Methods

Remarks

Spec, RenderMode, NpRandom and NpRandomSeed always read the env beneath; Spec extends the env's spec with this wrapper's WrapperSpec (recording its constructor arguments when it implements IRecordConstructorArgs) and caches it. Python attributes are not forwarded: wrapper.gravity raises, and GetWrapperAttr(string) is the way to reach an attribute of a lower layer.

When the wrapper's types differ from the env's, override Step(TWAct) and Reset(BigInteger?, IReadOnlyDictionary<string, object?>?) (or derive from ObservationWrapper<TWObs, TObs, TAct> or ActionWrapper<TObs, TWAct, TAct>): the default forwarding passes values through unchanged and throws InvalidCastException when a value is not also of the other type.

Reference: gymnasium/core.py.

Constructors

Wrapper(Env<TObs, TAct>)

Wraps env.

public Wrapper(Env<TObs, TAct> env)

Parameters

env Env<TObs, TAct>

The env to wrap, possibly another wrapper.

Exceptions

TypeError

Thrown when env is null, with Gymnasium's message (Expected env to be a gymnasium.Env but got <class 'NoneType'>).

Properties

ActionSpace

The env's action space, unless this wrapper was assigned its own (Python's _action_space). Forwarding needs the env's space to hold TWAct elements: a wrapper that changes the action type assigns its own space, as Gymnasium's action wrappers do.

public override Space<TWAct> ActionSpace { get; set; }

Property Value

Space<TWAct>

Exceptions

AttributeError

Thrown by the getter when neither this wrapper nor the env has one.

TypeError

Thrown by the getter when the env's space holds another element type and this wrapper has none of its own.

CachedSpec

The spec computed by the first read of Spec (Python's _cached_spec). Wrappers that override Spec use it the same way; clear it to recompute after the env's spec changed.

[PyName("_cached_spec")]
protected EnvSpec? CachedSpec { get; set; }

Property Value

EnvSpec

ClassMetadata

No class-level metadata: a wrapper's metadata exists only per instance (the env's, or its own once assigned), as Python's Wrapper.metadata is an instance property. make reads null here as "none", so a wrapper class used as an entry point skips the render-mode adjustments, as Gymnasium's fix #1672 does.

public static Metadata? ClassMetadata { get; }

Property Value

Metadata

Env

The wrapped env (env).

public Env<TObs, TAct> Env { get; }

Property Value

Env<TObs, TAct>

Metadata

The env's metadata, unless this wrapper was assigned its own (Python's _metadata); assigning null restores forwarding, as setting _metadata = None does.

public override Metadata Metadata { get; set; }

Property Value

Metadata

NpRandom

The env's generator; assigning one assigns the env's (so the innermost env's seed becomes -1).

public override Generator NpRandom { get; set; }

Property Value

Generator

NpRandomSeed

The env's NpRandomSeed, which a seeded reset through the wrapper sets on the innermost env.

public override BigInteger NpRandomSeed { get; }

Property Value

BigInteger

ObservationSpace

The env's observation space, unless this wrapper was assigned its own (Python's _observation_space).

public override Space<TWObs> ObservationSpace { get; set; }

Property Value

Space<TWObs>

Exceptions

AttributeError

Thrown by the getter when neither this wrapper nor the env has one.

TypeError

Thrown by the getter when the env's space holds another element type and this wrapper has none of its own.

RawNpRandom

Python's _np_random on a wrapper: an error, because a wrapper holds no generator of its own; read Unwrapped's or NpRandom instead.

[PyName("_np_random")]
protected override Generator? RawNpRandom { get; set; }

Property Value

Generator

Exceptions

AttributeError

Thrown by the getter with Gymnasium's message (Can't access _np_random of a wrapper, use .unwrapped._np_random or .np_random.) and by the setter as by a setter-less Python property.

RenderMode

The env's render mode; read-only on a wrapper (Python's property has no setter).

public override string? RenderMode { get; protected set; }

Property Value

string

Exceptions

AttributeError

Thrown when assigned (through SetAttr(object, string, object?)).

Spec

The env's spec extended with this wrapper (Python's spec property): a deep copy of the env's spec whose AdditionalWrappers ends with this wrapper's WrapperSpec, or null when the env has no spec. Computed once, then cached (_cached_spec).

public override EnvSpec? Spec { get; set; }

Property Value

EnvSpec

Exceptions

AttributeError

Thrown when assigned: property 'spec' of 'X' object has no setter.

Unwrapped

The innermost env, beneath every layer.

public override IEnv Unwrapped { get; }

Property Value

IEnv

WrapperActionSpace

This wrapper's own action space (Python's _action_space), null to forward the env's. The wrapper owns and disposes a space it is given (DR-40), except one an env beneath it already owns, such as the env's own space handed back: that one is referenced, never disposed here, so it is not released twice.

[PyName("_action_space")]
protected Space<TWAct>? WrapperActionSpace { get; set; }

Property Value

Space<TWAct>

Exceptions

InvalidOperationException

Thrown by the setter for a space an env outside this stack, not yet disposed, owns.

WrapperMetadata

This wrapper's own metadata (Python's _metadata), null to forward the env's.

[PyName("_metadata")]
protected Metadata? WrapperMetadata { get; set; }

Property Value

Metadata

WrapperObservationSpace

This wrapper's own observation space (Python's _observation_space), null to forward the env's; owned as WrapperActionSpace is.

[PyName("_observation_space")]
protected Space<TWObs>? WrapperObservationSpace { get; set; }

Property Value

Space<TWObs>

Exceptions

InvalidOperationException

Thrown by the setter for a space an env outside this stack, not yet disposed, owns.

Methods

ClassName()

The wrapper's class name (class_name()): the type name without generic arity, TimeLimit.

public virtual string ClassName()

Returns

string

The name its WrapperSpec records.

Close()

Closes the env beneath (self.env.close()).

public override void Close()

Dispose(bool)

Closes through Close(), then releases this wrapper's own spaces and disposes the env it wraps, which closes again (every env's close tolerates that) and releases the env's spaces: disposing the outermost wrapper disposes the whole stack.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true from Dispose().

GetWrapperAttr(string)

The Python attribute name from this wrapper when it has it, else from the first layer beneath that does.

public override object? GetWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

object

The value, boxed.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

AttributeError

Thrown when no layer has it: wrapper TimeLimit has no attribute 'x'. Python chains the lower layer's error as the cause (raise ... from e); NumSharp's AttributeError has no constructor taking an inner exception, so the chain is not kept.

HasWrapperAttr(string)

Whether this wrapper or any layer beneath it has the Python attribute name.

public override bool HasWrapperAttr(string name)

Parameters

name string

The attribute, in Python spelling.

Returns

bool

true when some layer has it.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

Render()

Forwards to the env (self.env.render()).

public override RenderResult Render()

Returns

RenderResult

The env's rendering.

Reset(BigInteger?, IReadOnlyDictionary<string, object?>?)

Forwards to the env (self.env.reset(seed=seed, options=options)); override to change the result.

public override ResetResult<TWObs> Reset(BigInteger? seed = null, IReadOnlyDictionary<string, object?>? options = null)

Parameters

seed BigInteger?

The seed, passed on to the env.

options IReadOnlyDictionary<string, object>

The options, passed on to the env.

Returns

ResetResult<TWObs>

The env's first observation, passed through unchanged, and info.

Exceptions

Error

Thrown for a negative seed (by the innermost env).

InvalidCastException

Thrown when the wrapper's and the env's observation types differ and the observation is not of both.

SetWrapperAttr(string, object?, bool)

Assigns the Python attribute name on this wrapper when it has it, else on the first layer beneath that has it (asking them with force=False); when no layer has it and force is set, creates it on this wrapper.

public override bool SetWrapperAttr(string name, object? value, bool force = true)

Parameters

name string

The attribute, in Python spelling.

value object

The value.

force bool

Create the attribute on this wrapper when no layer has it.

Returns

bool

true when some layer was assigned.

Remarks

Reference: gymnasium/core.py.

Exceptions

ArgumentNullException

Thrown when name is null.

AttributeError

Thrown when the attribute found is read-only.

TypeError

Thrown when the value does not fit the attribute's type.

Step(TWAct)

Forwards to the env (self.env.step(action)); override to change the transition.

public override StepResult<TWObs> Step(TWAct action)

Parameters

action TWAct

The action, passed through unchanged.

Returns

StepResult<TWObs>

The env's transition, its observation passed through unchanged.

Exceptions

InvalidCastException

Thrown when the wrapper's and the env's types differ and a value is not of both.

ToString()

The stack's description: <TimeLimit<OrderEnforcing<CartPoleEnv<CartPole-v1>>>>.

public override string ToString()

Returns

string

The wrapper's class name followed by the env's text.

Remarks

Reference: gymnasium/core.py.