class_docstr: A Python execution environment.
  
  Encapsulates a namespace for variable lookup
class_docstr_tok: ["A","Python","execution","environment",".","Encapsulates","a","namespace","for","variable","lookup"]
docstr: Capture an execution environment from the stack.
  
  Parameters
  ----------
  eval_env :
      If `eval_env` is already an `Environment`, it is
      returned unchanged.
  
      Otherwise, we walk up the stack by `eval_env` steps and capture
      that function's evaluation environment.
docstr_tok: ["Capture","an","execution","environment","from","the","stack",".","Parameters","--","--","--","--","--","eval_env",":","If","`","eval_env","`","is","already","an","`","Environment","`",",","it","is","returned","unchanged",".","Otherwise",",","we","walk","up","the","stack","by","`","eval_env","`","steps","and","capture","that","function","'s","evaluation","environment","."]
code: def capture(cls, eval_env: int | Self = 0):
      """
      Capture an execution environment from the stack.
  
      Parameters
      ----------
      eval_env :
          If `eval_env` is already an `Environment`, it is
          returned unchanged.
  
          Otherwise, we walk up the stack by `eval_env` steps and capture
          that function's evaluation environment.
  
      """
      import inspect
  
      if isinstance(eval_env, cls):
          return eval_env
  
      frame = inspect.currentframe()
      frame_msg = "call-stack is not that deep!"
      if frame is None:
          raise ValueError(frame_msg)
  
      try:
          for i in range(eval_env + 1):
              frame = frame.f_back
              if frame is None:
                  raise ValueError(frame_msg)
          return cls([frame.f_locals, frame.f_globals])
  
      # The try/finally is important to avoid a potential reference cycle --
      # any exception traceback will carry a reference to *our* frame, which
      # contains a reference to our local variables, which would otherwise
      # carry a reference to some parent frame, where the exception was
      # caught...:
      finally:
          del frame
  
imports: from __future__ import annotations
  from collections.abc import MutableMapping
  from contextlib import suppress
  from dataclasses import dataclass
  from functools import lru_cache
  from typing import TYPE_CHECKING
label_desc: Use image node_id 4 for calling the Environment obj's underlying member method code with example usage: obj.capture(cls, eval_env) and returns: eval_env, cls