langfun 0.1.2.dev202510310805__py3-none-any.whl → 0.1.2.dev202511010804__py3-none-any.whl

langfun/env/interface.py

@@ -238,6 +238,11 @@ class Environment(pg.Object):
         f'No image ID found for feature {feature.name} in {self.image_ids}.'
     )
 
+  @property
+  @abc.abstractmethod
+  def event_handler(self) -> 'EventHandler':
+    """Returns the event handler for the environment."""
+
   @property
   @abc.abstractmethod
   def status(self) -> Status:
@@ -306,10 +311,6 @@ class Environment(pg.Object):
     Environment._ENV_STACK.pop()
     self.shutdown()
 
-  def __del__(self):
-    """Deletes the environment."""
-    self.shutdown()
-
   @classmethod
   def current(cls) -> Optional['Environment']:
     """Returns the current environment."""
@@ -776,10 +777,6 @@ class Sandbox(pg.Object):
       return self.features[name]
     raise AttributeError(name)
 
-  def __del__(self):
-    """Deletes the sandbox."""
-    self.shutdown()
-
 
 class Feature(pg.Object):
   """Interface for sandbox features."""
@@ -792,6 +789,11 @@ class Feature(pg.Object):
   def name(self) -> str:
     """Name of the feature, which will be used as key to access the feature."""
 
+  @property
+  @abc.abstractmethod
+  def environment(self) -> Environment:
+    """Returns the environment that the feature is running in."""
+
   @property
   @abc.abstractmethod
   def sandbox(self) -> Sandbox:
@@ -1008,3 +1010,337 @@ def log_sandbox_activity(name: str | None = None):
         return func(self, *args, **kwargs)
     return method_wrapper
   return decorator
