Add files using upload-large-folder tool

lib/python3.12/site-packages/IPython/__init__.py

@@ -0,0 +1,144 @@
+# PYTHON_ARGCOMPLETE_OK
+"""
+IPython: tools for interactive and parallel computing in Python.
+
+https://ipython.org
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2008-2011, IPython Development Team.
+#  Copyright (c) 2001-2007, Fernando Perez <fernando.perez@colorado.edu>
+#  Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
+#  Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
+#
+#  Distributed under the terms of the Modified BSD License.
+#
+#  The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import sys
+import warnings
+
+#-----------------------------------------------------------------------------
+# Setup everything
+#-----------------------------------------------------------------------------
+
+# Don't forget to also update setup.py when this changes!
+if sys.version_info < (3, 11):
+    raise ImportError(
+        """
+IPython 8.31+ supports Python 3.11 and above, following SPEC0
+IPython 8.19+ supports Python 3.10 and above, following SPEC0.
+IPython 8.13+ supports Python 3.9 and above, following NEP 29.
+IPython 8.0-8.12 supports Python 3.8 and above, following NEP 29.
+When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
+Python 3.3 and 3.4 were supported up to IPython 6.x.
+Python 3.5 was supported with IPython 7.0 to 7.9.
+Python 3.6 was supported with IPython up to 7.16.
+Python 3.7 was still supported with the 7.x branch.
+
+See IPython `README.rst` file for more information:
+
+    https://github.com/ipython/ipython/blob/main/README.rst
+
+"""
+    )
+
+#-----------------------------------------------------------------------------
+# Setup the top level names
+#-----------------------------------------------------------------------------
+
+from .core.getipython import get_ipython
+from .core import release
+from .core.application import Application
+from .terminal.embed import embed
+
+from .core.interactiveshell import InteractiveShell
+from .utils.sysinfo import sys_info
+from .utils.frame import extract_module_locals
+
+__all__ = ["start_ipython", "embed", "embed_kernel"]
+
+# Release data
+__author__ = '%s <%s>' % (release.author, release.author_email)
+__license__  = release.license
+__version__  = release.version
+version_info = release.version_info
+# list of CVEs that should have been patched in this release.
+# this is informational and should not be relied upon.
+__patched_cves__ = {"CVE-2022-21699", "CVE-2023-24816"}
+
+
+def embed_kernel(module=None, local_ns=None, **kwargs):
+    """Embed and start an IPython kernel in a given scope.
+
+    If you don't want the kernel to initialize the namespace
+    from the scope of the surrounding function,
+    and/or you want to load full IPython configuration,
+    you probably want `IPython.start_kernel()` instead.
+
+    This is a deprecated alias for `ipykernel.embed.embed_kernel()`,
+    to be removed in the future.
+    You should import directly from `ipykernel.embed`; this wrapper
+    fails anyway if you don't have `ipykernel` package installed.
+
+    Parameters
+    ----------
+    module : types.ModuleType, optional
+        The module to load into IPython globals (default: caller)
+    local_ns : dict, optional
+        The namespace to load into IPython user namespace (default: caller)
+    **kwargs : various, optional
+        Further keyword args are relayed to the IPKernelApp constructor,
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the kernel.  Will only have an effect
+        on the first embed_kernel call for a given process.
+    """
+
+    warnings.warn(
+        "import embed_kernel from ipykernel.embed directly (since 2013)."
+        " Importing from IPython will be removed in the future",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    (caller_module, caller_locals) = extract_module_locals(1)
+    if module is None:
+        module = caller_module
+    if local_ns is None:
+        local_ns = dict(**caller_locals)
+    
+    # Only import .zmq when we really need it
+    from ipykernel.embed import embed_kernel as real_embed_kernel
+    real_embed_kernel(module=module, local_ns=local_ns, **kwargs)
+
+def start_ipython(argv=None, **kwargs):
+    """Launch a normal IPython instance (as opposed to embedded)
+
+    `IPython.embed()` puts a shell in a particular calling scope,
+    such as a function or method for debugging purposes,
+    which is often not desirable.
+
+    `start_ipython()` does full, regular IPython initialization,
+    including loading startup files, configuration, etc.
+    much of which is skipped by `embed()`.
+
+    This is a public API method, and will survive implementation changes.
+
+    Parameters
+    ----------
+    argv : list or None, optional
+        If unspecified or None, IPython will parse command-line options from sys.argv.
+        To prevent any command-line parsing, pass an empty list: `argv=[]`.
+    user_ns : dict, optional
+        specify this dictionary to initialize the IPython user namespace with particular values.
+    **kwargs : various, optional
+        Any other kwargs will be passed to the Application constructor,
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the instance (see :ref:`terminal_options`).
+    """
+    from IPython.terminal.ipapp import launch_new_instance
+    return launch_new_instance(argv=argv, **kwargs)

lib/python3.12/site-packages/IPython/__main__.py

@@ -0,0 +1,14 @@
+# PYTHON_ARGCOMPLETE_OK
+# encoding: utf-8
+"""Terminal-based IPython entry point."""
+# -----------------------------------------------------------------------------
+#  Copyright (c) 2012, IPython Development Team.
+#
+#  Distributed under the terms of the Modified BSD License.
+#
+#  The full license is in the file COPYING.txt, distributed with this software.
+# -----------------------------------------------------------------------------
+
+from IPython import start_ipython
+
+start_ipython()

lib/python3.12/site-packages/IPython/core/compilerop.py

@@ -0,0 +1,192 @@
+"""Compiler tools with improved interactive support.
+
+Provides compilation machinery similar to codeop, but with caching support so
+we can provide interactive tracebacks.
+
+Authors
+-------
+* Robert Kern
+* Fernando Perez
+* Thomas Kluyver
+"""
+
+# Note: though it might be more natural to name this module 'compiler', that
+# name is in the stdlib and name collisions with the stdlib tend to produce
+# weird problems (often with third-party tools).
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2010-2011 The IPython Development Team.
+#
+#  Distributed under the terms of the BSD License.
+#
+#  The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib imports
+import __future__
+from ast import PyCF_ONLY_AST
+import codeop
+import functools
+import hashlib
+import linecache
+import operator
+import time
+from contextlib import contextmanager
+
+#-----------------------------------------------------------------------------
+# Constants
+#-----------------------------------------------------------------------------
+
+# Roughly equal to PyCF_MASK | PyCF_MASK_OBSOLETE as defined in pythonrun.h,
+# this is used as a bitmask to extract future-related code flags.
+PyCF_MASK = functools.reduce(operator.or_,
+                             (getattr(__future__, fname).compiler_flag
+                              for fname in __future__.all_feature_names))
+
+#-----------------------------------------------------------------------------
+# Local utilities
+#-----------------------------------------------------------------------------
+
+def code_name(code, number=0):
+    """ Compute a (probably) unique name for code for caching.
+
+    This now expects code to be unicode.
+    """
+    hash_digest = hashlib.sha1(code.encode("utf-8")).hexdigest()
+    # Include the number and 12 characters of the hash in the name.  It's
+    # pretty much impossible that in a single session we'll have collisions
+    # even with truncated hashes, and the full one makes tracebacks too long
+    return '<ipython-input-{0}-{1}>'.format(number, hash_digest[:12])
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+class CachingCompiler(codeop.Compile):
+    """A compiler that caches code compiled from interactive statements.
+    """
+
+    def __init__(self):
+        codeop.Compile.__init__(self)
+
+        # Caching a dictionary { filename: execution_count } for nicely
+        # rendered tracebacks. The filename corresponds to the filename
+        # argument used for the builtins.compile function.
+        self._filename_map = {}
+
+    def ast_parse(self, source, filename='<unknown>', symbol='exec'):
+        """Parse code to an AST with the current compiler flags active.
+
+        Arguments are exactly the same as ast.parse (in the standard library),
+        and are passed to the built-in compile function."""
+        return compile(source, filename, symbol, self.flags | PyCF_ONLY_AST, 1)
+
+    def reset_compiler_flags(self):
+        """Reset compiler flags to default state."""
+        # This value is copied from codeop.Compile.__init__, so if that ever
+        # changes, it will need to be updated.
+        self.flags = codeop.PyCF_DONT_IMPLY_DEDENT
+
+    @property
+    def compiler_flags(self):
+        """Flags currently active in the compilation process.
+        """
+        return self.flags
+
+    def get_code_name(self, raw_code, transformed_code, number):
+        """Compute filename given the code, and the cell number.
+
+        Parameters
+        ----------
+        raw_code : str
+            The raw cell code.
+        transformed_code : str
+            The executable Python source code to cache and compile.
+        number : int
+            A number which forms part of the code's name. Used for the execution
+            counter.
+
+        Returns
+        -------
+        The computed filename.
+        """
+        return code_name(transformed_code, number)
+
+    def format_code_name(self, name):
+        """Return a user-friendly label and name for a code block.
+
+        Parameters
+        ----------
+        name : str
+            The name for the code block returned from get_code_name
+
+        Returns
+        -------
+        A (label, name) pair that can be used in tracebacks, or None if the default formatting should be used.
+        """
+        if name in self._filename_map:
+            return "Cell", "In[%s]" % self._filename_map[name]
+
+    def cache(self, transformed_code, number=0, raw_code=None):
+        """Make a name for a block of code, and cache the code.
+
+        Parameters
+        ----------
+        transformed_code : str
+            The executable Python source code to cache and compile.
+        number : int
+            A number which forms part of the code's name. Used for the execution
+            counter.
+        raw_code : str
+            The raw code before transformation, if None, set to `transformed_code`.
+
+        Returns
+        -------
+        The name of the cached code (as a string). Pass this as the filename
+        argument to compilation, so that tracebacks are correctly hooked up.
+        """
+        if raw_code is None:
+            raw_code = transformed_code
+
+        name = self.get_code_name(raw_code, transformed_code, number)
+
+        # Save the execution count
+        self._filename_map[name] = number
+
+        # Since Python 2.5, setting mtime to `None` means the lines will
+        # never be removed by `linecache.checkcache`.  This means all the
+        # monkeypatching has *never* been necessary, since this code was
+        # only added in 2010, at which point IPython had already stopped
+        # supporting Python 2.4.
+        #
+        # Note that `linecache.clearcache` and `linecache.updatecache` may
+        # still remove our code from the cache, but those show explicit
+        # intent, and we should not try to interfere.  Normally the former
+        # is never called except when out of memory, and the latter is only
+        # called for lines *not* in the cache.
+        entry = (
+            len(transformed_code),
+            None,
+            [line + "\n" for line in transformed_code.splitlines()],
+            name,
+        )
+        linecache.cache[name] = entry
+        return name
+
+    @contextmanager
+    def extra_flags(self, flags):
+        ## bits that we'll set to 1
+        turn_on_bits = ~self.flags & flags
+
+
+        self.flags = self.flags | flags
+        try:
+            yield
+        finally:
+            # turn off only the bits we turned on so that something like
+            # __future__ that set flags stays.
+            self.flags &= ~turn_on_bits

lib/python3.12/site-packages/IPython/core/crashhandler.py

@@ -0,0 +1,244 @@
+"""sys.excepthook for IPython itself, leaves a detailed report on disk.
+
+Authors:
+
+* Fernando Perez
+* Brian E. Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
+#  Copyright (C) 2008-2011  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import sys
+import traceback
+from pprint import pformat
+from pathlib import Path
+
+import builtins as builtin_mod
+
+from IPython.core import ultratb
+from IPython.core.application import Application
+from IPython.core.release import author_email
+from IPython.utils.sysinfo import sys_info
+
+from IPython.core.release import __version__ as version
+
+from typing import Optional, Dict
+import types
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+# Template for the user message.
+_default_message_template = """\
+Oops, {app_name} crashed. We do our best to make it stable, but...
+
+A crash report was automatically generated with the following information:
+  - A verbatim copy of the crash traceback.
+  - A copy of your input history during this session.
+  - Data on your current {app_name} configuration.
+
+It was left in the file named:
+\t'{crash_report_fname}'
+If you can email this file to the developers, the information in it will help
+them in understanding and correcting the problem.
+
+You can mail it to: {contact_name} at {contact_email}
+with the subject '{app_name} Crash Report'.
+
+If you want to do it now, the following command will work (under Unix):
+mail -s '{app_name} Crash Report' {contact_email} < {crash_report_fname}
+
+In your email, please also include information about:
+- The operating system under which the crash happened: Linux, macOS, Windows,
+  other, and which exact version (for example: Ubuntu 16.04.3, macOS 10.13.2,
+  Windows 10 Pro), and whether it is 32-bit or 64-bit;
+- How {app_name} was installed: using pip or conda, from GitHub, as part of
+  a Docker container, or other, providing more detail if possible;
+- How to reproduce the crash: what exact sequence of instructions can one
+  input to get the same crash? Ideally, find a minimal yet complete sequence
+  of instructions that yields the crash.
+
+To ensure accurate tracking of this issue, please file a report about it at:
+{bug_tracker}
+"""
+
+_lite_message_template = """
+If you suspect this is an IPython {version} bug, please report it at:
+    https://github.com/ipython/ipython/issues
+or send an email to the mailing list at {email}
+
+You can print a more detailed traceback right now with "%tb", or use "%debug"
+to interactively debug it.
+
+Extra-detailed tracebacks for bug-reporting purposes can be enabled via:
+    {config}Application.verbose_crash=True
+"""
+
+
+class CrashHandler:
+    """Customizable crash handlers for IPython applications.
+
+    Instances of this class provide a :meth:`__call__` method which can be
+    used as a ``sys.excepthook``.  The :meth:`__call__` signature is::
+
+        def __call__(self, etype, evalue, etb)
+    """
+
+    message_template = _default_message_template
+    section_sep = '\n\n'+'*'*75+'\n\n'
+    info: Dict[str, Optional[str]]
+
+    def __init__(
+        self,
+        app: Application,
+        contact_name: Optional[str] = None,
+        contact_email: Optional[str] = None,
+        bug_tracker: Optional[str] = None,
+        show_crash_traceback: bool = True,
+        call_pdb: bool = False,
+    ):
+        """Create a new crash handler
+
+        Parameters
+        ----------
+        app : Application
+            A running :class:`Application` instance, which will be queried at
+            crash time for internal information.
+        contact_name : str
+            A string with the name of the person to contact.
+        contact_email : str
+            A string with the email address of the contact.
+        bug_tracker : str
+            A string with the URL for your project's bug tracker.
+        show_crash_traceback : bool
+            If false, don't print the crash traceback on stderr, only generate
+            the on-disk report
+        call_pdb
+            Whether to call pdb on crash
+
+        Attributes
+        ----------
+        These instances contain some non-argument attributes which allow for
+        further customization of the crash handler's behavior. Please see the
+        source for further details.
+
+        """
+        self.crash_report_fname = "Crash_report_%s.txt" % app.name
+        self.app = app
+        self.call_pdb = call_pdb
+        #self.call_pdb = True # dbg
+        self.show_crash_traceback = show_crash_traceback
+        self.info = dict(app_name = app.name,
+                    contact_name = contact_name,
+                    contact_email = contact_email,
+                    bug_tracker = bug_tracker,
+                    crash_report_fname = self.crash_report_fname)
+
+    def __call__(
+        self,
+        etype: type[BaseException],
+        evalue: BaseException,
+        etb: types.TracebackType,
+    ) -> None:
+        """Handle an exception, call for compatible with sys.excepthook"""
+
+        # do not allow the crash handler to be called twice without reinstalling it
+        # this prevents unlikely errors in the crash handling from entering an
+        # infinite loop.
+        sys.excepthook = sys.__excepthook__
+        
+
+        # Use this ONLY for developer debugging (keep commented out for release)
+        ipython_dir = getattr(self.app, "ipython_dir", None)
+        if ipython_dir is not None:
+            assert isinstance(ipython_dir, str)
+            rptdir = Path(ipython_dir)
+        else:
+            rptdir = Path.cwd()
+        if not rptdir.is_dir():
+            rptdir = Path.cwd()
+        report_name = rptdir / self.crash_report_fname
+        # write the report filename into the instance dict so it can get
+        # properly expanded out in the user message template
+        self.crash_report_fname = str(report_name)
+        self.info["crash_report_fname"] = str(report_name)
+        TBhandler = ultratb.VerboseTB(
+            theme_name="nocolor",
+            long_header=True,
+            call_pdb=self.call_pdb,
+        )
+        if self.call_pdb:
+            TBhandler(etype,evalue,etb)
+            return
+        else:
+            traceback = TBhandler.text(etype,evalue,etb,context=31)
+
+        # print traceback to screen
+        if self.show_crash_traceback:
+            print(traceback, file=sys.stderr)
+
+        # and generate a complete report on disk
+        try:
+            report = open(report_name, "w", encoding="utf-8")
+        except:
+            print('Could not create crash report on disk.', file=sys.stderr)
+            return
+
+        with report:
+            # Inform user on stderr of what happened
+            print('\n'+'*'*70+'\n', file=sys.stderr)
+            print(self.message_template.format(**self.info), file=sys.stderr)
+
+            # Construct report on disk
+            report.write(self.make_report(str(traceback)))
+
+        builtin_mod.input("Hit <Enter> to quit (your terminal may close):")
+
+    def make_report(self, traceback: str) -> str:
+        """Return a string containing a crash report."""
+
+        sec_sep = self.section_sep
+
+        report = ['*'*75+'\n\n'+'IPython post-mortem report\n\n']
+        rpt_add = report.append
+        rpt_add(sys_info())
+
+        try:
+            config = pformat(self.app.config)
+            rpt_add(sec_sep)
+            rpt_add("Application name: %s\n\n" % self.app.name)
+            rpt_add("Current user configuration structure:\n\n")
+            rpt_add(config)
+        except:
+            pass
+        rpt_add(sec_sep+'Crash traceback:\n\n' + traceback)
+
+        return ''.join(report)
+
+
+def crash_handler_lite(
+    etype: type[BaseException], evalue: BaseException, tb: types.TracebackType
+) -> None:
+    """a light excepthook, adding a small message to the usual traceback"""
+    traceback.print_exception(etype, evalue, tb)
+    
+    from IPython.core.interactiveshell import InteractiveShell
+    if InteractiveShell.initialized():
+        # we are in a Shell environment, give %magic example
+        config = "%config "
+    else:
+        # we are not in a shell, show generic config
+        config = "c."
+    print(_lite_message_template.format(email=author_email, config=config, version=version), file=sys.stderr)
+

lib/python3.12/site-packages/IPython/core/displaypub.py

@@ -0,0 +1,205 @@
+"""An interface for publishing rich data to frontends.
+
+There are two components of the display system:
+
+* Display formatters, which take a Python object and compute the
+  representation of the object in various formats (text, HTML, SVG, etc.).
+* The display publisher that is used to send the representation data to the
+  various frontends.
+
+This module defines the logic display publishing. The display publisher uses
+the ``display_data`` message type that is defined in the IPython messaging
+spec.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import sys
+
+from traitlets.config.configurable import Configurable
+from traitlets import List
+
+# This used to be defined here - it is imported for backwards compatibility
+from .display_functions import publish_display_data
+from .history import HistoryOutput
+
+import typing as t
+
+# -----------------------------------------------------------------------------
+# Main payload class
+# -----------------------------------------------------------------------------
+
+_sentinel = object()
+
+
+class DisplayPublisher(Configurable):
+    """A traited class that publishes display data to frontends.
+
+    Instances of this class are created by the main IPython object and should
+    be accessed there.
+    """
+
+    def __init__(self, shell=None, *args, **kwargs):
+        self.shell = shell
+        self._is_publishing = False
+        self._in_post_execute = False
+        if self.shell:
+            self._setup_execution_tracking()
+        super().__init__(*args, **kwargs)
+
+    def _validate_data(self, data, metadata=None):
+        """Validate the display data.
+
+        Parameters
+        ----------
+        data : dict
+            The formata data dictionary.
+        metadata : dict
+            Any metadata for the data.
+        """
+
+        if not isinstance(data, dict):
+            raise TypeError("data must be a dict, got: %r" % data)
+        if metadata is not None:
+            if not isinstance(metadata, dict):
+                raise TypeError("metadata must be a dict, got: %r" % data)
+
+    def _setup_execution_tracking(self):
+        """Set up hooks to track execution state"""
+        self.shell.events.register("post_execute", self._on_post_execute)
+        self.shell.events.register("pre_execute", self._on_pre_execute)
+
+    def _on_post_execute(self):
+        """Called at start of post_execute phase"""
+        self._in_post_execute = True
+
+    def _on_pre_execute(self):
+        """Called at start of pre_execute phase"""
+        self._in_post_execute = False
+
+    # use * to indicate transient, update are keyword-only
+    def publish(
+        self,
+        data,
+        metadata=None,
+        source=_sentinel,
+        *,
+        transient=None,
+        update=False,
+        **kwargs,
+    ) -> None:
+        """Publish data and metadata to all frontends.
+
+        See the ``display_data`` message in the messaging documentation for
+        more details about this message type.
+
+        The following MIME types are currently implemented:
+
+        * text/plain
+        * text/html
+        * text/markdown
+        * text/latex
+        * application/json
+        * application/javascript
+        * image/png
+        * image/jpeg
+        * image/svg+xml
+
+        Parameters
+        ----------
+        data : dict
+            A dictionary having keys that are valid MIME types (like
+            'text/plain' or 'image/svg+xml') and values that are the data for
+            that MIME type. The data itself must be a JSON'able data
+            structure. Minimally all data should have the 'text/plain' data,
+            which can be displayed by all frontends. If more than the plain
+            text is given, it is up to the frontend to decide which
+            representation to use.
+        metadata : dict
+            A dictionary for metadata related to the data. This can contain
+            arbitrary key, value pairs that frontends can use to interpret
+            the data.  Metadata specific to each mime-type can be specified
+            in the metadata dict with the same mime-type keys as
+            the data itself.
+        source : str, deprecated
+            Unused.
+        transient : dict, keyword-only
+            A dictionary for transient data.
+            Data in this dictionary should not be persisted as part of saving this output.
+            Examples include 'display_id'.
+        update : bool, keyword-only, default: False
+            If True, only update existing outputs with the same display_id,
+            rather than creating a new output.
+        """
+
+        if source is not _sentinel:
+            import warnings
+
+            warnings.warn(
+                "The 'source' parameter is deprecated since IPython 3.0 and will be ignored "
+                "(this warning is present since 9.0). `source` parameter will be removed in the future.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        handlers: t.Dict = {}
+        if self.shell is not None:
+            handlers = getattr(self.shell, "mime_renderers", {})
+
+        outputs = self.shell.history_manager.outputs
+
+        target_execution_count = self.shell.execution_count - 1
+        if self._in_post_execute:
+            # We're in post_execute, so this is likely a matplotlib flush
+            # Use execution_count - 1 to associate with the cell that created the plot
+            target_execution_count = self.shell.execution_count - 1
+
+        outputs[target_execution_count].append(
+            HistoryOutput(output_type="display_data", bundle=data)
+        )
+
+        for mime, handler in handlers.items():
+            if mime in data:
+                handler(data[mime], metadata.get(mime, None))
+                return
+
+        self._is_publishing = True
+        if "text/plain" in data:
+            print(data["text/plain"])
+        self._is_publishing = False
+
+    @property
+    def is_publishing(self):
+        return self._is_publishing
+
+    def clear_output(self, wait=False):
+        """Clear the output of the cell receiving output."""
+        print("\033[2K\r", end="")
+        sys.stdout.flush()
+        print("\033[2K\r", end="")
+        sys.stderr.flush()
+
+
+class CapturingDisplayPublisher(DisplayPublisher):
+    """A DisplayPublisher that stores"""
+
+    outputs: List = List()
+
+    def publish(
+        self, data, metadata=None, source=None, *, transient=None, update=False
+    ):
+        self.outputs.append(
+            {
+                "data": data,
+                "metadata": metadata,
+                "transient": transient,
+                "update": update,
+            }
+        )
+
+    def clear_output(self, wait=False):
+        super(CapturingDisplayPublisher, self).clear_output(wait)
+
+        # empty the list, *do not* reassign a new list
+        self.outputs.clear()

lib/python3.12/site-packages/IPython/core/getipython.py

@@ -0,0 +1,23 @@
+"""Simple function to call to get the current InteractiveShell instance
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2013  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+
+def get_ipython():
+    """Get the global InteractiveShell instance.
+
+    Returns None if no InteractiveShell instance is registered.
+    """
+    from IPython.core.interactiveshell import InteractiveShell
+    if InteractiveShell.initialized():
+        return InteractiveShell.instance()

lib/python3.12/site-packages/IPython/core/guarded_eval.py

