h'S SrSSKJr SSKrSSKJr SSKJr SSKJ r J r J r SSK r SSK Jr SSKJrJrJrJr SS KJr SS KJrJrJrJrJr \ (aSS KJr /S Qr"S S\ R>\\\\4\ R@RB5r""SS\ R>\\\\4\ R@RB5r#"SS\ R>\\\\4\ R@RB5r$"SS\ R>\\\\4\ R@RB5r%"SS\ R>\\\\4\ R@RB5r&g)aA collection of common wrappers. * ``TimeLimit`` - Provides a time limit on the number of steps for an environment before it truncates * ``Autoreset`` - Auto-resets the environment * ``PassiveEnvChecker`` - Passive environment checker that does not modify any environment data * ``OrderEnforcing`` - Enforces the order of function calls to environments * ``RecordEpisodeStatistics`` - Records the episode statistics ) annotationsN)deque)deepcopy) TYPE_CHECKINGAny SupportsFloat)logger)ActTypeObsType RenderFrameWrapperObsType) ResetNeeded)check_action_spacecheck_observation_spaceenv_render_passive_checkerenv_reset_passive_checkerenv_step_passive_checker)EnvSpec) TimeLimit AutoresetPassiveEnvCheckerOrderEnforcingRecordEpisodeStatisticsc|^\rSrSrSrS SjrS SjrSSS.S U4Sjjjr\S Sj5r S r U=r $)r+abLimits the number of steps for an environment through truncating the environment if a maximum number of timesteps is exceeded. If a truncation is not defined inside the environment itself, this is the only place that the truncation signal is issued. Critically, this is different from the `terminated` signal that originates from the underlying environment as part of the MDP. No vector wrapper exists. Example using the TimeLimit wrapper: >>> from gymnasium.wrappers import TimeLimit >>> from gymnasium.envs.classic_control import CartPoleEnv >>> spec = gym.spec("CartPole-v1") >>> spec.max_episode_steps 500 >>> env = gym.make("CartPole-v1") >>> env # TimeLimit is included within the environment stack >>>> >>> env.spec # doctest: +ELLIPSIS EnvSpec(id='CartPole-v1', ..., max_episode_steps=500, ...) >>> env = gym.make("CartPole-v1", max_episode_steps=3) >>> env.spec # doctest: +ELLIPSIS EnvSpec(id='CartPole-v1', ..., max_episode_steps=3, ...) >>> env = TimeLimit(CartPoleEnv(), max_episode_steps=10) >>> env > Example of `TimeLimit` determining the episode step >>> env = gym.make("CartPole-v1", max_episode_steps=3) >>> _ = env.reset(seed=123) >>> _ = env.action_space.seed(123) >>> _, _, terminated, truncated, _ = env.step(env.action_space.sample()) >>> terminated, truncated (False, False) >>> _, _, terminated, truncated, _ = env.step(env.action_space.sample()) >>> terminated, truncated (False, False) >>> _, _, terminated, truncated, _ = env.step(env.action_space.sample()) >>> terminated, truncated (False, True) Change logs: * v0.10.6 - Initially added * v0.25.0 - With the step API update, the termination and truncation signal is returned separately. c[U[5(aUS:d SU35e[RRR XS9 [R R X5 X lSUlg)a#Initializes the :class:`TimeLimit` wrapper with an environment and the number of steps after which truncation will occur. Args: env: The environment to apply the wrapper max_episode_steps: the environment step after which the episode is truncated (``elapsed >= max_episode_steps``) rz9Expect the `max_episode_steps` to be positive, actually: )max_episode_stepsN) isinstanceintgymutilsRecordConstructorArgs__init__Wrapper_max_episode_steps_elapsed_steps)selfenvrs S/home/james-whalen/.local/lib/python3.13/site-packages/gymnasium/wrappers/common.pyr#TimeLimit.__init__Zsw (# . .3Dq3H [ FGXFY Z [ H ''00  1  T'"3"cURRU5up#pEnU=RS- slURUR:aSnX#XEU4$)aFSteps through the environment and if the number of steps elapsed exceeds ``max_episode_steps`` then truncate. Args: action: The environment step action Returns: The environment step ``(observation, reward, terminated, truncated, info)`` with `truncated=True` if the number of steps elapsed >= max episode steps T)r(stepr&r%)r'action observationreward terminated truncatedinfos r)r.TimeLimit.steppsU<@88==;P8 ZD q    $"9"9 9IJ4??r+Nseedoptionsc,>SUl[TU] XS9$)zResets the environment with :param:`**kwargs` and sets the number of steps elapsed to zero. Args: seed: Seed for the environment options: Options for the environment Returns: The reset environment rr6)r&superresetr'r7r8 __class__s r)r;TimeLimit.resets w}$}88r+c(URb UR$URRnUb[U5nURUlXlU$![ a/n[RRSUSU35 SnAgSnAff=f)zYModifies the environment spec to include the `max_episode_steps=self._max_episode_steps`.NAn exception occurred (%) while copying the environment spec=) _cached_specr(specrr%r Exceptionr r warnr'env_speces r)rCTimeLimit.specs    ($$ $88==   #H--1-D-D*%  -aS0UV^U_`  sA B"%B  B)rBr&r%)r(gym.Envrrr/r returnz9tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]]r7 int | Noner8dict[str, Any] | NonerLztuple[ObsType, dict[str, Any]]rLzEnvSpec | None) __name__ __module__ __qualname____firstlineno____doc__r#r.r;propertyrC__static_attributes__ __classcell__r=s@r)rr+su*X# ##,@@ B@,%)4 9! 93H 9 ' 9 9r+rc`^\rSrSrSrS SjrSSS.S U4SjjjrS SjrSrU=r $) raThe wrapped environment is automatically reset when a terminated or truncated state is reached. This follows the vector autoreset api where on the step after an episode terminates or truncated then the environment is reset. Change logs: * v0.24.0 - Initially added as `AutoResetWrapper` * v1.0.0 - renamed to `Autoreset` and autoreset order was changed to reset on the step after the environment terminates or truncates. As a result, `"final_observation"` and `"final_info"` is removed. c[RRRU5 [RRX5 SUlg)zA class for providing an automatic reset functionality for gymnasium environments when calling :meth:`self.step`. Args: env (gym.Env): The environment to apply the wrapper FN)r r!r"r#r$ autoresetr'r(s r)r#Autoreset.__init__s5 ''006 T'r+Nr6c,>SUl[TU] XS9$)z>Resets the environment and sets autoreset to False preventing.Fr6)r]r:r;r<s r)r;Autoreset.resetsw}$}88r+cUR(a"URR5up#SupEnOURRU5up$pVnU=(d UUlX$XVU4$)zSteps through the environment with action and resets the environment if a terminated or truncated signal is encountered. Args: action: The action to take Returns: The autoreset environment :meth:`step` )FF)r]r(r;r.)r'r/obsr4r1r2r3s r)r.Autoreset.stepsY >>(IC,= )F 7;xx}}V7L 4C#0yJ477r+)r])r(rJ)r7rNr8rOrLz%tuple[WrapperObsType, dict[str, Any]]rK) rQrRrSrTrUr#r;r.rWrXrYs@r)rrsP %)49!93H9 .9988 B88r+rcv\rSrSrSrS SjrS SjrSSS.SSjjrSSjr\ SS j5r S r S r g)raA passive wrapper that surrounds the ``step``, ``reset`` and ``render`` functions to check they follow Gymnasium's API. This wrapper is automatically applied during make and can be disabled with `disable_env_checker`. No vector version of the wrapper exists. Example: >>> import gymnasium as gym >>> env = gym.make("CartPole-v1") >>> env >>>> >>> env = gym.make("CartPole-v1", disable_env_checker=True) >>> env >>> Change logs: * v0.24.1 - Initially added however broken in several ways * v0.25.0 - Bugs was all fixed * v0.29.0 - Removed warnings for infinite bounds for Box observation and action spaces and inregular bound shapes cZ[RRRU5 [RRX5 [ U[R 5(dF[URR5S:Xa [S5e[S[U5S35e[US5(d [S5e[UR5 [US5(d [S5e[!UR"5 S UlS UlS UlS Ulg ) zZInitialises the wrapper with the environments, run the observation and action space tests.zzGym is incompatible with Gymnasium, please update the environment class to `gymnasium.Env`. See https://gymnasium.farama.org/introduction/create_custom_env/ for more info.zIThe environment must inherit from the gymnasium.Env class, actual class: zQ. See https://gymnasium.farama.org/introduction/create_custom_env/ for more info. action_spacezjThe environment must specify an action space. https://gymnasium.farama.org/introduction/create_custom_env/observation_spacezoThe environment must specify an observation space. https://gymnasium.farama.org/introduction/create_custom_env/FN)r r!r"r#r$rEnvstrr=__base__ TypeErrortypehasattrAttributeErrorrrirrj checked_reset checked_stepchecked_render close_calledr^s r)r#PassiveEnvChecker.__init__s ''006 T'#sww''3==))*.FFf  _`deh`i_jkff sN++ |  3++,s/00 B   5 56#("'$)"'r+cURSLaSUl[URU5$URRU5$)z[Steps through the environment that on the first call will run the `passive_env_step_check`.FT)rsrr(r.)r'r/s r)r.PassiveEnvChecker.steps>    % $D +DHHf= =88==( (r+Nr6cURSLaSUl[URXS9$URRXS9$)zUResets the environment that on the first call will run the `passive_env_reset_check`.FTr6)rrrr(r;)r'r7r8s r)r;PassiveEnvChecker.resets@    &!%D ,TXXDR R88>>t>= =r+cURSLaSUl[UR5$URR5$)zWRenders the environment that on the first call will run the `passive_env_render_check`.FT)rtrr(renderr's r)r|PassiveEnvChecker.render)s8   % '"&D -dhh7 788??$ $r+cURb UR$URRnUb[U5nSUlXlU$![ a/n[ RRSUSU35 SnAgSnAff=f)zGModifies the environment spec to such that `disable_env_checker=False`.NFr@rA) rBr(rCrdisable_env_checkerrDr r rErFs r)rCPassiveEnvChecker.spec1s    ($$ $88==   #H-/4,%  -aS0UV^U_`  A B%BBcUR(d!SUlURR5$URR5$![an[R "S5 UeSnAff=f)z5Warns if calling close on a closed environment fails.TziCalling `env.close()` on the closed environment should be allowed, but it raised the following exception.N)rur(closerDr rE)r'rHs r)rPassiveEnvChecker.closeEs`  $D 88>># # xx~~''    sA A5A00A5)rBrtrrrsru)r(gym.Env[ObsType, ActType]rKrMrLz&RenderFrame | list[RenderFrame] | NonerP) rQrRrSrTrUr#r.r;r|rVrCrrWr+r)rrsd( (D)) B)%)4>!>3H> '>%& r+rc^\rSrSrSrS S SjjrSU4SjjrSSS.SU4SjjjrSU4Sjjr\ S 5r \ SS j5r S r U=r $)riTaWill produce an error if ``step`` or ``render`` is called before ``reset``. No vector version of the wrapper exists. Example: >>> import gymnasium as gym >>> from gymnasium.wrappers import OrderEnforcing >>> env = gym.make("CartPole-v1", render_mode="human") >>> env = OrderEnforcing(env) >>> env.step(0) Traceback (most recent call last): ... gymnasium.error.ResetNeeded: Cannot call env.step() before calling env.reset() >>> env.render() Traceback (most recent call last): ... gymnasium.error.ResetNeeded: Cannot call `env.render()` before calling `env.reset()`, if this is an intended action, set `disable_render_order_enforcing=True` on the OrderEnforcer wrapper. >>> _ = env.reset() >>> env.render() >>> _ = env.step(0) >>> env.close() Change logs: * v0.22.0 - Initially added * v0.24.0 - Added order enforcing for the render function c[RRRXS9 [RRX5 SUlX lg)zA wrapper that will produce an error if :meth:`step` is called before an initial :meth:`reset`. Args: env: The environment to wrap disable_render_order_enforcing: If to disable render order enforcing )disable_render_order_enforcingFN)r r!r"r#r$ _has_reset_disable_render_order_enforcing)r'r(rs r)r#OrderEnforcing.__init__rsE ''00  1  T' %5S,r+cZ>UR(d [S5e[TU] U5$)zSteps through the environment.z1Cannot call env.step() before calling env.reset())rrr:r.)r'r/r=s r)r.OrderEnforcing.steps%QR Rw|F##r+Nr6c,>SUl[TU] XS9$)z%Resets the environment with `kwargs`.Tr6)rr:r;r<s r)r;OrderEnforcing.resetsw}$}88r+cz>UR(dUR(d [S5e[TU]5$)z&Renders the environment with `kwargs`.zCannot call `env.render()` before calling `env.reset()`, if this is an intended action, set `disable_render_order_enforcing=True` on the OrderEnforcer wrapper.)rrrr:r|)r'r=s r)r|OrderEnforcing.renders433DOOZ w~r+cUR$)z1Returns if the environment has been reset before.)rr}s r) has_resetOrderEnforcing.has_resetsr+cURb UR$URRnUb[U5nSUlXlU$![ a/n[ RRSUSU35 SnAgSnAff=f)z>Modifies the environment spec to add the `order_enforce=True`.NTr@rA) rBr(rCr order_enforcerDr r rErFs r)rCOrderEnforcing.specs    ($$ $88==   #H-)-&%  -aS0UV^U_`  r)rBrr)F)r(rrbool)r/r rLz/tuple[ObsType, SupportsFloat, bool, bool, dict]rMrrP)rQrRrSrTrUr#r.r;r|rVrrCrWrXrYs@r)rrTs<05T &T)-T&$%)49!93H9 '99 r+rcx^\rSrSrSrS S SjjrS U4SjjrSSS.S U4SjjjrSrU=r $) riaThis wrapper will keep track of cumulative rewards and episode lengths. At the end of an episode, the statistics of the episode will be added to ``info`` using the key ``episode``. If using a vectorized environment also the key ``_episode`` is used which indicates whether the env at the respective index has the episode statistics. A vector version of the wrapper exists, :class:`gymnasium.wrappers.vector.RecordEpisodeStatistics`. After the completion of an episode, ``info`` will look like this:: >>> info = { ... "episode": { ... "r": "", ... "l": "", ... "t": "" ... }, ... } For a vectorized environments the output will be in the form of:: >>> infos = { ... "episode": { ... "r": "", ... "l": "", ... "t": "" ... }, ... "_episode": "" ... } Moreover, the most recent rewards and episode lengths are stored in buffers that can be accessed via :attr:`wrapped_env.return_queue` and :attr:`wrapped_env.length_queue` respectively. Attributes: * time_queue: The time length of the last ``deque_size``-many episodes * return_queue: The cumulative rewards of the last ``deque_size``-many episodes * length_queue: The lengths of the last ``deque_size``-many episodes Change logs: * v0.15.4 - Initially added * v1.0.0 - Removed vector environment support (see :class:`gymnasium.wrappers.vector.RecordEpisodeStatistics`) and add attribute ``time_queue`` c,[RRRU5 [RRX5 X0lSUlSUlSUlSUl [US9Ul [US9Ul [US9Ul g)a'This wrapper will keep track of cumulative rewards and episode lengths. Args: env (Env): The environment to apply the wrapper buffer_length: The size of the buffers :attr:`return_queue`, :attr:`length_queue` and :attr:`time_queue` stats_key: The info key for the episode statistics rrc)maxlenN)r r!r"r#r$ _stats_key episode_countepisode_start_timeepisode_returnsepisode_lengthsr time_queue return_queue length_queue)r'r( buffer_length stats_keys r)r# RecordEpisodeStatistics.__init__sy ''006 T'#)+&)$%(-](C*/}*E(-](Cr+c>[TU]U5up#pEnU=RU- slU=RS- slU(dU(aURU;de[ [ R"5UR- S5nURURUS.X`R'URRU5 URRUR5 URRUR5 U=RS- sl [ R"5UlX#XEU4$)z@Steps through the environment, recording the episode statistics.r-)rlt)r:r.rrrroundtime perf_counterrrappendrrr) r'r/rdr1r2r3r4episode_time_lengthr=s r)r.RecordEpisodeStatistics.steps497<3G0ZD & ! ??$. .."'!!#d&=&==q# ))))(%D ! OO " "#6 7    $ $T%9%9 :    $ $T%9%9 :   ! # &*&7&7&9D #J477r+Nr6cx>[TU]XS9up4[R"5UlSUlSUlX44$)zYResets the environment using seed and options and resets the episode rewards and lengths.r6rcr)r:r;rrrrr)r'r7r8rdr4r=s r)r;RecordEpisodeStatistics.resets@GMtM= "&"3"3"5" yr+)rrrrrrrr)depisode)r(rrrrrlrKrM) rQrRrSrTrUr#r.r;rWrXrYs@r)rrst(Z!" D &DD D688 B8>%)4 ! 3H  '  r+r)'rU __future__rr collectionsrcopyrtypingrrr gymnasiumr r gymnasium.corer r r r gymnasium.errorr#gymnasium.utils.passive_env_checkerrrrrrgymnasium.envs.registrationr__all__r$r!r"rrrrrrr+r)rs)# 44HH'3 {KK'723SYY5T5T{|08KK'723SYY5T5T08fuKK'723SYY5T5Tup^KK'723SYY5T5T^BpKK'723SYY5T5Tpr+