+
+
+#
+# Interface for Environment event handlers.
+#
+
+
+class _SessionEventHandler:
+  """Base class for session event handlers."""
+
+  def on_session_start(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      session_id: str,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox session starts.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      session_id: The session ID.
+      duration: The time spent on starting the session.
+      error: The error that caused the session to start. If None, the session
+        started normally.
+    """
+
+  def on_session_end(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      session_id: str,
+      duration: float,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox session ends.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      session_id: The session ID.
+      duration: The time spent on ending the session.
+      lifetime: The session lifetime in seconds.
+      error: The error that caused the session to end. If None, the session
+        ended normally.
+    """
+
+
+class _FeatureEventHandler:
+  """Base class for feature event handlers."""
+
+  def on_feature_setup(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is setup.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature.
+      duration: The feature setup duration in seconds.
+      error: The error happened during the feature setup. If None,
+        the feature setup performed normally.
+    """
+
+  def on_feature_teardown(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox feature is teardown.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature.
+      duration: The feature teardown duration in seconds.
+      error: The error happened during the feature teardown. If None,
+        the feature teardown performed normally.
+    """
+
+  def on_feature_teardown_session(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature,
+      session_id: str,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a feature is teardown with a session.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature.
+      session_id: The session ID.
+      duration: The feature teardown session duration in seconds.
+      error: The error happened during the feature teardown session. If
+        None, the feature teardown session performed normally.
+    """
+
+  def on_feature_setup_session(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature,
+      session_id: str | None,
+      duration: float,
+      error: BaseException | None,
+  ) -> None:
+    """Called when a feature is setup with a session.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature.
+      session_id: The session ID.
+      duration: The feature setup session duration in seconds.
+      error: The error happened during the feature setup session. If
+        None, the feature setup session performed normally.
+    """
+
+  def on_feature_housekeep(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature,
+      counter: int,
+      duration: float,
+      error: BaseException | None,
+      **kwargs,
+  ) -> None:
+    """Called when a sandbox feature is housekeeping.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature.
+      counter: Zero-based counter of the housekeeping round.
+      duration: The feature housekeeping duration in seconds.
+      error: The error happened during the feature housekeeping. If None, the
+        feature housekeeping normally.
+      **kwargs: Feature-specific properties computed during housekeeping.
+    """
+
+
+class _SandboxEventHandler(_FeatureEventHandler, _SessionEventHandler):
+  """Base class for sandbox event handlers."""
+
+  def on_sandbox_start(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox is started.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      duration: The time spent on starting the sandbox.
+      error: The error that caused the sandbox to start. If None, the sandbox
+        started normally.
+    """
+
+  def on_sandbox_status_change(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      old_status: 'Sandbox.Status',
+      new_status: 'Sandbox.Status',
+      span: float,
+  ) -> None:
+    """Called when a sandbox status changes.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      old_status: The old sandbox status.
+      new_status: The new sandbox status.
+      span: Time spent on the old status in seconds.
+    """
+
+  def on_sandbox_shutdown(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      duration: float,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when a sandbox is shutdown.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      duration: The time spent on shutting down the sandbox.
+      lifetime: The sandbox lifetime in seconds.
+      error: The error that caused the sandbox to shutdown. If None, the
+        sandbox shutdown normally.
+    """
+
+  def on_sandbox_activity(
+      self,
+      name: str,
+      environment: Environment,
+      sandbox: Sandbox,
+      feature: Feature | None,
+      session_id: str | None,
+      duration: float,
+      error: BaseException | None,
+      **kwargs
+  ) -> None:
+    """Called when a sandbox activity is performed.
+
+    Args:
+      name: The name of the sandbox activity.
+      environment: The environment.
+      sandbox: The sandbox.
+      feature: The feature that is associated with the sandbox activity.
+      session_id: The session ID.
+      duration: The sandbox activity duration in seconds.
+      error: The error that caused the sandbox activity to perform. If None,
+        the sandbox activity performed normally.
+      **kwargs: The keyword arguments of the sandbox activity.
+    """
+
+  def on_sandbox_housekeep(
+      self,
+      environment: Environment,
+      sandbox: Sandbox,
+      counter: int,
+      duration: float,
+      error: BaseException | None,
+      **kwargs
+  ) -> None:
+    """Called when a sandbox finishes a round of housekeeping.
+
+    Args:
+      environment: The environment.
+      sandbox: The sandbox.
+      counter: Zero-based counter of the housekeeping round.
+      duration: The sandbox housekeeping duration in seconds.
+      error: The error that caused the sandbox to housekeeping. If None, the
+        sandbox housekeeping normally.
+      **kwargs: Sandbox-specific properties computed during housekeeping.
+    """
+
+
+class EventHandler(_SandboxEventHandler):
+  """Base class for event handlers of an environment."""
+
+  def on_environment_starting(self, environment: Environment) -> None:
+    """Called when the environment is getting started.
+
+    Args:
+      environment: The environment.
+    """
+
+  def on_environment_start(
+      self,
+      environment: Environment,
+      duration: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when the environment is started.
+
+    Args:
+      environment: The environment.
+      duration: The environment start duration in seconds.
+      error: The error that failed the environment start. If None, the
+        environment started normally.
+    """
+
+  def on_environment_housekeep(
+      self,
+      environment: Environment,
+      counter: int,
+      duration: float,
+      error: BaseException | None,
+      **kwargs
+  ) -> None:
+    """Called when the environment finishes a round of housekeeping.
+
+    Args:
+      environment: The environment.
+      counter: Zero-based counter of the housekeeping round.
+      duration: The environment start duration in seconds.
+      error: The error that failed the housekeeping. If None, the
+        housekeeping succeeded.
+      **kwargs: Environment-specific properties computed during housekeeping.
+    """
+
+  def on_environment_shutting_down(
+      self,
+      environment: Environment,
+      offline_duration: float,
+  ) -> None:
+    """Called when the environment is shutting down.
+
+    Args:
+      environment: The environment.
+      offline_duration: The environment offline duration in seconds.
+    """
+
+  def on_environment_shutdown(
+      self,
+      environment: Environment,
+      duration: float,
+      lifetime: float,
+      error: BaseException | None
+  ) -> None:
+    """Called when the environment is shutdown.
+
+    Args:
+      environment: The environment.
+      duration: The environment shutdown duration in seconds.
+      lifetime: The environment lifetime in seconds.
+      error: The error that caused the environment to shutdown. If None, the
+        environment shutdown normally.
+    """

langfun/env/test_utils.py

@@ -21,7 +21,6 @@ from langfun.env import base_environment
 from langfun.env import base_feature
 from langfun.env import base_sandbox
 from langfun.env import interface
-from langfun.env.event_handlers import base as event_handler_base
 import pyglove as pg
 
 
@@ -221,9 +220,7 @@ class TestingFeature(base_feature.BaseFeature):
       )
 
 
-class TestingEventHandler(
-    pg.Object, event_handler_base.EventHandler
-):
+class TestingEventHandler(pg.Object, interface.EventHandler):
   """Testing environment event handler for unit tests."""
 
   log_sandbox_status: bool = False

{langfun-0.1.2.dev202510310805.dist-info → langfun-0.1.2.dev202511010804.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langfun
-Version: 0.1.2.dev202510310805
+Version: 0.1.2.dev202511010804
 Summary: Langfun: Language as Functions.
 Home-page: https://github.com/google/langfun
 Author: Langfun Authors

{langfun-0.1.2.dev202510310805.dist-info → langfun-0.1.2.dev202511010804.dist-info}/RECORD

@@ -174,24 +174,26 @@ langfun/core/templates/demonstration.py,sha256=vCrgYubdZM5Umqcgp8NUVGXgr4P_c-fik
 langfun/core/templates/demonstration_test.py,sha256=SafcDQ0WgI7pw05EmPI2S4v1t3ABKzup8jReCljHeK4,2162
 langfun/core/templates/selfplay.py,sha256=yhgrJbiYwq47TgzThmHrDQTF4nDrTI09CWGhuQPNv-s,2273
 langfun/core/templates/selfplay_test.py,sha256=Ot__1P1M8oJfoTp-M9-PQ6HUXqZKyMwvZ5f7yQ3yfyM,2326
-langfun/env/__init__.py,sha256=VTjLmS_SkxtkBCmr6hBb4iACeLLPmcbWJkK7MEXsATA,1652
-langfun/env/base_environment.py,sha256=8Cpwb4D37zHj5AK4qgmGIPyxIMEDxTIPHXqxTSNkE_M,25030
-langfun/env/base_feature.py,sha256=JDEhL9LkbBHB0c603guchry7cy_zaIReg5vqExyQQgg,6902
-langfun/env/base_sandbox.py,sha256=0dduNozBtPqawvSX-pv6sEweDNTi89lrT_5qKk5FWak,30656
-langfun/env/base_test.py,sha256=6yHtExP3Soa-l0ug73ZSV9ZfS0B4vu-uaS_K_xvsDwk,74261
-langfun/env/interface.py,sha256=2X-gGD41cnejde5DIQ7QxgW3r85oKP4Gp0iWP-ABmLM,32126
+langfun/env/__init__.py,sha256=EOKAU4CrlUAQtGORBaXXP1q_fAS6NHd6rIMOnRwWrjg,1688
+langfun/env/base_environment.py,sha256=vU0IL6-Fmx7xAYeefRLPSjMfwuhCz5b23h5T1HeILTk,24742
+langfun/env/base_environment_test.py,sha256=zXaCMA6JrWFtit68SESx_jGWzO6h7NQZpux4FqCMueQ,15432
+langfun/env/base_feature.py,sha256=5vC-zXYRaImh_nAc0mkgV9vW4ObKYarLUepQeCVAEMw,8189
+langfun/env/base_sandbox.py,sha256=-TZZ4JeQ5PaH0qhfF_HxPPosAHAJLfyD7rGETrbyYhQ,28015
+langfun/env/base_sandbox_test.py,sha256=zs3HL90dyp2YybEhS7splyQNmODSO8J1B8BT8KUBlAY,59450
+langfun/env/interface.py,sha256=zjmrXJcN2cV7a-Ja3V1b-JdpKA11ajWQqk46obHxfsI,41656
 langfun/env/interface_test.py,sha256=d8vdXL1PkrNQGwzfEI2r6esd6SBnTMgc-3GNArsnuj4,3295
 langfun/env/load_balancers.py,sha256=qRhCthqzjZIQBwta8qC1C0s0J-VQAVomJQqI7Nqv-r4,1948
 langfun/env/load_balancers_test.py,sha256=Bg0h-AL7LpWb_aixFXs_FpgQp4dWLvodcsQj-mys6zs,4125
-langfun/env/test_utils.py,sha256=9fqhxxKERiyAte9bbtwqXqZ1ihNGyuOdCiPPY8G0I8w,14171
-langfun/env/event_handlers/__init__.py,sha256=H34n-TbKSgtxqBhE-yAti8fY6weF2_v3yw59M9_zmGM,443
-langfun/env/event_handlers/base.py,sha256=eGdJ6N5em9kX-c9wzm1TdnRP5_5IAltX5JTHILdjzLM,10124
-langfun/env/event_handlers/event_logger.py,sha256=3dbPjBe53dBgntYHlyLlj_77hVecPSXkmKeiGXMxlO0,12699
-langfun/env/event_handlers/event_logger_test.py,sha256=ryupxaEP9D8wdtSsSwZRSZwqFaHCaSD-bFSea_T7QJo,9133
-langfun/env/event_handlers/metric_writer.py,sha256=F_Gk1lpJX5SZ6-Hyrf_-utf4gvSKvMmcov8VkKogZCU,19618
-langfun/env/event_handlers/metric_writer_test.py,sha256=sntUifTPHGixUshIgVBX4Q9vJL-xbeS0Cpd5X5hSQyQ,5955
-langfun-0.1.2.dev202510310805.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-langfun-0.1.2.dev202510310805.dist-info/METADATA,sha256=IKnFNK0k4M96hXuSz3sVo6QOFf9z36tKYsRaeJNvKqg,7522
-langfun-0.1.2.dev202510310805.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-langfun-0.1.2.dev202510310805.dist-info/top_level.txt,sha256=RhlEkHxs1qtzmmtWSwYoLVJAc1YrbPtxQ52uh8Z9VvY,8
-langfun-0.1.2.dev202510310805.dist-info/RECORD,,
+langfun/env/test_utils.py,sha256=i6OadjYfLl5IBrDhEzWiJWsq_GWlplHnrBDD0LEB_HM,14090
+langfun/env/event_handlers/__init__.py,sha256=EE3pV0BlhvYfTG3njhVTMqj88IO_gwjLqZDGSGL95DE,449
+langfun/env/event_handlers/chain.py,sha256=elOAeY38rL0PzNKBq-jwsEqb6ZLE0aOI0LkRSQlQofs,7608
+langfun/env/event_handlers/chain_test.py,sha256=FI0hnDdzmyPe6nEJDeVDrczM49SL9Mhch3STCtgNp7w,8657
+langfun/env/event_handlers/event_logger.py,sha256=J5v9qPZk20ZscYU1Ko0cHaYaRa45Yurz9y8Yn-UATpY,12879
+langfun/env/event_handlers/event_logger_test.py,sha256=HDSO09eFEKIdMYSM_8UHDKhNhSXuqM6Tif63d0kAGjs,9130
+langfun/env/event_handlers/metric_writer.py,sha256=ABxvIkCJXtGpVb2KoaMqc61yMPhaHCoWB1gQraUqlEk,19793
+langfun/env/event_handlers/metric_writer_test.py,sha256=bjdYXoXMPWpWz_-HUPM6vFP1ez5G386u0fmPfe-SR_M,5952
+langfun-0.1.2.dev202511010804.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+langfun-0.1.2.dev202511010804.dist-info/METADATA,sha256=GkWja_YtYyrdLzgc8XtzAn4aL8nSz01TSIdgxZIq7iA,7522
+langfun-0.1.2.dev202511010804.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+langfun-0.1.2.dev202511010804.dist-info/top_level.txt,sha256=RhlEkHxs1qtzmmtWSwYoLVJAc1YrbPtxQ52uh8Z9VvY,8
+langfun-0.1.2.dev202511010804.dist-info/RECORD,,