Class EnvSpec
- Namespace
- Gym.Envs.Registration
- Assembly
- Gym.dll
Everything make needs to build an env and the wrappers it adds (time limit, order enforcing, env checker),
plus the wrappers applied since. An env built by make carries it as Spec; a wrapper's
Spec is a copy extended with the wrapper, so editing one never changes another.
public sealed record EnvSpec : IEquatable<EnvSpec>
- Inheritance
-
EnvSpec
- Implements
- Inherited Members
- Extension Methods
Remarks
Like the dataclass, every field is settable, and Namespace, Name and
Version are parsed from Id once, at construction (__post_init__): assigning
Id later does not re-parse them, and neither does a with expression, as editing a
deep-copied spec in Python does not.
Equality is the dataclass's, over every field in declaration order, Kwargs compared as Python dicts.
An entry point given as a class equals the "Namespace:Class" string that names it, the form
ToJson() writes, so a spec read back with FromJson(string) equals the original.
Reference: gymnasium/envs/registration.py.
Constructors
EnvSpec(string, object?, double?, bool, long?, bool, bool, Info?, IEnumerable<WrapperSpec>?, object?)
Creates a spec; the namespace, name and version are parsed from id, as
post_init does.
public EnvSpec(string id, object? entryPoint = null, double? rewardThreshold = null, bool nondeterministic = false, long? maxEpisodeSteps = null, bool orderEnforce = true, bool disableEnvChecker = false, Info? kwargs = null, IEnumerable<WrapperSpec>? additionalWrappers = null, object? vectorEntryPoint = null)
Parameters
idstringThe id
maketakes:namespace/[-v(version)], for example"CartPole-v1".entryPointobjectThe env's location, a
"Namespace:Class"string, or an EnvCreator; null when the spec only describes an env.rewardThresholddouble?The return at which the task counts as solved, or null.
nondeterministicboolWhether the same seed and actions can still give different observations.
maxEpisodeStepslong?The step limit a
TimeLimitenforces, or null for none.orderEnforceboolWhether
makeaddsOrderEnforcing(reset before step and render).disableEnvCheckerboolWhether
makeleaves out the passive env checker.kwargsInfoThe keyword arguments the env is constructed with; null is an empty dict (the dataclass's
default_factory).additionalWrappersIEnumerable<WrapperSpec>The wrappers applied on top, in order; null is none.
vectorEntryPointobjectThe location of a vectorized implementation, or null.
Exceptions
- ArgumentNullException
Thrown when
idis null.- Error
Thrown for a malformed id, with Gymnasium's message (see ParseEnvId(string)).
Properties
AdditionalWrappers
The wrappers applied on top of the env, in order (Python's tuple: replace it, do not edit it).
public IReadOnlyList<WrapperSpec> AdditionalWrappers { get; set; }
Property Value
DisableEnvChecker
Whether make leaves out the passive env checker.
public bool DisableEnvChecker { get; set; }
Property Value
EntryPoint
A "Namespace:Class" string, an EnvCreator, or null.
public object? EntryPoint { get; set; }
Property Value
Id
The id, namespace/[-v(version)].
public string Id { get; set; }
Property Value
Kwargs
The keyword arguments the env is constructed with, a Python dict.
public Info Kwargs { get; set; }
Property Value
MaxEpisodeSteps
The step limit a TimeLimit enforces, or null for none.
public long? MaxEpisodeSteps { get; set; }
Property Value
- long?
Name
The name parsed from Id at construction.
public string Name { get; set; }
Property Value
Namespace
public string? Namespace { get; set; }
Property Value
Nondeterministic
Whether the same seed and actions can still give different observations.
public bool Nondeterministic { get; set; }
Property Value
OrderEnforce
Whether make adds OrderEnforcing; true by default.
public bool OrderEnforce { get; set; }
Property Value
RewardThreshold
The return at which the task counts as solved, or null.
public double? RewardThreshold { get; set; }
Property Value
VectorEntryPoint
The location of a vectorized implementation (a string or a creator), or null.
public object? VectorEntryPoint { get; set; }
Property Value
Version
public long? Version { get; set; }
Property Value
- long?
Methods
DeepCopy()
copy.deepcopy(spec): a spec with the same fields whose kwargs and wrapper specs are copies, so a wrapper
can edit the copy (TimeLimit sets MaxEpisodeSteps) without touching the original.
public EnvSpec DeepCopy()
Returns
- EnvSpec
The copy; entry points are shared, as Python's deepcopy shares functions.
Equals(EnvSpec?)
The dataclass equality: every field equal, in declaration order, Kwargs as Python dicts.
public bool Equals(EnvSpec? other)
Parameters
Returns
FromJson(string)
Reads a spec back from ToJson()'s text (Python's from_json): the wrapper specs first, then the
spec from the remaining fields by name, as EnvSpec(**fields).
public static EnvSpec FromJson(string jsonEnvSpec)
Parameters
jsonEnvSpecstringThe JSON text.
Returns
- EnvSpec
The spec; its entry points are the strings the JSON holds.
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- ValueError
Thrown for malformed JSON, or fields that do not make a spec:
An issue occurred when trying to make {...} an EnvSpec(ora WrapperSpec), with the cause as the inner exception.- KeyError
Thrown when the JSON has no
additional_wrappersfield.- AttributeError
Thrown when the JSON is not an object.
- TypeError
Thrown when
additional_wrappersis not a list.
GetHashCode()
A hash consistent with Equals(EnvSpec?): the id and the counts of kwargs and wrappers.
public override int GetHashCode()
Returns
- int
The hash.
Make(object?, long?, bool?)
Builds the env this spec describes with make's wrappers (Python's spec.make(**kwargs)).
public IEnv Make(object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- IEnv
The env; the caller owns it.
Remarks
Reference: gymnasium/envs/registration.py.
Exceptions
- TypeError
Thrown when the env cannot be built from the kwargs.
- Error
Thrown when the spec has no entry point.
- ModuleNotFoundError
Thrown when a string entry point names a module that does not exist.
- AttributeError
Thrown when a string entry point's namespace has no such class.
- InvalidMetadata
Thrown when the env class's
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created.
- NotImplementedError
Thrown when
HumanRenderingwould be needed.
Make<TObs, TAct>(object?, long?, bool?)
Builds the env this spec describes as an Env<TObs, TAct> (DR-10); see Make(object?, long?, bool?).
public Env<TObs, TAct> Make<TObs, TAct>(object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)
Parameters
kwargsobjectThe env's constructor arguments by Python name, over the spec's.
maxEpisodeStepslong?The step limit instead of the spec's;
-1adds noTimeLimit.disableEnvCheckerbool?Whether to leave out
PassiveEnvChecker; null follows the spec.
Returns
- Env<TObs, TAct>
The env; the caller owns it.
Type Parameters
TObsThe observation type the env must have.
TActThe action type the env must have.
Exceptions
- TypeError
Thrown when the env is not an
Env<TObs, TAct>or cannot be built from the kwargs.- Error
Thrown when the spec has no entry point.
- ModuleNotFoundError
Thrown when a string entry point names a module that does not exist.
- AttributeError
Thrown when a string entry point's namespace has no such class.
- InvalidMetadata
Thrown when the env class's
ClassMetadatais not a dict.- ValueError
Thrown when a recorded wrapper cannot be re-created.
- NotImplementedError
Thrown when
HumanRenderingwould be needed.
Pprint(bool, bool, bool)
The spec as key=value lines: the id always, the other fields when they differ from their defaults (or
always with printAll).
public string? Pprint(bool disablePrint = false, bool includeEntryPoints = false, bool printAll = false)
Parameters
disablePrintboolReturn the text instead of writing it to the console.
includeEntryPointsboolAlso print the entry points of the env and of each wrapper.
printAllboolPrint every field, including those at their default values.
Returns
Remarks
Reference: gymnasium/envs/registration.py.
ToJson()
The spec as JSON (Python's to_json): dataclasses.asdict without the fields parsed from the id,
written by Python's json.dumps, so the text is Gymnasium's byte for byte where the fields agree.
public string ToJson()
Returns
- string
The JSON text.
Remarks
An entry point given as a class is written as its "Namespace:Class" string (Python would refuse a class
as a callable), the one field where Gym.NET's JSON differs from Gymnasium's by design: it names a .NET class.
Reference: gymnasium/envs/registration.py.
Exceptions
- ValueError
Thrown when an entry point is a function (an EnvCreator), which JSON cannot carry:
Callable found in CartPole-v1 for entry_point attribute with value=... Currently, Gymnasium does not support serialising callables.- TypeError
Thrown when a kwarg cannot be serialized (
Object of type ndarray is not JSON serializable).
ToString()
The dataclass repr, fields in declaration order: EnvSpec(id='CartPole-v1', entry_point=..., ...,
additional_wrappers=(), vector_entry_point=None). Wrapper and warning messages embed it.
public override string ToString()
Returns
- string
The text.