@@ -0,0 +1,1656 @@
+from copy import copy
+from inspect import isclass, signature, Signature, getmodule
+from typing import (
+    Annotated,
+    AnyStr,
+    Literal,
+    NamedTuple,
+    NewType,
+    Optional,
+    Protocol,
+    TypeGuard,
+    Union,
+    get_args,
+    get_origin,
+    is_typeddict,
+)
+from collections.abc import Callable, Sequence
+import ast
+import builtins
+import collections
+import dataclasses
+import operator
+import sys
+import typing
+import warnings
+from functools import cached_property
+from dataclasses import dataclass, field
+from types import MethodDescriptorType, ModuleType, MethodType
+
+from IPython.utils.decorators import undoc
+
+import types
+from typing import Self, LiteralString, get_type_hints
+
+if sys.version_info < (3, 12):
+    from typing_extensions import TypeAliasType
+else:
+    from typing import TypeAliasType
+
+
+@undoc
+class HasGetItem(Protocol):
+    def __getitem__(self, key) -> None:
+        ...
+
+
+@undoc
+class InstancesHaveGetItem(Protocol):
+    def __call__(self, *args, **kwargs) -> HasGetItem:
+        ...
+
+
+@undoc
+class HasGetAttr(Protocol):
+    def __getattr__(self, key) -> None:
+        ...
+
+
+@undoc
+class DoesNotHaveGetAttr(Protocol):
+    pass
+
+
+# By default `__getattr__` is not explicitly implemented on most objects
+MayHaveGetattr = Union[HasGetAttr, DoesNotHaveGetAttr]
+
+
+def _unbind_method(func: Callable) -> Union[Callable, None]:
+    """Get unbound method for given bound method.
+
+    Returns None if cannot get unbound method, or method is already unbound.
+    """
+    owner = getattr(func, "__self__", None)
+    owner_class = type(owner)
+    name = getattr(func, "__name__", None)
+    instance_dict_overrides = getattr(owner, "__dict__", None)
+    if (
+        owner is not None
+        and name
+        and (
+            not instance_dict_overrides
+            or (instance_dict_overrides and name not in instance_dict_overrides)
+        )
+    ):
+        return getattr(owner_class, name)
+    return None
+
+
+@undoc
+@dataclass
+class EvaluationPolicy:
+    """Definition of evaluation policy."""
+
+    allow_locals_access: bool = False
+    allow_globals_access: bool = False
+    allow_item_access: bool = False
+    allow_attr_access: bool = False
+    allow_builtins_access: bool = False
+    allow_all_operations: bool = False
+    allow_any_calls: bool = False
+    allow_auto_import: bool = False
+    allowed_calls: set[Callable] = field(default_factory=set)
+
+    def can_get_item(self, value, item):
+        return self.allow_item_access
+
+    def can_get_attr(self, value, attr):
+        return self.allow_attr_access
+
+    def can_operate(self, dunders: tuple[str, ...], a, b=None):
+        if self.allow_all_operations:
+            return True
+
+    def can_call(self, func):
+        if self.allow_any_calls:
+            return True
+
+        if func in self.allowed_calls:
+            return True
+
+        owner_method = _unbind_method(func)
+
+        if owner_method and owner_method in self.allowed_calls:
+            return True
+
+
+def _get_external(module_name: str, access_path: Sequence[str]):
+    """Get value from external module given a dotted access path.
+
+    Only gets value if the module is already imported.
+
+    Raises:
+    * `KeyError` if module is removed not found, and
+    * `AttributeError` if access path does not match an exported object
+    """
+    try:
+        member_type = sys.modules[module_name]
+        # standard module
+        for attr in access_path:
+            member_type = getattr(member_type, attr)
+        return member_type
+    except (KeyError, AttributeError):
+        # handle modules in namespace packages
+        module_path = ".".join([module_name, *access_path])
+        if module_path in sys.modules:
+            return sys.modules[module_path]
+        raise
+
+
+def _has_original_dunder_external(
+    value,
+    module_name: str,
+    access_path: Sequence[str],
+    method_name: str,
+):
+    if module_name not in sys.modules:
+        full_module_path = ".".join([module_name, *access_path])
+        if full_module_path not in sys.modules:
+            # LBYLB as it is faster
+            return False
+    try:
+        member_type = _get_external(module_name, access_path)
+        value_type = type(value)
+        if type(value) == member_type:
+            return True
+        if isinstance(member_type, ModuleType):
+            value_module = getmodule(value_type)
+            if not value_module or not value_module.__name__:
+                return False
+            if (
+                value_module.__name__ == member_type.__name__
+                or value_module.__name__.startswith(member_type.__name__ + ".")
+            ):
+                return True
+        if method_name == "__getattribute__":
+            # we have to short-circuit here due to an unresolved issue in
+            # `isinstance` implementation: https://bugs.python.org/issue32683
+            return False
+        if not isinstance(member_type, ModuleType) and isinstance(value, member_type):
+            method = getattr(value_type, method_name, None)
+            member_method = getattr(member_type, method_name, None)
+            if member_method == method:
+                return True
+        if isinstance(member_type, ModuleType):
+            method = getattr(value_type, method_name, None)
+            for base_class in value_type.__mro__[1:]:
+                base_module = getmodule(base_class)
+                if base_module and (
+                    base_module.__name__ == member_type.__name__
+                    or base_module.__name__.startswith(member_type.__name__ + ".")
+                ):
+                    # Check if the method comes from this trusted base class
+                    base_method = getattr(base_class, method_name, None)
+                    if base_method is not None and base_method == method:
+                        return True
+    except (AttributeError, KeyError):
+        return False
+
+
+def _has_original_dunder(
+    value, allowed_types, allowed_methods, allowed_external, method_name
+):
+    # note: Python ignores `__getattr__`/`__getitem__` on instances,
+    # we only need to check at class level
+    value_type = type(value)
+
+    # strict type check passes → no need to check method
+    if value_type in allowed_types:
+        return True
+
+    method = getattr(value_type, method_name, None)
+
+    if method is None:
+        return None
+
+    if method in allowed_methods:
+        return True
+
+    for module_name, *access_path in allowed_external:
+        if _has_original_dunder_external(value, module_name, access_path, method_name):
+            return True
+
+    return False
+
+
+def _coerce_path_to_tuples(
+    allow_list: set[tuple[str, ...] | str],
+) -> set[tuple[str, ...]]:
+    """Replace dotted paths on the provided allow-list with tuples."""
+    return {
+        path if isinstance(path, tuple) else tuple(path.split("."))
+        for path in allow_list
+    }
+
+
+@undoc
+@dataclass
+class SelectivePolicy(EvaluationPolicy):
+    allowed_getitem: set[InstancesHaveGetItem] = field(default_factory=set)
+    allowed_getitem_external: set[tuple[str, ...] | str] = field(default_factory=set)
+
+    allowed_getattr: set[MayHaveGetattr] = field(default_factory=set)
+    allowed_getattr_external: set[tuple[str, ...] | str] = field(default_factory=set)
+
+    allowed_operations: set = field(default_factory=set)
+    allowed_operations_external: set[tuple[str, ...] | str] = field(default_factory=set)
+
+    allow_getitem_on_types: bool = field(default_factory=bool)
+
+    _operation_methods_cache: dict[str, set[Callable]] = field(
+        default_factory=dict, init=False
+    )
+
+    def can_get_attr(self, value, attr):
+        allowed_getattr_external = _coerce_path_to_tuples(self.allowed_getattr_external)
+
+        has_original_attribute = _has_original_dunder(
+            value,
+            allowed_types=self.allowed_getattr,
+            allowed_methods=self._getattribute_methods,
+            allowed_external=allowed_getattr_external,
+            method_name="__getattribute__",
+        )
+        has_original_attr = _has_original_dunder(
+            value,
+            allowed_types=self.allowed_getattr,
+            allowed_methods=self._getattr_methods,
+            allowed_external=allowed_getattr_external,
+            method_name="__getattr__",
+        )
+
+        accept = False
+
+        # Many objects do not have `__getattr__`, this is fine.
+        if has_original_attr is None and has_original_attribute:
+            accept = True
+        else:
+            # Accept objects without modifications to `__getattr__` and `__getattribute__`
+            accept = has_original_attr and has_original_attribute
+
+        if accept:
+            # We still need to check for overridden properties.
+
+            value_class = type(value)
+            if not hasattr(value_class, attr):
+                return True
+
+            class_attr_val = getattr(value_class, attr)
+            is_property = isinstance(class_attr_val, property)
+
+            if not is_property:
+                return True
+
+            # Properties in allowed types are ok (although we do not include any
+            # properties in our default allow list currently).
+            if type(value) in self.allowed_getattr:
+                return True  # pragma: no cover
+
+            # Properties in subclasses of allowed types may be ok if not changed
+            for module_name, *access_path in allowed_getattr_external:
+                try:
+                    external_class = _get_external(module_name, access_path)
+                    external_class_attr_val = getattr(external_class, attr)
+                except (KeyError, AttributeError):
+                    return False  # pragma: no cover
+                return class_attr_val == external_class_attr_val
+
+        return False
+
+    def can_get_item(self, value, item):
+        """Allow accessing `__getiitem__` of allow-listed instances unless it was not modified."""
+        allowed_getitem_external = _coerce_path_to_tuples(self.allowed_getitem_external)
+        if self.allow_getitem_on_types:
+            # e.g. Union[str, int] or Literal[True, 1]
+            if isinstance(value, (typing._SpecialForm, typing._BaseGenericAlias)):
+                return True
+            # PEP 560 e.g. list[str]
+            if isinstance(value, type) and hasattr(value, "__class_getitem__"):
+                return True
+        return _has_original_dunder(
+            value,
+            allowed_types=self.allowed_getitem,
+            allowed_methods=self._getitem_methods,
+            allowed_external=allowed_getitem_external,
+            method_name="__getitem__",
+        )
+
+    def can_operate(self, dunders: tuple[str, ...], a, b=None):
+        allowed_operations_external = _coerce_path_to_tuples(
+            self.allowed_operations_external
+        )
+        objects = [a]
+        if b is not None:
+            objects.append(b)
+        return all(
+            [
+                _has_original_dunder(
+                    obj,
+                    allowed_types=self.allowed_operations,
+                    allowed_methods=self._operator_dunder_methods(dunder),
+                    allowed_external=allowed_operations_external,
+                    method_name=dunder,
+                )
+                for dunder in dunders
+                for obj in objects
+            ]
+        )
+
+    def _operator_dunder_methods(self, dunder: str) -> set[Callable]:
+        if dunder not in self._operation_methods_cache:
+            self._operation_methods_cache[dunder] = self._safe_get_methods(
+                self.allowed_operations, dunder
+            )
+        return self._operation_methods_cache[dunder]
+
+    @cached_property
+    def _getitem_methods(self) -> set[Callable]:
+        return self._safe_get_methods(self.allowed_getitem, "__getitem__")
+
+    @cached_property
+    def _getattr_methods(self) -> set[Callable]:
+        return self._safe_get_methods(self.allowed_getattr, "__getattr__")
+
+    @cached_property
+    def _getattribute_methods(self) -> set[Callable]:
+        return self._safe_get_methods(self.allowed_getattr, "__getattribute__")
+
+    def _safe_get_methods(self, classes, name) -> set[Callable]:
+        return {
+            method
+            for class_ in classes
+            for method in [getattr(class_, name, None)]
+            if method
+        }
+
+
+class _DummyNamedTuple(NamedTuple):
+    """Used internally to retrieve methods of named tuple instance."""
+
+
+EvaluationPolicyName = Literal["forbidden", "minimal", "limited", "unsafe", "dangerous"]
+
+
+@dataclass
+class EvaluationContext:
+    #: Local namespace
+    locals: dict
+    #: Global namespace
+    globals: dict
+    #: Evaluation policy identifier
+    evaluation: EvaluationPolicyName = "forbidden"
+    #: Whether the evaluation of code takes place inside of a subscript.
+    #: Useful for evaluating ``:-1, 'col'`` in ``df[:-1, 'col']``.
+    in_subscript: bool = False
+    #: Auto import method
+    auto_import: Callable[[Sequence[str]], ModuleType] | None = None
+    #: Overrides for evaluation policy
+    policy_overrides: dict = field(default_factory=dict)
+    #: Transient local namespace used to store mocks
+    transient_locals: dict = field(default_factory=dict)
+    #: Transients of class level
+    class_transients: dict | None = None
+    #: Instance variable name used in the method definition
+    instance_arg_name: str | None = None
+    #: Currently associated value
+    #: Useful for adding items to _Duck on annotated assignment
+    current_value: ast.AST | None = None
+
+    def replace(self, /, **changes):
+        """Return a new copy of the context, with specified changes"""
+        return dataclasses.replace(self, **changes)
+
+
+class _IdentitySubscript:
+    """Returns the key itself when item is requested via subscript."""
+
+    def __getitem__(self, key):
+        return key
+
+
+IDENTITY_SUBSCRIPT = _IdentitySubscript()
+SUBSCRIPT_MARKER = "__SUBSCRIPT_SENTINEL__"
+UNKNOWN_SIGNATURE = Signature()
+NOT_EVALUATED = object()
+
+
+class GuardRejection(Exception):
+    """Exception raised when guard rejects evaluation attempt."""
+
+    pass
+
+
+def guarded_eval(code: str, context: EvaluationContext):
+    """Evaluate provided code in the evaluation context.
+
+    If evaluation policy given by context is set to ``forbidden``
+    no evaluation will be performed; if it is set to ``dangerous``
+    standard :func:`eval` will be used; finally, for any other,
+    policy :func:`eval_node` will be called on parsed AST.
+    """
+    locals_ = context.locals
+
+    if context.evaluation == "forbidden":
+        raise GuardRejection("Forbidden mode")
+
+    # note: not using `ast.literal_eval` as it does not implement
+    # getitem at all, for example it fails on simple `[0][1]`
+
+    if context.in_subscript:
+        # syntactic sugar for ellipsis (:) is only available in subscripts
+        # so we need to trick the ast parser into thinking that we have
+        # a subscript, but we need to be able to later recognise that we did
+        # it so we can ignore the actual __getitem__ operation
+        if not code:
+            return tuple()
+        locals_ = locals_.copy()
+        locals_[SUBSCRIPT_MARKER] = IDENTITY_SUBSCRIPT
+        code = SUBSCRIPT_MARKER + "[" + code + "]"
+        context = context.replace(locals=locals_)
+
+    if context.evaluation == "dangerous":
+        return eval(code, context.globals, context.locals)
+
+    node = ast.parse(code, mode="exec")
+
+    return eval_node(node, context)
+
+
+BINARY_OP_DUNDERS: dict[type[ast.operator], tuple[str]] = {
+    ast.Add: ("__add__",),
+    ast.Sub: ("__sub__",),
+    ast.Mult: ("__mul__",),
+    ast.Div: ("__truediv__",),
+    ast.FloorDiv: ("__floordiv__",),
+    ast.Mod: ("__mod__",),
+    ast.Pow: ("__pow__",),
+    ast.LShift: ("__lshift__",),
+    ast.RShift: ("__rshift__",),
+    ast.BitOr: ("__or__",),
+    ast.BitXor: ("__xor__",),
+    ast.BitAnd: ("__and__",),
+    ast.MatMult: ("__matmul__",),
+}
+
+COMP_OP_DUNDERS: dict[type[ast.cmpop], tuple[str, ...]] = {
+    ast.Eq: ("__eq__",),
+    ast.NotEq: ("__ne__", "__eq__"),
+    ast.Lt: ("__lt__", "__gt__"),
+    ast.LtE: ("__le__", "__ge__"),
+    ast.Gt: ("__gt__", "__lt__"),
+    ast.GtE: ("__ge__", "__le__"),
+    ast.In: ("__contains__",),
+    # Note: ast.Is, ast.IsNot, ast.NotIn are handled specially
+}
+
+UNARY_OP_DUNDERS: dict[type[ast.unaryop], tuple[str, ...]] = {
+    ast.USub: ("__neg__",),
+    ast.UAdd: ("__pos__",),
+    # we have to check both __inv__ and __invert__!
+    ast.Invert: ("__invert__", "__inv__"),
+    ast.Not: ("__not__",),
+}
+
+GENERIC_CONTAINER_TYPES = (dict, list, set, tuple, frozenset)
+
+
+class ImpersonatingDuck:
+    """A dummy class used to create objects of other classes without calling their ``__init__``"""
+
+    # no-op: override __class__ to impersonate
+
+
+class _Duck:
+    """A dummy class used to create objects pretending to have given attributes"""
+
+    def __init__(self, attributes: Optional[dict] = None, items: Optional[dict] = None):
+        self.attributes = attributes if attributes is not None else {}
+        self.items = items if items is not None else {}
+
+    def __getattr__(self, attr: str):
+        return self.attributes[attr]
+
+    def __hasattr__(self, attr: str):
+        return attr in self.attributes
+
+    def __dir__(self):
+        return [*dir(super), *self.attributes]
+
+    def __getitem__(self, key: str):
+        return self.items[key]
+
+    def __hasitem__(self, key: str):
+        return self.items[key]
+
+    def _ipython_key_completions_(self):
+        return self.items.keys()
+
+
+def _find_dunder(node_op, dunders) -> Union[tuple[str, ...], None]:
+    dunder = None
+    for op, candidate_dunder in dunders.items():
+        if isinstance(node_op, op):
+            dunder = candidate_dunder
+    return dunder
+
+
+def get_policy(context: EvaluationContext) -> EvaluationPolicy:
+    policy = copy(EVALUATION_POLICIES[context.evaluation])
+
+    for key, value in context.policy_overrides.items():
+        if hasattr(policy, key):
+            setattr(policy, key, value)
+    return policy
+
+
+def _validate_policy_overrides(
+    policy_name: EvaluationPolicyName, policy_overrides: dict
+) -> bool:
+    policy = EVALUATION_POLICIES[policy_name]
+
+    all_good = True
+    for key, value in policy_overrides.items():
+        if not hasattr(policy, key):
+            warnings.warn(
+                f"Override {key!r} is not valid with {policy_name!r} evaluation policy"
+            )
+            all_good = False
+    return all_good
+
+
+def _is_type_annotation(obj) -> bool:
+    """
+    Returns True if obj is a type annotation, False otherwise.
+    """
+    if isinstance(obj, type):
+        return True
+    if isinstance(obj, types.GenericAlias):
+        return True
+    if hasattr(types, "UnionType") and isinstance(obj, types.UnionType):
+        return True
+    if isinstance(obj, (typing._SpecialForm, typing._BaseGenericAlias)):
+        return True
+    if isinstance(obj, typing.TypeVar):
+        return True
+    # Types that support __class_getitem__
+    if isinstance(obj, type) and hasattr(obj, "__class_getitem__"):
+        return True
+    # Fallback: check if get_origin returns something
+    if hasattr(typing, "get_origin") and get_origin(obj) is not None:
+        return True
+
+    return False
+
+
+def _handle_assign(node: ast.Assign, context: EvaluationContext):
+    value = eval_node(node.value, context)
+    transient_locals = context.transient_locals
+    policy = get_policy(context)
+    class_transients = context.class_transients
+    for target in node.targets:
+        if isinstance(target, (ast.Tuple, ast.List)):
+            # Handle unpacking assignment
+            values = list(value)
+            targets = target.elts
+            starred = [i for i, t in enumerate(targets) if isinstance(t, ast.Starred)]
+
+            # Unified handling: treat no starred as starred at end
+            star_or_last_idx = starred[0] if starred else len(targets)
+
+            # Before starred
+            for i in range(star_or_last_idx):
+                # Check for self.x assignment
+                if _is_instance_attribute_assignment(targets[i], context):
+                    class_transients[targets[i].attr] = values[i]
+                else:
+                    transient_locals[targets[i].id] = values[i]
+
+            # Starred if exists
+            if starred:
+                end = len(values) - (len(targets) - star_or_last_idx - 1)
+                if _is_instance_attribute_assignment(
+                    targets[star_or_last_idx], context
+                ):
+                    class_transients[targets[star_or_last_idx].attr] = values[
+                        star_or_last_idx:end
+                    ]
+                else:
+                    transient_locals[targets[star_or_last_idx].value.id] = values[
+                        star_or_last_idx:end
+                    ]
+
+                # After starred
+                for i in range(star_or_last_idx + 1, len(targets)):
+                    if _is_instance_attribute_assignment(targets[i], context):
+                        class_transients[targets[i].attr] = values[
+                            len(values) - (len(targets) - i)
+                        ]
+                    else:
+                        transient_locals[targets[i].id] = values[
+                            len(values) - (len(targets) - i)
+                        ]
+        elif isinstance(target, ast.Subscript):
+            if isinstance(target.value, ast.Name):
+                name = target.value.id
+                container = transient_locals.get(name)
+                if container is None:
+                    container = context.locals.get(name)
+                if container is None:
+                    container = context.globals.get(name)
+                if container is None:
+                    raise NameError(
+                        f"{name} not found in locals, globals, nor builtins"
+                    )
+                storage_dict = transient_locals
+                storage_key = name
+            elif isinstance(
+                target.value, ast.Attribute
+            ) and _is_instance_attribute_assignment(target.value, context):
+                attr = target.value.attr
+                container = class_transients.get(attr, None)
+                if container is None:
+                    raise NameError(f"{attr} not found in class transients")
+                storage_dict = class_transients
+                storage_key = attr
+            else:
+                return
+
+            key = eval_node(target.slice, context)
+            attributes = (
+                dict.fromkeys(dir(container))
+                if policy.can_call(container.__dir__)
+                else {}
+            )
+            items = {}
+
+            if policy.can_get_item(container, None):
+                try:
+                    items = dict(container.items())
+                except Exception:
+                    pass
+
+            items[key] = value
+            duck_container = _Duck(attributes=attributes, items=items)
+            storage_dict[storage_key] = duck_container
+        elif _is_instance_attribute_assignment(target, context):
+            class_transients[target.attr] = value
+        else:
+            transient_locals[target.id] = value
+    return None
+
+
+def _handle_annassign(node, context):
+    context_with_value = context.replace(current_value=getattr(node, "value", None))
+    annotation_result = eval_node(node.annotation, context_with_value)
+    if _is_type_annotation(annotation_result):
+        annotation_value = _resolve_annotation(annotation_result, context)
+        # Use Value for generic types
+        use_value = (
+            isinstance(annotation_value, GENERIC_CONTAINER_TYPES) and node.value is not None
+        )
+    else:
+        annotation_value = annotation_result
+        use_value = False
+
+    # LOCAL VARIABLE
+    if getattr(node, "simple", False) and isinstance(node.target, ast.Name):
+        name = node.target.id
+        if use_value:
+            return _handle_assign(
+                ast.Assign(targets=[node.target], value=node.value), context
+            )
+        context.transient_locals[name] = annotation_value
+        return None
+
+    # INSTANCE ATTRIBUTE
+    if _is_instance_attribute_assignment(node.target, context):
+        attr = node.target.attr
+        if use_value:
+            return _handle_assign(
+                ast.Assign(targets=[node.target], value=node.value), context
+            )
+        context.class_transients[attr] = annotation_value
+        return None
+
+    return None
+
+def _extract_args_and_kwargs(node: ast.Call, context: EvaluationContext):
+    args = [eval_node(arg, context) for arg in node.args]
+    kwargs = {
+        k: v
+        for kw in node.keywords
+        for k, v in (
+            {kw.arg: eval_node(kw.value, context)}
+            if kw.arg
+            else eval_node(kw.value, context)
+        ).items()
+    }
+    return args, kwargs
+
+
+def _is_instance_attribute_assignment(
+    target: ast.AST, context: EvaluationContext
+) -> bool:
+    """Return True if target is an attribute access on the instance argument."""
+    return (
+        context.class_transients is not None
+        and context.instance_arg_name is not None
+        and isinstance(target, ast.Attribute)
+        and isinstance(getattr(target, "value", None), ast.Name)
+        and getattr(target.value, "id", None) == context.instance_arg_name
+    )
+
+
+def _get_coroutine_attributes() -> dict[str, Optional[object]]:
+    async def _dummy():
+        return None
+
+    coro = _dummy()
+    try:
+        return {attr: getattr(coro, attr, None) for attr in dir(coro)}
+    finally:
+        coro.close()
+
+
+def eval_node(node: Union[ast.AST, None], context: EvaluationContext):
+    """Evaluate AST node in provided context.
+
+    Applies evaluation restrictions defined in the context. Currently does not support evaluation of functions with keyword arguments.
+
+    Does not evaluate actions that always have side effects:
+
+    - class definitions (``class sth: ...``)
+    - function definitions (``def sth: ...``)
+    - variable assignments (``x = 1``)
+    - augmented assignments (``x += 1``)
+    - deletions (``del x``)
+
+    Does not evaluate operations which do not return values:
+
+    - assertions (``assert x``)
+    - pass (``pass``)
+    - imports (``import x``)
+    - control flow:
+
+        - conditionals (``if x:``) except for ternary IfExp (``a if x else b``)
+        - loops (``for`` and ``while``)
+        - exception handling
+
+    The purpose of this function is to guard against unwanted side-effects;
+    it does not give guarantees on protection from malicious code execution.
+    """
+    policy = get_policy(context)
+
+    if node is None:
+        return None
+    if isinstance(node, (ast.Interactive, ast.Module)):
+        result = None
+        for child_node in node.body:
+            result = eval_node(child_node, context)
+        return result
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        is_async = isinstance(node, ast.AsyncFunctionDef)
+        func_locals = context.transient_locals.copy()
+        func_context = context.replace(transient_locals=func_locals)
+        is_property = False
+        is_static = False
+        is_classmethod = False
+        for decorator_node in node.decorator_list:
+            try:
+                decorator = eval_node(decorator_node, context)
+            except NameError:
+                # if the decorator is not yet defined this is fine
+                # especialy because we don't handle imports yet
+                continue
+            if decorator is property:
+                is_property = True
+            elif decorator is staticmethod:
+                is_static = True
+            elif decorator is classmethod:
+                is_classmethod = True
+
+        if func_context.class_transients is not None:
+            if not is_static and not is_classmethod:
+                func_context.instance_arg_name = (
+                    node.args.args[0].arg if node.args.args else None
+                )
+
+        return_type = eval_node(node.returns, context=context)
+
+        for child_node in node.body:
+            eval_node(child_node, func_context)
+
+        if is_property:
+            if return_type is not None:
+                if _is_type_annotation(return_type):
+                    context.transient_locals[node.name] = _resolve_annotation(
+                        return_type, context
+                    )
+                else:
+                    context.transient_locals[node.name] = return_type
+            else:
+                return_value = _infer_return_value(node, func_context)
+                context.transient_locals[node.name] = return_value
+
+            return None
+
+        def dummy_function(*args, **kwargs):
+            pass
+
+        if return_type is not None:
+            if _is_type_annotation(return_type):
+                dummy_function.__annotations__["return"] = return_type
+            else:
+                dummy_function.__inferred_return__ = return_type
+        else:
+            inferred_return = _infer_return_value(node, func_context)
+            if inferred_return is not None:
+                dummy_function.__inferred_return__ = inferred_return
+
+        dummy_function.__name__ = node.name
+        dummy_function.__node__ = node
+        dummy_function.__is_async__ = is_async
+        context.transient_locals[node.name] = dummy_function
+        return None
+    if isinstance(node, ast.Lambda):
+
+        def dummy_function(*args, **kwargs):
+            pass
+
+        dummy_function.__inferred_return__ = eval_node(node.body, context)
+        return dummy_function
+    if isinstance(node, ast.ClassDef):
+        # TODO support class decorators?
+        class_locals = {}
+        outer_locals = context.locals.copy()
+        outer_locals.update(context.transient_locals)
+        class_context = context.replace(
+            transient_locals=class_locals, locals=outer_locals
+        )
+        class_context.class_transients = class_locals
+        for child_node in node.body:
+            eval_node(child_node, class_context)
+        bases = tuple([eval_node(base, context) for base in node.bases])
+        dummy_class = type(node.name, bases, class_locals)
+        context.transient_locals[node.name] = dummy_class
+        return None
+    if isinstance(node, ast.Await):
+        value = eval_node(node.value, context)
+        if hasattr(value, "__awaited_type__"):
+            return value.__awaited_type__
+        return value
+    if isinstance(node, ast.While):
+        loop_locals = context.transient_locals.copy()
+        loop_context = context.replace(transient_locals=loop_locals)
+
+        result = None
+        for stmt in node.body:
+            result = eval_node(stmt, loop_context)
+
+        policy = get_policy(context)
+        merged_locals = _merge_dicts_by_key(
+            [loop_locals, context.transient_locals.copy()], policy
+        )
+        context.transient_locals.update(merged_locals)
+
+        return result
+    if isinstance(node, ast.For):
+        try:
+            iterable = eval_node(node.iter, context)
+        except Exception:
+            iterable = None
+
+        sample = None
+        if iterable is not None:
+            try:
+                if policy.can_call(getattr(iterable, "__iter__", None)):
+                    sample = next(iter(iterable))
+            except Exception:
+                sample = None
+
+        loop_locals = context.transient_locals.copy()
+        loop_context = context.replace(transient_locals=loop_locals)
+
+        if sample is not None:
+            try:
+                fake_assign = ast.Assign(
+                    targets=[node.target], value=ast.Constant(value=sample)
+                )
+                _handle_assign(fake_assign, loop_context)
+            except Exception:
+                pass
+
+        result = None
+        for stmt in node.body:
+            result = eval_node(stmt, loop_context)
+
+        policy = get_policy(context)
+        merged_locals = _merge_dicts_by_key(
+            [loop_locals, context.transient_locals.copy()], policy
+        )
+        context.transient_locals.update(merged_locals)
+
+        return result
+    if isinstance(node, ast.If):
+        branches = []
+        current = node
+        result = None
+        while True:
+            branch_locals = context.transient_locals.copy()
+            branch_context = context.replace(transient_locals=branch_locals)
+            for stmt in current.body:
+                result = eval_node(stmt, branch_context)
+            branches.append(branch_locals)
+            if not current.orelse:
+                break
+            elif len(current.orelse) == 1 and isinstance(current.orelse[0], ast.If):
+                # It's an elif - continue loop
+                current = current.orelse[0]
+            else:
+                # It's an else block - process and break
+                else_locals = context.transient_locals.copy()
+                else_context = context.replace(transient_locals=else_locals)
+                for stmt in current.orelse:
+                    result = eval_node(stmt, else_context)
+                branches.append(else_locals)
+                break
+        branches.append(context.transient_locals.copy())
+        policy = get_policy(context)
+        merged_locals = _merge_dicts_by_key(branches, policy)
+        context.transient_locals.update(merged_locals)
+        return result
+    if isinstance(node, ast.Assign):
+        return _handle_assign(node, context)
+    if isinstance(node, ast.AnnAssign):
+        return _handle_annassign(node, context)
+    if isinstance(node, ast.Expression):
+        return eval_node(node.body, context)
+    if isinstance(node, ast.Expr):
+        return eval_node(node.value, context)
+    if isinstance(node, ast.Pass):
+        return None
+    if isinstance(node, ast.Import):
+        # TODO: populate transient_locals
+        return None
+    if isinstance(node, (ast.AugAssign, ast.Delete)):
+        return None
+    if isinstance(node, (ast.Global, ast.Nonlocal)):
+        return None
+    if isinstance(node, ast.BinOp):
+        left = eval_node(node.left, context)
+        right = eval_node(node.right, context)
+        if (
+            isinstance(node.op, ast.BitOr)
+            and _is_type_annotation(left)
+            and _is_type_annotation(right)
+        ):
+            left_duck = (
+                _Duck(dict.fromkeys(dir(left)))
+                if policy.can_call(left.__dir__)
+                else _Duck()
+            )
+            right_duck = (
+                _Duck(dict.fromkeys(dir(right)))
+                if policy.can_call(right.__dir__)
+                else _Duck()
+            )
+            value_node = context.current_value
+            if value_node is not None and isinstance(value_node, ast.Dict):
+                if dict in [left, right]:
+                    return _merge_values(
+                        [left_duck, right_duck, ast.literal_eval(value_node)],
+                        policy=get_policy(context),
+                    )
+            return _merge_values([left_duck, right_duck], policy=get_policy(context))
+        dunders = _find_dunder(node.op, BINARY_OP_DUNDERS)
+        if dunders:
+            if policy.can_operate(dunders, left, right):
+                return getattr(left, dunders[0])(right)
+            else:
+                raise GuardRejection(
+                    f"Operation (`{dunders}`) for",
+                    type(left),
+                    f"not allowed in {context.evaluation} mode",
+                )
+    if isinstance(node, ast.Compare):
+        left = eval_node(node.left, context)
+        all_true = True
+        negate = False
+        for op, right in zip(node.ops, node.comparators):
+            right = eval_node(right, context)
+            dunder = None
+            dunders = _find_dunder(op, COMP_OP_DUNDERS)
+            if not dunders:
+                if isinstance(op, ast.NotIn):
+                    dunders = COMP_OP_DUNDERS[ast.In]
+                    negate = True
+                if isinstance(op, ast.Is):
+                    dunder = "is_"
+                if isinstance(op, ast.IsNot):
+                    dunder = "is_"
+                    negate = True
+            if not dunder and dunders:
+                dunder = dunders[0]
+            if dunder:
+                a, b = (right, left) if dunder == "__contains__" else (left, right)
+                if dunder == "is_" or dunders and policy.can_operate(dunders, a, b):
+                    result = getattr(operator, dunder)(a, b)
+                    if negate:
+                        result = not result
+                    if not result:
+                        all_true = False
+                    left = right
+                else:
+                    raise GuardRejection(
+                        f"Comparison (`{dunder}`) for",
+                        type(left),
+                        f"not allowed in {context.evaluation} mode",
+                    )
+            else:
+                raise ValueError(
+                    f"Comparison `{dunder}` not supported"
+                )  # pragma: no cover
+        return all_true
+    if isinstance(node, ast.Constant):
+        return node.value
+    if isinstance(node, ast.Tuple):
+        return tuple(eval_node(e, context) for e in node.elts)
+    if isinstance(node, ast.List):
+        return [eval_node(e, context) for e in node.elts]
+    if isinstance(node, ast.Set):
+        return {eval_node(e, context) for e in node.elts}
+    if isinstance(node, ast.Dict):
+        return dict(
+            zip(
+                [eval_node(k, context) for k in node.keys],
+                [eval_node(v, context) for v in node.values],
+            )
+        )
+    if isinstance(node, ast.Slice):
+        return slice(
+            eval_node(node.lower, context),
+            eval_node(node.upper, context),
+            eval_node(node.step, context),
+        )
+    if isinstance(node, ast.UnaryOp):
+        value = eval_node(node.operand, context)
+        dunders = _find_dunder(node.op, UNARY_OP_DUNDERS)
+        if dunders:
+            if policy.can_operate(dunders, value):
+                try:
+                    return getattr(value, dunders[0])()
+                except AttributeError:
+                    raise TypeError(
+                        f"bad operand type for unary {node.op}: {type(value)}"
+                    )
+            else:
+                raise GuardRejection(
+                    f"Operation (`{dunders}`) for",
+                    type(value),
+                    f"not allowed in {context.evaluation} mode",
+                )
+    if isinstance(node, ast.Subscript):
+        value = eval_node(node.value, context)
+        slice_ = eval_node(node.slice, context)
+        if policy.can_get_item(value, slice_):
+            return value[slice_]
+        raise GuardRejection(
+            "Subscript access (`__getitem__`) for",
+            type(value),  # not joined to avoid calling `repr`
+            f" not allowed in {context.evaluation} mode",
+        )
+    if isinstance(node, ast.Name):
+        return _eval_node_name(node.id, context)
+    if isinstance(node, ast.Attribute):
+        if (
+            context.class_transients is not None
+            and isinstance(node.value, ast.Name)
+            and node.value.id == context.instance_arg_name
+        ):
+            return context.class_transients.get(node.attr)
+        value = eval_node(node.value, context)
+        if policy.can_get_attr(value, node.attr):
+            return getattr(value, node.attr)
+        try:
+            cls = (
+                value if isinstance(value, type) else getattr(value, "__class__", None)
+            )
+            if cls is not None:
+                resolved_hints = get_type_hints(
+                    cls,
+                    globalns=(context.globals or {}),
+                    localns=(context.locals or {}),
+                )
+                if node.attr in resolved_hints:
+                    annotated = resolved_hints[node.attr]
+                    return _resolve_annotation(annotated, context)
+        except Exception:
+            # Fall through to the guard rejection
+            pass
+        raise GuardRejection(
+            "Attribute access (`__getattr__`) for",
+            type(value),  # not joined to avoid calling `repr`
+            f"not allowed in {context.evaluation} mode",
+        )
+    if isinstance(node, ast.IfExp):
+        test = eval_node(node.test, context)
+        if test:
+            return eval_node(node.body, context)
+        else:
+            return eval_node(node.orelse, context)
+    if isinstance(node, ast.Call):
+        func = eval_node(node.func, context)
+        if policy.can_call(func):
+            args, kwargs = _extract_args_and_kwargs(node, context)
+            return func(*args, **kwargs)
+        if isclass(func):
+            # this code path gets entered when calling class e.g. `MyClass()`
+            # or `my_instance.__class__()` - in both cases `func` is `MyClass`.
+            # Should return `MyClass` if `__new__` is not overridden,
+            # otherwise whatever `__new__` return type is.
+            overridden_return_type = _eval_return_type(func.__new__, node, context)
+            if overridden_return_type is not NOT_EVALUATED:
+                return overridden_return_type
+            return _create_duck_for_heap_type(func)
+        else:
+            inferred_return = getattr(func, "__inferred_return__", NOT_EVALUATED)
+            return_type = _eval_return_type(func, node, context)
+            if getattr(func, "__is_async__", False):
+                awaited_type = (
+                    inferred_return if inferred_return is not None else return_type
+                )
+                coroutine_duck = _Duck(attributes=_get_coroutine_attributes())
+                coroutine_duck.__awaited_type__ = awaited_type
+                return coroutine_duck
+            if inferred_return is not NOT_EVALUATED:
+                return inferred_return
+            if return_type is not NOT_EVALUATED:
+                return return_type
+        raise GuardRejection(
+            "Call for",
+            func,  # not joined to avoid calling `repr`
+            f"not allowed in {context.evaluation} mode",
+        )
+    if isinstance(node, ast.Assert):
+        # message is always the second item, so if it is defined user would be completing
+        # on the message, not on the assertion test
+        if node.msg:
+            return eval_node(node.msg, context)
+        return eval_node(node.test, context)
+    return None
+
+
+def _merge_dicts_by_key(dicts: list, policy: EvaluationPolicy):
+    """Merge multiple dictionaries, combining values for each key."""
+    if len(dicts) == 1:
+        return dicts[0]
+
+    all_keys = set()
+    for d in dicts:
+        all_keys.update(d.keys())
+
+    merged = {}
+    for key in all_keys:
+        values = [d[key] for d in dicts if key in d]
+        if values:
+            merged[key] = _merge_values(values, policy)
+
+    return merged
+
+
+def _merge_values(values, policy: EvaluationPolicy):
+    """Recursively merge multiple values, combining attributes and dict items."""
+    if len(values) == 1:
+        return values[0]
+
+    types = {type(v) for v in values}
+    merged_items = None
+    key_values = {}
+    attributes = set()
+    for v in values:
+        if policy.can_call(v.__dir__):
+            attributes.update(dir(v))
+        try:
+            if policy.can_call(v.items):
+                try:
+                    for k, val in v.items():
+                        key_values.setdefault(k, []).append(val)
+                except Exception as e:
+                    pass
+            elif policy.can_call(v.keys):
+                try:
+                    for k in v.keys():
+                        key_values.setdefault(k, []).append(None)
+                except Exception as e:
+                    pass
+        except Exception as e:
+            pass
+
+    if key_values:
+        merged_items = {
+            k: _merge_values(vals, policy) if vals[0] is not None else None
+            for k, vals in key_values.items()
+        }
+
+    if len(types) == 1:
+        t = next(iter(types))
+        if t not in (dict,) and not (
+            hasattr(next(iter(values)), "__getitem__")
+            and (
+                hasattr(next(iter(values)), "items")
+                or hasattr(next(iter(values)), "keys")
+            )
+        ):
+            if t in (list, set, tuple):
+                return t
+            return values[0]
+
+    return _Duck(attributes=dict.fromkeys(attributes), items=merged_items)
+
+
+def _infer_return_value(node: ast.FunctionDef, context: EvaluationContext):
+    """Infer the return value(s) of a function by evaluating all return statements."""
+    return_values = _collect_return_values(node.body, context)
+
+    if not return_values:
+        return None
+    if len(return_values) == 1:
+        return return_values[0]
+
+    policy = get_policy(context)
+    return _merge_values(return_values, policy)
+
+
+def _collect_return_values(body, context):
+    """Recursively collect return values from a list of AST statements."""
+    return_values = []
+    for stmt in body:
+        if isinstance(stmt, ast.Return):
+            if stmt.value is None:
+                continue
+            try:
+                value = eval_node(stmt.value, context)
+                if value is not None and value is not NOT_EVALUATED:
+                    return_values.append(value)
+            except Exception:
+                pass
+        if isinstance(
+            stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+        ):
+            continue
+        elif hasattr(stmt, "body") and isinstance(stmt.body, list):
+            return_values.extend(_collect_return_values(stmt.body, context))
+        if isinstance(stmt, ast.Try):
+            for h in stmt.handlers:
+                if hasattr(h, "body"):
+                    return_values.extend(_collect_return_values(h.body, context))
+            if hasattr(stmt, "orelse"):
+                return_values.extend(_collect_return_values(stmt.orelse, context))
+            if hasattr(stmt, "finalbody"):
+                return_values.extend(_collect_return_values(stmt.finalbody, context))
+        if hasattr(stmt, "orelse") and isinstance(stmt.orelse, list):
+            return_values.extend(_collect_return_values(stmt.orelse, context))
+    return return_values
+
+
+def _eval_return_type(func: Callable, node: ast.Call, context: EvaluationContext):
+    """Evaluate return type of a given callable function.
+
+    Returns the built-in type, a duck or NOT_EVALUATED sentinel.
+    """
+    try:
+        sig = signature(func)
+    except ValueError:
+        sig = UNKNOWN_SIGNATURE
+    # if annotation was not stringized, or it was stringized
+    # but resolved by signature call we know the return type
+    not_empty = sig.return_annotation is not Signature.empty
+    if not_empty:
+        return _resolve_annotation(sig.return_annotation, context, sig, func, node)
+    return NOT_EVALUATED
+
+
+def _eval_annotation(
+    annotation: str,
+    context: EvaluationContext,
+):
+    return (
+        _eval_node_name(annotation, context)
+        if isinstance(annotation, str)
+        else annotation
+    )
+
+
+class _GetItemDuck(dict):
+    """A dict subclass that always returns the factory instance and claims to have any item."""
+
+    def __init__(self, factory, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._factory = factory
+
+    def __getitem__(self, key):
+        return self._factory()
+
+    def __contains__(self, key):
+        return True
+
+
+def _resolve_annotation(
+    annotation: object | str,
+    context: EvaluationContext,
+    sig: Signature | None = None,
+    func: Callable | None = None,
+    node: ast.Call | None = None,
+):
+    """Resolve annotation created by user with `typing` module and custom objects."""
+    if annotation is None:
+        return None
+    annotation = _eval_annotation(annotation, context)
+    origin = get_origin(annotation)
+    if annotation is Self and func and hasattr(func, "__self__"):
+        return func.__self__
+    elif origin is Literal:
+        type_args = get_args(annotation)
+        if len(type_args) == 1:
+            return type_args[0]
+    elif annotation is LiteralString:
+        return ""
+    elif annotation is AnyStr:
+        index = None
+        if func and hasattr(func, "__node__"):
+            def_node = func.__node__
+            for i, arg in enumerate(def_node.args.args):
+                if not arg.annotation:
+                    continue
+                annotation = _eval_annotation(arg.annotation.id, context)
+                if annotation is AnyStr:
+                    index = i
+                    break
+            is_bound_method = (
+                isinstance(func, MethodType) and getattr(func, "__self__") is not None
+            )
+            if index and is_bound_method:
+                index -= 1
+        elif sig:
+            for i, (key, value) in enumerate(sig.parameters.items()):
+                if value.annotation is AnyStr:
+                    index = i
+                    break
+        if index is None:
+            return None
+        if index < 0 or index >= len(node.args):
+            return None
+        return eval_node(node.args[index], context)
+    elif origin is TypeGuard:
+        return False
+    elif origin is set or origin is list:
+        # only one type argument allowed
+        attributes = [
+            attr
+            for attr in dir(
+                _resolve_annotation(get_args(annotation)[0], context, sig, func, node)
+            )
+        ]
+        duck = _Duck(attributes=dict.fromkeys(attributes))
+        return _Duck(
+            attributes=dict.fromkeys(dir(origin())),
+            # items are not strrictly needed for set
+            items=_GetItemDuck(lambda: duck),
+        )
+    elif origin is tuple:
+        # multiple type arguments
+        return tuple(
+            _resolve_annotation(arg, context, sig, func, node)
+            for arg in get_args(annotation)
+        )
+    elif origin is Union:
+        # multiple type arguments
+        attributes = [
+            attr
+            for type_arg in get_args(annotation)
+            for attr in dir(_resolve_annotation(type_arg, context, sig, func, node))
+        ]
+        return _Duck(attributes=dict.fromkeys(attributes))
+    elif is_typeddict(annotation):
+        return _Duck(
+            attributes=dict.fromkeys(dir(dict())),
+            items={
+                k: _resolve_annotation(v, context, sig, func, node)
+                for k, v in annotation.__annotations__.items()
+            },
+        )
+    elif hasattr(annotation, "_is_protocol"):
+        return _Duck(attributes=dict.fromkeys(dir(annotation)))
+    elif origin is Annotated:
+        type_arg = get_args(annotation)[0]
+        return _resolve_annotation(type_arg, context, sig, func, node)
+    elif isinstance(annotation, NewType):
+        return _eval_or_create_duck(annotation.__supertype__, context)
+    elif isinstance(annotation, TypeAliasType):
+        return _eval_or_create_duck(annotation.__value__, context)
+    else:
+        return _eval_or_create_duck(annotation, context)
+
+
+def _eval_node_name(node_id: str, context: EvaluationContext):
+    policy = get_policy(context)
+    if node_id in context.transient_locals:
+        return context.transient_locals[node_id]
+    if policy.allow_locals_access and node_id in context.locals:
+        return context.locals[node_id]
+    if policy.allow_globals_access and node_id in context.globals:
+        return context.globals[node_id]
+    if policy.allow_builtins_access and hasattr(builtins, node_id):
+        # note: do not use __builtins__, it is implementation detail of cPython
+        return getattr(builtins, node_id)
+    if policy.allow_auto_import and context.auto_import:
+        return context.auto_import(node_id)
+    if not policy.allow_globals_access and not policy.allow_locals_access:
+        raise GuardRejection(
+            f"Namespace access not allowed in {context.evaluation} mode"
+        )
+    else:
+        raise NameError(f"{node_id} not found in locals, globals, nor builtins")
+
+
+def _eval_or_create_duck(duck_type, context: EvaluationContext):
+    policy = get_policy(context)
+    # if allow-listed builtin is on type annotation, instantiate it
+    if policy.can_call(duck_type):
+        return duck_type()
+    # if custom class is in type annotation, mock it
+    return _create_duck_for_heap_type(duck_type)
+
+
+def _create_duck_for_heap_type(duck_type):
+    """Create an imitation of an object of a given type (a duck).
+
+    Returns the duck or NOT_EVALUATED sentinel if duck could not be created.
+    """
+    duck = ImpersonatingDuck()
+    try:
+        # this only works for heap types, not builtins
+        duck.__class__ = duck_type
+        return duck
+    except TypeError:
+        pass
+    return NOT_EVALUATED
+
+
+SUPPORTED_EXTERNAL_GETITEM = {
+    ("pandas", "core", "indexing", "_iLocIndexer"),
+    ("pandas", "core", "indexing", "_LocIndexer"),
+    ("pandas", "DataFrame"),
+    ("pandas", "Series"),
+    ("numpy", "ndarray"),
+    ("numpy", "void"),
+}
+
+
+BUILTIN_GETITEM: set[InstancesHaveGetItem] = {
+    dict,
+    str,  # type: ignore[arg-type]
+    bytes,  # type: ignore[arg-type]
+    list,
+    tuple,
+    type,  # for type annotations like list[str]
+    _Duck,
+    collections.defaultdict,
+    collections.deque,
+    collections.OrderedDict,
+    collections.ChainMap,
+    collections.UserDict,
+    collections.UserList,
+    collections.UserString,  # type: ignore[arg-type]
+    _DummyNamedTuple,
+    _IdentitySubscript,
+}
+
+
+def _list_methods(cls, source=None):
+    """For use on immutable objects or with methods returning a copy"""
+    return [getattr(cls, k) for k in (source if source else dir(cls))]
+
+
+dict_non_mutating_methods = ("copy", "keys", "values", "items")
+list_non_mutating_methods = ("copy", "index", "count")
+set_non_mutating_methods = set(dir(set)) & set(dir(frozenset))
+
+
+dict_keys: type[collections.abc.KeysView] = type({}.keys())
+dict_values: type = type({}.values())
+dict_items: type = type({}.items())
+
+NUMERICS = {int, float, complex}
+
+ALLOWED_CALLS = {
+    bytes,
+    *_list_methods(bytes),
+    bytes.__iter__,
+    dict,
+    *_list_methods(dict, dict_non_mutating_methods),
+    dict.__iter__,
+    dict_keys.__iter__,
+    dict_values.__iter__,
+    dict_items.__iter__,
+    dict_keys.isdisjoint,
+    list,
+    *_list_methods(list, list_non_mutating_methods),
+    list.__iter__,
+    set,
+    *_list_methods(set, set_non_mutating_methods),
+    set.__iter__,
+    frozenset,
+    *_list_methods(frozenset),
+    frozenset.__iter__,
+    range,
+    range.__iter__,
+    str,
+    *_list_methods(str),
+    str.__iter__,
+    tuple,
+    *_list_methods(tuple),
+    tuple.__iter__,
+    bool,
+    *_list_methods(bool),
+    *NUMERICS,
+    *[method for numeric_cls in NUMERICS for method in _list_methods(numeric_cls)],
+    collections.deque,
+    *_list_methods(collections.deque, list_non_mutating_methods),
+    collections.deque.__iter__,
+    collections.defaultdict,
+    *_list_methods(collections.defaultdict, dict_non_mutating_methods),
+    collections.defaultdict.__iter__,
+    collections.OrderedDict,
+    *_list_methods(collections.OrderedDict, dict_non_mutating_methods),
+    collections.OrderedDict.__iter__,
+    collections.UserDict,
+    *_list_methods(collections.UserDict, dict_non_mutating_methods),
+    collections.UserDict.__iter__,
+    collections.UserList,
+    *_list_methods(collections.UserList, list_non_mutating_methods),
+    collections.UserList.__iter__,
+    collections.UserString,
+    *_list_methods(collections.UserString, dir(str)),
+    collections.UserString.__iter__,
+    collections.Counter,
+    *_list_methods(collections.Counter, dict_non_mutating_methods),
+    collections.Counter.__iter__,
+    collections.Counter.elements,
+    collections.Counter.most_common,
+    object.__dir__,
+    type.__dir__,
+    _Duck.__dir__,
+}
+
+BUILTIN_GETATTR: set[MayHaveGetattr] = {
+    *BUILTIN_GETITEM,
+    set,
+    frozenset,
+    object,
+    type,  # `type` handles a lot of generic cases, e.g. numbers as in `int.real`.
+    *NUMERICS,
+    dict_keys,
+    MethodDescriptorType,
+    ModuleType,
+}
+
+
+BUILTIN_OPERATIONS = {*BUILTIN_GETATTR}
+
+EVALUATION_POLICIES = {
+    "minimal": EvaluationPolicy(
+        allow_builtins_access=True,
+        allow_locals_access=False,
+        allow_globals_access=False,
+        allow_item_access=False,
+        allow_attr_access=False,
+        allowed_calls=set(),
+        allow_any_calls=False,
+        allow_all_operations=False,
+    ),
+    "limited": SelectivePolicy(
+        allowed_getitem=BUILTIN_GETITEM,
+        allowed_getitem_external=SUPPORTED_EXTERNAL_GETITEM,
+        allowed_getattr=BUILTIN_GETATTR,
+        allowed_getattr_external={
+            # pandas Series/Frame implements custom `__getattr__`
+            ("pandas", "DataFrame"),
+            ("pandas", "Series"),
+        },
+        allowed_operations=BUILTIN_OPERATIONS,
+        allow_builtins_access=True,
+        allow_locals_access=True,
+        allow_globals_access=True,
+        allow_getitem_on_types=True,
+        allowed_calls=ALLOWED_CALLS,
+    ),
+    "unsafe": EvaluationPolicy(
+        allow_builtins_access=True,
+        allow_locals_access=True,
+        allow_globals_access=True,
+        allow_attr_access=True,
+        allow_item_access=True,
+        allow_any_calls=True,
+        allow_all_operations=True,
+    ),
+}
+
+
+__all__ = [
+    "guarded_eval",
+    "eval_node",
+    "GuardRejection",
+    "EvaluationContext",
+    "_unbind_method",
+]

lib/python3.12/site-packages/IPython/core/magic.py

@@ -0,0 +1,786 @@
+from __future__ import annotations
+
+"""Magic functions for InteractiveShell."""
+
+# -----------------------------------------------------------------------------
+#  Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
+#  Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
+#  Copyright (C) 2008 The IPython Development Team
+
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+# -----------------------------------------------------------------------------
+
+import os
+import re
+import sys
+from getopt import getopt, GetoptError
+
+from traitlets.config.configurable import Configurable
+from . import oinspect
+from .error import UsageError
+from .inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
+from ..utils.ipstruct import Struct
+from ..utils.process import arg_split
+from ..utils.text import dedent
+from traitlets import Bool, Dict, Instance, observe
+from logging import error
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from IPython.core.interactiveshell import InteractiveShell
+
+
+# -----------------------------------------------------------------------------
+# Globals
+# -----------------------------------------------------------------------------
+
+# A dict we'll use for each class that has magics, used as temporary storage to
+# pass information between the @line/cell_magic method decorators and the
+# @magics_class class decorator, because the method decorators have no
+# access to the class when they run.  See for more details:
+# http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
+
+magics: t.Dict = dict(line={}, cell={})
+
+magic_kinds = ("line", "cell")
+magic_spec = ("line", "cell", "line_cell")
+magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
+
+# -----------------------------------------------------------------------------
+# Utility classes and functions
+# -----------------------------------------------------------------------------
+
+
+class Bunch:
+    pass
+
+
+def on_off(tag):
+    """Return an ON/OFF string for a 1/0 input. Simple utility function."""
+    return ["OFF", "ON"][tag]
+
+
+def compress_dhist(dh):
+    """Compress a directory history into a new one with at most 20 entries.
+
+    Return a new list made from the first and last 10 elements of dhist after
+    removal of duplicates.
+    """
+    head, tail = dh[:-10], dh[-10:]
+
+    newhead = []
+    done = set()
+    for h in head:
+        if h in done:
+            continue
+        newhead.append(h)
+        done.add(h)
+
+    return newhead + tail
+
+
+def needs_local_scope(func):
+    """Decorator to mark magic functions which need to local scope to run."""
+    func.needs_local_scope = True
+    return func
+
+
+# -----------------------------------------------------------------------------
+# Class and method decorators for registering magics
+# -----------------------------------------------------------------------------
+
+
+def magics_class(cls):
+    """Class decorator for all subclasses of the main Magics class.
+
+    Any class that subclasses Magics *must* also apply this decorator, to
+    ensure that all the methods that have been decorated as line/cell magics
+    get correctly registered in the class instance.  This is necessary because
+    when method decorators run, the class does not exist yet, so they
+    temporarily store their information into a module global.  Application of
+    this class decorator copies that global data to the class instance and
+    clears the global.
+
+    Obviously, this mechanism is not thread-safe, which means that the
+    *creation* of subclasses of Magic should only be done in a single-thread
+    context.  Instantiation of the classes has no restrictions.  Given that
+    these classes are typically created at IPython startup time and before user
+    application code becomes active, in practice this should not pose any
+    problems.
+    """
+    cls.registered = True
+    cls.magics = dict(line=magics["line"], cell=magics["cell"])
+    magics["line"] = {}
+    magics["cell"] = {}
+    return cls
+
+
+def record_magic(dct, magic_kind, magic_name, func):
+    """Utility function to store a function as a magic of a specific kind.
+
+    Parameters
+    ----------
+    dct : dict
+        A dictionary with 'line' and 'cell' subdicts.
+    magic_kind : str
+        Kind of magic to be stored.
+    magic_name : str
+        Key to store the magic as.
+    func : function
+        Callable object to store.
+    """
+    if magic_kind == "line_cell":
+        dct["line"][magic_name] = dct["cell"][magic_name] = func
+    else:
+        dct[magic_kind][magic_name] = func
+
+
+def validate_type(magic_kind):
+    """Ensure that the given magic_kind is valid.
+
+    Check that the given magic_kind is one of the accepted spec types (stored
+    in the global `magic_spec`), raise ValueError otherwise.
+    """
+    if magic_kind not in magic_spec:
+        raise ValueError(
+            "magic_kind must be one of %s, %s given" % magic_kinds, magic_kind
+        )
+
+
+# The docstrings for the decorator below will be fairly similar for the two
+# types (method and function), so we generate them here once and reuse the
+# templates below.
+_docstring_template = """Decorate the given {0} as {1} magic.
+
+The decorator can be used with or without arguments, as follows.
+
+i) without arguments: it will create a {1} magic named as the {0} being
+decorated::
+
+    @deco
+    def foo(...)
+
+will create a {1} magic named `foo`.
+
+ii) with one string argument: which will be used as the actual name of the
+resulting magic::
+
+    @deco('bar')
+    def foo(...)
+
+will create a {1} magic named `bar`.
+
+To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
+"""
+
+# These two are decorator factories.  While they are conceptually very similar,
+# there are enough differences in the details that it's simpler to have them
+# written as completely standalone functions rather than trying to share code
+# and make a single one with convoluted logic.
+
+
+def _method_magic_marker(magic_kind):
+    """Decorator factory for methods in Magics subclasses."""
+
+    validate_type(magic_kind)
+
+    # This is a closure to capture the magic_kind.  We could also use a class,
+    # but it's overkill for just that one bit of state.
+    def magic_deco(arg):
+        if callable(arg):
+            # "Naked" decorator call (just @foo, no args)
+            func = arg
+            name = func.__name__
+            retval = arg
+            record_magic(magics, magic_kind, name, name)
+        elif isinstance(arg, str):
+            # Decorator called with arguments (@foo('bar'))
+            name = arg
+
+            def mark(func, *a, **kw):
+                record_magic(magics, magic_kind, name, func.__name__)
+                return func
+
+            retval = mark
+        else:
+            raise TypeError("Decorator can only be called with string or function")
+        return retval
+
+    # Ensure the resulting decorator has a usable docstring
+    magic_deco.__doc__ = _docstring_template.format("method", magic_kind)
+    return magic_deco
+
+
+def _function_magic_marker(magic_kind):
+    """Decorator factory for standalone functions."""
+    validate_type(magic_kind)
+
+    # This is a closure to capture the magic_kind.  We could also use a class,
+    # but it's overkill for just that one bit of state.
+    def magic_deco(arg):
+        # Find get_ipython() in the caller's namespace
+        caller = sys._getframe(1)
+        for ns in ["f_locals", "f_globals", "f_builtins"]:
+            get_ipython = getattr(caller, ns).get("get_ipython")
+            if get_ipython is not None:
+                break
+        else:
+            raise NameError(
+                "Decorator can only run in context where `get_ipython` exists"
+            )
+
+        ip = get_ipython()
+
+        if callable(arg):
+            # "Naked" decorator call (just @foo, no args)
+            func = arg
+            name = func.__name__
+            ip.register_magic_function(func, magic_kind, name)
+            retval = arg
+        elif isinstance(arg, str):
+            # Decorator called with arguments (@foo('bar'))
+            name = arg
+
+            def mark(func, *a, **kw):
+                ip.register_magic_function(func, magic_kind, name)
+                return func
+
+            retval = mark
+        else:
+            raise TypeError("Decorator can only be called with string or function")
+        return retval
+
+    # Ensure the resulting decorator has a usable docstring
+    ds = _docstring_template.format("function", magic_kind)
+
+    ds += dedent(
+        """
+    Note: this decorator can only be used in a context where IPython is already
+    active, so that the `get_ipython()` call succeeds.  You can therefore use
+    it in your startup files loaded after IPython initializes, but *not* in the
+    IPython configuration file itself, which is executed before IPython is
+    fully up and running.  Any file located in the `startup` subdirectory of
+    your configuration profile will be OK in this sense.
+    """
+    )
+
+    magic_deco.__doc__ = ds
+    return magic_deco
+
+
+MAGIC_NO_VAR_EXPAND_ATTR = "_ipython_magic_no_var_expand"
+MAGIC_OUTPUT_CAN_BE_SILENCED = "_ipython_magic_output_can_be_silenced"
+
+
+def no_var_expand(magic_func):
+    """Mark a magic function as not needing variable expansion
+
+    By default, IPython interprets `{a}` or `$a` in the line passed to magics
+    as variables that should be interpolated from the interactive namespace
+    before passing the line to the magic function.
+    This is not always desirable, e.g. when the magic executes Python code
+    (%timeit, %time, etc.).
+    Decorate magics with `@no_var_expand` to opt-out of variable expansion.
+
+    .. versionadded:: 7.3
+    """
+    setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
+    return magic_func
+
+
+def output_can_be_silenced(magic_func):
+    """Mark a magic function so its output may be silenced.
+
+    The output is silenced if the Python code used as a parameter of
+    the magic ends in a semicolon, not counting a Python comment that can
+    follow it.
+    """
+    setattr(magic_func, MAGIC_OUTPUT_CAN_BE_SILENCED, True)
+    return magic_func
+
+
+# Create the actual decorators for public use
+
+# These three are used to decorate methods in class definitions
+line_magic = _method_magic_marker("line")
+cell_magic = _method_magic_marker("cell")
+line_cell_magic = _method_magic_marker("line_cell")
+
+# These three decorate standalone functions and perform the decoration
+# immediately.  They can only run where get_ipython() works
+register_line_magic = _function_magic_marker("line")
+register_cell_magic = _function_magic_marker("cell")
+register_line_cell_magic = _function_magic_marker("line_cell")
+
+# -----------------------------------------------------------------------------
+# Core Magic classes
+# -----------------------------------------------------------------------------
+
+
+class MagicsManager(Configurable):
+    """Object that handles all magic-related functionality for IPython."""
+
+    # Non-configurable class attributes
+
+    # A two-level dict, first keyed by magic type, then by magic function, and
+    # holding the actual callable object as value.  This is the dict used for
+    # magic function dispatch
+    magics = Dict()
+    lazy_magics = Dict(
+        help="""
+    Mapping from magic names to modules to load.
+
+    This can be used in IPython/IPykernel configuration to declare lazy magics
+    that will only be imported/registered on first use.
+
+    For example::
+
+        c.MagicsManager.lazy_magics = {
+          "my_magic": "slow.to.import",
+          "my_other_magic": "also.slow",
+        }
+
+    On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
+    `%%my_other_magic`, the corresponding module will be loaded as an ipython
+    extensions as if you had previously done `%load_ext ipython`.
+
+    Magics names should be without percent(s) as magics can be both cell
+    and line magics.
+
+    Lazy loading happen relatively late in execution process, and
+    complex extensions that manipulate Python/IPython internal state or global state
+    might not support lazy loading.
+    """
+    ).tag(
+        config=True,
+    )
+
+    # A registry of the original objects that we've been given holding magics.
+    registry = Dict()
+
+    shell = Instance(
+        "IPython.core.interactiveshell.InteractiveShellABC", allow_none=True
+    )
+
+    auto_magic = Bool(
+        True, help="Automatically call line magics without requiring explicit % prefix"
+    ).tag(config=True)
+
+    @observe("auto_magic")
+    def _auto_magic_changed(self, change):
+        assert self.shell is not None
+        self.shell.automagic = change["new"]
+
+    _auto_status = [
+        "Automagic is OFF, % prefix IS needed for line magics.",
+        "Automagic is ON, % prefix IS NOT needed for line magics.",
+    ]
+
+    user_magics = Instance("IPython.core.magics.UserMagics", allow_none=True)
+
+    def __init__(self, shell=None, config=None, user_magics=None, **traits):
+        super(MagicsManager, self).__init__(
+            shell=shell, config=config, user_magics=user_magics, **traits
+        )
+        self.magics = dict(line={}, cell={})
+        # Let's add the user_magics to the registry for uniformity, so *all*
+        # registered magic containers can be found there.
+        self.registry[user_magics.__class__.__name__] = user_magics
+
+    def auto_status(self):
+        """Return descriptive string with automagic status."""
+        return self._auto_status[self.auto_magic]
+
+    def lsmagic(self):
+        """Return a dict of currently available magic functions.
+
+        The return dict has the keys 'line' and 'cell', corresponding to the
+        two types of magics we support.  Each value is a list of names.
+        """
+        return self.magics
+
+    def lsmagic_docs(self, brief=False, missing=""):
+        """Return dict of documentation of magic functions.
+
+        The return dict has the keys 'line' and 'cell', corresponding to the
+        two types of magics we support. Each value is a dict keyed by magic
+        name whose value is the function docstring. If a docstring is
+        unavailable, the value of `missing` is used instead.
+
+        If brief is True, only the first line of each docstring will be returned.
+        """
+        docs = {}
+        for m_type in self.magics:
+            m_docs = {}
+            for m_name, m_func in self.magics[m_type].items():
+                if m_func.__doc__:
+                    if brief:
+                        m_docs[m_name] = m_func.__doc__.split("\n", 1)[0]
+                    else:
+                        m_docs[m_name] = m_func.__doc__.rstrip()
+                else:
+                    m_docs[m_name] = missing
+            docs[m_type] = m_docs
+        return docs
+
+    def register_lazy(self, name: str, fully_qualified_name: str) -> None:
+        """
+        Lazily register a magic via an extension.
+
+
+        Parameters
+        ----------
+        name : str
+            Name of the magic you wish to register.
+        fully_qualified_name :
+            Fully qualified name of the module/submodule that should be loaded
+            as an extensions when the magic is first called.
+            It is assumed that loading this extensions will register the given
+            magic.
+        """
+
+        self.lazy_magics[name] = fully_qualified_name
+
+    def register(self, *magic_objects):
+        """Register one or more instances of Magics.
+
+        Take one or more classes or instances of classes that subclass the main
+        `core.Magic` class, and register them with IPython to use the magic
+        functions they provide.  The registration process will then ensure that
+        any methods that have decorated to provide line and/or cell magics will
+        be recognized with the `%x`/`%%x` syntax as a line/cell magic
+        respectively.
+
+        If classes are given, they will be instantiated with the default
+        constructor.  If your classes need a custom constructor, you should
+        instanitate them first and pass the instance.
+
+        The provided arguments can be an arbitrary mix of classes and instances.
+
+        Parameters
+        ----------
+        *magic_objects : one or more classes or instances
+        """
+        # Start by validating them to ensure they have all had their magic
+        # methods registered at the instance level
+        for m in magic_objects:
+            if not m.registered:
+                raise ValueError(
+                    "Class of magics %r was constructed without "
+                    "the @register_magics class decorator"
+                )
+            if isinstance(m, type):
+                # If we're given an uninstantiated class
+                m = m(shell=self.shell)
+
+            # Now that we have an instance, we can register it and update the
+            # table of callables
+            self.registry[m.__class__.__name__] = m
+            for mtype in magic_kinds:
+                self.magics[mtype].update(m.magics[mtype])
+
+    def register_function(self, func, magic_kind="line", magic_name=None):
+        """Expose a standalone function as magic function for IPython.
+
+        This will create an IPython magic (line, cell or both) from a
+        standalone function.  The functions should have the following
+        signatures:
+
+        * For line magics: `def f(line)`
+        * For cell magics: `def f(line, cell)`
+        * For a function that does both: `def f(line, cell=None)`
+
+        In the latter case, the function will be called with `cell==None` when
+        invoked as `%f`, and with cell as a string when invoked as `%%f`.
+
+        Parameters
+        ----------
+        func : callable
+            Function to be registered as a magic.
+        magic_kind : str
+            Kind of magic, one of 'line', 'cell' or 'line_cell'
+        magic_name : optional str
+            If given, the name the magic will have in the IPython namespace.  By
+            default, the name of the function itself is used.
+        """
+
+        # Create the new method in the user_magics and register it in the
+        # global table
+        validate_type(magic_kind)
+        magic_name = func.__name__ if magic_name is None else magic_name
+        setattr(self.user_magics, magic_name, func)
+        record_magic(self.magics, magic_kind, magic_name, func)
+
+    def register_alias(
+        self, alias_name, magic_name, magic_kind="line", magic_params=None
+    ):
+        """Register an alias to a magic function.
+
+        The alias is an instance of :class:`MagicAlias`, which holds the
+        name and kind of the magic it should call. Binding is done at
+        call time, so if the underlying magic function is changed the alias
+        will call the new function.
+
+        Parameters
+        ----------
+        alias_name : str
+            The name of the magic to be registered.
+        magic_name : str
+            The name of an existing magic.
+        magic_kind : str
+            Kind of magic, one of 'line' or 'cell'
+        """
+
+        # `validate_type` is too permissive, as it allows 'line_cell'
+        # which we do not handle.
+        if magic_kind not in magic_kinds:
+            raise ValueError(
+                "magic_kind must be one of %s, %s given" % magic_kinds, magic_kind
+            )
+
+        alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
+        setattr(self.user_magics, alias_name, alias)
+        record_magic(self.magics, magic_kind, alias_name, alias)
+
+
+# Key base class that provides the central functionality for magics.
+
+
+class Magics(Configurable):
+    """Base class for implementing magic functions.
+
+    Shell functions which can be reached as %function_name. All magic
+    functions should accept a string, which they can parse for their own
+    needs. This can make some functions easier to type, eg `%cd ../`
+    vs. `%cd("../")`
+
+    Classes providing magic functions need to subclass this class, and they
+    MUST:
+
+    - Use the method decorators `@line_magic` and `@cell_magic` to decorate
+      individual methods as magic functions, AND
+
+    - Use the class decorator `@magics_class` to ensure that the magic
+      methods are properly registered at the instance level upon instance
+      initialization.
+
+    See :mod:`magic_functions` for examples of actual implementation classes.
+    """
+
+    # Dict holding all command-line options for each magic.
+    options_table: dict[str, t.Any] = {}
+    # Dict for the mapping of magic names to methods, set by class decorator
+    magics: dict[str, t.Any] = {}
+    # Flag to check that the class decorator was properly applied
+    registered: bool = False
+    # Instance of IPython shell
+    shell: None | InteractiveShell = None
+
+    def __init__(self, shell=None, **kwargs):
+        if not (self.__class__.registered):
+            raise ValueError(
+                "Magics subclass without registration - "
+                "did you forget to apply @magics_class?"
+            )
+        if shell is not None:
+            if hasattr(shell, "configurables"):
+                shell.configurables.append(self)
+            if hasattr(shell, "config"):
+                kwargs.setdefault("parent", shell)
+
+        self.shell = shell
+        self.options_table = {}
+        # The method decorators are run when the instance doesn't exist yet, so
+        # they can only record the names of the methods they are supposed to
+        # grab.  Only now, that the instance exists, can we create the proper
+        # mapping to bound methods.  So we read the info off the original names
+        # table and replace each method name by the actual bound method.
+        # But we mustn't clobber the *class* mapping, in case of multiple instances.
+        class_magics = self.magics
+        self.magics = {}
+        for mtype in magic_kinds:
+            tab = self.magics[mtype] = {}
+            cls_tab = class_magics[mtype]
+            for magic_name, meth_name in cls_tab.items():
+                if isinstance(meth_name, str):
+                    # it's a method name, grab it
+                    tab[magic_name] = getattr(self, meth_name)
+                else:
+                    # it's the real thing
+                    tab[magic_name] = meth_name
+        # Configurable **needs** to be initiated at the end or the config
+        # magics get screwed up.
+        super(Magics, self).__init__(**kwargs)
+
+    def arg_err(self, func):
+        """Print docstring if incorrect arguments were passed"""
+        print("Error in arguments:")
+        print(oinspect.getdoc(func))
+
+    def format_latex(self, strng):
+        """Format a string for latex inclusion."""
+
+        # Characters that need to be escaped for latex:
+        escape_re = re.compile(r"(%|_|\$|#|&)", re.MULTILINE)
+        # Magic command names as headers:
+        cmd_name_re = re.compile(r"^(%s.*?):" % ESC_MAGIC, re.MULTILINE)
+        # Magic commands
+        cmd_re = re.compile(r"(?P<cmd>%s.+?\b)(?!\}\}:)" % ESC_MAGIC, re.MULTILINE)
+        # Paragraph continue
+        par_re = re.compile(r"\\$", re.MULTILINE)
+
+        # The "\n" symbol
+        newline_re = re.compile(r"\\n")
+
+        # Now build the string for output:
+        # strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
+        strng = cmd_name_re.sub(r"\n\\bigskip\n\\texttt{\\textbf{ \1}}:", strng)
+        strng = cmd_re.sub(r"\\texttt{\g<cmd>}", strng)
+        strng = par_re.sub(r"\\\\", strng)
+        strng = escape_re.sub(r"\\\1", strng)
+        strng = newline_re.sub(r"\\textbackslash{}n", strng)
+        return strng
+
+    def parse_options(self, arg_str, opt_str, *long_opts, **kw):
+        """Parse options passed to an argument string.
+
+        The interface is similar to that of :func:`getopt.getopt`, but it
+        returns a :class:`~IPython.utils.struct.Struct` with the options as keys
+        and the stripped argument string still as a string.
+
+        arg_str is quoted as a true sys.argv vector by using shlex.split.
+        This allows us to easily expand variables, glob files, quote
+        arguments, etc.
+
+        Parameters
+        ----------
+        arg_str : str
+            The arguments to parse.
+        opt_str : str
+            The options specification.
+        mode : str, default 'string'
+            If given as 'list', the argument string is returned as a list (split
+            on whitespace) instead of a string.
+        list_all : bool, default False
+            Put all option values in lists. Normally only options
+            appearing more than once are put in a list.
+        posix : bool, default True
+            Whether to split the input line in POSIX mode or not, as per the
+            conventions outlined in the :mod:`shlex` module from the standard
+            library.
+        """
+
+        # inject default options at the beginning of the input line
+        caller = sys._getframe(1).f_code.co_name
+        arg_str = "%s %s" % (self.options_table.get(caller, ""), arg_str)
+
+        mode = kw.get("mode", "string")
+        if mode not in ["string", "list"]:
+            raise ValueError("incorrect mode given: %s" % mode)
+        # Get options
+        list_all = kw.get("list_all", 0)
+        posix = kw.get("posix", os.name == "posix")
+        strict = kw.get("strict", True)
+
+        preserve_non_opts = kw.get("preserve_non_opts", False)
+        remainder_arg_str = arg_str
+
+        # Check if we have more than one argument to warrant extra processing:
+        odict: dict[str, t.Any] = {}  # Dictionary with options
+        args = arg_str.split()
+        if len(args) >= 1:
+            # If the list of inputs only has 0 or 1 thing in it, there's no
+            # need to look for options
+            argv = arg_split(arg_str, posix, strict)
+            # Do regular option processing
+            try:
+                opts, args = getopt(argv, opt_str, long_opts)
+            except GetoptError as e:
+                raise UsageError(
+                    '%s (allowed: "%s"%s)'
+                    % (e.msg, opt_str, " ".join(("",) + long_opts) if long_opts else "")
+                ) from e
+            for o, a in opts:
+                if mode == "string" and preserve_non_opts:
+                    # remove option-parts from the original args-string and preserve remaining-part.
+                    # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
+                    # returned in the original order.
+                    remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
+                        a, "", 1
+                    )
+                if o.startswith("--"):
+                    o = o[2:]
+                else:
+                    o = o[1:]
+                try:
+                    odict[o].append(a)
+                except AttributeError:
+                    odict[o] = [odict[o], a]
+                except KeyError:
+                    if list_all:
+                        odict[o] = [a]
+                    else:
+                        odict[o] = a
+
+        # Prepare opts,args for return
+        opts = Struct(odict)  # type: ignore[assignment]
+        if mode == "string":
+            if preserve_non_opts:
+                args = remainder_arg_str.lstrip()
+            else:
+                args = " ".join(args)
+
+        return opts, args
+
+    def default_option(self, fn, optstr):
+        """Make an entry in the options_table for fn, with value optstr"""
+        assert False, "is this even called?"
+        if fn not in self.lsmagic():
+            error("%s is not a magic function" % fn)
+        self.options_table[fn] = optstr
+
+
+class MagicAlias:
+    """An alias to another magic function.
+
+    An alias is determined by its magic name and magic kind. Lookup
+    is done at call time, so if the underlying magic changes the alias
+    will call the new function.
+
+    Use the :meth:`MagicsManager.register_alias` method or the
+    `%alias_magic` magic function to create and register a new alias.
+    """
+
+    def __init__(self, shell, magic_name, magic_kind, magic_params=None):
+        self.shell = shell
+        self.magic_name = magic_name
+        self.magic_params = magic_params
+        self.magic_kind = magic_kind
+
+        self.pretty_target = "%s%s" % (magic_escapes[self.magic_kind], self.magic_name)
+        self.__doc__ = "Alias for `%s`." % self.pretty_target
+
+        self._in_call = False
+
+    def __call__(self, *args, **kwargs):
+        """Call the magic alias."""
+        fn = self.shell.find_magic(self.magic_name, self.magic_kind)
+        if fn is None:
+            raise UsageError("Magic `%s` not found." % self.pretty_target)
+
+        # Protect against infinite recursion.
+        if self._in_call:
+            raise UsageError(
+                "Infinite recursion detected; magic aliases cannot call themselves."
+            )
+        self._in_call = True
+        try:
+            if self.magic_params:
+                args_list = list(args)
+                args_list[0] = self.magic_params + " " + args[0]
+                args = tuple(args_list)
+            return fn(*args, **kwargs)
+        finally:
+            self._in_call = False

