Class PyEnums
Python's view of the C# enums marked PyEnumAttribute (DR-84): a member's Python .name,
.value, str and repr, parsing a member from its value as Python's Enum(value) call does,
and the members in declaration order.
public static class PyEnums
- Inheritance
-
PyEnums
- Inherited Members
Remarks
The attributes are read by reflection once per enum type and cached, so the calls cost a dictionary lookup. Every member of such an enum must carry a PyValueAttribute: a type missing one is refused at its first use with an InvalidOperationException, a programming error in the enum, not in the caller.
Methods
IsPyEnum(Type?)
Whether type is a C# enum marked PyEnumAttribute.
public static bool IsPyEnum(Type? type)
Parameters
Returns
Exceptions
- InvalidOperationException
Thrown when the type is marked but a member has no PyValueAttribute.
IsStringEnum(Type?)
Whether type is a marked enum whose members stand for plain Python strings (no Enum class).
public static bool IsStringEnum(Type? type)
Parameters
Returns
- bool
true for a string enum such as RenderMode.
Exceptions
- InvalidOperationException
Thrown when the type is marked but a member has no PyValueAttribute.
Members<TEnum>()
The members in declaration order, which is Gymnasium's order for its Enum classes (what list(AutoresetMode) gives).
public static IReadOnlyList<TEnum> Members<TEnum>() where TEnum : struct, Enum
Returns
- IReadOnlyList<TEnum>
The members; a shared, read-only list.
Type Parameters
TEnumThe enum, marked PyEnumAttribute.
Exceptions
- ArgumentException
Thrown when
TEnumis not marked PyEnumAttribute.
Name(Enum)
Python's .name of a member: the constant's name in its Enum class (NEXT_STEP), from its
PyNameAttribute; a string member's own value, the only name Python has for it.
public static string Name(Enum member)
Parameters
memberEnumThe member.
Returns
- string
The name.
Exceptions
- ArgumentNullException
Thrown when
memberis null.- ArgumentException
Thrown when the member's enum is not marked PyEnumAttribute.
- ArgumentOutOfRangeException
Thrown for a value the enum does not declare.
Of<TEnum>(string?)
Python's Enum(value): the member whose value is value. Only the value is accepted
("NextStep", "rgb_array"), never the member's name ("NEXT_STEP", "RgbArray"), as
Python's call refuses names.
public static TEnum Of<TEnum>(string? value) where TEnum : struct, Enum
Parameters
valuestringThe value.
Returns
- TEnum
The member.
Type Parameters
TEnumThe enum, marked PyEnumAttribute.
Exceptions
- ValueError
Thrown for any other value, with Python's text:
'x' is not a valid AutoresetMode.- ArgumentException
Thrown when
TEnumis not marked PyEnumAttribute.
Repr(Enum)
Python's repr(member), what a printed dict shows: <AutoresetMode.NEXT_STEP: 'NextStep'> for an
Enum member, the quoted string ('rgb_array') for a string member.
public static string Repr(Enum member)
Parameters
memberEnumThe member.
Returns
- string
The text.
Exceptions
- ArgumentNullException
Thrown when
memberis null.- ArgumentException
Thrown when the member's enum is not marked PyEnumAttribute.
- ArgumentOutOfRangeException
Thrown for a value the enum does not declare.
Str(Enum)
Python's str(member), what an f-string shows: AutoresetMode.SAME_STEP for an Enum member,
the string itself for a string member. Gymnasium's messages that format a member with an f-string use this.
public static string Str(Enum member)
Parameters
memberEnumThe member.
Returns
- string
The text.
Exceptions
- ArgumentNullException
Thrown when
memberis null.- ArgumentException
Thrown when the member's enum is not marked PyEnumAttribute.
- ArgumentOutOfRangeException
Thrown for a value the enum does not declare.
ToPython(object?)
The value Python holds for value: a string member becomes its string (RenderMode.Human
is "human"); anything else, an Enum member included, is returned as it is. make's kwargs go
through it, so a spec records render_mode='human' as Gymnasium's does.
public static object? ToPython(object? value)
Parameters
valueobjectAny value.
Returns
- object
The value as Python holds it.
Exceptions
- ArgumentOutOfRangeException
Thrown for a string enum's value it does not declare (
(RenderMode)99).
TryOf<TEnum>(string?, out TEnum)
Python's Enum(value) without the exception: the member whose value is value, if any.
public static bool TryOf<TEnum>(string? value, out TEnum member) where TEnum : struct, Enum
Parameters
valuestringThe value; null matches no member.
memberTEnumThe member, when true is returned; the enum's default otherwise.
Returns
Type Parameters
TEnumThe enum, marked PyEnumAttribute.
Exceptions
- ArgumentException
Thrown when
TEnumis not marked PyEnumAttribute.
Value(Enum)
Python's .value of a member: "NextStep", or the string a string member stands for ("rgb_array").
public static string Value(Enum member)
Parameters
memberEnumThe member.
Returns
- string
The value.
Exceptions
- ArgumentNullException
Thrown when
memberis null.- ArgumentException
Thrown when the member's enum is not marked PyEnumAttribute.
- ArgumentOutOfRangeException
Thrown for a value the enum does not declare (
(AutoresetMode)7).