Class Wrapper<TWObs, TWAct, TObs, TAct>
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
TWObsThe observation type the wrapper returns.
TWActThe action type the wrapper takes.
TObsThe wrapped env's observation type.
TActThe 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
envEnv<TObs, TAct>The env to wrap, possibly another wrapper.
Exceptions
- TypeError
Thrown when
envis null, with Gymnasium's message (Expected env to be a).gymnasium.Envbut 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
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
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
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
NpRandomSeed
The env's NpRandomSeed, which a seeded reset through the wrapper sets on the innermost env.
public override BigInteger NpRandomSeed { get; }
Property Value
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
Exceptions
- AttributeError
Thrown by the getter with Gymnasium's message (
Can't access) and by the setter as by a setter-less Python property._np_randomof a wrapper, use.unwrapped._np_randomor.np_random.
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
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
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
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
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
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
namestringThe attribute, in Python spelling.
Returns
- object
The value, boxed.
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis 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
namestringThe attribute, in Python spelling.
Returns
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis 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
seedBigInteger?The seed, passed on to the env.
optionsIReadOnlyDictionary<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
namestringThe attribute, in Python spelling.
valueobjectThe value.
forceboolCreate the attribute on this wrapper when no layer has it.
Returns
Remarks
Reference: gymnasium/core.py.
Exceptions
- ArgumentNullException
Thrown when
nameis 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
actionTWActThe 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.