lib/python3.12/site-packages/IPython/core/release.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""Release data for the IPython project."""
+
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2008, IPython Development Team.
+#  Copyright (c) 2001, Fernando Perez <fernando.perez@colorado.edu>
+#  Copyright (c) 2001, Janko Hauser <jhauser@zscout.de>
+#  Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>
+#
+#  Distributed under the terms of the Modified BSD License.
+#
+#  The full license is in the file COPYING.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+# IPython version information.  An empty _version_extra corresponds to a full
+# release.  'dev' as a _version_extra string means this is a development
+# version
+_version_major = 9
+_version_minor = 10
+_version_patch = 0
+_version_extra = ".dev"
+# _version_extra = "b2"
+_version_extra = ""  # Uncomment this for full releases
+
+# Construct full version string from these.
+_ver = [_version_major, _version_minor, _version_patch]
+
+__version__ = '.'.join(map(str, _ver))
+if _version_extra:
+    __version__ = __version__  + _version_extra
+
+version = __version__  # backwards compatibility name
+version_info = (_version_major, _version_minor, _version_patch, _version_extra)
+
+
+license = "BSD-3-Clause"
+
+authors = {
+    "Fernando": ("Fernando Perez", "fperez.net@gmail.com"),
+    "M": ("M Bussonnier", "mbussonnier@gmail.com"),
+}
+
+author = 'The IPython Development Team'
+
+author_email = 'ipython-dev@python.org'

lib/python3.12/site-packages/IPython/display.py

@@ -0,0 +1,41 @@
+"""Public API for display tools in IPython."""
+
+# -----------------------------------------------------------------------------
+#       Copyright (C) 2012 The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+
+from IPython.core.display_functions import *
+from IPython.core.display import (
+    display_pretty as display_pretty,
+    display_html as display_html,
+    display_markdown as display_markdown,
+    display_svg as display_svg,
+    display_png as display_png,
+    display_jpeg as display_jpeg,
+    display_latex as display_latex,
+    display_json as display_json,
+    display_javascript as display_javascript,
+    display_pdf as display_pdf,
+    DisplayObject as DisplayObject,
+    TextDisplayObject as TextDisplayObject,
+    Pretty as Pretty,
+    HTML as HTML,
+    Markdown as Markdown,
+    Math as Math,
+    Latex as Latex,
+    SVG as SVG,
+    ProgressBar as ProgressBar,
+    JSON as JSON,
+    GeoJSON as GeoJSON,
+    Javascript as Javascript,
+    Image as Image,
+    Video as Video,
+)
+from IPython.lib.display import *

lib/python3.12/site-packages/IPython/paths.py

@@ -0,0 +1,122 @@
+"""Find files and directories which IPython uses.
+"""
+import os.path
+import tempfile
+from warnings import warn
+
+import IPython
+from IPython.utils.importstring import import_item
+from IPython.utils.path import (
+    get_home_dir,
+    get_xdg_dir,
+    get_xdg_cache_dir,
+    compress_user,
+    _writable_dir,
+    ensure_dir_exists,
+)
+
+
+def get_ipython_dir() -> str:
+    """Get the IPython directory for this platform and user.
+
+    This uses the logic in `get_home_dir` to find the home directory
+    and then adds .ipython to the end of the path.
+    """
+
+    env = os.environ
+    pjoin = os.path.join
+
+
+    ipdir_def = '.ipython'
+
+    home_dir = get_home_dir()
+    xdg_dir = get_xdg_dir()
+
+    ipdir = env.get("IPYTHONDIR", None)
+    if ipdir is None:
+        # not set explicitly, use ~/.ipython
+        ipdir = pjoin(home_dir, ipdir_def)
+        if xdg_dir:
+            # Several IPython versions (up to 1.x) defaulted to .config/ipython
+            # on Linux. We have decided to go back to using .ipython everywhere
+            xdg_ipdir = pjoin(xdg_dir, 'ipython')
+
+            if _writable_dir(xdg_ipdir):
+                cu = compress_user
+                if os.path.exists(ipdir):
+                    warn(('Ignoring {0} in favour of {1}. Remove {0} to '
+                        'get rid of this message').format(cu(xdg_ipdir), cu(ipdir)))
+                elif os.path.islink(xdg_ipdir):
+                    warn(('{0} is deprecated. Move link to {1} to '
+                        'get rid of this message').format(cu(xdg_ipdir), cu(ipdir)))
+                else:
+                    ipdir = xdg_ipdir
+
+    ipdir = os.path.normpath(os.path.expanduser(ipdir))
+
+    if os.path.exists(ipdir) and not _writable_dir(ipdir):
+        # ipdir exists, but is not writable
+        warn("IPython dir '{0}' is not a writable location,"
+                " using a temp directory.".format(ipdir))
+        ipdir = tempfile.mkdtemp()
+    elif not os.path.exists(ipdir):
+        parent = os.path.dirname(ipdir)
+        if not _writable_dir(parent):
+            # ipdir does not exist and parent isn't writable
+            warn("IPython parent '{0}' is not a writable location,"
+                    " using a temp directory.".format(parent))
+            ipdir = tempfile.mkdtemp()
+        else:
+            os.makedirs(ipdir, exist_ok=True)
+    assert isinstance(ipdir, str), "all path manipulation should be str(unicode), but are not."
+    return ipdir
+
+
+def get_ipython_cache_dir() -> str:
+    """Get the cache directory it is created if it does not exist."""
+    xdgdir = get_xdg_cache_dir()
+    if xdgdir is None:
+        return get_ipython_dir()
+    ipdir = os.path.join(xdgdir, "ipython")
+    if not os.path.exists(ipdir) and _writable_dir(xdgdir):
+        ensure_dir_exists(ipdir)
+    elif not _writable_dir(xdgdir):
+        return get_ipython_dir()
+
+    return ipdir
+
+
+def get_ipython_package_dir() -> str:
+    """Get the base directory where IPython itself is installed."""
+    ipdir = os.path.dirname(IPython.__file__)
+    assert isinstance(ipdir, str)
+    return ipdir
+
+
+def get_ipython_module_path(module_str):
+    """Find the path to an IPython module in this version of IPython.
+
+    This will always find the version of the module that is in this importable
+    IPython package. This will always return the path to the ``.py``
+    version of the module.
+    """
+    if module_str == 'IPython':
+        return os.path.join(get_ipython_package_dir(), '__init__.py')
+    mod = import_item(module_str)
+    the_path = mod.__file__.replace('.pyc', '.py')
+    the_path = the_path.replace('.pyo', '.py')
+    return the_path
+
+
+def locate_profile(profile='default'):
+    """Find the path to the folder associated with a given profile.
+
+    I.e. find $IPYTHONDIR/profile_whatever.
+    """
+    from IPython.core.profiledir import ProfileDir, ProfileDirError
+    try:
+        pd = ProfileDir.find_profile_dir_by_name(get_ipython_dir(), profile)
+    except ProfileDirError as e:
+        # IOError makes more sense when people are expecting a path
+        raise IOError("Couldn't find profile %r" % profile) from e
+    return pd.location

lib/python3.12/site-packages/IPython/sphinxext/custom_doctests.py

@@ -0,0 +1,155 @@
+"""
+Handlers for IPythonDirective's @doctest pseudo-decorator.
+
+The Sphinx extension that provides support for embedded IPython code provides
+a pseudo-decorator @doctest, which treats the input/output block as a
+doctest, raising a RuntimeError during doc generation if the actual output
+(after running the input) does not match the expected output.
+
+An example usage is:
+
+.. code-block:: rst
+
+   .. ipython::
+
+        In [1]: x = 1
+
+        @doctest
+        In [2]: x + 2
+        Out[3]: 3
+
+One can also provide arguments to the decorator. The first argument should be
+the name of a custom handler. The specification of any other arguments is
+determined by the handler. For example,
+
+.. code-block:: rst
+
+      .. ipython::
+
+         @doctest float
+         In [154]: 0.1 + 0.2
+         Out[154]: 0.3
+
+allows the actual output ``0.30000000000000004`` to match the expected output
+due to a comparison with `np.allclose`.
+
+This module contains handlers for the @doctest pseudo-decorator. Handlers
+should have the following function signature::
+
+    handler(sphinx_shell, args, input_lines, found, submitted)
+
+where `sphinx_shell` is the embedded Sphinx shell, `args` contains the list
+of arguments that follow: '@doctest handler_name', `input_lines` contains
+a list of the lines relevant to the current doctest, `found` is a string
+containing the output from the IPython shell, and `submitted` is a string
+containing the expected output from the IPython shell.
+
+Handlers must be registered in the `doctests` dict at the end of this module.
+
+"""
+
+def str_to_array(s):
+    """
+    Simplistic converter of strings from repr to float NumPy arrays.
+
+    If the repr representation has ellipsis in it, then this will fail.
+
+    Parameters
+    ----------
+    s : str
+        The repr version of a NumPy array.
+
+    Examples
+    --------
+    >>> s = "array([ 0.3,  inf,  nan])"
+    >>> a = str_to_array(s)
+
+    """
+    import numpy as np
+
+    # Need to make sure eval() knows about inf and nan.
+    # This also assumes default printoptions for NumPy.
+    from numpy import inf, nan
+
+    if s.startswith(u'array'):
+        # Remove array( and )
+        s = s[6:-1]
+
+    if s.startswith(u'['):
+        a = np.array(eval(s), dtype=float)
+    else:
+        # Assume its a regular float. Force 1D so we can index into it.
+        a = np.atleast_1d(float(s))
+    return a
+
+def float_doctest(sphinx_shell, args, input_lines, found, submitted):
+    """
+    Doctest which allow the submitted output to vary slightly from the input.
+
+    Here is how it might appear in an rst file:
+
+    .. code-block:: rst
+
+       .. ipython::
+
+          @doctest float
+          In [1]: 0.1 + 0.2
+          Out[1]: 0.3
+
+    """
+    import numpy as np
+
+    if len(args) == 2:
+        rtol = 1e-05
+        atol = 1e-08
+    else:
+        # Both must be specified if any are specified.
+        try:
+            rtol = float(args[2])
+            atol = float(args[3])
+        except IndexError:
+            e = ("Both `rtol` and `atol` must be specified "
+                 "if either are specified: {0}".format(args))
+            raise IndexError(e) from e
+
+    try:
+        submitted = str_to_array(submitted)
+        found = str_to_array(found)
+    except:
+        # For example, if the array is huge and there are ellipsis in it.
+        error = True
+    else:
+        found_isnan = np.isnan(found)
+        submitted_isnan = np.isnan(submitted)
+        error = not np.allclose(found_isnan, submitted_isnan)
+        error |= not np.allclose(found[~found_isnan],
+                                 submitted[~submitted_isnan],
+                                 rtol=rtol, atol=atol)
+
+    TAB = ' ' * 4
+    directive = sphinx_shell.directive
+    if directive is None:
+        source = 'Unavailable'
+        content = 'Unavailable'
+    else:
+        source = directive.state.document.current_source
+        # Add tabs and make into a single string.
+        content = '\n'.join([TAB + line for line in directive.content])
+
+    if error:
+
+        e = ('doctest float comparison failure\n\n'
+             'Document source: {0}\n\n'
+             'Raw content: \n{1}\n\n'
+             'On input line(s):\n{TAB}{2}\n\n'
+             'we found output:\n{TAB}{3}\n\n'
+             'instead of the expected:\n{TAB}{4}\n\n')
+        e = e.format(source, content, '\n'.join(input_lines), repr(found),
+                     repr(submitted), TAB=TAB)
+        raise RuntimeError(e)
+
+# dict of allowable doctest handlers. The key represents the first argument
+# that must be given to @doctest in order to activate the handler.
+doctests = {
+    'float': float_doctest,
+}

lib/python3.12/site-packages/IPython/sphinxext/ipython_console_highlighting.py

@@ -0,0 +1,28 @@
+"""
+reST directive for syntax-highlighting ipython interactive sessions.
+
+"""
+
+from sphinx import highlighting
+from ipython_pygments_lexers import IPyLexer
+
+
+def setup(app):
+    """Setup as a sphinx extension."""
+
+    # This is only a lexer, so adding it below to pygments appears sufficient.
+    # But if somebody knows what the right API usage should be to do that via
+    # sphinx, by all means fix it here.  At least having this setup.py
+    # suppresses the sphinx warning we'd get without it.
+    metadata = {"parallel_read_safe": True, "parallel_write_safe": True}
+    return metadata
+
+
+# Register the extension as a valid pygments lexer.
+# Alternatively, we could register the lexer with pygments instead. This would
+# require using setuptools entrypoints: http://pygments.org/docs/plugins
+
+ipy3 = IPyLexer()
+
+highlighting.lexers["ipython"] = ipy3
+highlighting.lexers["ipython3"] = ipy3

lib/python3.12/site-packages/IPython/sphinxext/ipython_directive.py

@@ -0,0 +1,1278 @@
+# -*- coding: utf-8 -*-
+"""
+Sphinx directive to support embedded IPython code.
+
+IPython provides an extension for `Sphinx <http://www.sphinx-doc.org/>`_ to
+highlight and run code.
+
+This directive allows pasting of entire interactive IPython sessions, prompts
+and all, and their code will actually get re-executed at doc build time, with
+all prompts renumbered sequentially. It also allows you to input code as a pure
+python input by giving the argument python to the directive. The output looks
+like an interactive ipython section.
+
+Here is an example of how the IPython directive can
+**run** python code, at build time.
+
+.. ipython::
+
+   In [1]: 1+1
+
+   In [1]: import datetime
+      ...: datetime.date.fromisoformat('2022-02-22')
+
+It supports IPython construct that plain
+Python does not understand (like magics):
+
+.. ipython::
+
+   In [0]: import time
+
+   In [0]: %pdoc time.sleep
+
+This will also support top-level async when using IPython 7.0+
+
+.. ipython::
+
+   In [2]: import asyncio
+      ...: print('before')
+      ...: await asyncio.sleep(1)
+      ...: print('after')
+
+
+The namespace will persist across multiple code chucks, Let's define a variable:
+
+.. ipython::
+
+   In [0]: who = "World"
+
+And now say hello:
+
+.. ipython::
+
+   In [0]: print('Hello,', who)
+
+If the current section raises an exception, you can add the ``:okexcept:`` flag
+to the current block, otherwise the build will fail.
+
+.. ipython::
+   :okexcept:
+
+   In [1]: 1/0
+
+IPython Sphinx directive module
+===============================
+
+To enable this directive, simply list it in your Sphinx ``conf.py`` file
+(making sure the directory where you placed it is visible to sphinx, as is
+needed for all Sphinx directives). For example, to enable syntax highlighting
+and the IPython directive::
+
+    extensions = ['IPython.sphinxext.ipython_console_highlighting',
+                  'IPython.sphinxext.ipython_directive']
+
+The IPython directive outputs code-blocks with the language 'ipython'. So
+if you do not have the syntax highlighting extension enabled as well, then
+all rendered code-blocks will be uncolored. By default this directive assumes
+that your prompts are unchanged IPython ones, but this can be customized.
+The configurable options that can be placed in conf.py are:
+
+ipython_savefig_dir:
+    The directory in which to save the figures. This is relative to the
+    Sphinx source directory. The default is `html_static_path`.
+ipython_rgxin:
+    The compiled regular expression to denote the start of IPython input
+    lines. The default is ``re.compile('In \\[(\\d+)\\]:\\s?(.*)\\s*')``. You
+    shouldn't need to change this.
+ipython_warning_is_error: [default to True]
+    Fail the build if something unexpected happen, for example if a block raise
+    an exception but does not have the `:okexcept:` flag. The exact behavior of
+    what is considered strict, may change between the sphinx directive version.
+ipython_rgxout:
+    The compiled regular expression to denote the start of IPython output
+    lines. The default is ``re.compile('Out\\[(\\d+)\\]:\\s?(.*)\\s*')``. You
+    shouldn't need to change this.
+ipython_promptin:
+    The string to represent the IPython input prompt in the generated ReST.
+    The default is ``'In [%d]:'``. This expects that the line numbers are used
+    in the prompt.
+ipython_promptout:
+    The string to represent the IPython prompt in the generated ReST. The
+    default is ``'Out [%d]:'``. This expects that the line numbers are used
+    in the prompt.
+ipython_mplbackend:
+    The string which specifies if the embedded Sphinx shell should import
+    Matplotlib and set the backend. The value specifies a backend that is
+    passed to `matplotlib.use()` before any lines in `ipython_execlines` are
+    executed. If not specified in conf.py, then the default value of 'agg' is
+    used. To use the IPython directive without matplotlib as a dependency, set
+    the value to `None`. It may end up that matplotlib is still imported
+    if the user specifies so in `ipython_execlines` or makes use of the
+    @savefig pseudo decorator.
+ipython_execlines:
+    A list of strings to be exec'd in the embedded Sphinx shell. Typical
+    usage is to make certain packages always available. Set this to an empty
+    list if you wish to have no imports always available. If specified in
+    ``conf.py`` as `None`, then it has the effect of making no imports available.
+    If omitted from conf.py altogether, then the default value of
+    ['import numpy as np', 'import matplotlib.pyplot as plt'] is used.
+ipython_holdcount
+    When the @suppress pseudo-decorator is used, the execution count can be
+    incremented or not. The default behavior is to hold the execution count,
+    corresponding to a value of `True`. Set this to `False` to increment
+    the execution count after each suppressed command.
+
+As an example, to use the IPython directive when `matplotlib` is not available,
+one sets the backend to `None`::
+
+    ipython_mplbackend = None
+
+An example usage of the directive is:
+
+.. code-block:: rst
+
+    .. ipython::
+
+        In [1]: x = 1
+
+        In [2]: y = x**2
+
+        In [3]: print(y)
+
+See http://matplotlib.org/sampledoc/ipython_directive.html for additional
+documentation.
+
+Pseudo-Decorators
+=================
+
+Note: Only one decorator is supported per input. If more than one decorator
+is specified, then only the last one is used.
+
+In addition to the Pseudo-Decorators/options described at the above link,
+several enhancements have been made. The directive will emit a message to the
+console at build-time if code-execution resulted in an exception or warning.
+You can suppress these on a per-block basis by specifying the :okexcept:
+or :okwarning: options:
+
+.. code-block:: rst
+
+    .. ipython::
+        :okexcept:
+        :okwarning:
+
+        In [1]: 1/0
+        In [2]: # raise warning.
+
+To Do
+=====
+
+- Turn the ad-hoc test() function into a real test suite.
+- Break up ipython-specific functionality from matplotlib stuff into better
+  separated code.
+
+"""
+
+# Authors
+# =======
+#
+# - John D Hunter: original author.
+# - Fernando Perez: refactoring, documentation, cleanups, port to 0.11.
+# - VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations.
+# - Skipper Seabold, refactoring, cleanups, pure python addition
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib
+import atexit
+import errno
+import os
+import pathlib
+import re
+import sys
+import tempfile
+import ast
+import warnings
+import shutil
+from io import StringIO
+from typing import Any, Dict, Set
+
+# Third-party
+from docutils.parsers.rst import directives
+from docutils.parsers.rst import Directive
+from sphinx.util import logging
+
+# Our own
+from traitlets.config import Config
+from IPython import InteractiveShell
+from IPython.core.profiledir import ProfileDir
+
+use_matplotlib = False
+try:
+    import matplotlib
+    use_matplotlib = True
+except Exception:
+    pass
+
+#-----------------------------------------------------------------------------
+# Globals
+#-----------------------------------------------------------------------------
+# for tokenizing blocks
+COMMENT, INPUT, OUTPUT =  range(3)
+
+PSEUDO_DECORATORS = ["suppress", "verbatim", "savefig", "doctest"]
+
+#-----------------------------------------------------------------------------
+# Functions and class declarations
+#-----------------------------------------------------------------------------
+
+def block_parser(part, rgxin, rgxout, fmtin, fmtout):
+    """
+    part is a string of ipython text, comprised of at most one
+    input, one output, comments, and blank lines.  The block parser
+    parses the text into a list of::
+
+      blocks = [ (TOKEN0, data0), (TOKEN1, data1), ...]
+
+    where TOKEN is one of [COMMENT | INPUT | OUTPUT ] and
+    data is, depending on the type of token::
+
+      COMMENT : the comment string
+
+      INPUT: the (DECORATOR, INPUT_LINE, REST) where
+         DECORATOR: the input decorator (or None)
+         INPUT_LINE: the input as string (possibly multi-line)
+         REST : any stdout generated by the input line (not OUTPUT)
+
+      OUTPUT: the output string, possibly multi-line
+
+    """
+    block = []
+    lines = part.split('\n')
+    N = len(lines)
+    i = 0
+    decorator = None
+    while 1:
+
+        if i==N:
+            # nothing left to parse -- the last line
+            break
+
+        line = lines[i]
+        i += 1
+        line_stripped = line.strip()
+        if line_stripped.startswith('#'):
+            block.append((COMMENT, line))
+            continue
+
+        if any(
+            line_stripped.startswith("@" + pseudo_decorator)
+            for pseudo_decorator in PSEUDO_DECORATORS
+        ):
+            if decorator:
+                raise RuntimeError(
+                    "Applying multiple pseudo-decorators on one line is not supported"
+                )
+            else:
+                decorator = line_stripped
+                continue
+
+        # does this look like an input line?
+        matchin = rgxin.match(line)
+        if matchin:
+            lineno, inputline = int(matchin.group(1)), matchin.group(2)
+
+            # the ....: continuation string
+            continuation = '   %s:'%''.join(['.']*(len(str(lineno))+2))
+            Nc = len(continuation)
+            # input lines can continue on for more than one line, if
+            # we have a '\' line continuation char or a function call
+            # echo line 'print'.  The input line can only be
+            # terminated by the end of the block or an output line, so
+            # we parse out the rest of the input line if it is
+            # multiline as well as any echo text
+
+            rest = []
+            while i<N:
+
+                # look ahead; if the next line is blank, or a comment, or
+                # an output line, we're done
+
+                nextline = lines[i]
+                matchout = rgxout.match(nextline)
+                # print("nextline=%s, continuation=%s, starts=%s"%(nextline, continuation, nextline.startswith(continuation)))
+                if matchout or nextline.startswith('#'):
+                    break
+                elif nextline.startswith(continuation):
+                    # The default ipython_rgx* treat the space following the colon as optional.
+                    # However, If the space is there we must consume it or code
+                    # employing the cython_magic extension will fail to execute.
+                    #
+                    # This works with the default ipython_rgx* patterns,
+                    # If you modify them, YMMV.
+                    nextline = nextline[Nc:]
+                    if nextline and nextline[0] == ' ':
+                        nextline = nextline[1:]
+
+                    inputline += '\n' +  nextline
+                else:
+                    rest.append(nextline)
+                i+= 1
+
+            block.append((INPUT, (decorator, inputline, '\n'.join(rest))))
+            continue
+
+        # if it looks like an output line grab all the text to the end
+        # of the block
+        matchout = rgxout.match(line)
+        if matchout:
+            lineno, output = int(matchout.group(1)), matchout.group(2)
+            if i<N-1:
+                output = '\n'.join([output] + lines[i:])
+
+            block.append((OUTPUT, output))
+            break
+
+    return block
+
+
+class EmbeddedSphinxShell:
+    """An embedded IPython instance to run inside Sphinx"""
+
+    def __init__(self, exec_lines=None):
+
+        self.cout = StringIO()
+
+        if exec_lines is None:
+            exec_lines = []
+
+        # Create config object for IPython
+        config = Config()
+        config.HistoryManager.hist_file = ':memory:'
+        config.InteractiveShell.autocall = False
+        config.InteractiveShell.autoindent = False
+        config.InteractiveShell.colors = "nocolor"
+
+        # create a profile so instance history isn't saved
+        tmp_profile_dir = tempfile.mkdtemp(prefix='profile_')
+        profname = 'auto_profile_sphinx_build'
+        pdir = os.path.join(tmp_profile_dir,profname)
+        profile = ProfileDir.create_profile_dir(pdir)
+
+        # Create and initialize global ipython, but don't start its mainloop.
+        # This will persist across different EmbeddedSphinxShell instances.
+        IP = InteractiveShell.instance(config=config, profile_dir=profile)
+        atexit.register(self.cleanup)
+
+        # Store a few parts of IPython we'll need.
+        self.IP = IP
+        self.user_ns = self.IP.user_ns
+        self.user_global_ns = self.IP.user_global_ns
+
+        self.input = ''
+        self.output = ''
+        self.tmp_profile_dir = tmp_profile_dir
+
+        self.is_verbatim = False
+        self.is_doctest = False
+        self.is_suppress = False
+
+        # Optionally, provide more detailed information to shell.
+        # this is assigned by the SetUp method of IPythonDirective
+        # to point at itself.
+        #
+        # So, you can access handy things at self.directive.state
+        self.directive = None
+
+        # on the first call to the savefig decorator, we'll import
+        # pyplot as plt so we can make a call to the plt.gcf().savefig
+        self._pyplot_imported = False
+
+        # Prepopulate the namespace.
+        for line in exec_lines:
+            self.process_input_line(line, store_history=False)
+
+    def cleanup(self):
+        shutil.rmtree(self.tmp_profile_dir, ignore_errors=True)
+
+    def clear_cout(self):
+        self.cout.seek(0)
+        self.cout.truncate(0)
+
+    def process_input_line(self, line, store_history):
+        return self.process_input_lines([line], store_history=store_history)
+
+    def process_input_lines(self, lines, store_history=True):
+        """process the input, capturing stdout"""
+        stdout = sys.stdout
+        source_raw = '\n'.join(lines)
+        try:
+            sys.stdout = self.cout
+            self.IP.run_cell(source_raw, store_history=store_history)
+        finally:
+            sys.stdout = stdout
+
+    def process_image(self, decorator):
+        """
+        # build out an image directive like
+        # .. image:: somefile.png
+        #    :width 4in
+        #
+        # from an input like
+        # savefig somefile.png width=4in
+        """
+        savefig_dir = self.savefig_dir
+        source_dir = self.source_dir
+        saveargs = decorator.split(' ')
+        filename = saveargs[1]
+        # insert relative path to image file in source
+        # as absolute path for Sphinx
+        # sphinx expects a posix path, even on Windows
+        path = pathlib.Path(savefig_dir, filename)
+        outfile = '/' + path.relative_to(source_dir).as_posix()
+
+        imagerows = ['.. image:: %s' % outfile]
+
+        for kwarg in saveargs[2:]:
+            arg, val = kwarg.split('=')
+            arg = arg.strip()
+            val = val.strip()
+            imagerows.append('   :%s: %s'%(arg, val))
+
+        image_file = os.path.basename(outfile) # only return file name
+        image_directive = '\n'.join(imagerows)
+        return image_file, image_directive
+
+    # Callbacks for each type of token
+    def process_input(self, data, input_prompt, lineno):
+        """
+        Process data block for INPUT token.
+
+        """
+        decorator, input, rest = data
+        image_file = None
+        image_directive = None
+
+        is_verbatim = decorator=='@verbatim' or self.is_verbatim
+        is_doctest = (decorator is not None and \
+                     decorator.startswith('@doctest')) or self.is_doctest
+        is_suppress = decorator=='@suppress' or self.is_suppress
+        is_okexcept = decorator=='@okexcept' or self.is_okexcept
+        is_okwarning = decorator=='@okwarning' or self.is_okwarning
+        is_savefig = decorator is not None and \
+                     decorator.startswith('@savefig')
+
+        input_lines = input.split('\n')
+        if len(input_lines) > 1:
+            if input_lines[-1] != "":
+                input_lines.append('') # make sure there's a blank line
+                                       # so splitter buffer gets reset
+
+        continuation = '   %s:'%''.join(['.']*(len(str(lineno))+2))
+
+        if is_savefig:
+            image_file, image_directive = self.process_image(decorator)
+
+        ret = []
+        is_semicolon = False
+
+        # Hold the execution count, if requested to do so.
+        if is_suppress and self.hold_count:
+            store_history = False
+        else:
+            store_history = True
+
+        # Note: catch_warnings is not thread safe
+        with warnings.catch_warnings(record=True) as ws:
+            if input_lines[0].endswith(';'):
+                is_semicolon = True
+            #for i, line in enumerate(input_lines):
+
+            # process the first input line
+            if is_verbatim:
+                self.process_input_lines([''])
+                self.IP.execution_count += 1 # increment it anyway
+            else:
+                # only submit the line in non-verbatim mode
+                self.process_input_lines(input_lines, store_history=store_history)
+
+        if not is_suppress:
+            for i, line in enumerate(input_lines):
+                if i == 0:
+                    formatted_line = '%s %s'%(input_prompt, line)
+                else:
+                    formatted_line = '%s %s'%(continuation, line)
+                ret.append(formatted_line)
+
+        if not is_suppress and len(rest.strip()) and is_verbatim:
+            # The "rest" is the standard output of the input. This needs to be
+            # added when in verbatim mode. If there is no "rest", then we don't
+            # add it, as the new line will be added by the processed output.
+            ret.append(rest)
+
+        # Fetch the processed output. (This is not the submitted output.)
+        self.cout.seek(0)
+        processed_output = self.cout.read()
+        if not is_suppress and not is_semicolon:
+            #
+            # In IPythonDirective.run, the elements of `ret` are eventually
+            # combined such that '' entries correspond to newlines. So if
+            # `processed_output` is equal to '', then the adding it to `ret`
+            # ensures that there is a blank line between consecutive inputs
+            # that have no outputs, as in:
+            #
+            #    In [1]: x = 4
+            #
+            #    In [2]: x = 5
+            #
+            # When there is processed output, it has a '\n' at the tail end. So
+            # adding the output to `ret` will provide the necessary spacing
+            # between consecutive input/output blocks, as in:
+            #
+            #   In [1]: x
+            #   Out[1]: 5
+            #
+            #   In [2]: x
+            #   Out[2]: 5
+            #
+            # When there is stdout from the input, it also has a '\n' at the
+            # tail end, and so this ensures proper spacing as well. E.g.:
+            #
+            #   In [1]: print(x)
+            #   5
+            #
+            #   In [2]: x = 5
+            #
+            # When in verbatim mode, `processed_output` is empty (because
+            # nothing was passed to IP. Sometimes the submitted code block has
+            # an Out[] portion and sometimes it does not. When it does not, we
+            # need to ensure proper spacing, so we have to add '' to `ret`.
+            # However, if there is an Out[] in the submitted code, then we do
+            # not want to add a newline as `process_output` has stuff to add.
+            # The difficulty is that `process_input` doesn't know if
+            # `process_output` will be called---so it doesn't know if there is
+            # Out[] in the code block. The requires that we include a hack in
+            # `process_block`. See the comments there.
+            #
+            ret.append(processed_output)
+        elif is_semicolon:
+            # Make sure there is a newline after the semicolon.
+            ret.append('')
+
+        # context information
+        filename = "Unknown"
+        lineno = 0
+        if self.directive.state:
+            filename = self.directive.state.document.current_source
+            lineno = self.directive.state.document.current_line
+
+        # Use sphinx logger for warnings
+        logger = logging.getLogger(__name__)
+
+        # output any exceptions raised during execution to stdout
+        # unless :okexcept: has been specified.
+        if not is_okexcept and (
+            ("Traceback" in processed_output) or ("SyntaxError" in processed_output)
+        ):
+            s = "\n>>>" + ("-" * 73) + "\n"
+            s += "Exception in %s at block ending on line %s\n" % (filename, lineno)
+            s += "Specify :okexcept: as an option in the ipython:: block to suppress this message\n"
+            s += processed_output + "\n"
+            s += "<<<" + ("-" * 73)
+            logger.warning(s)
+            if self.warning_is_error:
+                raise RuntimeError(
+                    "Unexpected exception in `{}` line {}".format(filename, lineno)
+                )
+
+        # output any warning raised during execution to stdout
+        # unless :okwarning: has been specified.
+        if not is_okwarning:
+            for w in ws:
+                s = "\n>>>" + ("-" * 73) + "\n"
+                s += "Warning in %s at block ending on line %s\n" % (filename, lineno)
+                s += "Specify :okwarning: as an option in the ipython:: block to suppress this message\n"
+                s += ("-" * 76) + "\n"
+                s += warnings.formatwarning(
+                    w.message, w.category, w.filename, w.lineno, w.line
+                )
+                s += "<<<" + ("-" * 73)
+                logger.warning(s)
+                if self.warning_is_error:
+                    raise RuntimeError(
+                        "Unexpected warning in `{}` line {}".format(filename, lineno)
+                    )
+
+        self.clear_cout()
+        return (ret, input_lines, processed_output,
+                is_doctest, decorator, image_file, image_directive)
+
+
+    def process_output(self, data, output_prompt, input_lines, output,
+                       is_doctest, decorator, image_file):
+        """
+        Process data block for OUTPUT token.
+
+        """
+        # Recall: `data` is the submitted output, and `output` is the processed
+        # output from `input_lines`.
+
+        TAB = ' ' * 4
+
+        if is_doctest and output is not None:
+
+            found = output # This is the processed output
+            found = found.strip()
+            submitted = data.strip()
+
+            if self.directive is None:
+                source = 'Unavailable'
+                content = 'Unavailable'
+            else:
+                source = self.directive.state.document.current_source
+                content = self.directive.content
+                # Add tabs and join into a single string.
+                content = '\n'.join([TAB + line for line in content])
+
+            # Make sure the output contains the output prompt.
+            ind = found.find(output_prompt)
+            if ind < 0:
+                e = ('output does not contain output prompt\n\n'
+                     'Document source: {0}\n\n'
+                     'Raw content: \n{1}\n\n'
+                     'Input line(s):\n{TAB}{2}\n\n'
+                     'Output line(s):\n{TAB}{3}\n\n')
+                e = e.format(source, content, '\n'.join(input_lines),
+                             repr(found), TAB=TAB)
+                raise RuntimeError(e)
+            found = found[len(output_prompt):].strip()
+
+            # Handle the actual doctest comparison.
+            if decorator.strip() == '@doctest':
+                # Standard doctest
+                if found != submitted:
+                    e = ('doctest failure\n\n'
+                         'Document source: {0}\n\n'
+                         'Raw content: \n{1}\n\n'
+                         'On input line(s):\n{TAB}{2}\n\n'
+                         'we found output:\n{TAB}{3}\n\n'
+                         'instead of the expected:\n{TAB}{4}\n\n')
+                    e = e.format(source, content, '\n'.join(input_lines),
+                                 repr(found), repr(submitted), TAB=TAB)
+                    raise RuntimeError(e)
+            else:
+                self.custom_doctest(decorator, input_lines, found, submitted)
+
+        # When in verbatim mode, this holds additional submitted output
+        # to be written in the final Sphinx output.
+        # https://github.com/ipython/ipython/issues/5776
+        out_data = []
+
+        is_verbatim = decorator=='@verbatim' or self.is_verbatim
+        if is_verbatim and data.strip():
+            # Note that `ret` in `process_block` has '' as its last element if
+            # the code block was in verbatim mode. So if there is no submitted
+            # output, then we will have proper spacing only if we do not add
+            # an additional '' to `out_data`. This is why we condition on
+            # `and data.strip()`.
+
+            # The submitted output has no output prompt. If we want the
+            # prompt and the code to appear, we need to join them now
+            # instead of adding them separately---as this would create an
+            # undesired newline. How we do this ultimately depends on the
+            # format of the output regex. I'll do what works for the default
+            # prompt for now, and we might have to adjust if it doesn't work
+            # in other cases. Finally, the submitted output does not have
+            # a trailing newline, so we must add it manually.
+            out_data.append("{0} {1}\n".format(output_prompt, data))
+
+        return out_data
+
+    def process_comment(self, data):
+        """Process data fPblock for COMMENT token."""
+        if not self.is_suppress:
+            return [data]
+
+    def save_image(self, image_file):
+        """
+        Saves the image file to disk.
+        """
+        self.ensure_pyplot()
+        command = 'plt.gcf().savefig("%s")'%image_file
+        # print('SAVEFIG', command)  # dbg
+        self.process_input_line('bookmark ipy_thisdir', store_history=False)
+        self.process_input_line('cd -b ipy_savedir', store_history=False)
+        self.process_input_line(command, store_history=False)
+        self.process_input_line('cd -b ipy_thisdir', store_history=False)
+        self.process_input_line('bookmark -d ipy_thisdir', store_history=False)
+        self.clear_cout()
+
+    def process_block(self, block):
+        """
+        process block from the block_parser and return a list of processed lines
+        """
+        ret = []
+        output = None
+        input_lines = None
+        lineno = self.IP.execution_count
+
+        input_prompt = self.promptin % lineno
+        output_prompt = self.promptout % lineno
+        image_file = None
+        image_directive = None
+
+        found_input = False
+        for token, data in block:
+            if token == COMMENT:
+                out_data = self.process_comment(data)
+            elif token == INPUT:
+                found_input = True
+                (out_data, input_lines, output, is_doctest,
+                 decorator, image_file, image_directive) = \
+                          self.process_input(data, input_prompt, lineno)
+            elif token == OUTPUT:
+                if not found_input:
+
+                    TAB = ' ' * 4
+                    linenumber = 0
+                    source = 'Unavailable'
+                    content = 'Unavailable'
+                    if self.directive:
+                        linenumber = self.directive.state.document.current_line
+                        source = self.directive.state.document.current_source
+                        content = self.directive.content
+                        # Add tabs and join into a single string.
+                        content = '\n'.join([TAB + line for line in content])
+
+                    e = ('\n\nInvalid block: Block contains an output prompt '
+                         'without an input prompt.\n\n'
+                         'Document source: {0}\n\n'
+                         'Content begins at line {1}: \n\n{2}\n\n'
+                         'Problematic block within content: \n\n{TAB}{3}\n\n')
+                    e = e.format(source, linenumber, content, block, TAB=TAB)
+
+                    # Write, rather than include in exception, since Sphinx
+                    # will truncate tracebacks.
+                    sys.stdout.write(e)
+                    raise RuntimeError('An invalid block was detected.')
+                out_data = \
+                    self.process_output(data, output_prompt, input_lines,
+                                        output, is_doctest, decorator,
+                                        image_file)
+                if out_data:
+                    # Then there was user submitted output in verbatim mode.
+                    # We need to remove the last element of `ret` that was
+                    # added in `process_input`, as it is '' and would introduce
+                    # an undesirable newline.
+                    assert(ret[-1] == '')
+                    del ret[-1]
+
+            if out_data:
+                ret.extend(out_data)
+
+        # save the image files
+        if image_file is not None:
+            self.save_image(image_file)
+
+        return ret, image_directive
+
+    def ensure_pyplot(self):
+        """
+        Ensures that pyplot has been imported into the embedded IPython shell.
+
+        Also, makes sure to set the backend appropriately if not set already.
+
+        """
+        # We are here if the @figure pseudo decorator was used. Thus, it's
+        # possible that we could be here even if python_mplbackend were set to
+        # `None`. That's also strange and perhaps worthy of raising an
+        # exception, but for now, we just set the backend to 'agg'.
+
+        if not self._pyplot_imported:
+            if 'matplotlib.backends' not in sys.modules:
+                # Then ipython_matplotlib was set to None but there was a
+                # call to the @figure decorator (and ipython_execlines did
+                # not set a backend).
+                #raise Exception("No backend was set, but @figure was used!")
+                import matplotlib
+                matplotlib.use('agg')
+
+            # Always import pyplot into embedded shell.
+            self.process_input_line('import matplotlib.pyplot as plt',
+                                    store_history=False)
+            self._pyplot_imported = True
+
+    def process_pure_python(self, content):
+        """
+        content is a list of strings. it is unedited directive content
+
+        This runs it line by line in the InteractiveShell, prepends
+        prompts as needed capturing stderr and stdout, then returns
+        the content as a list as if it were ipython code
+        """
+        output = []
+        savefig = False # keep up with this to clear figure
+        multiline = False # to handle line continuation
+        multiline_start = None
+        fmtin = self.promptin
+
+        ct = 0
+
+        for lineno, line in enumerate(content):
+
+            line_stripped = line.strip()
+            if not len(line):
+                output.append(line)
+                continue
+
+            # handle pseudo-decorators, whilst ensuring real python decorators are treated as input
+            if any(
+                line_stripped.startswith("@" + pseudo_decorator)
+                for pseudo_decorator in PSEUDO_DECORATORS
+            ):
+                output.extend([line])
+                if 'savefig' in line:
+                    savefig = True # and need to clear figure
+                continue
+
+            # handle comments
+            if line_stripped.startswith('#'):
+                output.extend([line])
+                continue
+
+            # deal with lines checking for multiline
+            continuation  = u'   %s:'% ''.join(['.']*(len(str(ct))+2))
+            if not multiline:
+                modified = u"%s %s" % (fmtin % ct, line_stripped)
+                output.append(modified)
+                ct += 1
+                try:
+                    ast.parse(line_stripped)
+                    output.append(u'')
+                except Exception: # on a multiline
+                    multiline = True
+                    multiline_start = lineno
+            else: # still on a multiline
+                modified = u'%s %s' % (continuation, line)
+                output.append(modified)
+
+                # if the next line is indented, it should be part of multiline
+                if len(content) > lineno + 1:
+                    nextline = content[lineno + 1]
+                    if len(nextline) - len(nextline.lstrip()) > 3:
+                        continue
+                try:
+                    mod = ast.parse(
+                            '\n'.join(content[multiline_start:lineno+1]))
+                    if isinstance(mod.body[0], ast.FunctionDef):
+                        # check to see if we have the whole function
+                        for element in mod.body[0].body:
+                            if isinstance(element, ast.Return):
+                                multiline = False
+                    else:
+                        output.append(u'')
+                        multiline = False
+                except Exception:
+                    pass
+
+            if savefig: # clear figure if plotted
+                self.ensure_pyplot()
+                self.process_input_line('plt.clf()', store_history=False)
+                self.clear_cout()
+                savefig = False
+
+        return output
+
+    def custom_doctest(self, decorator, input_lines, found, submitted):
+        """
+        Perform a specialized doctest.
+
+        """
+        from .custom_doctests import doctests
+
+        args = decorator.split()
+        doctest_type = args[1]
+        if doctest_type in doctests:
+            doctests[doctest_type](self, args, input_lines, found, submitted)
+        else:
+            e = "Invalid option to @doctest: {0}".format(doctest_type)
+            raise Exception(e)
+
+
+class IPythonDirective(Directive):
+
+    has_content: bool = True
+    required_arguments: int = 0
+    optional_arguments: int = 4  # python, suppress, verbatim, doctest
+    final_argumuent_whitespace: bool = True
+    option_spec: Dict[str, Any] = {
+        "python": directives.unchanged,
+        "suppress": directives.flag,
+        "verbatim": directives.flag,
+        "doctest": directives.flag,
+        "okexcept": directives.flag,
+        "okwarning": directives.flag,
+    }
+
+    shell = None
+
+    seen_docs: Set = set()
+
+    def get_config_options(self):
+        # contains sphinx configuration variables
+        config = self.state.document.settings.env.config
+
+        # get config variables to set figure output directory
+        savefig_dir = config.ipython_savefig_dir
+        source_dir = self.state.document.settings.env.srcdir
+        savefig_dir = os.path.join(source_dir, savefig_dir)
+
+        # get regex and prompt stuff
+        rgxin      = config.ipython_rgxin
+        rgxout     = config.ipython_rgxout
+        warning_is_error= config.ipython_warning_is_error
+        promptin   = config.ipython_promptin
+        promptout  = config.ipython_promptout
+        mplbackend = config.ipython_mplbackend
+        exec_lines = config.ipython_execlines
+        hold_count = config.ipython_holdcount
+
+        return (savefig_dir, source_dir, rgxin, rgxout,
+                promptin, promptout, mplbackend, exec_lines, hold_count, warning_is_error)
+
+    def setup(self):
+        # Get configuration values.
+        (savefig_dir, source_dir, rgxin, rgxout, promptin, promptout,
+         mplbackend, exec_lines, hold_count, warning_is_error) = self.get_config_options()
+
+        try:
+            os.makedirs(savefig_dir)
+        except OSError as e:
+            if e.errno != errno.EEXIST:
+                raise
+
+        if self.shell is None:
+            # We will be here many times.  However, when the
+            # EmbeddedSphinxShell is created, its interactive shell member
+            # is the same for each instance.
+
+            if mplbackend and 'matplotlib.backends' not in sys.modules and use_matplotlib:
+                import matplotlib
+                matplotlib.use(mplbackend)
+
+            # Must be called after (potentially) importing matplotlib and
+            # setting its backend since exec_lines might import pylab.
+            self.shell = EmbeddedSphinxShell(exec_lines)
+
+            # Store IPython directive to enable better error messages
+            self.shell.directive = self
+
+        # reset the execution count if we haven't processed this doc
+        #NOTE: this may be borked if there are multiple seen_doc tmp files
+        #check time stamp?
+        if self.state.document.current_source not in self.seen_docs:
+            self.shell.IP.history_manager.reset()
+            self.shell.IP.execution_count = 1
+            self.seen_docs.add(self.state.document.current_source)
+
+        # and attach to shell so we don't have to pass them around
+        self.shell.rgxin = rgxin
+        self.shell.rgxout = rgxout
+        self.shell.promptin = promptin
+        self.shell.promptout = promptout
+        self.shell.savefig_dir = savefig_dir
+        self.shell.source_dir = source_dir
+        self.shell.hold_count = hold_count
+        self.shell.warning_is_error = warning_is_error
+
+        # setup bookmark for saving figures directory
+        self.shell.process_input_line(
+            'bookmark ipy_savedir "%s"' % savefig_dir, store_history=False
+        )
+        self.shell.clear_cout()
+
+        return rgxin, rgxout, promptin, promptout
+
+    def teardown(self):
+        # delete last bookmark
+        self.shell.process_input_line('bookmark -d ipy_savedir',
+                                      store_history=False)
+        self.shell.clear_cout()
+
+    def run(self):
+        debug = False
+
+        #TODO, any reason block_parser can't be a method of embeddable shell
+        # then we wouldn't have to carry these around
+        rgxin, rgxout, promptin, promptout = self.setup()
+
+        options = self.options
+        self.shell.is_suppress = 'suppress' in options
+        self.shell.is_doctest = 'doctest' in options
+        self.shell.is_verbatim = 'verbatim' in options
+        self.shell.is_okexcept = 'okexcept' in options
+        self.shell.is_okwarning = 'okwarning' in options
+
+        # handle pure python code
+        if 'python' in self.arguments:
+            content = self.content
+            self.content = self.shell.process_pure_python(content)
+
+        # parts consists of all text within the ipython-block.
+        # Each part is an input/output block.
+        parts = '\n'.join(self.content).split('\n\n')
+
+        lines = ['.. code-block:: ipython', '']
+        figures = []
+
+        # Use sphinx logger for warnings
+        logger = logging.getLogger(__name__)
+
+        for part in parts:
+            block = block_parser(part, rgxin, rgxout, promptin, promptout)
+            if len(block):
+                rows, figure = self.shell.process_block(block)
+                for row in rows:
+                    lines.extend(['   {0}'.format(line)
+                                  for line in row.split('\n')])
+
+                if figure is not None:
+                    figures.append(figure)
+            else:
+                message = 'Code input with no code at {}, line {}'\
+                            .format(
+                                self.state.document.current_source,
+                                self.state.document.current_line)
+                if self.shell.warning_is_error:
+                    raise RuntimeError(message)
+                else:
+                    logger.warning(message)
+
+        for figure in figures:
+            lines.append('')
+            lines.extend(figure.split('\n'))
+            lines.append('')
+
+        if len(lines) > 2:
+            if debug:
+                print('\n'.join(lines))
+            else:
+                # This has to do with input, not output. But if we comment
+                # these lines out, then no IPython code will appear in the
+                # final output.
+                self.state_machine.insert_input(
+                    lines, self.state_machine.input_lines.source(0))
+
+        # cleanup
+        self.teardown()
+
+        return []
+
+# Enable as a proper Sphinx directive
+def setup(app):
+    setup.app = app
+
+    app.add_directive('ipython', IPythonDirective)
+    app.add_config_value('ipython_savefig_dir', 'savefig', 'env')
+    app.add_config_value('ipython_warning_is_error', True, 'env')
+    app.add_config_value('ipython_rgxin',
+                         re.compile(r'In \[(\d+)\]:\s?(.*)\s*'), 'env')
+    app.add_config_value('ipython_rgxout',
+                         re.compile(r'Out\[(\d+)\]:\s?(.*)\s*'), 'env')
+    app.add_config_value('ipython_promptin', 'In [%d]:', 'env')
+    app.add_config_value('ipython_promptout', 'Out[%d]:', 'env')
+
+    # We could just let matplotlib pick whatever is specified as the default
+    # backend in the matplotlibrc file, but this would cause issues if the
+    # backend didn't work in headless environments. For this reason, 'agg'
+    # is a good default backend choice.
+    app.add_config_value('ipython_mplbackend', 'agg', 'env')
+
+    # If the user sets this config value to `None`, then EmbeddedSphinxShell's
+    # __init__ method will treat it as [].
+    execlines = ['import numpy as np']
+    if use_matplotlib:
+        execlines.append('import matplotlib.pyplot as plt')
+    app.add_config_value('ipython_execlines', execlines, 'env')
+
+    app.add_config_value('ipython_holdcount', True, 'env')
+
+    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
+    return metadata
+
+# Simple smoke test, needs to be converted to a proper automatic test.
+def test():
+
+    examples = [
+        r"""
+In [9]: pwd
+Out[9]: '/home/jdhunter/py4science/book'
+
+In [10]: cd bookdata/
+/home/jdhunter/py4science/book/bookdata
+
+In [2]: from pylab import *
+
+In [2]: ion()
+
+In [3]: im = imread('stinkbug.png')
+
+@savefig mystinkbug.png width=4in
+In [4]: imshow(im)
+Out[4]: <matplotlib.image.AxesImage object at 0x39ea850>
+
+""",
+        r"""
+
+In [1]: x = 'hello world'
+
+# string methods can be
+# used to alter the string
+@doctest
+In [2]: x.upper()
+Out[2]: 'HELLO WORLD'
+
+@verbatim
+In [3]: x.st<TAB>
+x.startswith  x.strip
+""",
+    r"""
+
+In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\
+   .....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv'
+
+In [131]: print url.split('&')
+['http://ichart.finance.yahoo.com/table.csv?s=CROX', 'd=9', 'e=22', 'f=2009', 'g=d', 'a=1', 'b=8', 'c=2006', 'ignore=.csv']
+
+In [60]: import urllib
+
+""",
+    r"""\
+
+In [133]: import numpy.random
+
+@suppress
+In [134]: numpy.random.seed(2358)
+
+@doctest
+In [135]: numpy.random.rand(10,2)
+Out[135]:
+array([[ 0.64524308,  0.59943846],
+       [ 0.47102322,  0.8715456 ],
+       [ 0.29370834,  0.74776844],
+       [ 0.99539577,  0.1313423 ],
+       [ 0.16250302,  0.21103583],
+       [ 0.81626524,  0.1312433 ],
+       [ 0.67338089,  0.72302393],
+       [ 0.7566368 ,  0.07033696],
+       [ 0.22591016,  0.77731835],
+       [ 0.0072729 ,  0.34273127]])
+
+""",
+
+    r"""
+In [106]: print x
+jdh
+
+In [109]: for i in range(10):
+   .....:     print i
+   .....:
+   .....:
+0
+1
+2
+3
+4
+5
+6
+7
+8
+9
+""",
+
+        r"""
+
+In [144]: from pylab import *
+
+In [145]: ion()
+
+# use a semicolon to suppress the output
+@savefig test_hist.png width=4in
+In [151]: hist(np.random.randn(10000), 100);
+
+
+@savefig test_plot.png width=4in
+In [151]: plot(np.random.randn(10000), 'o');
+   """,
+
+        r"""
+# use a semicolon to suppress the output
+In [151]: plt.clf()
+
+@savefig plot_simple.png width=4in
+In [151]: plot([1,2,3])
+
+@savefig hist_simple.png width=4in
+In [151]: hist(np.random.randn(10000), 100);
+
+""",
+     r"""
+# update the current fig
+In [151]: ylabel('number')
+
+In [152]: title('normal distribution')
+
+
+@savefig hist_with_text.png
+In [153]: grid(True)
+
+@doctest float
+In [154]: 0.1 + 0.2
+Out[154]: 0.3
+
+@doctest float
+In [155]: np.arange(16).reshape(4,4)
+Out[155]:
+array([[ 0,  1,  2,  3],
+       [ 4,  5,  6,  7],
+       [ 8,  9, 10, 11],
+       [12, 13, 14, 15]])
+
+In [1]: x = np.arange(16, dtype=float).reshape(4,4)
+
+In [2]: x[0,0] = np.inf
+
+In [3]: x[0,1] = np.nan
+
+@doctest float
+In [4]: x
+Out[4]:
+array([[ inf,  nan,   2.,   3.],
+       [  4.,   5.,   6.,   7.],
+       [  8.,   9.,  10.,  11.],
+       [ 12.,  13.,  14.,  15.]])
+
+
+        """,
+        ]
+    # skip local-file depending first example:
+    examples = examples[1:]
+
+    #ipython_directive.DEBUG = True  # dbg
+    #options = dict(suppress=True)  # dbg
+    options = {}
+    for example in examples:
+        content = example.split('\n')
+        IPythonDirective('debug', arguments=None, options=options,
+                          content=content, lineno=0,
+                          content_offset=None, block_text=None,
+                          state=None, state_machine=None,
+                          )
+
+# Run test suite as a script
+if __name__=='__main__':
+    if not os.path.isdir('_static'):
+        os.mkdir('_static')
+    test()
+    print('All OK? Check figures in _static/')

lib/python3.12/site-packages/IPython/testing/__init__.py

@@ -0,0 +1,20 @@
+"""Testing support (tools to test IPython itself).
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2009-2011  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+
+import os
+
+#-----------------------------------------------------------------------------
+# Constants
+#-----------------------------------------------------------------------------
+
+# We scale all timeouts via this factor, slow machines can increase it
+IPYTHON_TESTING_TIMEOUT_SCALE = float(os.getenv(
+                                    'IPYTHON_TESTING_TIMEOUT_SCALE', 1))

