Skip to content

unienv_interface.wrapper.transformation

WrapperBArrayT module-attribute

WrapperBArrayT = TypeVar('WrapperBArrayT')

WrapperContextT module-attribute

WrapperContextT = TypeVar('WrapperContextT')

WrapperObsT module-attribute

WrapperObsT = TypeVar('WrapperObsT')

WrapperActT module-attribute

WrapperActT = TypeVar('WrapperActT')

WrapperBDeviceT module-attribute

WrapperBDeviceT = TypeVar('WrapperBDeviceT')

WrapperBDtypeT module-attribute

WrapperBDtypeT = TypeVar('WrapperBDtypeT')

WrapperBRngT module-attribute

WrapperBRngT = TypeVar('WrapperBRngT')

WrapperRenderFrame module-attribute

WrapperRenderFrame = TypeVar('WrapperRenderFrame')

Wrapper

Wrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType])

Bases: Env[WrapperBArrayT, WrapperContextT, WrapperObsT, WrapperActT, WrapperRenderFrame, WrapperBDeviceT, WrapperBDtypeT, WrapperBRngT], Generic[WrapperBArrayT, WrapperContextT, WrapperObsT, WrapperActT, WrapperRenderFrame, WrapperBDeviceT, WrapperBDtypeT, WrapperBRngT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

Base class for stateful environment wrappers.

The wrapper forwards all operations to env by default while allowing subclasses to override spaces, RNG handling, and selected lifecycle methods.

Space-forwarding invariant

By default the wrapper exposes the wrapped env's action_space, observation_space, and context_space unchanged. Because the :class:Env contract guarantees that these spaces already include the batch dimension when the env is batched, subclasses that do override a space must ensure the replacement still matches the batching status of the underlying env. Never wrap an already-batched env space in an additional batch_space call.

Wrap env and optionally override spaces or metadata later.

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

env instance-attribute

env = env

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

step

step(action: WrapperActT) -> Tuple[WrapperObsT, Union[SupportsFloat, WrapperBArrayT], Union[bool, WrapperBArrayT], Union[bool, WrapperBArrayT], Dict[str, Any]]

reset

reset(*args, mask: Optional[WrapperBArrayT] = None, seed: Optional[int] = None, **kwargs) -> Tuple[WrapperContextT, WrapperObsT, Dict[str, Any]]

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required

ActionWrapper

ActionWrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType])

Bases: Wrapper[BArrayType, ContextType, ObsType, WrapperActT, RenderFrame, BDeviceType, BDtypeType, BRNGType, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType], Generic[WrapperActT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

Wrapper that exposes a transformed action interface.

Wrap env and optionally override spaces or metadata later.

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

env instance-attribute

env = env

reset

reset(*args, mask: Optional[WrapperBArrayT] = None, seed: Optional[int] = None, **kwargs) -> Tuple[WrapperContextT, WrapperObsT, Dict[str, Any]]

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required

map_action abstractmethod

map_action(action: WrapperActT) -> ActType

Map an outer action into the wrapped environment's action space.

reverse_map_action

reverse_map_action(action: ActType) -> WrapperActT

Map an inner action back to the wrapper-facing representation.

step

step(action: WrapperActT) -> Tuple[ObsType, Union[SupportsFloat, BArrayType], Union[bool, BArrayType], Union[bool, BArrayType], Dict[str, Any]]

ContextObservationWrapper

ContextObservationWrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType])

Bases: Wrapper[BArrayType, WrapperContextT, WrapperObsT, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType], Generic[WrapperContextT, WrapperObsT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

Wrapper that transforms context and observation values.

Wrap env and optionally override spaces or metadata later.

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

env instance-attribute

env = env

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required

map_context

map_context(context: WrapperContextT) -> ContextType

Convert wrapped context into the wrapper-facing representation.

reverse_map_context

reverse_map_context(context: ContextType) -> WrapperContextT

Convert wrapper-facing context back into the wrapped representation.

map_observation

map_observation(observation: WrapperObsT) -> ObsType

Convert wrapped observations into the wrapper-facing representation.

reverse_map_observation

reverse_map_observation(observation: ObsType) -> WrapperObsT

Convert wrapper-facing observations back into the wrapped representation.

reset

reset(*args, mask: Optional[BArrayType] = None, seed: Optional[int] = None, **kwargs) -> Tuple[WrapperContextT, WrapperObsT, Dict[str, Any]]

step

step(action: ActType) -> Tuple[WrapperObsT, Union[float, BArrayType], Union[bool, BArrayType], Union[bool, BArrayType], Dict[str, Any]]

TransformWrapper

TransformWrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType], context_transformation: Optional[DataTransformation] = None, observation_transformation: Optional[DataTransformation] = None, action_transformation: Optional[DataTransformation] = None, target_action_space: Optional[Space[BArrayType, BDeviceType, BDtypeType, BRNGType]] = None)