lib/python3.12/site-packages/IPython/testing/decorators.py

@@ -0,0 +1,147 @@
+import os
+import shutil
+import sys
+import tempfile
+from importlib import import_module
+
+import pytest
+
+# Expose the unittest-driven decorators
+from .ipunittest import ipdoctest, ipdocstring
+
+def skipif(skip_condition, msg=None):
+    """Make function raise SkipTest exception if skip_condition is true
+
+    Parameters
+    ----------
+
+    skip_condition : bool or callable
+      Flag to determine whether to skip test. If the condition is a
+      callable, it is used at runtime to dynamically make the decision. This
+      is useful for tests that may require costly imports, to delay the cost
+      until the test suite is actually executed.
+    msg : string
+      Message to give on raising a SkipTest exception.
+
+    Returns
+    -------
+    decorator : function
+      Decorator, which, when applied to a function, causes SkipTest
+      to be raised when the skip_condition was True, and the function
+      to be called normally otherwise.
+    """
+    if msg is None:
+        msg = "Test skipped due to test condition."
+
+    assert isinstance(skip_condition, bool)
+    return pytest.mark.skipif(skip_condition, reason=msg)
+
+
+# A version with the condition set to true, common case just to attach a message
+# to a skip decorator
+def skip(msg=None):
+    """Decorator factory - mark a test function for skipping from test suite.
+
+    Parameters
+    ----------
+      msg : string
+        Optional message to be added.
+
+    Returns
+    -------
+       decorator : function
+         Decorator, which, when applied to a function, causes SkipTest
+         to be raised, with the optional message added.
+    """
+    if msg and not isinstance(msg, str):
+        raise ValueError(
+            "invalid object passed to `@skip` decorator, did you "
+            "meant `@skip()` with brackets ?"
+        )
+    return skipif(True, msg)
+
+
+def onlyif(condition, msg):
+    """The reverse from skipif, see skipif for details."""
+
+    return skipif(not condition, msg)
+
+
+# -----------------------------------------------------------------------------
+# Utility functions for decorators
+def module_not_available(module):
+    """Can module be imported?  Returns true if module does NOT import.
+
+    This is used to make a decorator to skip tests that require module to be
+    available, but delay the 'import numpy' to test execution time.
+    """
+    try:
+        mod = import_module(module)
+        mod_not_avail = False
+    except ImportError:
+        mod_not_avail = True
+
+    return mod_not_avail
+
+
+# -----------------------------------------------------------------------------
+# Decorators for public use
+
+# Decorators to skip certain tests on specific platforms.
+skip_win32 = skipif(sys.platform == "win32", "This test does not run under Windows")
+
+
+# Decorators to skip tests if not on specific platforms.
+skip_if_not_win32 = skipif(sys.platform != "win32", "This test only runs under Windows")
+skip_if_not_osx = skipif(
+    not sys.platform.startswith("darwin"), "This test only runs under macOS"
+)
+
+_x11_skip_cond = (
+    sys.platform not in ("darwin", "win32") and os.environ.get("DISPLAY", "") == ""
+)
+_x11_skip_msg = "Skipped under *nix when X11/XOrg not available"
+
+skip_if_no_x11 = skipif(_x11_skip_cond, _x11_skip_msg)
+
+# Other skip decorators
+
+# generic skip without module
+skip_without = lambda mod: skipif(
+    module_not_available(mod), "This test requires %s" % mod
+)
+
+skipif_not_numpy = skip_without("numpy")
+
+skipif_not_matplotlib = skip_without("matplotlib")
+
+# A null 'decorator', useful to make more readable code that needs to pick
+# between different decorators based on OS or other conditions
+null_deco = lambda f: f
+
+# Some tests only run where we can use unicode paths. Note that we can't just
+# check os.path.supports_unicode_filenames, which is always False on Linux.
+try:
+    f = tempfile.NamedTemporaryFile(prefix="tmp€")
+except UnicodeEncodeError:
+    unicode_paths = False
+# TODO: should this be finnally ?
+else:
+    unicode_paths = True
+    f.close()
+
+onlyif_unicode_paths = onlyif(
+    unicode_paths,
+    ("This test is only applicable where we can use unicode in filenames."),
+)
+
+
+def onlyif_cmds_exist(*commands):
+    """
+    Decorator to skip test when at least one of `commands` is not found.
+    """
+    for cmd in commands:
+        reason = f"This test runs only if command '{cmd}' is installed"
+        if not shutil.which(cmd):
+            return pytest.mark.skip(reason=reason)
+    return null_deco

lib/python3.12/site-packages/IPython/testing/globalipapp.py

@@ -0,0 +1,114 @@
+"""Global IPython app to support test running.
+
+We must start our own ipython object and heavily muck with it so that all the
+modifications IPython makes to system behavior don't send the doctest machinery
+into a fit.  This code should be considered a gross hack, but it gets the job
+done.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import builtins as builtin_mod
+import sys
+import types
+
+from pathlib import Path
+
+from . import tools
+
+from IPython.core import page
+from IPython.utils import io
+from IPython.terminal.interactiveshell import TerminalInteractiveShell
+
+
+def get_ipython():
+    # This will get replaced by the real thing once we start IPython below
+    return start_ipython()
+
+
+# A couple of methods to override those in the running IPython to interact
+# better with doctest (doctest captures on raw stdout, so we need to direct
+# various types of output there otherwise it will miss them).
+
+def xsys(self, cmd):
+    """Replace the default system call with a capturing one for doctest.
+    """
+    # We use getoutput, but we need to strip it because pexpect captures
+    # the trailing newline differently from commands.getoutput
+    print(self.getoutput(cmd, split=False, depth=1).rstrip(), end='', file=sys.stdout)
+    sys.stdout.flush()
+
+
+def _showtraceback(self, etype, evalue, stb):
+    """Print the traceback purely on stdout for doctest to capture it.
+    """
+    print(self.InteractiveTB.stb2text(stb), file=sys.stdout)
+
+
+def start_ipython():
+    """Start a global IPython shell, which we need for IPython-specific syntax.
+    """
+    global get_ipython
+
+    # This function should only ever run once!
+    if hasattr(start_ipython, 'already_called'):
+        return
+    start_ipython.already_called = True
+
+    # Store certain global objects that IPython modifies
+    _displayhook = sys.displayhook
+    _excepthook = sys.excepthook
+    _main = sys.modules.get('__main__')
+
+    # Create custom argv and namespaces for our IPython to be test-friendly
+    config = tools.default_config()
+    config.TerminalInteractiveShell.simple_prompt = True
+
+    # Create and initialize our test-friendly IPython instance.
+    shell = TerminalInteractiveShell.instance(config=config,
+                                              )
+
+    # A few more tweaks needed for playing nicely with doctests...
+
+    # remove history file
+    shell.tempfiles.append(Path(config.HistoryManager.hist_file))
+
+    # These traps are normally only active for interactive use, set them
+    # permanently since we'll be mocking interactive sessions.
+    shell.builtin_trap.activate()
+
+    # Modify the IPython system call with one that uses getoutput, so that we
+    # can capture subcommands and print them to Python's stdout, otherwise the
+    # doctest machinery would miss them.
+    shell.system = types.MethodType(xsys, shell)
+
+    shell._showtraceback = types.MethodType(_showtraceback, shell)
+
+    # IPython is ready, now clean up some global state...
+
+    # Deactivate the various python system hooks added by ipython for
+    # interactive convenience so we don't confuse the doctest system
+    sys.modules['__main__'] = _main
+    sys.displayhook = _displayhook
+    sys.excepthook = _excepthook
+
+    # So that ipython magics and aliases can be doctested (they work by making
+    # a call into a global _ip object).  Also make the top-level get_ipython
+    # now return this without recursively calling here again.
+    _ip = shell
+    get_ipython = _ip.get_ipython
+    builtin_mod._ip = _ip
+    builtin_mod.ip = _ip
+    builtin_mod.get_ipython = get_ipython
+
+    # Override paging, so we don't require user interaction during the tests.
+    def nopage(strng, start=0, screen_lines=0, pager_cmd=None):
+        if isinstance(strng, dict):
+           strng = strng.get('text/plain', '')
+        print(strng)
+    
+    page.orig_page = page.pager_page
+    page.pager_page = nopage
+
+    return _ip

lib/python3.12/site-packages/IPython/testing/ipunittest.py

@@ -0,0 +1,187 @@
+"""Experimental code for cleaner support of IPython syntax with unittest.
+
+In IPython up until 0.10, we've used very hacked up nose machinery for running
+tests with IPython special syntax, and this has proved to be extremely slow.
+This module provides decorators to try a different approach, stemming from a
+conversation Brian and I (FP) had about this problem Sept/09.
+
+The goal is to be able to easily write simple functions that can be seen by
+unittest as tests, and ultimately for these to support doctests with full
+IPython syntax.  Nose already offers this based on naming conventions and our
+hackish plugins, but we are seeking to move away from nose dependencies if
+possible.
+
+This module follows a different approach, based on decorators.
+
+- A decorator called @ipdoctest can mark any function as having a docstring
+  that should be viewed as a doctest, but after syntax conversion.
+
+Authors
+-------
+
+- Fernando Perez <Fernando.Perez@berkeley.edu>
+"""
+
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2009-2011  The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib
+import re
+import sys
+import unittest
+import builtins
+from doctest import DocTestFinder, DocTestRunner, TestResults
+from IPython.terminal.interactiveshell import InteractiveShell
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+def count_failures(runner):
+    """Count number of failures in a doctest runner.
+
+    Code modeled after the summarize() method in doctest.
+    """
+    if sys.version_info < (3, 13):
+        return [TestResults(f, t) for f, t in runner._name2ft.values() if f > 0]
+    else:
+        return [
+            TestResults(failure, try_)
+            for failure, try_, skip in runner._stats.values()
+            if failure > 0
+        ]
+
+
+class IPython2PythonConverter:
+    """Convert IPython 'syntax' to valid Python.
+
+    Eventually this code may grow to be the full IPython syntax conversion
+    implementation, but for now it only does prompt conversion."""
+    
+    def __init__(self):
+        self.rps1 = re.compile(r'In\ \[\d+\]: ')
+        self.rps2 = re.compile(r'\ \ \ \.\.\.+: ')
+        self.rout = re.compile(r'Out\[\d+\]: \s*?\n?')
+        self.pyps1 = '>>> '
+        self.pyps2 = '... '
+        self.rpyps1 = re.compile (r'(\s*%s)(.*)$' % self.pyps1)
+        self.rpyps2 = re.compile (r'(\s*%s)(.*)$' % self.pyps2)
+
+    def __call__(self, ds):
+        """Convert IPython prompts to python ones in a string."""
+        from . import globalipapp
+
+        pyps1 = '>>> '
+        pyps2 = '... '
+        pyout = ''
+
+        dnew = ds
+        dnew = self.rps1.sub(pyps1, dnew)
+        dnew = self.rps2.sub(pyps2, dnew)
+        dnew = self.rout.sub(pyout, dnew)
+        ip = InteractiveShell.instance()
+
+        # Convert input IPython source into valid Python.
+        out = []
+        newline = out.append
+        for line in dnew.splitlines():
+
+            mps1 = self.rpyps1.match(line)
+            if mps1 is not None:
+                prompt, text = mps1.groups()
+                newline(prompt+ip.prefilter(text, False))
+                continue
+
+            mps2 = self.rpyps2.match(line)
+            if mps2 is not None:
+                prompt, text = mps2.groups()
+                newline(prompt+ip.prefilter(text, True))
+                continue
+            
+            newline(line)
+        newline('')  # ensure a closing newline, needed by doctest
+        # print("PYSRC:", '\n'.join(out))  # dbg
+        return '\n'.join(out)
+
+    #return dnew
+
+
+class Doc2UnitTester:
+    """Class whose instances act as a decorator for docstring testing.
+
+    In practice we're only likely to need one instance ever, made below (though
+    no attempt is made at turning it into a singleton, there is no need for
+    that).
+    """
+    def __init__(self, verbose=False):
+        """New decorator.
+
+        Parameters
+        ----------
+
+        verbose : boolean, optional (False)
+          Passed to the doctest finder and runner to control verbosity.
+        """
+        self.verbose = verbose
+        # We can reuse the same finder for all instances
+        self.finder = DocTestFinder(verbose=verbose, recurse=False)
+
+    def __call__(self, func):
+        """Use as a decorator: doctest a function's docstring as a unittest.
+        
+        This version runs normal doctests, but the idea is to make it later run
+        ipython syntax instead."""
+
+        # Capture the enclosing instance with a different name, so the new
+        # class below can see it without confusion regarding its own 'self'
+        # that will point to the test instance at runtime
+        d2u = self
+
+        # Rewrite the function's docstring to have python syntax
+        if func.__doc__ is not None:
+            func.__doc__ = ip2py(func.__doc__)
+
+        # Now, create a tester object that is a real unittest instance, so
+        # normal unittest machinery (or Nose, or Trial) can find it.
+        class Tester(unittest.TestCase):
+            def test(self):
+                # Make a new runner per function to be tested
+                runner = DocTestRunner(verbose=d2u.verbose)
+                for the_test in d2u.finder.find(func, func.__name__):
+                    runner.run(the_test)
+                failed = count_failures(runner)
+                if failed:
+                    # Since we only looked at a single function's docstring,
+                    # failed should contain at most one item.  More than that
+                    # is a case we can't handle and should error out on
+                    if len(failed) > 1:
+                        err = "Invalid number of test results: %s" % failed
+                        raise ValueError(err)
+                    # Report a normal failure.
+                    self.fail('failed doctests: %s' % str(failed[0]))
+                    
+        # Rename it so test reports have the original signature.
+        Tester.__name__ = func.__name__
+        return Tester
+
+
+def ipdocstring(func):
+    """Change the function docstring via ip2py.
+    """
+    if func.__doc__ is not None:
+        func.__doc__ = ip2py(func.__doc__)
+    return func
+
+        
+# Make an instance of the classes for public use
+ipdoctest = Doc2UnitTester()
+ip2py = IPython2PythonConverter()

lib/python3.12/site-packages/IPython/testing/plugin/dtexample.py

@@ -0,0 +1,167 @@
+"""Simple example using doctests.
+
+This file just contains doctests both using plain python and IPython prompts.
+All tests should be loaded by nose.
+"""
+
+import os
+
+
+def pyfunc():
+    """Some pure python tests...
+
+    >>> pyfunc()
+    'pyfunc'
+
+    >>> import os
+
+    >>> 2+3
+    5
+
+    >>> for i in range(3):
+    ...     print(i, end=' ')
+    ...     print(i+1, end=' ')
+    ...
+    0 1 1 2 2 3 
+    """
+    return 'pyfunc'
+
+def ipfunc():
+    """Some ipython tests...
+
+    In [1]: import os
+
+    In [3]: 2+3
+    Out[3]: 5
+
+    In [26]: for i in range(3):
+       ....:     print(i, end=' ')
+       ....:     print(i+1, end=' ')
+       ....:
+    0 1 1 2 2 3
+
+
+    It's OK to use '_' for the last result, but do NOT try to use IPython's
+    numbered history of _NN outputs, since those won't exist under the
+    doctest environment:
+
+    In [7]: 'hi'
+    Out[7]: 'hi'
+
+    In [8]: print(repr(_))
+    'hi'
+
+    In [7]: 3+4
+    Out[7]: 7
+
+    In [8]: _+3
+    Out[8]: 10
+
+    In [9]: ipfunc()
+    Out[9]: 'ipfunc'
+    """
+    return "ipfunc"
+
+
+def ipos():
+    """Examples that access the operating system work:
+
+    In [1]: !echo hello
+    hello
+
+    In [2]: !echo hello > /tmp/foo_iptest
+
+    In [3]: !cat /tmp/foo_iptest
+    hello
+
+    In [4]: rm -f /tmp/foo_iptest
+    """
+    pass
+
+
+ipos.__skip_doctest__ = os.name == "nt"
+
+
+def ranfunc():
+    """A function with some random output.
+
+       Normal examples are verified as usual:
+       >>> 1+3
+       4
+
+       But if you put '# random' in the output, it is ignored:
+       >>> 1+3
+       junk goes here...  # random
+
+       >>> 1+2
+       again,  anything goes #random
+       if multiline, the random mark is only needed once.
+
+       >>> 1+2
+       You can also put the random marker at the end:
+       # random
+
+       >>> 1+2
+       # random
+       .. or at the beginning.
+
+       More correct input is properly verified:
+       >>> ranfunc()
+       'ranfunc'
+    """
+    return 'ranfunc'
+
+
+def random_all():
+    """A function where we ignore the output of ALL examples.
+
+    Examples:
+
+      # all-random
+
+      This mark tells the testing machinery that all subsequent examples should
+      be treated as random (ignoring their output).  They are still executed,
+      so if a they raise an error, it will be detected as such, but their
+      output is completely ignored.
+
+      >>> 1+3
+      junk goes here...
+
+      >>> 1+3
+      klasdfj;
+
+      >>> 1+2
+      again,  anything goes
+      blah...
+    """
+    pass
+
+def iprand():
+    """Some ipython tests with random output.
+
+    In [7]: 3+4
+    Out[7]: 7
+
+    In [8]: print('hello')
+    world  # random
+
+    In [9]: iprand()
+    Out[9]: 'iprand'
+    """
+    return 'iprand'
+
+def iprand_all():
+    """Some ipython tests with fully random output.
+
+    # all-random
+    
+    In [7]: 1
+    Out[7]: 99
+
+    In [8]: print('hello')
+    world
+
+    In [9]: iprand_all()
+    Out[9]: 'junk'
+    """
+    return 'iprand_all'

lib/python3.12/site-packages/IPython/testing/plugin/ipdoctest.py

@@ -0,0 +1,299 @@
+"""Nose Plugin that supports IPython doctests.
+
+Limitations:
+
+- When generating examples for use as doctests, make sure that you have
+  pretty-printing OFF.  This can be done either by setting the
+  ``PlainTextFormatter.pprint`` option in your configuration file to  False, or
+  by interactively disabling it with  %Pprint.  This is required so that IPython
+  output matches that of normal Python, which is used by doctest for internal
+  execution.
+
+- Do not rely on specific prompt numbers for results (such as using
+  '_34==True', for example).  For IPython tests run via an external process the
+  prompt numbers may be different, and IPython tests run as normal python code
+  won't even have these special _NN variables set at all.
+"""
+
+#-----------------------------------------------------------------------------
+# Module imports
+
+# From the standard library
+import doctest
+import logging
+import re
+
+from testpath import modified_env
+
+#-----------------------------------------------------------------------------
+# Module globals and other constants
+#-----------------------------------------------------------------------------
+
+log = logging.getLogger(__name__)
+
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+
+class DocTestFinder(doctest.DocTestFinder):
+    def _get_test(self, obj, name, module, globs, source_lines):
+        test = super()._get_test(obj, name, module, globs, source_lines)
+
+        if bool(getattr(obj, "__skip_doctest__", False)) and test is not None:
+            for example in test.examples:
+                example.options[doctest.SKIP] = True
+
+        return test
+
+
+class IPDoctestOutputChecker(doctest.OutputChecker):
+    """Second-chance checker with support for random tests.
+
+    If the default comparison doesn't pass, this checker looks in the expected
+    output string for flags that tell us to ignore the output.
+    """
+
+    random_re = re.compile(r'#\s*random\s+')
+
+    def check_output(self, want, got, optionflags):
+        """Check output, accepting special markers embedded in the output.
+
+        If the output didn't pass the default validation but the special string
+        '#random' is included, we accept it."""
+
+        # Let the original tester verify first, in case people have valid tests
+        # that happen to have a comment saying '#random' embedded in.
+        ret = doctest.OutputChecker.check_output(self, want, got,
+                                                 optionflags)
+        if not ret and self.random_re.search(want):
+            # print('RANDOM OK:',want, file=sys.stderr)  # dbg
+            return True
+
+        return ret
+
+
+# A simple subclassing of the original with a different class name, so we can
+# distinguish and treat differently IPython examples from pure python ones.
+class IPExample(doctest.Example): pass
+
+
+class IPDocTestParser(doctest.DocTestParser):
+    """
+    A class used to parse strings containing doctest examples.
+
+    Note: This is a version modified to properly recognize IPython input and
+    convert any IPython examples into valid Python ones.
+    """
+    # This regular expression is used to find doctest examples in a
+    # string.  It defines three groups: `source` is the source code
+    # (including leading indentation and prompts); `indent` is the
+    # indentation of the first (PS1) line of the source code; and
+    # `want` is the expected output (including leading indentation).
+
+    # Classic Python prompts or default IPython ones
+    _PS1_PY = r'>>>'
+    _PS2_PY = r'\.\.\.'
+
+    _PS1_IP = r'In\ \[\d+\]:'
+    _PS2_IP = r'\ \ \ \.\.\.+:'
+
+    _RE_TPL = r'''
+        # Source consists of a PS1 line followed by zero or more PS2 lines.
+        (?P<source>
+            (?:^(?P<indent> [ ]*) (?P<ps1> %s) .*)    # PS1 line
+            (?:\n           [ ]*  (?P<ps2> %s) .*)*)  # PS2 lines
+        \n? # a newline
+        # Want consists of any non-blank lines that do not start with PS1.
+        (?P<want> (?:(?![ ]*$)    # Not a blank line
+                     (?![ ]*%s)   # Not a line starting with PS1
+                     (?![ ]*%s)   # Not a line starting with PS2
+                     .*$\n?       # But any other line
+                  )*)
+                  '''
+
+    _EXAMPLE_RE_PY = re.compile( _RE_TPL % (_PS1_PY,_PS2_PY,_PS1_PY,_PS2_PY),
+                                 re.MULTILINE | re.VERBOSE)
+
+    _EXAMPLE_RE_IP = re.compile( _RE_TPL % (_PS1_IP,_PS2_IP,_PS1_IP,_PS2_IP),
+                                 re.MULTILINE | re.VERBOSE)
+
+    # Mark a test as being fully random.  In this case, we simply append the
+    # random marker ('#random') to each individual example's output.  This way
+    # we don't need to modify any other code.
+    _RANDOM_TEST = re.compile(r'#\s*all-random\s+')
+
+    def ip2py(self,source):
+        """Convert input IPython source into valid Python."""
+        block = _ip.input_transformer_manager.transform_cell(source)
+        if len(block.splitlines()) == 1:
+            return _ip.prefilter(block)
+        else:
+            return block
+
+    def parse(self, string, name='<string>'):
+        """
+        Divide the given string into examples and intervening text,
+        and return them as a list of alternating Examples and strings.
+        Line numbers for the Examples are 0-based.  The optional
+        argument `name` is a name identifying this string, and is only
+        used for error messages.
+        """
+
+        # print('Parse string:\n',string)  # dbg
+
+        string = string.expandtabs()
+        # If all lines begin with the same indentation, then strip it.
+        min_indent = self._min_indent(string)
+        if min_indent > 0:
+            string = '\n'.join([l[min_indent:] for l in string.split('\n')])
+
+        output = []
+        charno, lineno = 0, 0
+
+        # We make 'all random' tests by adding the '# random' mark to every
+        # block of output in the test.
+        if self._RANDOM_TEST.search(string):
+            random_marker = '\n# random'
+        else:
+            random_marker = ''
+
+        # Whether to convert the input from ipython to python syntax
+        ip2py = False
+        # Find all doctest examples in the string.  First, try them as Python
+        # examples, then as IPython ones
+        terms = list(self._EXAMPLE_RE_PY.finditer(string))
+        if terms:
+            # Normal Python example
+            Example = doctest.Example
+        else:
+            # It's an ipython example.
+            terms = list(self._EXAMPLE_RE_IP.finditer(string))
+            Example = IPExample
+            ip2py = True
+
+        for m in terms:
+            # Add the pre-example text to `output`.
+            output.append(string[charno:m.start()])
+            # Update lineno (lines before this example)
+            lineno += string.count('\n', charno, m.start())
+            # Extract info from the regexp match.
+            (source, options, want, exc_msg) = \
+                     self._parse_example(m, name, lineno,ip2py)
+
+            # Append the random-output marker (it defaults to empty in most
+            # cases, it's only non-empty for 'all-random' tests):
+            want += random_marker
+
+            # Create an Example, and add it to the list.
+            if not self._IS_BLANK_OR_COMMENT(source):
+                output.append(Example(source, want, exc_msg,
+                                      lineno=lineno,
+                                      indent=min_indent+len(m.group('indent')),
+                                      options=options))
+            # Update lineno (lines inside this example)
+            lineno += string.count('\n', m.start(), m.end())
+            # Update charno.
+            charno = m.end()
+        # Add any remaining post-example text to `output`.
+        output.append(string[charno:])
+        return output
+
+    def _parse_example(self, m, name, lineno,ip2py=False):
+        """
+        Given a regular expression match from `_EXAMPLE_RE` (`m`),
+        return a pair `(source, want)`, where `source` is the matched
+        example's source code (with prompts and indentation stripped);
+        and `want` is the example's expected output (with indentation
+        stripped).
+
+        `name` is the string's name, and `lineno` is the line number
+        where the example starts; both are used for error messages.
+
+        Optional:
+        `ip2py`: if true, filter the input via IPython to convert the syntax
+        into valid python.
+        """
+
+        # Get the example's indentation level.
+        indent = len(m.group('indent'))
+
+        # Divide source into lines; check that they're properly
+        # indented; and then strip their indentation & prompts.
+        source_lines = m.group('source').split('\n')
+
+        # We're using variable-length input prompts
+        ps1 = m.group('ps1')
+        ps2 = m.group('ps2')
+        ps1_len = len(ps1)
+
+        self._check_prompt_blank(source_lines, indent, name, lineno,ps1_len)
+        if ps2:
+            self._check_prefix(source_lines[1:], ' '*indent + ps2, name, lineno)
+
+        source = '\n'.join([sl[indent+ps1_len+1:] for sl in source_lines])
+
+        if ip2py:
+            # Convert source input from IPython into valid Python syntax
+            source = self.ip2py(source)
+
+        # Divide want into lines; check that it's properly indented; and
+        # then strip the indentation.  Spaces before the last newline should
+        # be preserved, so plain rstrip() isn't good enough.
+        want = m.group('want')
+        want_lines = want.split('\n')
+        if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
+            del want_lines[-1]  # forget final newline & spaces after it
+        self._check_prefix(want_lines, ' '*indent, name,
+                           lineno + len(source_lines))
+
+        # Remove ipython output prompt that might be present in the first line
+        want_lines[0] = re.sub(r'Out\[\d+\]: \s*?\n?','',want_lines[0])
+
+        want = '\n'.join([wl[indent:] for wl in want_lines])
+
+        # If `want` contains a traceback message, then extract it.
+        m = self._EXCEPTION_RE.match(want)
+        if m:
+            exc_msg = m.group('msg')
+        else:
+            exc_msg = None
+
+        # Extract options from the source.
+        options = self._find_options(source, name, lineno)
+
+        return source, options, want, exc_msg
+
+    def _check_prompt_blank(self, lines, indent, name, lineno, ps1_len):
+        """
+        Given the lines of a source string (including prompts and
+        leading indentation), check to make sure that every prompt is
+        followed by a space character.  If any line is not followed by
+        a space character, then raise ValueError.
+
+        Note: IPython-modified version which takes the input prompt length as a
+        parameter, so that prompts of variable length can be dealt with.
+        """
+        space_idx = indent+ps1_len
+        min_len = space_idx+1
+        for i, line in enumerate(lines):
+            if len(line) >=  min_len and line[space_idx] != ' ':
+                raise ValueError('line %r of the docstring for %s '
+                                 'lacks blank after %s: %r' %
+                                 (lineno+i+1, name,
+                                  line[indent:space_idx], line))
+
+
+SKIP = doctest.register_optionflag('SKIP')
+
+
+class IPDocTestRunner(doctest.DocTestRunner):
+    """Test runner that synchronizes the IPython namespace with test globals.
+    """
+
+    def run(self, test, compileflags=None, out=None, clear_globs=True):
+        # Override terminal size to standardise traceback format
+        with modified_env({'COLUMNS': '80', 'LINES': '24'}):
+            return super(IPDocTestRunner,self).run(test,
+                                                   compileflags,out,clear_globs)

lib/python3.12/site-packages/IPython/testing/plugin/pytest_ipdoctest.py

@@ -0,0 +1,877 @@
+# Based on Pytest doctest.py
+# Original license:
+# The MIT License (MIT)
+#
+# Copyright (c) 2004-2021 Holger Krekel and others
+"""Discover and run ipdoctests in modules and test files."""
+
+import bdb
+import builtins
+import inspect
+import os
+import platform
+import sys
+import traceback
+import types
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
+from re import Pattern
+from collections.abc import Callable, Generator, Iterable, Sequence
+
+import pytest
+from _pytest import outcomes
+from _pytest._code.code import ExceptionInfo, ReprFileLocation, TerminalRepr
+from _pytest._io import TerminalWriter
+from _pytest.compat import safe_getattr
+from _pytest.config import Config
+from _pytest.config.argparsing import Parser
+
+try:
+    from _pytest.fixtures import TopRequest as FixtureRequest
+except ImportError:
+    from _pytest.fixtures import FixtureRequest
+from _pytest.nodes import Collector
+from _pytest.outcomes import OutcomeException
+from _pytest.pathlib import fnmatch_ex, import_path
+from _pytest.python_api import approx
+from _pytest.warning_types import PytestWarning
+
+if TYPE_CHECKING:
+    import doctest
+
+    from .ipdoctest import IPDoctestOutputChecker
+
+DOCTEST_REPORT_CHOICE_NONE = "none"
+DOCTEST_REPORT_CHOICE_CDIFF = "cdiff"
+DOCTEST_REPORT_CHOICE_NDIFF = "ndiff"
+DOCTEST_REPORT_CHOICE_UDIFF = "udiff"
+DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE = "only_first_failure"
+
+DOCTEST_REPORT_CHOICES = (
+    DOCTEST_REPORT_CHOICE_NONE,
+    DOCTEST_REPORT_CHOICE_CDIFF,
+    DOCTEST_REPORT_CHOICE_NDIFF,
+    DOCTEST_REPORT_CHOICE_UDIFF,
+    DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE,
+)
+
+# Lazy definition of runner class
+RUNNER_CLASS = None
+# Lazy definition of output checker class
+CHECKER_CLASS: Optional[Type["IPDoctestOutputChecker"]] = None
+
+pytest_version = tuple([int(part) for part in pytest.__version__.split(".")])
+
+
+def pytest_addoption(parser: Parser) -> None:
+    parser.addini(
+        "ipdoctest_optionflags",
+        "option flags for ipdoctests",
+        type="args",
+        default=["ELLIPSIS"],
+    )
+    parser.addini(
+        "ipdoctest_encoding", "encoding used for ipdoctest files", default="utf-8"
+    )
+    group = parser.getgroup("collect")
+    group.addoption(
+        "--ipdoctest-modules",
+        action="store_true",
+        default=False,
+        help="run ipdoctests in all .py modules",
+        dest="ipdoctestmodules",
+    )
+    group.addoption(
+        "--ipdoctest-report",
+        type=str.lower,
+        default="udiff",
+        help="choose another output format for diffs on ipdoctest failure",
+        choices=DOCTEST_REPORT_CHOICES,
+        dest="ipdoctestreport",
+    )
+    group.addoption(
+        "--ipdoctest-glob",
+        action="append",
+        default=[],
+        metavar="pat",
+        help="ipdoctests file matching pattern, default: test*.txt",
+        dest="ipdoctestglob",
+    )
+    group.addoption(
+        "--ipdoctest-ignore-import-errors",
+        action="store_true",
+        default=False,
+        help="ignore ipdoctest ImportErrors",
+        dest="ipdoctest_ignore_import_errors",
+    )
+    group.addoption(
+        "--ipdoctest-continue-on-failure",
+        action="store_true",
+        default=False,
+        help="for a given ipdoctest, continue to run after the first failure",
+        dest="ipdoctest_continue_on_failure",
+    )
+
+
+def pytest_unconfigure() -> None:
+    global RUNNER_CLASS
+
+    RUNNER_CLASS = None
+
+
+def pytest_collect_file(
+    file_path: Path,
+    parent: Collector,
+) -> Optional[Union["IPDoctestModule", "IPDoctestTextfile"]]:
+    config = parent.config
+    if file_path.suffix == ".py":
+        if config.option.ipdoctestmodules and not any(
+            (_is_setup_py(file_path), _is_main_py(file_path))
+        ):
+            mod: IPDoctestModule = IPDoctestModule.from_parent(parent, path=file_path)
+            return mod
+    elif _is_ipdoctest(config, file_path, parent):
+        txt: IPDoctestTextfile = IPDoctestTextfile.from_parent(parent, path=file_path)
+        return txt
+    return None
+
+
+if pytest_version[0] < 7:
+    _collect_file = pytest_collect_file
+
+    def pytest_collect_file(
+        path,
+        parent: Collector,
+    ) -> Optional[Union["IPDoctestModule", "IPDoctestTextfile"]]:
+        return _collect_file(Path(path), parent)
+
+    _import_path = import_path
+
+    def import_path(path, root):
+        import py.path
+
+        return _import_path(py.path.local(path))
+
+
+def _is_setup_py(path: Path) -> bool:
+    if path.name != "setup.py":
+        return False
+    contents = path.read_bytes()
+    return b"setuptools" in contents or b"distutils" in contents
+
+
+def _is_ipdoctest(config: Config, path: Path, parent: Collector) -> bool:
+    if path.suffix in (".txt", ".rst") and parent.session.isinitpath(path):
+        return True
+    globs = config.getoption("ipdoctestglob") or ["test*.txt"]
+    return any(fnmatch_ex(glob, path) for glob in globs)
+
+
+def _is_main_py(path: Path) -> bool:
+    return path.name == "__main__.py"
+
+
+class ReprFailDoctest(TerminalRepr):
+    def __init__(
+        self, reprlocation_lines: Sequence[Tuple[ReprFileLocation, Sequence[str]]]
+    ) -> None:
+        self.reprlocation_lines = reprlocation_lines
+
+    def toterminal(self, tw: TerminalWriter) -> None:
+        for reprlocation, lines in self.reprlocation_lines:
+            for line in lines:
+                tw.line(line)
+            reprlocation.toterminal(tw)
+
+
+class MultipleDoctestFailures(Exception):
+    def __init__(self, failures: Sequence["doctest.DocTestFailure"]) -> None:
+        super().__init__()
+        self.failures = failures
+
+
+def _init_runner_class() -> Type["IPDocTestRunner"]:
+    import doctest
+    from .ipdoctest import IPDocTestRunner
+
+    class PytestDoctestRunner(IPDocTestRunner):
+        """Runner to collect failures.
+
+        Note that the out variable in this case is a list instead of a
+        stdout-like object.
+        """
+
+        def __init__(
+            self,
+            checker: Optional["IPDoctestOutputChecker"] = None,
+            verbose: Optional[bool] = None,
+            optionflags: int = 0,
+            continue_on_failure: bool = True,
+        ) -> None:
+            super().__init__(checker=checker, verbose=verbose, optionflags=optionflags)
+            self.continue_on_failure = continue_on_failure
+
+        def report_failure(
+            self,
+            out,
+            test: "doctest.DocTest",
+            example: "doctest.Example",
+            got: str,
+        ) -> None:
+            failure = doctest.DocTestFailure(test, example, got)
+            if self.continue_on_failure:
+                out.append(failure)
+            else:
+                raise failure
+
+        def report_unexpected_exception(
+            self,
+            out,
+            test: "doctest.DocTest",
+            example: "doctest.Example",
+            exc_info: Tuple[Type[BaseException], BaseException, types.TracebackType],
+        ) -> None:
+            if isinstance(exc_info[1], OutcomeException):
+                raise exc_info[1]
+            if isinstance(exc_info[1], bdb.BdbQuit):
+                outcomes.exit("Quitting debugger")
+            failure = doctest.UnexpectedException(test, example, exc_info)
+            if self.continue_on_failure:
+                out.append(failure)
+            else:
+                raise failure
+
+    return PytestDoctestRunner
+
+
+def _get_runner(
+    checker: Optional["IPDoctestOutputChecker"] = None,
+    verbose: Optional[bool] = None,
+    optionflags: int = 0,
+    continue_on_failure: bool = True,
+) -> "IPDocTestRunner":
+    # We need this in order to do a lazy import on doctest
+    global RUNNER_CLASS
+    if RUNNER_CLASS is None:
+        RUNNER_CLASS = _init_runner_class()
+    # Type ignored because the continue_on_failure argument is only defined on
+    # PytestDoctestRunner, which is lazily defined so can't be used as a type.
+    return RUNNER_CLASS(  # type: ignore
+        checker=checker,
+        verbose=verbose,
+        optionflags=optionflags,
+        continue_on_failure=continue_on_failure,
+    )
+
+
+class IPDoctestItem(pytest.Item):
+    _user_ns_orig: Dict[str, Any]
+
+    def __init__(
+        self,
+        name: str,
+        parent: "Union[IPDoctestTextfile, IPDoctestModule]",
+        runner: Optional["IPDocTestRunner"] = None,
+        dtest: Optional["doctest.DocTest"] = None,
+    ) -> None:
+        super().__init__(name, parent)
+        self.runner = runner
+        self.dtest = dtest
+        self.obj = None
+        self.fixture_request: Optional[FixtureRequest] = None
+        self._user_ns_orig = {}
+
+    @classmethod
+    def from_parent(  # type: ignore
+        cls,
+        parent: "Union[IPDoctestTextfile, IPDoctestModule]",
+        *,
+        name: str,
+        runner: "IPDocTestRunner",
+        dtest: "doctest.DocTest",
+    ):
+        # incompatible signature due to imposed limits on subclass
+        """The public named constructor."""
+        return super().from_parent(name=name, parent=parent, runner=runner, dtest=dtest)
+
+    def setup(self) -> None:
+        if self.dtest is not None:
+            self.fixture_request = _setup_fixtures(self)
+            globs = dict(getfixture=self.fixture_request.getfixturevalue)
+            for name, value in self.fixture_request.getfixturevalue(
+                "ipdoctest_namespace"
+            ).items():
+                globs[name] = value
+            self.dtest.globs.update(globs)
+
+            from .ipdoctest import IPExample
+
+            if isinstance(self.dtest.examples[0], IPExample):
+                # for IPython examples *only*, we swap the globals with the ipython
+                # namespace, after updating it with the globals (which doctest
+                # fills with the necessary info from the module being tested).
+                self._user_ns_orig = {}
+                self._user_ns_orig.update(_ip.user_ns)
+                _ip.user_ns.update(self.dtest.globs)
+                # We must remove the _ key in the namespace, so that Python's
+                # doctest code sets it naturally
+                _ip.user_ns.pop("_", None)
+                _ip.user_ns["__builtins__"] = builtins
+                self.dtest.globs = _ip.user_ns
+
+    def teardown(self) -> None:
+        from .ipdoctest import IPExample
+
+        # Undo the test.globs reassignment we made
+        if isinstance(self.dtest.examples[0], IPExample):
+            self.dtest.globs = {}
+            _ip.user_ns.clear()
+            _ip.user_ns.update(self._user_ns_orig)
+            del self._user_ns_orig
+
+        self.dtest.globs.clear()
+
+    def runtest(self) -> None:
+        assert self.dtest is not None
+        assert self.runner is not None
+        _check_all_skipped(self.dtest)
+        self._disable_output_capturing_for_darwin()
+        failures: List[doctest.DocTestFailure] = []
+
+        # exec(compile(..., "single", ...), ...) puts result in builtins._
+        had_underscore_value = hasattr(builtins, "_")
+        underscore_original_value = getattr(builtins, "_", None)
+
+        # Save our current directory and switch out to the one where the
+        # test was originally created, in case another doctest did a
+        # directory change.  We'll restore this in the finally clause.
+        curdir = os.getcwd()
+        os.chdir(self.fspath.dirname)
+        try:
+            # Type ignored because we change the type of `out` from what
+            # ipdoctest expects.
+            self.runner.run(self.dtest, out=failures, clear_globs=False)  # type: ignore[arg-type]
+        finally:
+            os.chdir(curdir)
+            if had_underscore_value:
+                setattr(builtins, "_", underscore_original_value)
+            elif hasattr(builtins, "_"):
+                delattr(builtins, "_")
+
+        if failures:
+            raise MultipleDoctestFailures(failures)
+
+    def _disable_output_capturing_for_darwin(self) -> None:
+        """Disable output capturing. Otherwise, stdout is lost to ipdoctest (pytest#985)."""
+        if platform.system() != "Darwin":
+            return
+        capman = self.config.pluginmanager.getplugin("capturemanager")
+        if capman:
+            capman.suspend_global_capture(in_=True)
+            out, err = capman.read_global_capture()
+            sys.stdout.write(out)
+            sys.stderr.write(err)
+
+    # TODO: Type ignored -- breaks Liskov Substitution.
+    def repr_failure(  # type: ignore[override]
+        self,
+        excinfo: ExceptionInfo[BaseException],
+    ) -> Union[str, TerminalRepr]:
+        import doctest
+
+        failures: Optional[
+            Sequence[Union[doctest.DocTestFailure, doctest.UnexpectedException]]
+        ] = None
+        if isinstance(
+            excinfo.value, (doctest.DocTestFailure, doctest.UnexpectedException)
+        ):
+            failures = [excinfo.value]
+        elif isinstance(excinfo.value, MultipleDoctestFailures):
+            failures = excinfo.value.failures
+
+        if failures is None:
+            return super().repr_failure(excinfo)
+
+        reprlocation_lines = []
+        for failure in failures:
+            example = failure.example
+            test = failure.test
+            filename = test.filename
+            if test.lineno is None:
+                lineno = None
+            else:
+                lineno = test.lineno + example.lineno + 1
+            message = type(failure).__name__
+            # TODO: ReprFileLocation doesn't expect a None lineno.
+            reprlocation = ReprFileLocation(filename, lineno, message)  # type: ignore[arg-type]
+            checker = _get_checker()
+            report_choice = _get_report_choice(self.config.getoption("ipdoctestreport"))
+            if lineno is not None:
+                assert failure.test.docstring is not None
+                lines = failure.test.docstring.splitlines(False)
+                # add line numbers to the left of the error message
+                assert test.lineno is not None
+                lines = [
+                    "%03d %s" % (i + test.lineno + 1, x) for (i, x) in enumerate(lines)
+                ]
+                # trim docstring error lines to 10
+                lines = lines[max(example.lineno - 9, 0) : example.lineno + 1]
+            else:
+                lines = [
+                    "EXAMPLE LOCATION UNKNOWN, not showing all tests of that example"
+                ]
+                indent = ">>>"
+                for line in example.source.splitlines():
+                    lines.append(f"??? {indent} {line}")
+                    indent = "..."
+            if isinstance(failure, doctest.DocTestFailure):
+                lines += checker.output_difference(
+                    example, failure.got, report_choice
+                ).split("\n")
+            else:
+                inner_excinfo = ExceptionInfo.from_exc_info(failure.exc_info)
+                lines += ["UNEXPECTED EXCEPTION: %s" % repr(inner_excinfo.value)]
+                lines += [
+                    x.strip("\n") for x in traceback.format_exception(*failure.exc_info)
+                ]
+            reprlocation_lines.append((reprlocation, lines))
+        return ReprFailDoctest(reprlocation_lines)
+
+    def reportinfo(self) -> Tuple[Union["os.PathLike[str]", str], Optional[int], str]:
+        assert self.dtest is not None
+        return self.path, self.dtest.lineno, "[ipdoctest] %s" % self.name
+
+    if pytest_version[0] < 7:
+
+        @property
+        def path(self) -> Path:
+            return Path(self.fspath)
+
+
+def _get_flag_lookup() -> Dict[str, int]:
+    import doctest
+
+    return dict(
+        DONT_ACCEPT_TRUE_FOR_1=doctest.DONT_ACCEPT_TRUE_FOR_1,
+        DONT_ACCEPT_BLANKLINE=doctest.DONT_ACCEPT_BLANKLINE,
+        NORMALIZE_WHITESPACE=doctest.NORMALIZE_WHITESPACE,
+        ELLIPSIS=doctest.ELLIPSIS,
+        IGNORE_EXCEPTION_DETAIL=doctest.IGNORE_EXCEPTION_DETAIL,
+        COMPARISON_FLAGS=doctest.COMPARISON_FLAGS,
+        ALLOW_UNICODE=_get_allow_unicode_flag(),
+        ALLOW_BYTES=_get_allow_bytes_flag(),
+        NUMBER=_get_number_flag(),
+    )
+
+
+def get_optionflags(parent):
+    optionflags_str = parent.config.getini("ipdoctest_optionflags")
+    flag_lookup_table = _get_flag_lookup()
+    flag_acc = 0
+    for flag in optionflags_str:
+        flag_acc |= flag_lookup_table[flag]
+    return flag_acc
+
+
+def _get_continue_on_failure(config):
+    continue_on_failure = config.getvalue("ipdoctest_continue_on_failure")
+    if continue_on_failure:
+        # We need to turn off this if we use pdb since we should stop at
+        # the first failure.
+        if config.getvalue("usepdb"):
+            continue_on_failure = False
+    return continue_on_failure
+
+
+class IPDoctestTextfile(pytest.Module):
+    obj = None
+
+    def collect(self) -> Iterable[IPDoctestItem]:
+        import doctest
+        from .ipdoctest import IPDocTestParser
+
+        # Inspired by doctest.testfile; ideally we would use it directly,
+        # but it doesn't support passing a custom checker.
+        encoding = self.config.getini("ipdoctest_encoding")
+        text = self.path.read_text(encoding)
+        filename = str(self.path)
+        name = self.path.name
+        globs = {"__name__": "__main__"}
+
+        optionflags = get_optionflags(self)
+
+        runner = _get_runner(
+            verbose=False,
+            optionflags=optionflags,
+            checker=_get_checker(),
+            continue_on_failure=_get_continue_on_failure(self.config),
+        )
+
+        parser = IPDocTestParser()
+        test = parser.get_doctest(text, globs, name, filename, 0)
+        if test.examples:
+            yield IPDoctestItem.from_parent(
+                self, name=test.name, runner=runner, dtest=test
+            )
+
+    if pytest_version[0] < 7:
+
+        @property
+        def path(self) -> Path:
+            return Path(self.fspath)
+
+        @classmethod
+        def from_parent(
+            cls,
+            parent,
+            *,
+            fspath=None,
+            path: Optional[Path] = None,
+            **kw,
+        ):
+            if path is not None:
+                import py.path
+
+                fspath = py.path.local(path)
+            return super().from_parent(parent=parent, fspath=fspath, **kw)
+
+
+def _check_all_skipped(test: "doctest.DocTest") -> None:
+    """Raise pytest.skip() if all examples in the given DocTest have the SKIP
+    option set."""
+    import doctest
+
+    all_skipped = all(x.options.get(doctest.SKIP, False) for x in test.examples)
+    if all_skipped:
+        pytest.skip("all docstests skipped by +SKIP option")
+
+
+def _is_mocked(obj: object) -> bool:
+    """Return if an object is possibly a mock object by checking the
+    existence of a highly improbable attribute."""
+    return (
+        safe_getattr(obj, "pytest_mock_example_attribute_that_shouldnt_exist", None)
+        is not None
+    )
+
+
+@contextmanager
+def _patch_unwrap_mock_aware() -> Generator[None, None, None]:
+    """Context manager which replaces ``inspect.unwrap`` with a version
+    that's aware of mock objects and doesn't recurse into them."""
+    real_unwrap = inspect.unwrap
+
+    def _mock_aware_unwrap(
+        func: Callable[..., Any], *, stop: Optional[Callable[[Any], Any]] = None
+    ) -> Any:
+        try:
+            if stop is None or stop is _is_mocked:
+                return real_unwrap(func, stop=_is_mocked)
+            _stop = stop
+            return real_unwrap(func, stop=lambda obj: _is_mocked(obj) or _stop(func))
+        except Exception as e:
+            warnings.warn(
+                "Got %r when unwrapping %r.  This is usually caused "
+                "by a violation of Python's object protocol; see e.g. "
+                "https://github.com/pytest-dev/pytest/issues/5080" % (e, func),
+                PytestWarning,
+            )
+            raise
+
+    inspect.unwrap = _mock_aware_unwrap
+    try:
+        yield
+    finally:
+        inspect.unwrap = real_unwrap
+
+
+class IPDoctestModule(pytest.Module):
+    def collect(self) -> Iterable[IPDoctestItem]:
+        import doctest
+        from .ipdoctest import DocTestFinder, IPDocTestParser
+
+        class MockAwareDocTestFinder(DocTestFinder):
+            """A hackish ipdoctest finder that overrides stdlib internals to fix a stdlib bug.
+
+            https://github.com/pytest-dev/pytest/issues/3456
+            https://bugs.python.org/issue25532
+            """
+
+            def _find_lineno(self, obj, source_lines):
+                """Doctest code does not take into account `@property`, this
+                is a hackish way to fix it. https://bugs.python.org/issue17446
+
+                Wrapped Doctests will need to be unwrapped so the correct
+                line number is returned. This will be reported upstream. #8796
+                """
+                if isinstance(obj, property):
+                    obj = getattr(obj, "fget", obj)
+
+                if hasattr(obj, "__wrapped__"):
+                    # Get the main obj in case of it being wrapped
+                    obj = inspect.unwrap(obj)
+
+                # Type ignored because this is a private function.
+                return super()._find_lineno(  # type:ignore[misc]
+                    obj,
+                    source_lines,
+                )
+
+            def _find(
+                self, tests, obj, name, module, source_lines, globs, seen
+            ) -> None:
+                if _is_mocked(obj):
+                    return
+                with _patch_unwrap_mock_aware():
+                    # Type ignored because this is a private function.
+                    super()._find(  # type:ignore[misc]
+                        tests, obj, name, module, source_lines, globs, seen
+                    )
+
+        if self.path.name == "conftest.py":
+            if pytest_version[0] < 7:
+                module = self.config.pluginmanager._importconftest(
+                    self.path,
+                    self.config.getoption("importmode"),
+                )
+            else:
+                kwargs = {"rootpath": self.config.rootpath}
+                if pytest_version >= (8, 1):
+                    kwargs["consider_namespace_packages"] = False
+                module = self.config.pluginmanager._importconftest(
+                    self.path,
+                    self.config.getoption("importmode"),
+                    **kwargs,
+                )
+        else:
+            try:
+                kwargs = {"root": self.config.rootpath}
+                if pytest_version >= (8, 1):
+                    kwargs["consider_namespace_packages"] = False
+                module = import_path(self.path, **kwargs)
+            except ImportError:
+                if self.config.getvalue("ipdoctest_ignore_import_errors"):
+                    pytest.skip("unable to import module %r" % self.path)
+                else:
+                    raise
+        # Uses internal doctest module parsing mechanism.
+        finder = MockAwareDocTestFinder(parser=IPDocTestParser())
+        optionflags = get_optionflags(self)
+        runner = _get_runner(
+            verbose=False,
+            optionflags=optionflags,
+            checker=_get_checker(),
+            continue_on_failure=_get_continue_on_failure(self.config),
+        )
+
+        for test in finder.find(module, module.__name__):
+            if test.examples:  # skip empty ipdoctests
+                yield IPDoctestItem.from_parent(
+                    self, name=test.name, runner=runner, dtest=test
+                )
+
+    if pytest_version[0] < 7:
+
+        @property
+        def path(self) -> Path:
+            return Path(self.fspath)
+
+        @classmethod
+        def from_parent(
+            cls,
+            parent,
+            *,
+            fspath=None,
+            path: Optional[Path] = None,
+            **kw,
+        ):
+            if path is not None:
+                import py.path
+
+                fspath = py.path.local(path)
+            return super().from_parent(parent=parent, fspath=fspath, **kw)
+
+
+def _setup_fixtures(doctest_item: IPDoctestItem) -> FixtureRequest:
+    """Used by IPDoctestTextfile and IPDoctestItem to setup fixture information."""
+
+    def func() -> None:
+        pass
+
+    doctest_item.funcargs = {}  # type: ignore[attr-defined]
+    fm = doctest_item.session._fixturemanager
+    kwargs = {"node": doctest_item, "func": func, "cls": None}
+    if pytest_version <= (8, 0):
+        kwargs["funcargs"] = False
+    doctest_item._fixtureinfo = fm.getfixtureinfo(  # type: ignore[attr-defined]
+        **kwargs
+    )
+    fixture_request = FixtureRequest(doctest_item, _ispytest=True)
+    if pytest_version <= (8, 0):
+        fixture_request._fillfixtures()
+    return fixture_request
+
+
+def _init_checker_class() -> Type["IPDoctestOutputChecker"]:
+    import doctest
+    import re
+    from .ipdoctest import IPDoctestOutputChecker
+
+    class LiteralsOutputChecker(IPDoctestOutputChecker):
+        # Based on doctest_nose_plugin.py from the nltk project
+        # (https://github.com/nltk/nltk) and on the "numtest" doctest extension
+        # by Sebastien Boisgerault (https://github.com/boisgera/numtest).
+
+        _unicode_literal_re = re.compile(r"(\W|^)[uU]([rR]?[\'\"])", re.UNICODE)
+        _bytes_literal_re = re.compile(r"(\W|^)[bB]([rR]?[\'\"])", re.UNICODE)
+        _number_re = re.compile(
+            r"""
+            (?P<number>
+              (?P<mantissa>
+                (?P<integer1> [+-]?\d*)\.(?P<fraction>\d+)
+                |
+                (?P<integer2> [+-]?\d+)\.
+              )
+              (?:
+                [Ee]
+                (?P<exponent1> [+-]?\d+)
+              )?
+              |
+              (?P<integer3> [+-]?\d+)
+              (?:
+                [Ee]
+                (?P<exponent2> [+-]?\d+)
+              )
+            )
+            """,
+            re.VERBOSE,
+        )
+
+        def check_output(self, want: str, got: str, optionflags: int) -> bool:
+            if super().check_output(want, got, optionflags):
+                return True
+
+            allow_unicode = optionflags & _get_allow_unicode_flag()
+            allow_bytes = optionflags & _get_allow_bytes_flag()
+            allow_number = optionflags & _get_number_flag()
+
+            if not allow_unicode and not allow_bytes and not allow_number:
+                return False
+
+            def remove_prefixes(regex: Pattern[str], txt: str) -> str:
+                return re.sub(regex, r"\1\2", txt)
+
+            if allow_unicode:
+                want = remove_prefixes(self._unicode_literal_re, want)
+                got = remove_prefixes(self._unicode_literal_re, got)
+
+            if allow_bytes:
+                want = remove_prefixes(self._bytes_literal_re, want)
+                got = remove_prefixes(self._bytes_literal_re, got)
+
+            if allow_number:
+                got = self._remove_unwanted_precision(want, got)
+
+            return super().check_output(want, got, optionflags)
+
+        def _remove_unwanted_precision(self, want: str, got: str) -> str:
+            wants = list(self._number_re.finditer(want))
+            gots = list(self._number_re.finditer(got))
+            if len(wants) != len(gots):
+                return got
+            offset = 0
+            for w, g in zip(wants, gots):
+                fraction: Optional[str] = w.group("fraction")
+                exponent: Optional[str] = w.group("exponent1")
+                if exponent is None:
+                    exponent = w.group("exponent2")
+                precision = 0 if fraction is None else len(fraction)
+                if exponent is not None:
+                    precision -= int(exponent)
+                if float(w.group()) == approx(float(g.group()), abs=10**-precision):
+                    # They're close enough. Replace the text we actually
+                    # got with the text we want, so that it will match when we
+                    # check the string literally.
+                    got = (
+                        got[: g.start() + offset] + w.group() + got[g.end() + offset :]
+                    )
+                    offset += w.end() - w.start() - (g.end() - g.start())
+            return got
+
+    return LiteralsOutputChecker
+
+
+def _get_checker() -> "IPDoctestOutputChecker":
+    """Return a IPDoctestOutputChecker subclass that supports some
+    additional options:
+
+    * ALLOW_UNICODE and ALLOW_BYTES options to ignore u'' and b''
+      prefixes (respectively) in string literals. Useful when the same
+      ipdoctest should run in Python 2 and Python 3.
+
+    * NUMBER to ignore floating-point differences smaller than the
+      precision of the literal number in the ipdoctest.
+
+    An inner class is used to avoid importing "ipdoctest" at the module
+    level.
+    """
+    global CHECKER_CLASS
+    if CHECKER_CLASS is None:
+        CHECKER_CLASS = _init_checker_class()
+    return CHECKER_CLASS()
+
+
+def _get_allow_unicode_flag() -> int:
+    """Register and return the ALLOW_UNICODE flag."""
+    import doctest
+
+    return doctest.register_optionflag("ALLOW_UNICODE")
+
+
+def _get_allow_bytes_flag() -> int:
+    """Register and return the ALLOW_BYTES flag."""
+    import doctest
+
+    return doctest.register_optionflag("ALLOW_BYTES")
+
+
+def _get_number_flag() -> int:
+    """Register and return the NUMBER flag."""
+    import doctest
+
+    return doctest.register_optionflag("NUMBER")
+
+
+def _get_report_choice(key: str) -> int:
+    """Return the actual `ipdoctest` module flag value.
+
+    We want to do it as late as possible to avoid importing `ipdoctest` and all
+    its dependencies when parsing options, as it adds overhead and breaks tests.
+    """
+    import doctest
+
+    return {
+        DOCTEST_REPORT_CHOICE_UDIFF: doctest.REPORT_UDIFF,
+        DOCTEST_REPORT_CHOICE_CDIFF: doctest.REPORT_CDIFF,
+        DOCTEST_REPORT_CHOICE_NDIFF: doctest.REPORT_NDIFF,
+        DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE: doctest.REPORT_ONLY_FIRST_FAILURE,
+        DOCTEST_REPORT_CHOICE_NONE: 0,
+    }[key]
+
+
+@pytest.fixture(scope="session")
+def ipdoctest_namespace() -> Dict[str, Any]:
+    """Fixture that returns a :py:class:`dict` that will be injected into the
+    namespace of ipdoctests."""
+    return dict()

lib/python3.12/site-packages/IPython/testing/plugin/setup.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+"""A Nose plugin to support IPython doctests.
+"""
+
+from setuptools import setup
+
+setup(name='IPython doctest plugin',
+      version='0.1',
+      author='The IPython Team',
+      description = 'Nose plugin to load IPython-extended doctests',
+      license = 'LGPL',
+      py_modules = ['ipdoctest'],
+      entry_points = {
+        'nose.plugins.0.10': ['ipdoctest = ipdoctest:IPythonDoctest',
+                              'extdoctest = ipdoctest:ExtensionDoctest',
+                              ],
+        },
+      )

lib/python3.12/site-packages/IPython/testing/plugin/simple.py

@@ -0,0 +1,45 @@
+"""Simple example using doctests.
+
+This file just contains doctests both using plain python and IPython prompts.
+All tests should be loaded by Pytest.
+"""
+
+
+def pyfunc():
+    """Some pure python tests...
+
+    >>> pyfunc()
+    'pyfunc'
+
+    >>> import os
+
+    >>> 2+3
+    5
+
+    >>> for i in range(3):
+    ...     print(i, end=' ')
+    ...     print(i+1, end=' ')
+    ...
+    0 1 1 2 2 3
+    """
+    return "pyfunc"
+
+
+def ipyfunc():
+    """Some IPython tests...
+
+    In [1]: ipyfunc()
+    Out[1]: 'ipyfunc'
+
+    In [2]: import os
+
+    In [3]: 2+3
+    Out[3]: 5
+
+    In [4]: for i in range(3):
+       ...:     print(i, end=' ')
+       ...:     print(i+1, end=' ')
+       ...:
+    Out[4]: 0 1 1 2 2 3
+    """
+    return "ipyfunc"

lib/python3.12/site-packages/IPython/testing/plugin/test_combo.txt

@@ -0,0 +1,36 @@
+=======================
+ Combo testing example
+=======================
+
+This is a simple example that mixes ipython doctests::
+
+    In [1]: import code
+
+    In [2]: 2**12
+    Out[2]: 4096
+
+with command-line example information that does *not* get executed::
+
+    $ mpirun -n 4 ipengine --controller-port=10000 --controller-ip=host0
+
+and with literal examples of Python source code::
+
+    controller = dict(host='myhost',
+		      engine_port=None, # default is 10105
+		      control_port=None,
+		      )
+
+    # keys are hostnames, values are the number of engine on that host
+    engines = dict(node1=2,
+		   node2=2,
+		   node3=2,
+		   node3=2,
+		   )
+
+    # Force failure to detect that this test is being run.
+    1/0
+
+These source code examples are executed but no output is compared at all.  An
+error or failure is reported only if an exception is raised.
+
+NOTE: the execution of pure python blocks is not yet working!

lib/python3.12/site-packages/IPython/testing/plugin/test_exampleip.txt

@@ -0,0 +1,30 @@
+=================================
+ Tests in example form - IPython
+=================================
+
+You can write text files with examples that use IPython prompts (as long as you
+use the nose ipython doctest plugin), but you can not mix and match prompt
+styles in a single file.  That is, you either use all ``>>>`` prompts or all
+IPython-style prompts.  Your test suite *can* have both types, you just need to
+put each type of example in a separate. Using IPython prompts, you can paste
+directly from your session::
+
+    In [5]: s="Hello World"
+
+    In [6]: s.upper()
+    Out[6]: 'HELLO WORLD'
+
+Another example::
+
+    In [8]: 1+3
+    Out[8]: 4
+
+Just like in IPython docstrings, you can use all IPython syntax and features::
+
+    In [9]: !echo hello
+    hello
+
+    In [10]: a='hi'
+
+    In [11]: !echo $a
+    hi

lib/python3.12/site-packages/IPython/testing/plugin/test_ipdoctest.py

@@ -0,0 +1,92 @@
+"""Tests for the ipdoctest machinery itself.
+
+Note: in a file named test_X, functions whose only test is their docstring (as
+a doctest) and which have no test functionality of their own, should be called
+'doctest_foo' instead of 'test_foo', otherwise they get double-counted (the
+empty function call is counted as a test, which just inflates tests numbers
+artificially).
+"""
+
+def doctest_simple():
+    """ipdoctest must handle simple inputs
+    
+    In [1]: 1
+    Out[1]: 1
+
+    In [2]: print(1)
+    1
+    """
+
+def doctest_multiline1():
+    """The ipdoctest machinery must handle multiline examples gracefully.
+
+    In [2]: for i in range(4):
+       ...:     print(i)
+       ...:      
+    0
+    1
+    2
+    3
+    """
+
+def doctest_multiline2():
+    """Multiline examples that define functions and print output.
+
+    In [7]: def f(x):
+       ...:     return x+1
+       ...: 
+
+    In [8]: f(1)
+    Out[8]: 2
+
+    In [9]: def g(x):
+       ...:     print('x is:',x)
+       ...:      
+
+    In [10]: g(1)
+    x is: 1
+
+    In [11]: g('hello')
+    x is: hello
+    """
+
+
+def doctest_multiline3():
+    """Multiline examples with blank lines.
+
+    In [12]: def h(x):
+       ....:     if x>1:
+       ....:         return x**2
+       ....:     # To leave a blank line in the input, you must mark it
+       ....:     # with a comment character:
+       ....:     #
+       ....:     # otherwise the doctest parser gets confused.
+       ....:     else:
+       ....:         return -1
+       ....:      
+
+    In [13]: h(5)
+    Out[13]: 25
+
+    In [14]: h(1)
+    Out[14]: -1
+
+    In [15]: h(0)
+    Out[15]: -1
+   """
+
+
+def doctest_builtin_underscore():
+    """Defining builtins._ should not break anything outside the doctest
+    while also should be working as expected inside the doctest.
+
+    In [1]: import builtins
+
+    In [2]: builtins._ = 42
+
+    In [3]: builtins._
+    Out[3]: 42
+
+    In [4]: _
+    Out[4]: 42
+    """

lib/python3.12/site-packages/IPython/testing/plugin/test_refs.py

@@ -0,0 +1,39 @@
+"""Some simple tests for the plugin while running scripts.
+"""
+# Module imports
+# Std lib
+import inspect
+
+# Our own
+
+#-----------------------------------------------------------------------------
+# Testing functions
+
+def test_trivial():
+    """A trivial passing test."""
+    pass
+
+def doctest_run():
+    """Test running a trivial script.
+
+    In [13]: run simplevars.py
+    x is: 1
+    """
+
+def doctest_runvars():
+    """Test that variables defined in scripts get loaded correctly via %run.
+
+    In [13]: run simplevars.py
+    x is: 1
+
+    In [14]: x
+    Out[14]: 1
+    """
+
+def doctest_ivars():
+    """Test that variables defined interactively are picked up.
+    In [5]: zz=1
+
+    In [6]: zz
+    Out[6]: 1
+    """

lib/python3.12/site-packages/IPython/testing/skipdoctest.py

@@ -0,0 +1,19 @@
+"""Decorators marks that a doctest should be skipped.
+
+The IPython.testing.decorators module triggers various extra imports, including
+numpy and sympy if they're present. Since this decorator is used in core parts
+of IPython, it's in a separate module so that running IPython doesn't trigger
+those imports."""
+
+# Copyright (C) IPython Development Team
+# Distributed under the terms of the Modified BSD License.
+
+
+def skip_doctest(f):
+    """Decorator - mark a function or method for skipping its doctest.
+
+    This decorator allows you to mark a function whose docstring you wish to
+    omit from testing, while preserving the docstring for introspection, help,
+    etc."""
+    f.__skip_doctest__ = True
+    return f

lib/python3.12/site-packages/IPython/testing/tools.py

@@ -0,0 +1,434 @@
+"""Generic testing tools.
+
+Authors
+-------
+- Fernando Perez <Fernando.Perez@berkeley.edu>
+"""
+
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+import unittest
+
+from contextlib import contextmanager
+from io import StringIO
+from subprocess import Popen, PIPE
+from unittest.mock import patch
+
+from traitlets.config.loader import Config
+from IPython.utils.process import get_output_error_code
+from IPython.utils.text import list_strings
+from IPython.utils.io import temp_pyfile, Tee
+from IPython.utils import py3compat
+
+from . import decorators as dec
+from . import skipdoctest
+
+
+# The docstring for full_path doctests differently on win32 (different path
+# separator) so just skip the doctest there.  The example remains informative.
+doctest_deco = skipdoctest.skip_doctest if sys.platform == 'win32' else dec.null_deco
+
+@doctest_deco
+def full_path(startPath: str, files: list[str]) -> list[str]:
+    """Make full paths for all the listed files, based on startPath.
+
+    Only the base part of startPath is kept, since this routine is typically
+    used with a script's ``__file__`` variable as startPath. The base of startPath
+    is then prepended to all the listed files, forming the output list.
+
+    Parameters
+    ----------
+    startPath : string
+      Initial path to use as the base for the results.  This path is split
+      using os.path.split() and only its first component is kept.
+
+    files : list
+      One or more files.
+
+    Examples
+    --------
+
+    >>> full_path('/foo/bar.py',['a.txt','b.txt'])
+    ['/foo/a.txt', '/foo/b.txt']
+
+    >>> full_path('/foo',['a.txt','b.txt'])
+    ['/a.txt', '/b.txt']
+
+    """
+    assert isinstance(files, list)
+    base = os.path.split(startPath)[0]
+    return [ os.path.join(base,f) for f in files ]
+
+
+def parse_test_output(txt):
+    """Parse the output of a test run and return errors, failures.
+
+    Parameters
+    ----------
+    txt : str
+      Text output of a test run, assumed to contain a line of one of the
+      following forms::
+
+        'FAILED (errors=1)'
+        'FAILED (failures=1)'
+        'FAILED (errors=1, failures=1)'
+
+    Returns
+    -------
+    nerr, nfail
+      number of errors and failures.
+    """
+
+    err_m = re.search(r'^FAILED \(errors=(\d+)\)', txt, re.MULTILINE)
+    if err_m:
+        nerr = int(err_m.group(1))
+        nfail = 0
+        return  nerr, nfail
+
+    fail_m = re.search(r'^FAILED \(failures=(\d+)\)', txt, re.MULTILINE)
+    if fail_m:
+        nerr = 0
+        nfail = int(fail_m.group(1))
+        return  nerr, nfail
+
+    both_m = re.search(r'^FAILED \(errors=(\d+), failures=(\d+)\)', txt,
+                       re.MULTILINE)
+    if both_m:
+        nerr = int(both_m.group(1))
+        nfail = int(both_m.group(2))
+        return  nerr, nfail
+
+    # If the input didn't match any of these forms, assume no error/failures
+    return 0, 0
+
+
+# So nose doesn't think this is a test
+parse_test_output.__test__ = False
+
+
+def default_argv():
+    """Return a valid default argv for creating testing instances of ipython"""
+
+    return [
+        "--quick",  # so no config file is loaded
+        # Other defaults to minimize side effects on stdout
+        "--colors=nocolor",
+        "--no-term-title",
+        "--no-banner",
+        "--autocall=0",
+    ]
+
+
+def default_config():
+    """Return a config object with good defaults for testing."""
+    config = Config()
+    config.TerminalInteractiveShell.colors = "nocolor"
+    config.TerminalTerminalInteractiveShell.term_title = (False,)
+    config.TerminalInteractiveShell.autocall = 0
+    f = tempfile.NamedTemporaryFile(suffix="test_hist.sqlite", delete=False)
+    config.HistoryManager.hist_file = Path(f.name)
+    f.close()
+    config.HistoryManager.db_cache_size = 10000
+    return config
+
+
+def get_ipython_cmd(as_string=False):
+    """
+    Return appropriate IPython command line name. By default, this will return
+    a list that can be used with subprocess.Popen, for example, but passing
+    `as_string=True` allows for returning the IPython command as a string.
+
+    Parameters
+    ----------
+    as_string: bool
+        Flag to allow to return the command as a string.
+    """
+    ipython_cmd = [sys.executable, "-m", "IPython"]
+
+    if as_string:
+        ipython_cmd = " ".join(ipython_cmd)
+
+    return ipython_cmd
+
+def ipexec(fname, options=None, commands=()):
+    """Utility to call 'ipython filename'.
+
+    Starts IPython with a minimal and safe configuration to make startup as fast
+    as possible.
+
+    Note that this starts IPython in a subprocess!
+
+    Parameters
+    ----------
+    fname : str, Path
+      Name of file to be executed (should have .py or .ipy extension).
+
+    options : optional, list
+      Extra command-line flags to be passed to IPython.
+
+    commands : optional, list
+      Commands to send in on stdin
+
+    Returns
+    -------
+    ``(stdout, stderr)`` of ipython subprocess.
+    """
+    __tracebackhide__ = True
+
+    if options is None:
+        options = []
+
+    cmdargs = default_argv() + options
+
+    test_dir = os.path.dirname(__file__)
+
+    ipython_cmd = get_ipython_cmd()
+    # Absolute path for filename
+    full_fname = os.path.join(test_dir, fname)
+    full_cmd = ipython_cmd + cmdargs + ['--', full_fname]
+    env = os.environ.copy()
+    # FIXME: ignore all warnings in ipexec while we have shims
+    # should we keep suppressing warnings here, even after removing shims?
+    env['PYTHONWARNINGS'] = 'ignore'
+    # env.pop('PYTHONWARNINGS', None)  # Avoid extraneous warnings appearing on stderr
+    # Prevent coloring under PyCharm ("\x1b[0m" at the end of the stdout)
+    env.pop("PYCHARM_HOSTED", None)
+    for k, v in env.items():
+        # Debug a bizarre failure we've seen on Windows:
+        # TypeError: environment can only contain strings
+        if not isinstance(v, str):
+            print(k, v)
+    p = Popen(full_cmd, stdout=PIPE, stderr=PIPE, stdin=PIPE, env=env)
+    out, err = p.communicate(input=py3compat.encode('\n'.join(commands)) or None)
+    out, err = py3compat.decode(out), py3compat.decode(err)
+    # `import readline` causes 'ESC[?1034h' to be output sometimes,
+    # so strip that out before doing comparisons
+    if out:
+        out = re.sub(r'\x1b\[[^h]+h', '', out)
+    return out, err
+
+
+def ipexec_validate(fname, expected_out, expected_err='',
+                    options=None, commands=()):
+    """Utility to call 'ipython filename' and validate output/error.
+
+    This function raises an AssertionError if the validation fails.
+
+    Note that this starts IPython in a subprocess!
+
+    Parameters
+    ----------
+    fname : str, Path
+      Name of the file to be executed (should have .py or .ipy extension).
+
+    expected_out : str
+      Expected stdout of the process.
+
+    expected_err : optional, str
+      Expected stderr of the process.
+
+    options : optional, list
+      Extra command-line flags to be passed to IPython.
+
+    Returns
+    -------
+    None
+    """
+    __tracebackhide__ = True
+
+    out, err = ipexec(fname, options, commands)
+    # print('OUT', out)  # dbg
+    # print('ERR', err)  # dbg
+    # If there are any errors, we must check those before stdout, as they may be
+    # more informative than simply having an empty stdout.
+    if err:
+        if expected_err:
+            assert "\n".join(err.strip().splitlines()) == "\n".join(
+                expected_err.strip().splitlines()
+            )
+        else:
+            raise ValueError('Running file %r produced error: %r' %
+                             (fname, err))
+    # If no errors or output on stderr was expected, match stdout
+    assert "\n".join(out.strip().splitlines()) == "\n".join(
+        expected_out.strip().splitlines()
+    )
+
+
+class TempFileMixin(unittest.TestCase):
+    """Utility class to create temporary Python/IPython files.
+
+    Meant as a mixin class for test cases."""
+
+    def mktmp(self, src, ext='.py'):
+        """Make a valid python temp file."""
+        fname = temp_pyfile(src, ext)
+        if not hasattr(self, 'tmps'):
+            self.tmps=[]
+        self.tmps.append(fname)
+        self.fname = fname
+
+    def tearDown(self):
+        # If the tmpfile wasn't made because of skipped tests, like in
+        # win32, there's nothing to cleanup.
+        if hasattr(self, 'tmps'):
+            for fname in self.tmps:
+                # If the tmpfile wasn't made because of skipped tests, like in
+                # win32, there's nothing to cleanup.
+                try:
+                    os.unlink(fname)
+                except:
+                    # On Windows, even though we close the file, we still can't
+                    # delete it.  I have no clue why
+                    pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.tearDown()
+
+
+MyStringIO = StringIO
+
+_re_type = type(re.compile(r''))
+
+notprinted_msg = """Did not find {0!r} in printed output (on {1}):
+-------
+{2!s}
+-------
+"""
+
+class AssertPrints:
+    """Context manager for testing that code prints certain text.
+
+    Examples
+    --------
+    >>> with AssertPrints("abc", suppress=False):
+    ...     print("abcd")
+    ...     print("def")
+    ...
+    abcd
+    def
+    """
+    def __init__(self, s, channel='stdout', suppress=True):
+        self.s = s
+        if isinstance(self.s, (str, _re_type)):
+            self.s = [self.s]
+        self.channel = channel
+        self.suppress = suppress
+
+    def __enter__(self):
+        self.orig_stream = getattr(sys, self.channel)
+        self.buffer = MyStringIO()
+        self.tee = Tee(self.buffer, channel=self.channel)
+        setattr(sys, self.channel, self.buffer if self.suppress else self.tee)
+
+    def __exit__(self, etype, value, traceback):
+        __tracebackhide__ = True
+
+        try:
+            if value is not None:
+                # If an error was raised, don't check anything else
+                return False
+            self.tee.flush()
+            setattr(sys, self.channel, self.orig_stream)
+            printed = self.buffer.getvalue()
+            for s in self.s:
+                if isinstance(s, _re_type):
+                    assert s.search(printed), notprinted_msg.format(s.pattern, self.channel, printed)
+                else:
+                    assert s in printed, notprinted_msg.format(s, self.channel, printed)
+            return False
+        finally:
+            self.tee.close()
+
+printed_msg = """Found {0!r} in printed output (on {1}):
+-------
+{2!s}
+-------
+"""
+
+class AssertNotPrints(AssertPrints):
+    """Context manager for checking that certain output *isn't* produced.
+
+    Counterpart of AssertPrints"""
+    def __exit__(self, etype, value, traceback):
+        __tracebackhide__ = True
+
+        try:
+            if value is not None:
+                # If an error was raised, don't check anything else
+                self.tee.close()
+                return False
+            self.tee.flush()
+            setattr(sys, self.channel, self.orig_stream)
+            printed = self.buffer.getvalue()
+            for s in self.s:
+                if isinstance(s, _re_type):
+                    assert not s.search(printed),printed_msg.format(
+                        s.pattern, self.channel, printed)
+                else:
+                    assert s not in printed, printed_msg.format(
+                        s, self.channel, printed)
+            return False
+        finally:
+            self.tee.close()
+
+@contextmanager
+def make_tempfile(name):
+    """Create an empty, named, temporary file for the duration of the context."""
+    open(name, "w", encoding="utf-8").close()
+    try:
+        yield
+    finally:
+        os.unlink(name)
+
+def fake_input(inputs):
+    """Temporarily replace the input() function to return the given values
+
+    Use as a context manager:
+
+    with fake_input(['result1', 'result2']):
+        ...
+
+    Values are returned in order. If input() is called again after the last value
+    was used, EOFError is raised.
+    """
+    it = iter(inputs)
+    def mock_input(prompt=''):
+        try:
+            return next(it)
+        except StopIteration as e:
+            raise EOFError('No more inputs given') from e
+
+    return patch('builtins.input', mock_input)
+
+def help_output_test(subcommand=''):
+    """test that `ipython [subcommand] -h` works"""
+    cmd = get_ipython_cmd() + [subcommand, '-h']
+    out, err, rc = get_output_error_code(cmd)
+    assert rc == 0, err
+    assert "Traceback" not in err
+    assert "Options" in out
+    assert "--help-all" in out
+    return out, err
+
+
+def help_all_output_test(subcommand=''):
+    """test that `ipython [subcommand] --help-all` works"""
+    cmd = get_ipython_cmd() + [subcommand, '--help-all']
+    out, err, rc = get_output_error_code(cmd)
+    assert rc == 0, err
+    assert "Traceback" not in err
+    assert "Options" in out
+    assert "Class" in out
+    return out, err
+