Bases: Wrapper[WrapperBArrayT, WrapperContextT, WrapperObsT, WrapperActT, WrapperRenderFrame, WrapperBDeviceT, WrapperBDtypeT, WrapperBRngT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

context_transformation property writable

context_transformation: Optional[DataTransformation]

observation_transformation property writable

observation_transformation: Optional[DataTransformation]

action_transformation property

action_transformation: Optional[DataTransformation]

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

env instance-attribute

env = env

set_action_transformation

set_action_transformation(action_transformation: Optional[DataTransformation] = None, target_action_space: Optional[Space[BArrayType, BDeviceType, BDtypeType, BRNGType]] = None) -> None

step

step(action: ActType) -> Tuple[ObsType, Union[SupportsFloat, BArrayType], Union[bool, BArrayType], Union[bool, BArrayType], DictT[str, Any]]

reset

reset(*args, mask: Optional[BArrayType] = None, seed: Optional[int] = None, **kwargs) -> Tuple[ContextType, ObsType, DictT[str, Any]]

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required

ContextObservationTransformWrapper

ContextObservationTransformWrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType], context_transformation: Optional[DataTransformation] = None, observation_transformation: Optional[DataTransformation] = None)

Bases: ContextObservationWrapper[WrapperContextT, WrapperObsT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

context_transformation property writable

context_transformation: Optional[DataTransformation]

observation_transformation property writable

observation_transformation: Optional[DataTransformation]

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

env instance-attribute

env = env

map_context

map_context(context: ContextType) -> WrapperContextT

reverse_map_context

reverse_map_context(context: WrapperContextT) -> ContextType

map_observation

map_observation(observation: ObsType) -> WrapperObsT

reverse_map_observation

reverse_map_observation(observation: WrapperObsT) -> ObsType

step

step(action: ActType) -> Tuple[WrapperObsT, Union[float, BArrayType], Union[bool, BArrayType], Union[bool, BArrayType], Dict[str, Any]]

reset

reset(*args, mask: Optional[BArrayType] = None, seed: Optional[int] = None, **kwargs) -> Tuple[WrapperContextT, WrapperObsT, Dict[str, Any]]

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required

ActionTransformWrapper

ActionTransformWrapper(env: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType], action_transformation: DataTransformation, target_action_space: Space[BArrayType, BDeviceType, BDtypeType, BRNGType])

Bases: ActionWrapper[WrapperActT, BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

action_transformation property

action_transformation: DataTransformation

metadata property writable

metadata: Dict[str, Any]

Returns the :attr:Env :attr:metadata.

render_mode property

render_mode: Optional[WrapperRenderFrame]

render_fps property

render_fps: Optional[int]

backend property

backend: ComputeBackend[Any, WrapperBDeviceT, Any, WrapperBRngT]

device property

device: Optional[WrapperBDeviceT]

batch_size property

batch_size: Optional[int]

action_space property writable

action_space: Space[WrapperActT, WrapperBDeviceT, Any, WrapperBRngT]

observation_space property writable

observation_space: Space[WrapperObsT, WrapperBDeviceT, Any, WrapperBRngT]

context_space property writable

context_space: Optional[Space[WrapperContextT, WrapperBDeviceT, Any, WrapperBRngT]]

rng property writable

rng: WrapperBRngT

Returns the :attr:Env :attr:rng attribute.

unwrapped property

unwrapped: Env

Returns the base environment of the wrapper.

This will be the bare :class:gymnasium.Env environment, underneath all layers of wrappers.

prev_wrapper_layer property

prev_wrapper_layer: Env[BArrayType, ContextType, ObsType, ActType, RenderFrame, BDeviceType, BDtypeType, BRNGType]

env instance-attribute

env = env

set_action_transformation

set_action_transformation(action_transformation: DataTransformation, target_action_space: Space[BArrayType, BDeviceType, BDtypeType, BRNGType] = None) -> None

map_action

map_action(action: WrapperActT) -> ActType

reverse_map_action

reverse_map_action(action: ActType) -> WrapperActT

step

step(action: WrapperActT) -> Tuple[ObsType, Union[SupportsFloat, BArrayType], Union[bool, BArrayType], Union[bool, BArrayType], Dict[str, Any]]

reset

reset(*args, mask: Optional[WrapperBArrayT] = None, seed: Optional[int] = None, **kwargs) -> Tuple[WrapperContextT, WrapperObsT, Dict[str, Any]]

render

render() -> RenderFrame | Sequence[RenderFrame] | None

close

close()

sample_space

sample_space(space: Space) -> Any

Sample from space using and updating self.rng.

sample_action

sample_action() -> ActType

Sample one action from action_space.

sample_observation

sample_observation() -> ObsType

Sample one observation from observation_space.

sample_context

sample_context() -> Optional[ContextType]

Sample one context value if context_space is defined.

update_observation_post_reset

update_observation_post_reset(old_obs: ObsType, newobs_masked: ObsType, mask: BArrayType) -> ObsType

Merge masked reset observations back into a full batched observation.

update_context_post_reset

update_context_post_reset(old_context: ContextType, new_context: ContextType, mask: BArrayType) -> ContextType

Merge masked reset contexts back into a full batched context.

has_wrapper_attr

has_wrapper_attr(name: str) -> bool

Checks if the given attribute is within the wrapper or its environment.

get_wrapper_attr

get_wrapper_attr(name: str) -> Any

Gets an attribute from the wrapper and lower environments if name doesn't exist in this object.

Parameters:

Name Type Description Default
name str

The variable name to get

required

Returns:

Type Description
Any

The variable with name in wrapper or lower environments

set_wrapper_attr

set_wrapper_attr(name: str, value: Any)

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

Name Type Description Default
name str

The variable name

required
value Any

The new variable value

required