first commit

README.md

@@ -0,0 +1 @@
+...

app.py

@@ -0,0 +1,557 @@
+import time
+print(f"Starting up: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+
+# Standard library imports
+import os
+from pathlib import Path
+from datetime import datetime
+from itertools import chain
+
+# Third-party imports
+import numpy as np
+import pandas as pd
+import torch
+import gradio as gr
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+import uvicorn
+import matplotlib.pyplot as plt
+import tqdm
+import colormaps
+import matplotlib.colors as mcolors
+
+
+import opinionated # for fonts
+plt.style.use("opinionated_rc")
+
+from sklearn.neighbors import NearestNeighbors
+
+
+def is_running_in_hf_space():
+    return "SPACE_ID" in os.environ
+
+if is_running_in_hf_space():
+    import spaces # necessary to run on Zero.
+
+import datamapplot
+import pyalex
+
+# Local imports
+from openalex_utils import (
+    openalex_url_to_pyalex_query, 
+    get_field,
+    process_records_to_df,
+    openalex_url_to_filename
+)
+from styles import DATAMAP_CUSTOM_CSS
+from data_setup import (
+    download_required_files,
+    setup_basemap_data,
+    setup_mapper,
+    setup_embedding_model,
+    
+)
+
+# Configure OpenAlex
+pyalex.config.email = "[email protected]"
+
+print(f"Imports completed: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+
+# FastAPI setup
+app = FastAPI()
+static_dir = Path('./static')
+static_dir.mkdir(parents=True, exist_ok=True)
+app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+# Gradio configuration
+gr.set_static_paths(paths=["static/"])
+
+# Resource configuration
+REQUIRED_FILES = {
+    "100k_filtered_OA_sample_cluster_and_positions_supervised.pkl": 
+        "https://huggingface.co/datasets/m7n/intermediate_sci_pickle/resolve/main/100k_filtered_OA_sample_cluster_and_positions_supervised.pkl",
+    "umap_mapper_250k_random_OA_discipline_tuned_specter_2_params.pkl":
+        "https://huggingface.co/datasets/m7n/intermediate_sci_pickle/resolve/main/umap_mapper_250k_random_OA_discipline_tuned_specter_2_params.pkl"
+}
+BASEMAP_PATH = "100k_filtered_OA_sample_cluster_and_positions_supervised.pkl"
+MAPPER_PARAMS_PATH = "umap_mapper_250k_random_OA_discipline_tuned_specter_2_params.pkl"
+MODEL_NAME = "m7n/discipline-tuned_specter_2_024"
+
+# Initialize models and data
+start_time = time.time()
+print("Initializing resources...")
+
+download_required_files(REQUIRED_FILES)
+basedata_df = setup_basemap_data(BASEMAP_PATH)
+mapper = setup_mapper(MAPPER_PARAMS_PATH)
+model = setup_embedding_model(MODEL_NAME)
+
+print(f"Resources initialized in {time.time() - start_time:.2f} seconds")
+
+
+
+# Setting up decorators for embedding on HF-Zero:
+def no_op_decorator(func):
+    """A no-op (no operation) decorator that simply returns the function."""
+    def wrapper(*args, **kwargs):
+        # Do nothing special
+        return func(*args, **kwargs)
+    return wrapper
+
+# Decide which decorator to use based on environment
+decorator_to_use = spaces.GPU(duration=60) if is_running_in_hf_space() else no_op_decorator
+
+    
+@decorator_to_use
+def create_embeddings(texts_to_embedd):
+    """Create embeddings for the input texts using the loaded model."""
+    return model.encode(texts_to_embedd, show_progress_bar=True, batch_size=192)
+
+def predict(text_input, sample_size_slider, reduce_sample_checkbox, sample_reduction_method, 
+           plot_time_checkbox, locally_approximate_publication_date_checkbox, 
+           download_csv_checkbox, download_png_checkbox, progress=gr.Progress()):
+    """
+    Main prediction pipeline that processes OpenAlex queries and creates visualizations.
+    
+    Args:
+        text_input (str): OpenAlex query URL
+        sample_size_slider (int): Maximum number of samples to process
+        reduce_sample_checkbox (bool): Whether to reduce sample size
+        sample_reduction_method (str): Method for sample reduction ("Random" or "Order of Results")
+        plot_time_checkbox (bool): Whether to color points by publication date
+        locally_approximate_publication_date_checkbox (bool): Whether to approximate publication date locally before plotting.
+        progress (gr.Progress): Gradio progress tracker
+    
+    Returns:
+        tuple: (link to visualization, iframe HTML)
+    """
+    # Check if input is empty or whitespace
+    print(f"Input: {text_input}")
+    if not text_input or text_input.isspace():
+        return "Error: Please enter a valid OpenAlex URL in the 'OpenAlex-search URL'-field", gr.DownloadButton(label=f"Download Interactive Visualization", value='html_file_path', visible=False)
+
+    
+    # Check if the input is a valid OpenAlex URL
+
+    
+    
+    start_time = time.time()
+    print('Starting data projection pipeline')
+    progress(0.1, desc="Starting...")
+
+    # Query OpenAlex
+    query_start = time.time()
+    query, params = openalex_url_to_pyalex_query(text_input)
+    
+    filename = openalex_url_to_filename(text_input)
+    print(f"Filename: {filename}")
+    
+    query_length = query.count()
+    print(f'Requesting {query_length} entries...')
+    
+    records = []
+    target_size = sample_size_slider if reduce_sample_checkbox and sample_reduction_method == "First n samples" else query_length
+    
+    
+    should_break = False
+    for page in query.paginate(per_page=200,n_max=None):
+        for record in page:
+            records.append(record)
+            progress(0.1 + (0.2 * len(records) / target_size), desc="Getting queried data...")
+           # print(len(records))
+            if reduce_sample_checkbox and sample_reduction_method == "First n samples" and len(records) >= target_size:
+                should_break = True
+                break
+        if should_break:
+            break
+    
+    print(f"Query completed in {time.time() - query_start:.2f} seconds")
+
+    # Process records
+    processing_start = time.time()
+    records_df = process_records_to_df(records)
+    
+    if reduce_sample_checkbox and sample_reduction_method != "All":
+        sample_size = min(sample_size_slider, len(records_df))        
+        if sample_reduction_method == "n random samples":
+            records_df = records_df.sample(sample_size)
+        elif sample_reduction_method == "First n samples":
+            records_df = records_df.iloc[:sample_size]
+    print(f"Records processed in {time.time() - processing_start:.2f} seconds")
+    
+    # Create embeddings
+    embedding_start = time.time()
+    progress(0.3, desc="Embedding Data...")
+    texts_to_embedd = [f"{title} {abstract}" for title, abstract 
+                      in zip(records_df['title'], records_df['abstract'])]
+    embeddings = create_embeddings(texts_to_embedd)
+    print(f"Embeddings created in {time.time() - embedding_start:.2f} seconds")
+
+    # Project embeddings
+    projection_start = time.time()
+    progress(0.5, desc="Project into UMAP-embedding...")
+    umap_embeddings = mapper.transform(embeddings)
+    records_df[['x','y']] = umap_embeddings
+    print(f"Projection completed in {time.time() - projection_start:.2f} seconds")
+
+    # Prepare visualization data
+    viz_prep_start = time.time()
+    progress(0.6, desc="Preparing visualization data...")
+    
+    basedata_df['color'] = '#ced4d211'
+    
+    if not plot_time_checkbox:
+        records_df['color'] = '#5e2784'
+    else:
+        cmap = colormaps.haline
+        if not locally_approximate_publication_date_checkbox:
+            # Create color mapping based on publication years
+            years = pd.to_numeric(records_df['publication_year'])
+            norm = mcolors.Normalize(vmin=years.min(), vmax=years.max())
+            records_df['color'] = [mcolors.to_hex(cmap(norm(year))) for year in years]
+            
+        else:
+            n_neighbors = 10  # Adjust this value to control smoothing
+            nn = NearestNeighbors(n_neighbors=n_neighbors)
+            nn.fit(umap_embeddings)
+            distances, indices = nn.kneighbors(umap_embeddings)
+
+            # Calculate local average publication year for each point
+            local_years = np.array([
+                np.mean(records_df['publication_year'].iloc[idx])
+                for idx in indices
+            ])
+            norm = mcolors.Normalize(vmin=local_years.min(), vmax=local_years.max())
+            records_df['color'] = [mcolors.to_hex(cmap(norm(year))) for year in local_years]
+                        
+            
+
+    stacked_df = pd.concat([basedata_df, records_df], axis=0, ignore_index=True)
+    stacked_df = stacked_df.fillna("Unlabelled")
+    stacked_df['parsed_field'] = [get_field(row) for ix, row in stacked_df.iterrows()]
+    extra_data = pd.DataFrame(stacked_df['doi'])
+    print(f"Visualization data prepared in {time.time() - viz_prep_start:.2f} seconds")
+    
+    # Create and save plot
+    plot_start = time.time()
+    progress(0.7, desc="Creating plot...")
+    
+    
+    plot = datamapplot.create_interactive_plot(
+        stacked_df[['x','y']].values,
+                                np.array(stacked_df['cluster_2_labels']),
+        np.array(['Unlabelled' if pd.isna(x) else x for x in stacked_df['parsed_field']]),
+        
+        hover_text=[str(row['title']) for ix, row in stacked_df.iterrows()],
+        marker_color_array=stacked_df['color'],
+        use_medoids=True,
+        width=1000,
+        height=1000,
+        point_radius_min_pixels=1,
+        text_outline_width=5,
+        point_hover_color='#5e2784',
+        point_radius_max_pixels=7,
+        color_label_text=False,
+        font_family="Roboto Condensed",
+        font_weight=700,
+        tooltip_font_weight=600,
+        tooltip_font_family="Roboto Condensed",
+        extra_point_data=extra_data,
+        on_click="window.open(`{doi}`)",
+        custom_css=DATAMAP_CUSTOM_CSS,
+        initial_zoom_fraction=.8,
+        enable_search=False
+    )
+
+    # Save plot
+    html_file_name = f"{filename}.html"
+    html_file_path = static_dir / html_file_name
+    plot.save(html_file_path)
+    print(f"Plot created and saved in {time.time() - plot_start:.2f} seconds")
+
+    
+   
+    # Save additional files if requested
+    csv_file_path = static_dir / f"{filename}.csv"
+    png_file_path = static_dir / f"{filename}.png"
+    
+    if download_csv_checkbox:
+        # Export relevant columns
+        export_df = records_df[['title', 'abstract', 'doi', 'publication_year', 'x', 'y']]
+        export_df.to_csv(csv_file_path, index=False)
+        
+    if download_png_checkbox:
+        png_start_time = time.time()
+        print("Starting PNG generation...")
+
+        # Sample and prepare data
+        sample_prep_start = time.time()
+        sample_to_plot = basedata_df#.sample(20000)
+        labels1 = np.array(sample_to_plot['cluster_2_labels'])
+        labels2 = np.array(['Unlabelled' if pd.isna(x) else x for x in sample_to_plot['parsed_field']])
+        
+        ratio = 0.6
+        mask = np.random.random(size=len(labels1)) < ratio
+        combined_labels = np.where(mask, labels1, labels2)
+        
+        # Get the 30 most common labels
+        unique_labels, counts = np.unique(combined_labels, return_counts=True)
+        top_30_labels = set(unique_labels[np.argsort(counts)[-50:]])
+        
+        # Replace less common labels with 'Unlabelled'
+        combined_labels = np.array(['Unlabelled' if label not in top_30_labels else label for label in combined_labels])
+        
+        colors_base = ['#536878' for _ in range(len(labels1))]
+        print(f"Sample preparation completed in {time.time() - sample_prep_start:.2f} seconds")
+
+        # Create main plot
+        print(sample_to_plot[['x','y']].values)
+        print(combined_labels)
+        
+        main_plot_start = time.time()
+        fig, ax = datamapplot.create_plot(
+            sample_to_plot[['x','y']].values,
+            combined_labels,
+            label_wrap_width=12,
+            label_over_points=True,
+            dynamic_label_size=True,
+            use_medoids=True,
+            point_size=2,
+            marker_color_array=colors_base,
+            force_matplotlib=True,
+            max_font_size=12,
+            min_font_size=4,
+            min_font_weight=100,
+            max_font_weight=300,
+            font_family="Roboto Condensed",
+            color_label_text=False, add_glow=False,
+            highlight_labels=list(np.unique(labels1)),
+            label_font_size=8,
+            highlight_label_keywords={"fontsize": 12, "fontweight": "bold", "bbox":{"boxstyle":"circle", "pad":0.75,'alpha':0.}},
+        )
+        print(f"Main plot creation completed in {time.time() - main_plot_start:.2f} seconds")
+
+        # Time-based visualization
+        scatter_start = time.time()
+        if plot_time_checkbox:
+            if locally_approximate_publication_date_checkbox:
+                scatter = plt.scatter(
+                    umap_embeddings[:,0],
+                    umap_embeddings[:,1],
+                    c=local_years,
+                    cmap=colormaps.haline,
+                    alpha=0.8,
+                    s=5
+                )
+            else:
+                years = pd.to_numeric(records_df['publication_year'])
+                scatter = plt.scatter(
+                    umap_embeddings[:,0],
+                    umap_embeddings[:,1],
+                    c=years,
+                    cmap=colormaps.haline,
+                    alpha=0.8,
+                    s=5
+                )
+            plt.colorbar(scatter, shrink=0.5, format='%d')
+        else:
+            scatter = plt.scatter(
+                umap_embeddings[:,0],
+                umap_embeddings[:,1],
+                c=records_df['color'],
+                alpha=0.8,
+                s=5
+            )
+        print(f"Scatter plot creation completed in {time.time() - scatter_start:.2f} seconds")
+
+        # Save plot
+        save_start = time.time()
+        plt.axis('off')
+        png_file_path = static_dir / f"{filename}.png"
+        plt.savefig(png_file_path, dpi=300, bbox_inches='tight')
+        plt.close()
+        print(f"Plot saving completed in {time.time() - save_start:.2f} seconds")
+        
+        print(f"Total PNG generation completed in {time.time() - png_start_time:.2f} seconds")
+
+
+
+
+
+
+
+    progress(1.0, desc="Done!")
+    print(f"Total pipeline completed in {time.time() - start_time:.2f} seconds")
+    
+    iframe = f"""<iframe src="/static/{html_file_name}" width="100%" height="1000px"></iframe>"""
+    
+    # Return iframe and download buttons with appropriate visibility
+    return [
+        iframe,
+        gr.DownloadButton(label="Download Interactive Visualization", value=html_file_path, visible=True),
+        gr.DownloadButton(label="Download CSV Data", value=csv_file_path, visible=download_csv_checkbox),
+        gr.DownloadButton(label="Download Static Plot", value=png_file_path, visible=download_png_checkbox),
+        gr.Button(visible=False)  # Return hidden state for cancel button
+    ]
+
+
+theme = gr.themes.Monochrome(
+    font=[gr.themes.GoogleFont("Roboto Condensed"), "ui-sans-serif", "system-ui", "sans-serif"],
+    
+    text_size="lg",
+
+)
+
+
+# Gradio interface setup
+with gr.Blocks(theme=theme) as demo:
+    gr.Markdown("""
+    <div style="max-width: 100%; margin: 0 auto;">
+    <br>
+    
+    # OpenAlex Mapper
+    
+    OpenAlex Mapper is a way of projecting search queries from the amazing OpenAlex database on a background map of randomly sampled papers from OpenAlex, which allows you to easily investigate interdisciplinary connections. OpenAlex Mapper was developed by Maximilian Noichl and Andrea Loettgers at the Possible Life project.
+
+    To use OpenAlex Mapper, first head over to [OpenAlex](https://openalex.org/) and search for something that interests you. For example, you could search for all the papers that make use of the [Kuramoto model](https://openalex.org/works?page=1&filter=default.search%3A%22Kuramoto%20Model%22), for all the papers that were published by researchers at [Utrecht University in 2019](https://openalex.org/works?page=1&filter=authorships.institutions.lineage%3Ai193662353,publication_year%3A2019), or for all the papers that cite Wittgenstein's [Philosophical Investigations](https://openalex.org/works?page=1&filter=cites%3Aw4251395411). Then you copy the URL to that search query into the OpenAlex search URL box below and click "Run Query." It will take a moment to download all of these records from OpenAlex and embed them on our interactive map. After a little time, that map will appear and be available for you to interact with and download. You can find more explanations in the FAQs below.
+    </div>
+    """)
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            with gr.Row():
+                run_btn = gr.Button("Run Query", variant='primary')
+                cancel_btn = gr.Button("Cancel", visible=False, variant='secondary')
+            
+            # Create separate download buttons
+            html_download = gr.DownloadButton("Download Interactive Visualization", visible=False)
+            csv_download = gr.DownloadButton("Download CSV Data", visible=False)
+            png_download = gr.DownloadButton("Download Static Plot", visible=False)
+
+            text_input = gr.Textbox(label="OpenAlex-search URL",
+                                    info="Enter the URL to an OpenAlex-search.")
+            
+            gr.Markdown("### Sample Settings")
+            reduce_sample_checkbox = gr.Checkbox(
+                label="Reduce Sample Size",
+                value=True,
+                info="Reduce sample size."
+            )
+            sample_reduction_method = gr.Dropdown(
+                ["All", "First n samples", "n random samples"],
+                label="Sample Selection Method",
+                value="First n samples",
+                info="How to choose the samples to keep."
+            )
+            sample_size_slider = gr.Slider(
+                label="Sample Size",
+                minimum=500,
+                maximum=20000,
+                step=10,
+                value=1000,
+                info="How many samples to keep.",
+                visible=True
+            )
+            
+            gr.Markdown("### Plot Settings")
+            plot_time_checkbox = gr.Checkbox(
+                label="Plot Time",
+                value=True,
+                info="Colour points by their publication date."
+            )
+            locally_approximate_publication_date_checkbox = gr.Checkbox(
+                label="Locally Approximate Publication Date",
+                value=True,
+                info="Colour points by the average publicaion date in their area."
+            )
+            
+            gr.Markdown("### Download Options")
+            download_csv_checkbox = gr.Checkbox(
+                label="Generate CSV Export",
+                value=False,
+                info="Export the data as CSV file"
+            )
+            download_png_checkbox = gr.Checkbox(
+                label="Generate Static PNG Plot",
+                value=False,
+                info="Export a static PNG visualization. This will make things slower!"
+            )
+            
+            
+            
+            
+        with gr.Column(scale=2):
+            html = gr.HTML(
+                value='<div style="width: 100%; height: 1000px; display: flex; justify-content: center; align-items: center; border: 1px solid #ccc; background-color: #f8f9fa;"><p style="font-size: 1.2em; color: #666;">The visualization map will appear here after running a query</p></div>',
+                label="HTML preview", 
+                show_label=True
+            )
+    gr.Markdown("""
+    <div style="max-width: 100%; margin: 0 auto;">
+    
+    # FAQs
+    
+    ## Who made this?
+
+    This project was developed by [Maximilian Noichl](https://maxnoichl.eu) (Utrecht University), in cooperation with Andrea Loettger and Tarja Knuuttila at the [Possible Life project](http://www.possiblelife.eu/), at the University of Vienna. If this project is useful in any way for your research, we would appreciate citation of **...**
+
+    This project received funding from the European Research Council under the European Union's Horizon 2020 research and innovation programme (LIFEMODE project, grant agreement No. 818772).
+
+    ## How does it work?
+
+    The base map for this project is developed by randomly downloading 250,000 articles from OpenAlex, then embedding their abstracts using our [fine-tuned](https://huggingface.co/m7n/discipline-tuned_specter_2_024) version of the [specter-2](https://huggingface.co/allenai/specter2_aug2023refresh_base) language model, running these embeddings through [UMAP](https://umap-learn.readthedocs.io/en/latest/) to give us a two-dimensional representation, and displaying that in an interactive window using [datamapplot](https://datamapplot.readthedocs.io/en/latest/index.html). After the data for your query is downloaded from OpenAlex, it then undergoes the exact same process, but the pre-trained UMAP model from earlier is used to project your new data points onto this original map, showing where they would show up if they were included in the original sample. For more details, you can take a look at the method section of this paper: **...**
+
+    ## I think I found a mistake in  the map.
+
+    There are various considerations to take into account when working with this map:
+
+    1. The language model we use is fine-tuned to separate disciplines from each other, but of course, disciplines are weird, partially subjective social categories, so what the model has learned might not always correspond perfectly to what you would expect to see.
+
+    2. When pressing down a really high-dimensional space into a low-dimensional one, there will be trade-offs. For example, we see this big ring structure of the sciences on the map, but in the middle of the map there is a overly stretchedstring of bioinformaticsthat stretches from computer science at the bottom up to the life sciences clusters at the top. This is one of the areas where the UMAP algorithm had trouble pressing our high-dimensional dataset into a low-dimensional space. For more information on how to read a UMAP plot, I recommend looking into ["Understanding UMAP"](https://pair-code.github.io/understanding-umap/) by Andy Coenen & Adam Pearce.
+    
+    3. Finally, the labels we're using for the regions of this plot are created from OpenAlex's own labels of sub-disciplines. They give a rough indication of the papers that could be expected in this broad area of the map, but they are not necessarily the perfect label for the articles that are precisely below them. They are just located at the median point of a usually much larger, much broader, and fuzzier category, so they should always be taken with quite a big grain of salt.
+    </div>
+    """)
+
+    def update_slider_visibility(method):
+        return gr.Slider(visible=(method != "All"))
+
+    sample_reduction_method.change(
+        fn=update_slider_visibility,
+        inputs=[sample_reduction_method],
+        outputs=[sample_size_slider]
+    )
+    
+    def show_cancel_button():
+        return gr.Button(visible=True)
+    
+    def hide_cancel_button():
+        return gr.Button(visible=False)
+
+    # Update the run button click event
+    run_event = run_btn.click(
+        fn=show_cancel_button,
+        outputs=cancel_btn,
+        queue=False
+    ).then(
+        fn=predict,
+        inputs=[text_input, sample_size_slider, reduce_sample_checkbox, 
+                sample_reduction_method, plot_time_checkbox, 
+                locally_approximate_publication_date_checkbox,
+                download_csv_checkbox, download_png_checkbox],
+        outputs=[html, html_download, csv_download, png_download, cancel_btn]
+    )
+
+    # Add cancel button click event
+    cancel_btn.click(
+        fn=hide_cancel_button,
+        outputs=cancel_btn,
+        cancels=[run_event],
+        queue=False  # Important to make the button hide immediately
+    )
+
+# Mount and run app
+app = gr.mount_gradio_app(app, demo, path="/")
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

data_setup.py

@@ -0,0 +1,117 @@
+import pickle
+import requests
+import umap
+from numba.typed import List
+import torch
+from sentence_transformers import SentenceTransformer
+import time
+from pathlib import Path
+
+def check_resources(files_dict, basemap_path, mapper_params_path):
+    """
+    Check if all required resources are present.
+    
+    Args:
+        files_dict (dict): Dictionary mapping filenames to their download URLs
+        basemap_path (str): Path to the basemap pickle file
+        mapper_params_path (str): Path to the UMAP mapper parameters pickle file
+        
+    Returns:
+        bool: True if all resources are present, False otherwise
+    """
+    all_files_present = True
+    
+    # Check downloaded files
+    for filename in files_dict.keys():
+        if not Path(filename).exists():
+            print(f"Missing file: {filename}")
+            all_files_present = False
+    
+    # Check basemap
+    if not Path(basemap_path).exists():
+        print(f"Missing basemap file: {basemap_path}")
+        all_files_present = False
+        
+    # Check mapper params
+    if not Path(mapper_params_path).exists():
+        print(f"Missing mapper params file: {mapper_params_path}")
+        all_files_present = False
+    
+    return all_files_present
+
+def download_required_files(files_dict):
+    """
+    Download required files from URLs only if they don't exist.
+    
+    Args:
+        files_dict (dict): Dictionary mapping filenames to their download URLs
+    """
+    print(f"Checking required files: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    files_to_download = {
+        filename: url 
+        for filename, url in files_dict.items() 
+        if not Path(filename).exists()
+    }
+    
+    if not files_to_download:
+        print("All files already present, skipping downloads")
+        return
+        
+    print(f"Downloading missing files: {list(files_to_download.keys())}")
+    for filename, url in files_to_download.items():
+        print(f"Downloading {filename}...")
+        response = requests.get(url)
+        with open(filename, "wb") as f:
+            f.write(response.content)
+
+def setup_basemap_data(basemap_path):
+    """
+    Load and setup the base map data.
+    
+    Args:
+        basemap_path (str): Path to the basemap pickle file
+    """
+    print(f"Getting basemap data: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    basedata_df = pickle.load(open(basemap_path, 'rb'))
+    return basedata_df
+
+def setup_mapper(mapper_params_path):
+    """
+    Setup and configure the UMAP mapper.
+    
+    Args:
+        mapper_params_path (str): Path to the UMAP mapper parameters pickle file
+    """
+    print(f"Getting Mapper: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    params_new = pickle.load(open(mapper_params_path, 'rb'))
+    print("setting up mapper...")
+    mapper = umap.UMAP()
+    
+    umap_params = {k: v for k, v in params_new.get('umap_params', {}).items() 
+                  if k != 'target_backend'}
+    mapper.set_params(**umap_params)
+    
+    for attr, value in params_new.get('umap_attributes', {}).items():
+        if attr != 'embedding_':
+            setattr(mapper, attr, value)
+    
+    if 'embedding_' in params_new.get('umap_attributes', {}):
+        mapper.embedding_ = List(params_new['umap_attributes']['embedding_'])
+    
+    return mapper
+
+def setup_embedding_model(model_name):
+    """
+    Setup the SentenceTransformer model.
+    
+    Args:
+        model_name (str): Name or path of the SentenceTransformer model
+    """
+    print(f"Setting up language model: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Using device: {device}")
+    
+    model = SentenceTransformer(model_name)
+    return model 

openalex_env_map/lib/python3.10/site-packages/IPython/__init__.py

@@ -0,0 +1,163 @@
+# 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 <[email protected]>
+#  Copyright (c) 2001, Janko Hauser <[email protected]>
+#  Copyright (c) 2001, Nathaniel Gray <[email protected]>
+#
+#  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
+
+#-----------------------------------------------------------------------------
+# Setup everything
+#-----------------------------------------------------------------------------
+
+# Don't forget to also update setup.py when this changes!
+if sys.version_info < (3, 10):
+    raise ImportError(
+        """
+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", "start_kernel", "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.
+
+    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 (see :ref:`kernel_options`).  Will only have an effect
+        on the first embed_kernel call for a given process.
+    """
+    
+    (caller_module, caller_locals) = extract_module_locals(1)
+    if module is None:
+        module = caller_module
+    if local_ns is None:
+        local_ns = 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)
+
+def start_kernel(argv=None, **kwargs):
+    """Launch a normal IPython kernel instance (as opposed to embedded)
+
+    `IPython.embed_kernel()` puts a shell in a particular calling scope,
+    such as a function or method for debugging purposes,
+    which is often not desirable.
+
+    `start_kernel()` does full, regular IPython initialization,
+    including loading startup files, configuration, etc.
+    much of which is skipped by `embed_kernel()`.
+
+    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 kernel (see :ref:`kernel_options`).
+    """
+    import warnings
+
+    warnings.warn(
+        "start_kernel is deprecated since IPython 8.0, use from `ipykernel.kernelapp.launch_new_instance`",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    from ipykernel.kernelapp import launch_new_instance
+    return launch_new_instance(argv=argv, **kwargs)

openalex_env_map/lib/python3.10/site-packages/IPython/__main__.py

@@ -0,0 +1,15 @@
+# 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()

openalex_env_map/lib/python3.10/site-packages/IPython/conftest.py

@@ -0,0 +1,87 @@
+import builtins
+import inspect
+import os
+import pathlib
+import shutil
+import sys
+import types
+
+import pytest
+
+# Must register before it gets imported
+pytest.register_assert_rewrite("IPython.testing.tools")
+
+from .testing import tools
+
+
+def pytest_collection_modifyitems(items):
+    """This function is automatically run by pytest passing all collected test
+    functions.
+
+    We use it to add asyncio marker to all async tests and assert we don't use
+    test functions that are async generators which wouldn't make sense.
+    """
+    for item in items:
+        if inspect.iscoroutinefunction(item.obj):
+            item.add_marker("asyncio")
+        assert not inspect.isasyncgenfunction(item.obj)
+
+
+def get_ipython():
+    from .terminal.interactiveshell import TerminalInteractiveShell
+    if TerminalInteractiveShell._instance:
+        return TerminalInteractiveShell.instance()
+
+    config = tools.default_config()
+    config.TerminalInteractiveShell.simple_prompt = True
+
+    # Create and initialize our test-friendly IPython instance.
+    shell = TerminalInteractiveShell.instance(config=config)
+    return shell
+
+
+@pytest.fixture(scope='session', autouse=True)
+def work_path():
+    path = pathlib.Path("./tmp-ipython-pytest-profiledir")
+    os.environ["IPYTHONDIR"] = str(path.absolute())
+    if path.exists():
+        raise ValueError('IPython dir temporary path already exists ! Did previous test run exit successfully ?')
+    path.mkdir()
+    yield
+    shutil.rmtree(str(path.resolve()))
+
+
+def nopage(strng, start=0, screen_lines=0, pager_cmd=None):
+    if isinstance(strng, dict):
+        strng = strng.get("text/plain", "")
+    print(strng)
+
+
+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()
+
+
+# for things to work correctly we would need this as a session fixture;
+# unfortunately this will fail on some test that get executed as _collection_
+# time (before the fixture run), in particular parametrized test that contain
+# yields. so for now execute at import time.
+#@pytest.fixture(autouse=True, scope='session')
+def inject():
+
+    builtins.get_ipython = get_ipython
+    builtins._ip = get_ipython()
+    builtins.ip = get_ipython()
+    builtins.ip.system = types.MethodType(xsys, ip)
+    builtins.ip.builtin_trap.activate()
+    from .core import page
+
+    page.pager_page = nopage
+    # yield
+
+
+inject()

openalex_env_map/lib/python3.10/site-packages/IPython/consoleapp.py

@@ -0,0 +1,12 @@
+"""
+Shim to maintain backwards compatibility with old IPython.consoleapp imports.
+"""
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+from warnings import warn
+
+warn("The `IPython.consoleapp` package has been deprecated since IPython 4.0."
+     "You should import from jupyter_client.consoleapp instead.", stacklevel=2)
+
+from jupyter_client.consoleapp import *

openalex_env_map/lib/python3.10/site-packages/IPython/core/alias.py

@@ -0,0 +1,267 @@
+# encoding: utf-8
+"""
+System command aliases.
+
+Authors:
+
+* Fernando Perez
+* Brian Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-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
+#-----------------------------------------------------------------------------
+
+import os
+import re
+import sys
+
+from traitlets.config.configurable import Configurable
+from .error import UsageError
+
+from traitlets import List, Instance
+from logging import error
+
+import typing as t
+
+
+#-----------------------------------------------------------------------------
+# Utilities
+#-----------------------------------------------------------------------------
+
+# This is used as the pattern for calls to split_user_input.
+shell_line_split = re.compile(r'^(\s*)()(\S+)(.*$)')
+
+def default_aliases() -> t.List[t.Tuple[str, str]]:
+    """Return list of shell aliases to auto-define.
+    """
+    # Note: the aliases defined here should be safe to use on a kernel
+    # regardless of what frontend it is attached to.  Frontends that use a
+    # kernel in-process can define additional aliases that will only work in
+    # their case.  For example, things like 'less' or 'clear' that manipulate
+    # the terminal should NOT be declared here, as they will only work if the
+    # kernel is running inside a true terminal, and not over the network.
+
+    if os.name == 'posix':
+        default_aliases = [('mkdir', 'mkdir'), ('rmdir', 'rmdir'),
+                           ('mv', 'mv'), ('rm', 'rm'), ('cp', 'cp'),
+                           ('cat', 'cat'),
+                           ]
+        # Useful set of ls aliases.  The GNU and BSD options are a little
+        # different, so we make aliases that provide as similar as possible
+        # behavior in ipython, by passing the right flags for each platform
+        if sys.platform.startswith('linux'):
+            ls_aliases = [('ls', 'ls -F --color'),
+                          # long ls
+                          ('ll', 'ls -F -o --color'),
+                          # ls normal files only
+                          ('lf', 'ls -F -o --color %l | grep ^-'),
+                          # ls symbolic links
+                          ('lk', 'ls -F -o --color %l | grep ^l'),
+                          # directories or links to directories,
+                          ('ldir', 'ls -F -o --color %l | grep /$'),
+                          # things which are executable
+                          ('lx', 'ls -F -o --color %l | grep ^-..x'),
+                          ]
+        elif sys.platform.startswith('openbsd') or sys.platform.startswith('netbsd'):
+            # OpenBSD, NetBSD. The ls implementation on these platforms do not support
+            # the -G switch and lack the ability to use colorized output.
+            ls_aliases = [('ls', 'ls -F'),
+                          # long ls
+                          ('ll', 'ls -F -l'),
+                          # ls normal files only
+                          ('lf', 'ls -F -l %l | grep ^-'),
+                          # ls symbolic links
+                          ('lk', 'ls -F -l %l | grep ^l'),
+                          # directories or links to directories,
+                          ('ldir', 'ls -F -l %l | grep /$'),
+                          # things which are executable
+                          ('lx', 'ls -F -l %l | grep ^-..x'),
+                          ]
+        else:
+            # BSD, OSX, etc.
+            ls_aliases = [('ls', 'ls -F -G'),
+                          # long ls
+                          ('ll', 'ls -F -l -G'),
+                          # ls normal files only
+                          ('lf', 'ls -F -l -G %l | grep ^-'),
+                          # ls symbolic links
+                          ('lk', 'ls -F -l -G %l | grep ^l'),
+                          # directories or links to directories,
+                          ('ldir', 'ls -F -G -l %l | grep /$'),
+                          # things which are executable
+                          ('lx', 'ls -F -l -G %l | grep ^-..x'),
+                          ]
+        default_aliases = default_aliases + ls_aliases
+    elif os.name in ['nt', 'dos']:
+        default_aliases = [('ls', 'dir /on'),
+                           ('ddir', 'dir /ad /on'), ('ldir', 'dir /ad /on'),
+                           ('mkdir', 'mkdir'), ('rmdir', 'rmdir'),
+                           ('echo', 'echo'), ('ren', 'ren'), ('copy', 'copy'),
+                           ]
+    else:
+        default_aliases = []
+
+    return default_aliases
+
+
+class AliasError(Exception):
+    pass
+
+
+class InvalidAliasError(AliasError):
+    pass
+
+class Alias(object):
+    """Callable object storing the details of one alias.
+
+    Instances are registered as magic functions to allow use of aliases.
+    """
+
+    # Prepare blacklist
+    blacklist = {'cd','popd','pushd','dhist','alias','unalias'}
+
+    def __init__(self, shell, name, cmd):
+        self.shell = shell
+        self.name = name
+        self.cmd = cmd
+        self.__doc__ = "Alias for `!{}`".format(cmd)
+        self.nargs = self.validate()
+
+    def validate(self):
+        """Validate the alias, and return the number of arguments."""
+        if self.name in self.blacklist:
+            raise InvalidAliasError("The name %s can't be aliased "
+                                    "because it is a keyword or builtin." % self.name)
+        try:
+            caller = self.shell.magics_manager.magics['line'][self.name]
+        except KeyError:
+            pass
+        else:
+            if not isinstance(caller, Alias):
+                raise InvalidAliasError("The name %s can't be aliased "
+                                        "because it is another magic command." % self.name)
+
+        if not (isinstance(self.cmd, str)):
+            raise InvalidAliasError("An alias command must be a string, "
+                                    "got: %r" % self.cmd)
+
+        nargs = self.cmd.count('%s') - self.cmd.count('%%s')
+  
+        if (nargs > 0) and (self.cmd.find('%l') >= 0):
+            raise InvalidAliasError('The %s and %l specifiers are mutually '
+                                    'exclusive in alias definitions.')
+
+        return nargs
+
+    def __repr__(self):
+        return "<alias {} for {!r}>".format(self.name, self.cmd)
+
+    def __call__(self, rest=''):
+        cmd = self.cmd
+        nargs = self.nargs
+        # Expand the %l special to be the user's input line
+        if cmd.find('%l') >= 0:
+            cmd = cmd.replace('%l', rest)
+            rest = ''
+        
+        if nargs==0:
+            if cmd.find('%%s') >= 1:
+                cmd = cmd.replace('%%s', '%s')
+            # Simple, argument-less aliases
+            cmd = '%s %s' % (cmd, rest)
+        else:
+            # Handle aliases with positional arguments
+            args = rest.split(None, nargs)
+            if len(args) < nargs:
+                raise UsageError('Alias <%s> requires %s arguments, %s given.' %
+                      (self.name, nargs, len(args)))
+            cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
+
+        self.shell.system(cmd)
+
+#-----------------------------------------------------------------------------
+# Main AliasManager class
+#-----------------------------------------------------------------------------
+
+class AliasManager(Configurable):
+    default_aliases: List = List(default_aliases()).tag(config=True)
+    user_aliases: List = List(default_value=[]).tag(config=True)
+    shell = Instance(
+        "IPython.core.interactiveshell.InteractiveShellABC", allow_none=True
+    )
+
+    def __init__(self, shell=None, **kwargs):
+        super(AliasManager, self).__init__(shell=shell, **kwargs)
+        # For convenient access
+        if self.shell is not None:
+            self.linemagics = self.shell.magics_manager.magics["line"]
+            self.init_aliases()
+
+    def init_aliases(self):
+        # Load default & user aliases
+        for name, cmd in self.default_aliases + self.user_aliases:
+            if (
+                cmd.startswith("ls ")
+                and self.shell is not None
+                and self.shell.colors == "NoColor"
+            ):
+                cmd = cmd.replace(" --color", "")
+            self.soft_define_alias(name, cmd)
+
+    @property
+    def aliases(self):
+        return [(n, func.cmd) for (n, func) in self.linemagics.items()
+                            if isinstance(func, Alias)]
+
+    def soft_define_alias(self, name, cmd):
+        """Define an alias, but don't raise on an AliasError."""
+        try:
+            self.define_alias(name, cmd)
+        except AliasError as e:
+            error("Invalid alias: %s" % e)
+
+    def define_alias(self, name, cmd):
+        """Define a new alias after validating it.
+
+        This will raise an :exc:`AliasError` if there are validation
+        problems.
+        """
+        caller = Alias(shell=self.shell, name=name, cmd=cmd)
+        self.shell.magics_manager.register_function(caller, magic_kind='line',
+                                                    magic_name=name)
+
+    def get_alias(self, name):
+        """Return an alias, or None if no alias by that name exists."""
+        aname = self.linemagics.get(name, None)
+        return aname if isinstance(aname, Alias) else None
+
+    def is_alias(self, name):
+        """Return whether or not a given name has been defined as an alias"""
+        return self.get_alias(name) is not None
+
+    def undefine_alias(self, name):
+        if self.is_alias(name):
+            del self.linemagics[name]
+        else:
+            raise ValueError('%s is not an alias' % name)
+
+    def clear_aliases(self):
+        for name, _ in self.aliases:
+            self.undefine_alias(name)
+
+    def retrieve_alias(self, name):
+        """Retrieve the command to which an alias expands."""
+        caller = self.get_alias(name)
+        if caller:
+            return caller.cmd
+        else:
+            raise ValueError('%s is not an alias' % name)

openalex_env_map/lib/python3.10/site-packages/IPython/core/application.py

@@ -0,0 +1,492 @@
+# encoding: utf-8
+"""
+An application for IPython.
+
+All top-level applications should use the classes in this module for
+handling configuration and creating configurables.
+
+The job of an :class:`Application` is to create the master configuration
+object and then create the configurable objects, passing the config to them.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import atexit
+from copy import deepcopy
+import logging
+import os
+import shutil
+import sys
+
+from pathlib import Path
+
+from traitlets.config.application import Application, catch_config_error
+from traitlets.config.loader import ConfigFileNotFound, PyFileConfigLoader
+from IPython.core import release, crashhandler
+from IPython.core.profiledir import ProfileDir, ProfileDirError
+from IPython.paths import get_ipython_dir, get_ipython_package_dir
+from IPython.utils.path import ensure_dir_exists
+from traitlets import (
+    List, Unicode, Type, Bool, Set, Instance, Undefined,
+    default, observe,
+)
+
+if os.name == "nt":
+    programdata = os.environ.get("PROGRAMDATA", None)
+    if programdata is not None:
+        SYSTEM_CONFIG_DIRS = [str(Path(programdata) / "ipython")]
+    else:  # PROGRAMDATA is not defined by default on XP.
+        SYSTEM_CONFIG_DIRS = []
+else:
+    SYSTEM_CONFIG_DIRS = [
+        "/usr/local/etc/ipython",
+        "/etc/ipython",
+    ]
+
+
+ENV_CONFIG_DIRS = []
+_env_config_dir = os.path.join(sys.prefix, 'etc', 'ipython')
+if _env_config_dir not in SYSTEM_CONFIG_DIRS:
+    # only add ENV_CONFIG if sys.prefix is not already included
+    ENV_CONFIG_DIRS.append(_env_config_dir)
+
+
+_envvar = os.environ.get('IPYTHON_SUPPRESS_CONFIG_ERRORS')
+if _envvar in {None, ''}:
+    IPYTHON_SUPPRESS_CONFIG_ERRORS = None
+else:
+    if _envvar.lower() in {'1','true'}:
+        IPYTHON_SUPPRESS_CONFIG_ERRORS = True
+    elif _envvar.lower() in {'0','false'} :
+        IPYTHON_SUPPRESS_CONFIG_ERRORS = False
+    else:
+        sys.exit("Unsupported value for environment variable: 'IPYTHON_SUPPRESS_CONFIG_ERRORS' is set to '%s' which is none of  {'0', '1', 'false', 'true', ''}."% _envvar )
+
+# aliases and flags
+
+base_aliases = {}
+if isinstance(Application.aliases, dict):
+    # traitlets 5
+    base_aliases.update(Application.aliases)
+base_aliases.update(
+    {
+        "profile-dir": "ProfileDir.location",
+        "profile": "BaseIPythonApplication.profile",
+        "ipython-dir": "BaseIPythonApplication.ipython_dir",
+        "log-level": "Application.log_level",
+        "config": "BaseIPythonApplication.extra_config_file",
+    }
+)
+
+base_flags = dict()
+if isinstance(Application.flags, dict):
+    # traitlets 5
+    base_flags.update(Application.flags)
+base_flags.update(
+    dict(
+        debug=(
+            {"Application": {"log_level": logging.DEBUG}},
+            "set log level to logging.DEBUG (maximize logging output)",
+        ),
+        quiet=(
+            {"Application": {"log_level": logging.CRITICAL}},
+            "set log level to logging.CRITICAL (minimize logging output)",
+        ),
+        init=(
+            {
+                "BaseIPythonApplication": {
+                    "copy_config_files": True,
+                    "auto_create": True,
+                }
+            },
+            """Initialize profile with default config files.  This is equivalent
+            to running `ipython profile create <profile>` prior to startup.
+            """,
+        ),
+    )
+)
+
+
+class ProfileAwareConfigLoader(PyFileConfigLoader):
+    """A Python file config loader that is aware of IPython profiles."""
+    def load_subconfig(self, fname, path=None, profile=None):
+        if profile is not None:
+            try:
+                profile_dir = ProfileDir.find_profile_dir_by_name(
+                        get_ipython_dir(),
+                        profile,
+                )
+            except ProfileDirError:
+                return
+            path = profile_dir.location
+        return super(ProfileAwareConfigLoader, self).load_subconfig(fname, path=path)
+
+class BaseIPythonApplication(Application):
+    name = "ipython"
+    description = "IPython: an enhanced interactive Python shell."
+    version = Unicode(release.version)
+
+    aliases = base_aliases
+    flags = base_flags
+    classes = List([ProfileDir])
+    
+    # enable `load_subconfig('cfg.py', profile='name')`
+    python_config_loader_class = ProfileAwareConfigLoader
+
+    # Track whether the config_file has changed,
+    # because some logic happens only if we aren't using the default.
+    config_file_specified = Set()
+
+    config_file_name = Unicode()
+    @default('config_file_name')
+    def _config_file_name_default(self):
+        return self.name.replace('-','_') + u'_config.py'
+    @observe('config_file_name')
+    def _config_file_name_changed(self, change):
+        if change['new'] != change['old']:
+            self.config_file_specified.add(change['new'])
+
+    # The directory that contains IPython's builtin profiles.
+    builtin_profile_dir = Unicode(
+        os.path.join(get_ipython_package_dir(), u'config', u'profile', u'default')
+    )
+    
+    config_file_paths = List(Unicode())
+    @default('config_file_paths')
+    def _config_file_paths_default(self):
+        return []
+
+    extra_config_file = Unicode(
+    help="""Path to an extra config file to load.
+    
+    If specified, load this config file in addition to any other IPython config.
+    """).tag(config=True)
+    @observe('extra_config_file')
+    def _extra_config_file_changed(self, change):
+        old = change['old']
+        new = change['new']
+        try:
+            self.config_files.remove(old)
+        except ValueError:
+            pass
+        self.config_file_specified.add(new)
+        self.config_files.append(new)
+
+    profile = Unicode(u'default',
+        help="""The IPython profile to use."""
+    ).tag(config=True)
+    
+    @observe('profile')
+    def _profile_changed(self, change):
+        self.builtin_profile_dir = os.path.join(
+                get_ipython_package_dir(), u'config', u'profile', change['new']
+        )
+
+    add_ipython_dir_to_sys_path = Bool(
+        False,
+        """Should the IPython profile directory be added to sys path ?
+
+        This option was non-existing before IPython 8.0, and ipython_dir was added to
+        sys path to allow import of extensions present there. This was historical
+        baggage from when pip did not exist. This now default to false,
+        but can be set to true for legacy reasons.
+        """,
+    ).tag(config=True)
+
+    ipython_dir = Unicode(
+        help="""
+        The name of the IPython directory. This directory is used for logging
+        configuration (through profiles), history storage, etc. The default
+        is usually $HOME/.ipython. This option can also be specified through
+        the environment variable IPYTHONDIR.
+        """
+    ).tag(config=True)
+    @default('ipython_dir')
+    def _ipython_dir_default(self):
+        d = get_ipython_dir()
+        self._ipython_dir_changed({
+            'name': 'ipython_dir',
+            'old': d,
+            'new': d,
+        })
+        return d
+    
+    _in_init_profile_dir = False
+
+    profile_dir = Instance(ProfileDir, allow_none=True)
+
+    @default('profile_dir')
+    def _profile_dir_default(self):
+        # avoid recursion
+        if self._in_init_profile_dir:
+            return
+        # profile_dir requested early, force initialization
+        self.init_profile_dir()
+        return self.profile_dir
+
+    overwrite = Bool(False,
+        help="""Whether to overwrite existing config files when copying"""
+    ).tag(config=True)
+
+    auto_create = Bool(False,
+        help="""Whether to create profile dir if it doesn't exist"""
+    ).tag(config=True)
+
+    config_files = List(Unicode())
+
+    @default('config_files')
+    def _config_files_default(self):
+        return [self.config_file_name]
+
+    copy_config_files = Bool(False,
+        help="""Whether to install the default config files into the profile dir.
+        If a new profile is being created, and IPython contains config files for that
+        profile, then they will be staged into the new directory.  Otherwise,
+        default config files will be automatically generated.
+        """).tag(config=True)
+    
+    verbose_crash = Bool(False,
+        help="""Create a massive crash report when IPython encounters what may be an
+        internal error.  The default is to append a short message to the
+        usual traceback""").tag(config=True)
+
+    # The class to use as the crash handler.
+    crash_handler_class = Type(crashhandler.CrashHandler)
+
+    @catch_config_error
+    def __init__(self, **kwargs):
+        super(BaseIPythonApplication, self).__init__(**kwargs)
+        # ensure current working directory exists
+        try:
+            os.getcwd()
+        except:
+            # exit if cwd doesn't exist
+            self.log.error("Current working directory doesn't exist.")
+            self.exit(1)
+
+    #-------------------------------------------------------------------------
+    # Various stages of Application creation
+    #-------------------------------------------------------------------------
+    
+    def init_crash_handler(self):
+        """Create a crash handler, typically setting sys.excepthook to it."""
+        self.crash_handler = self.crash_handler_class(self)
+        sys.excepthook = self.excepthook
+        def unset_crashhandler():
+            sys.excepthook = sys.__excepthook__
+        atexit.register(unset_crashhandler)
+    
+    def excepthook(self, etype, evalue, tb):
+        """this is sys.excepthook after init_crashhandler
+
+        set self.verbose_crash=True to use our full crashhandler, instead of
+        a regular traceback with a short message (crash_handler_lite)
+        """
+        
+        if self.verbose_crash:
+            return self.crash_handler(etype, evalue, tb)
+        else:
+            return crashhandler.crash_handler_lite(etype, evalue, tb)
+
+    @observe('ipython_dir')
+    def _ipython_dir_changed(self, change):
+        old = change['old']
+        new = change['new']
+        if old is not Undefined:
+            str_old = os.path.abspath(old)
+            if str_old in sys.path:
+                sys.path.remove(str_old)
+        if self.add_ipython_dir_to_sys_path:
+            str_path = os.path.abspath(new)
+            sys.path.append(str_path)
+            ensure_dir_exists(new)
+            readme = os.path.join(new, "README")
+            readme_src = os.path.join(
+                get_ipython_package_dir(), "config", "profile", "README"
+            )
+            if not os.path.exists(readme) and os.path.exists(readme_src):
+                shutil.copy(readme_src, readme)
+            for d in ("extensions", "nbextensions"):
+                path = os.path.join(new, d)
+                try:
+                    ensure_dir_exists(path)
+                except OSError as e:
+                    # this will not be EEXIST
+                    self.log.error("couldn't create path %s: %s", path, e)
+            self.log.debug("IPYTHONDIR set to: %s", new)
+
+    def load_config_file(self, suppress_errors=IPYTHON_SUPPRESS_CONFIG_ERRORS):
+        """Load the config file.
+
+        By default, errors in loading config are handled, and a warning
+        printed on screen. For testing, the suppress_errors option is set
+        to False, so errors will make tests fail.
+
+        `suppress_errors` default value is to be `None` in which case the
+        behavior default to the one of `traitlets.Application`.
+
+        The default value can be set :
+           - to `False` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '0', or 'false' (case insensitive).
+           - to `True` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '1' or 'true' (case insensitive).
+           - to `None` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '' (empty string) or leaving it unset.
+
+        Any other value are invalid, and will make IPython exit with a non-zero return code.
+        """
+
+
+        self.log.debug("Searching path %s for config files", self.config_file_paths)
+        base_config = 'ipython_config.py'
+        self.log.debug("Attempting to load config file: %s" %
+                       base_config)
+        try:
+            if suppress_errors is not None:
+                old_value = Application.raise_config_file_errors
+                Application.raise_config_file_errors = not suppress_errors;
+            Application.load_config_file(
+                self,
+                base_config,
+                path=self.config_file_paths
+            )
+        except ConfigFileNotFound:
+            # ignore errors loading parent
+            self.log.debug("Config file %s not found", base_config)
+            pass
+        if suppress_errors is not None:
+            Application.raise_config_file_errors = old_value
+        
+        for config_file_name in self.config_files:
+            if not config_file_name or config_file_name == base_config:
+                continue
+            self.log.debug("Attempting to load config file: %s" %
+                           self.config_file_name)
+            try:
+                Application.load_config_file(
+                    self,
+                    config_file_name,
+                    path=self.config_file_paths
+                )
+            except ConfigFileNotFound:
+                # Only warn if the default config file was NOT being used.
+                if config_file_name in self.config_file_specified:
+                    msg = self.log.warning
+                else:
+                    msg = self.log.debug
+                msg("Config file not found, skipping: %s", config_file_name)
+            except Exception:
+                # For testing purposes.
+                if not suppress_errors:
+                    raise
+                self.log.warning("Error loading config file: %s" %
+                              self.config_file_name, exc_info=True)
+
+    def init_profile_dir(self):
+        """initialize the profile dir"""
+        self._in_init_profile_dir = True
+        if self.profile_dir is not None:
+            # already ran
+            return
+        if 'ProfileDir.location' not in self.config:
+            # location not specified, find by profile name
+            try:
+                p = ProfileDir.find_profile_dir_by_name(self.ipython_dir, self.profile, self.config)
+            except ProfileDirError:
+                # not found, maybe create it (always create default profile)
+                if self.auto_create or self.profile == 'default':
+                    try:
+                        p = ProfileDir.create_profile_dir_by_name(self.ipython_dir, self.profile, self.config)
+                    except ProfileDirError:
+                        self.log.fatal("Could not create profile: %r"%self.profile)
+                        self.exit(1)
+                    else:
+                        self.log.info("Created profile dir: %r"%p.location)
+                else:
+                    self.log.fatal("Profile %r not found."%self.profile)
+                    self.exit(1)
+            else:
+                self.log.debug("Using existing profile dir: %r", p.location)
+        else:
+            location = self.config.ProfileDir.location
+            # location is fully specified
+            try:
+                p = ProfileDir.find_profile_dir(location, self.config)
+            except ProfileDirError:
+                # not found, maybe create it
+                if self.auto_create:
+                    try:
+                        p = ProfileDir.create_profile_dir(location, self.config)
+                    except ProfileDirError:
+                        self.log.fatal("Could not create profile directory: %r"%location)
+                        self.exit(1)
+                    else:
+                        self.log.debug("Creating new profile dir: %r"%location)
+                else:
+                    self.log.fatal("Profile directory %r not found."%location)
+                    self.exit(1)
+            else:
+                self.log.debug("Using existing profile dir: %r", p.location)
+            # if profile_dir is specified explicitly, set profile name
+            dir_name = os.path.basename(p.location)
+            if dir_name.startswith('profile_'):
+                self.profile = dir_name[8:]
+
+        self.profile_dir = p
+        self.config_file_paths.append(p.location)
+        self._in_init_profile_dir = False
+
+    def init_config_files(self):
+        """[optionally] copy default config files into profile dir."""
+        self.config_file_paths.extend(ENV_CONFIG_DIRS)
+        self.config_file_paths.extend(SYSTEM_CONFIG_DIRS)
+        # copy config files
+        path = Path(self.builtin_profile_dir)
+        if self.copy_config_files:
+            src = self.profile
+
+            cfg = self.config_file_name
+            if path and (path / cfg).exists():
+                self.log.warning(
+                    "Staging %r from %s into %r [overwrite=%s]"
+                    % (cfg, src, self.profile_dir.location, self.overwrite)
+                )
+                self.profile_dir.copy_config_file(cfg, path=path, overwrite=self.overwrite)
+            else:
+                self.stage_default_config_file()
+        else:
+            # Still stage *bundled* config files, but not generated ones
+            # This is necessary for `ipython profile=sympy` to load the profile
+            # on the first go
+            files = path.glob("*.py")
+            for fullpath in files:
+                cfg = fullpath.name
+                if self.profile_dir.copy_config_file(cfg, path=path, overwrite=False):
+                    # file was copied
+                    self.log.warning("Staging bundled %s from %s into %r"%(
+                            cfg, self.profile, self.profile_dir.location)
+                    )
+
+
+    def stage_default_config_file(self):
+        """auto generate default config file, and stage it into the profile."""
+        s = self.generate_config_file()
+        config_file = Path(self.profile_dir.location) / self.config_file_name
+        if self.overwrite or not config_file.exists():
+            self.log.warning("Generating default config file: %r", (config_file))
+            config_file.write_text(s, encoding="utf-8")
+
+    @catch_config_error
+    def initialize(self, argv=None):
+        # don't hook up crash handler before parsing command-line
+        self.parse_command_line(argv)
+        self.init_crash_handler()
+        if self.subapp is not None:
+            # stop here if subapp is taking over
+            return
+        # save a copy of CLI config to re-load after config files
+        # so that it has highest priority
+        cl_config = deepcopy(self.config)
+        self.init_profile_dir()
+        self.init_config_files()
+        self.load_config_file()
+        # enforce cl-opts override configfile opts:
+        self.update_config(cl_config)

openalex_env_map/lib/python3.10/site-packages/IPython/core/async_helpers.py

@@ -0,0 +1,155 @@
+"""
+Async helper function that are invalid syntax on Python 3.5 and below.
+
+This code is best effort, and may have edge cases not behaving as expected. In
+particular it contain a number of heuristics to detect whether code is
+effectively async and need to run in an event loop or not.
+
+Some constructs (like top-level `return`, or `yield`) are taken care of
+explicitly to actually raise a SyntaxError and stay as close as possible to
+Python semantics.
+"""
+
+import ast
+import asyncio
+import inspect
+from functools import wraps
+
+_asyncio_event_loop = None
+
+
+def get_asyncio_loop():
+    """asyncio has deprecated get_event_loop
+
+    Replicate it here, with our desired semantics:
+
+    - always returns a valid, not-closed loop
+    - not thread-local like asyncio's,
+      because we only want one loop for IPython
+    - if called from inside a coroutine (e.g. in ipykernel),
+      return the running loop
+
+    .. versionadded:: 8.0
+    """
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        # not inside a coroutine,
+        # track our own global
+        pass
+
+    # not thread-local like asyncio's,
+    # because we only track one event loop to run for IPython itself,
+    # always in the main thread.
+    global _asyncio_event_loop
+    if _asyncio_event_loop is None or _asyncio_event_loop.is_closed():
+        _asyncio_event_loop = asyncio.new_event_loop()
+    return _asyncio_event_loop
+
+
+class _AsyncIORunner:
+    def __call__(self, coro):
+        """
+        Handler for asyncio autoawait
+        """
+        return get_asyncio_loop().run_until_complete(coro)
+
+    def __str__(self):
+        return "asyncio"
+
+
+_asyncio_runner = _AsyncIORunner()
+
+
+class _AsyncIOProxy:
+    """Proxy-object for an asyncio
+
+    Any coroutine methods will be wrapped in event_loop.run_
+    """
+
+    def __init__(self, obj, event_loop):
+        self._obj = obj
+        self._event_loop = event_loop
+
+    def __repr__(self):
+        return f"<_AsyncIOProxy({self._obj!r})>"
+
+    def __getattr__(self, key):
+        attr = getattr(self._obj, key)
+        if inspect.iscoroutinefunction(attr):
+            # if it's a coroutine method,
+            # return a threadsafe wrapper onto the _current_ asyncio loop
+            @wraps(attr)
+            def _wrapped(*args, **kwargs):
+                concurrent_future = asyncio.run_coroutine_threadsafe(
+                    attr(*args, **kwargs), self._event_loop
+                )
+                return asyncio.wrap_future(concurrent_future)
+
+            return _wrapped
+        else:
+            return attr
+
+    def __dir__(self):
+        return dir(self._obj)
+
+
+def _curio_runner(coroutine):
+    """
+    handler for curio autoawait
+    """
+    import curio
+
+    return curio.run(coroutine)
+
+
+def _trio_runner(async_fn):
+    import trio
+
+    async def loc(coro):
+        """
+        We need the dummy no-op async def to protect from
+        trio's internal. See https://github.com/python-trio/trio/issues/89
+        """
+        return await coro
+
+    return trio.run(loc, async_fn)
+
+
+def _pseudo_sync_runner(coro):
+    """
+    A runner that does not really allow async execution, and just advance the coroutine.
+
+    See discussion in https://github.com/python-trio/trio/issues/608,
+
+    Credit to Nathaniel Smith
+    """
+    try:
+        coro.send(None)
+    except StopIteration as exc:
+        return exc.value
+    else:
+        # TODO: do not raise but return an execution result with the right info.
+        raise RuntimeError(
+            "{coro_name!r} needs a real async loop".format(coro_name=coro.__name__)
+        )
+
+
+def _should_be_async(cell: str) -> bool:
+    """Detect if a block of code need to be wrapped in an `async def`
+
+    Attempt to parse the block of code, it it compile we're fine.
+    Otherwise we  wrap if and try to compile.
+
+    If it works, assume it should be async. Otherwise Return False.
+
+    Not handled yet: If the block of code has a return statement as the top
+    level, it will be seen as async. This is a know limitation.
+    """
+    try:
+        code = compile(
+            cell, "<>", "exec", flags=getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
+        )
+        return inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
+    except (SyntaxError, MemoryError):
+        return False

openalex_env_map/lib/python3.10/site-packages/IPython/core/autocall.py

@@ -0,0 +1,70 @@
+# encoding: utf-8
+"""
+Autocall capabilities for IPython.core.
+
+Authors:
+
+* Brian Granger
+* Fernando Perez
+* Thomas Kluyver
+
+Notes
+-----
+"""
+
+#-----------------------------------------------------------------------------
+#  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
+#-----------------------------------------------------------------------------
+
+
+#-----------------------------------------------------------------------------
+# Code
+#-----------------------------------------------------------------------------
+
+class IPyAutocall(object):
+    """ Instances of this class are always autocalled
+    
+    This happens regardless of 'autocall' variable state. Use this to
+    develop macro-like mechanisms.
+    """
+    _ip = None
+    rewrite = True
+    def __init__(self, ip=None):
+        self._ip = ip
+    
+    def set_ip(self, ip):
+        """Will be used to set _ip point to current ipython instance b/f call
+
+        Override this method if you don't want this to happen.
+
+        """
+        self._ip = ip
+
+
+class ExitAutocall(IPyAutocall):
+    """An autocallable object which will be added to the user namespace so that
+    exit, exit(), quit or quit() are all valid ways to close the shell."""
+    rewrite = False
+    
+    def __call__(self):
+        self._ip.ask_exit()
+        
+class ZMQExitAutocall(ExitAutocall):
+    """Exit IPython. Autocallable, so it needn't be explicitly called.
+    
+    Parameters
+    ----------
+    keep_kernel : bool
+      If True, leave the kernel alive. Otherwise, tell the kernel to exit too
+      (default).
+    """
+    def __call__(self, keep_kernel=False):
+        self._ip.keepkernel_on_exit = keep_kernel
+        self._ip.ask_exit()

openalex_env_map/lib/python3.10/site-packages/IPython/core/builtin_trap.py

@@ -0,0 +1,86 @@
+"""
+A context manager for managing things injected into :mod:`builtins`.
+"""
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+import builtins as builtin_mod
+
+from traitlets.config.configurable import Configurable
+
+from traitlets import Instance
+
+
+class __BuiltinUndefined(object): pass
+BuiltinUndefined = __BuiltinUndefined()
+
+class __HideBuiltin(object): pass
+HideBuiltin = __HideBuiltin()
+
+
+class BuiltinTrap(Configurable):
+
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC',
+                     allow_none=True)
+
+    def __init__(self, shell=None):
+        super(BuiltinTrap, self).__init__(shell=shell, config=None)
+        self._orig_builtins = {}
+        # We define this to track if a single BuiltinTrap is nested.
+        # Only turn off the trap when the outermost call to __exit__ is made.
+        self._nested_level = 0
+        self.shell = shell
+        # builtins we always add - if set to HideBuiltin, they will just
+        # be removed instead of being replaced by something else
+        self.auto_builtins = {'exit': HideBuiltin,
+                              'quit': HideBuiltin,
+                              'get_ipython': self.shell.get_ipython,
+                              }
+
+    def __enter__(self):
+        if self._nested_level == 0:
+            self.activate()
+        self._nested_level += 1
+        # I return self, so callers can use add_builtin in a with clause.
+        return self
+
+    def __exit__(self, type, value, traceback):
+        if self._nested_level == 1:
+            self.deactivate()
+        self._nested_level -= 1
+        # Returning False will cause exceptions to propagate
+        return False
+
+    def add_builtin(self, key, value):
+        """Add a builtin and save the original."""
+        bdict = builtin_mod.__dict__
+        orig = bdict.get(key, BuiltinUndefined)
+        if value is HideBuiltin:
+            if orig is not BuiltinUndefined: #same as 'key in bdict'
+                self._orig_builtins[key] = orig
+                del bdict[key]
+        else:
+            self._orig_builtins[key] = orig
+            bdict[key] = value
+
+    def remove_builtin(self, key, orig):
+        """Remove an added builtin and re-set the original."""
+        if orig is BuiltinUndefined:
+            del builtin_mod.__dict__[key]
+        else:
+            builtin_mod.__dict__[key] = orig
+
+    def activate(self):
+        """Store ipython references in the __builtin__ namespace."""
+
+        add_builtin = self.add_builtin
+        for name, func in self.auto_builtins.items():
+            add_builtin(name, func)
+
+    def deactivate(self):
+        """Remove any builtins which might have been added by add_builtins, or
+        restore overwritten ones to their previous values."""
+        remove_builtin = self.remove_builtin
+        for key, val in self._orig_builtins.items():
+            remove_builtin(key, val)
+        self._orig_builtins.clear()
+        self._builtins_added = False

openalex_env_map/lib/python3.10/site-packages/IPython/core/compilerop.py

@@ -0,0 +1,214 @@
+"""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
+
+
+def check_linecache_ipython(*args):
+    """Deprecated since IPython 8.6.  Call linecache.checkcache() directly.
+
+    It was already not necessary to call this function directly.  If no
+    CachingCompiler had been created, this function would fail badly.  If
+    an instance had been created, this function would've been monkeypatched
+    into place.
+
+    As of IPython 8.6, the monkeypatching has gone away entirely.  But there
+    were still internal callers of this function, so maybe external callers
+    also existed?
+    """
+    import warnings
+
+    warnings.warn(
+        "Deprecated Since IPython 8.6, Just call linecache.checkcache() directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    linecache.checkcache()

openalex_env_map/lib/python3.10/site-packages/IPython/core/completerlib.py

@@ -0,0 +1,382 @@
+# encoding: utf-8
+"""Implementations for various useful completers.
+
+These are all loaded by default by IPython.
+"""
+#-----------------------------------------------------------------------------
+#  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 glob
+import inspect
+import os
+import re
+import sys
+from importlib import import_module
+from importlib.machinery import all_suffixes
+
+
+# Third-party imports
+from time import time
+from zipimport import zipimporter
+
+# Our own imports
+from .completer import expand_user, compress_user
+from .error import TryNext
+from ..utils._process_common import arg_split
+
+# FIXME: this should be pulled in with the right call via the component system
+from IPython import get_ipython
+
+from typing import List
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+_suffixes = all_suffixes()
+
+# Time in seconds after which the rootmodules will be stored permanently in the
+# ipython ip.db database (kept in the user's .ipython dir).
+TIMEOUT_STORAGE = 2
+
+# Time in seconds after which we give up
+TIMEOUT_GIVEUP = 20
+
+# Regular expression for the python import statement
+import_re = re.compile(r'(?P<name>[^\W\d]\w*?)'
+                       r'(?P<package>[/\\]__init__)?'
+                       r'(?P<suffix>%s)$' %
+                       r'|'.join(re.escape(s) for s in _suffixes))
+
+# RE for the ipython %run command (python + ipython scripts)
+magic_run_re = re.compile(r'.*(\.ipy|\.ipynb|\.py[w]?)$')
+
+#-----------------------------------------------------------------------------
+# Local utilities
+#-----------------------------------------------------------------------------
+
+
+def module_list(path: str) -> List[str]:
+    """
+    Return the list containing the names of the modules available in the given
+    folder.
+    """
+    # sys.path has the cwd as an empty string, but isdir/listdir need it as '.'
+    if path == '':
+        path = '.'
+
+    # A few local constants to be used in loops below
+    pjoin = os.path.join
+
+    if os.path.isdir(path):
+        # Build a list of all files in the directory and all files
+        # in its subdirectories. For performance reasons, do not
+        # recurse more than one level into subdirectories.
+        files: List[str] = []
+        for root, dirs, nondirs in os.walk(path, followlinks=True):
+            subdir = root[len(path)+1:]
+            if subdir:
+                files.extend(pjoin(subdir, f) for f in nondirs)
+                dirs[:] = [] # Do not recurse into additional subdirectories.
+            else:
+                files.extend(nondirs)
+
+    else:
+        try:
+            files = list(zipimporter(path)._files.keys())  # type: ignore
+        except Exception:
+            files = []
+
+    # Build a list of modules which match the import_re regex.
+    modules = []
+    for f in files:
+        m = import_re.match(f)
+        if m:
+            modules.append(m.group('name'))
+    return list(set(modules))
+
+
+def get_root_modules():
+    """
+    Returns a list containing the names of all the modules available in the
+    folders of the pythonpath.
+
+    ip.db['rootmodules_cache'] maps sys.path entries to list of modules.
+    """
+    ip = get_ipython()
+    if ip is None:
+        # No global shell instance to store cached list of modules.
+        # Don't try to scan for modules every time.
+        return list(sys.builtin_module_names)
+
+    if getattr(ip.db, "_mock", False):
+        rootmodules_cache = {}
+    else:
+        rootmodules_cache = ip.db.get("rootmodules_cache", {})
+    rootmodules = list(sys.builtin_module_names)
+    start_time = time()
+    store = False
+    for path in sys.path:
+        try:
+            modules = rootmodules_cache[path]
+        except KeyError:
+            modules = module_list(path)
+            try:
+                modules.remove('__init__')
+            except ValueError:
+                pass
+            if path not in ('', '.'): # cwd modules should not be cached
+                rootmodules_cache[path] = modules
+            if time() - start_time > TIMEOUT_STORAGE and not store:
+                store = True
+                print("\nCaching the list of root modules, please wait!")
+                print("(This will only be done once - type '%rehashx' to "
+                      "reset cache!)\n")
+                sys.stdout.flush()
+            if time() - start_time > TIMEOUT_GIVEUP:
+                print("This is taking too long, we give up.\n")
+                return []
+        rootmodules.extend(modules)
+    if store:
+        ip.db['rootmodules_cache'] = rootmodules_cache
+    rootmodules = list(set(rootmodules))
+    return rootmodules
+
+
+def is_importable(module, attr: str, only_modules) -> bool:
+    if only_modules:
+        try:
+            mod = getattr(module, attr)
+        except ModuleNotFoundError:
+            # See gh-14434
+            return False
+        return inspect.ismodule(mod)
+    else:
+        return not(attr[:2] == '__' and attr[-2:] == '__')
+
+def is_possible_submodule(module, attr):
+    try:
+        obj = getattr(module, attr)
+    except AttributeError:
+        # Is possibly an unimported submodule
+        return True
+    except TypeError:
+        # https://github.com/ipython/ipython/issues/9678
+        return False
+    return inspect.ismodule(obj)
+
+
+def try_import(mod: str, only_modules=False) -> List[str]:
+    """
+    Try to import given module and return list of potential completions.
+    """
+    mod = mod.rstrip('.')
+    try:
+        m = import_module(mod)
+    except:
+        return []
+
+    m_is_init = '__init__' in (getattr(m, '__file__', '') or '')
+
+    completions = []
+    if (not hasattr(m, '__file__')) or (not only_modules) or m_is_init:
+        completions.extend( [attr for attr in dir(m) if
+                             is_importable(m, attr, only_modules)])
+
+    m_all = getattr(m, "__all__", [])
+    if only_modules:
+        completions.extend(attr for attr in m_all if is_possible_submodule(m, attr))
+    else:
+        completions.extend(m_all)
+
+    if m_is_init:
+        file_ = m.__file__
+        file_path = os.path.dirname(file_)  # type: ignore
+        if file_path is not None:
+            completions.extend(module_list(file_path))
+    completions_set = {c for c in completions if isinstance(c, str)}
+    completions_set.discard('__init__')
+    return list(completions_set)
+
+
+#-----------------------------------------------------------------------------
+# Completion-related functions.
+#-----------------------------------------------------------------------------
+
+def quick_completer(cmd, completions):
+    r""" Easily create a trivial completer for a command.
+
+    Takes either a list of completions, or all completions in string (that will
+    be split on whitespace).
+
+    Example::
+
+        [d:\ipython]|1> import ipy_completers
+        [d:\ipython]|2> ipy_completers.quick_completer('foo', ['bar','baz'])
+        [d:\ipython]|3> foo b<TAB>
+        bar baz
+        [d:\ipython]|3> foo ba
+    """
+
+    if isinstance(completions, str):
+        completions = completions.split()
+
+    def do_complete(self, event):
+        return completions
+
+    get_ipython().set_hook('complete_command',do_complete, str_key = cmd)
+
+def module_completion(line):
+    """
+    Returns a list containing the completion possibilities for an import line.
+
+    The line looks like this :
+    'import xml.d'
+    'from xml.dom import'
+    """
+
+    words = line.split(' ')
+    nwords = len(words)
+
+    # from whatever <tab> -> 'import '
+    if nwords == 3 and words[0] == 'from':
+        return ['import ']
+
+    # 'from xy<tab>' or 'import xy<tab>'
+    if nwords < 3 and (words[0] in {'%aimport', 'import', 'from'}) :
+        if nwords == 1:
+            return get_root_modules()
+        mod = words[1].split('.')
+        if len(mod) < 2:
+            return get_root_modules()
+        completion_list = try_import('.'.join(mod[:-1]), True)
+        return ['.'.join(mod[:-1] + [el]) for el in completion_list]
+
+    # 'from xyz import abc<tab>'
+    if nwords >= 3 and words[0] == 'from':
+        mod = words[1]
+        return try_import(mod)
+
+#-----------------------------------------------------------------------------
+# Completers
+#-----------------------------------------------------------------------------
+# These all have the func(self, event) signature to be used as custom
+# completers
+
+def module_completer(self,event):
+    """Give completions after user has typed 'import ...' or 'from ...'"""
+
+    # This works in all versions of python.  While 2.5 has
+    # pkgutil.walk_packages(), that particular routine is fairly dangerous,
+    # since it imports *EVERYTHING* on sys.path.  That is: a) very slow b) full
+    # of possibly problematic side effects.
+    # This search the folders in the sys.path for available modules.
+
+    return module_completion(event.line)
+
+# FIXME: there's a lot of logic common to the run, cd and builtin file
+# completers, that is currently reimplemented in each.
+
+def magic_run_completer(self, event):
+    """Complete files that end in .py or .ipy or .ipynb for the %run command.
+    """
+    comps = arg_split(event.line, strict=False)
+    # relpath should be the current token that we need to complete.
+    if (len(comps) > 1) and (not event.line.endswith(' ')):
+        relpath = comps[-1].strip("'\"")
+    else:
+        relpath = ''
+
+    #print("\nev=", event)  # dbg
+    #print("rp=", relpath)  # dbg
+    #print('comps=', comps)  # dbg
+
+    lglob = glob.glob
+    isdir = os.path.isdir
+    relpath, tilde_expand, tilde_val = expand_user(relpath)
+
+    # Find if the user has already typed the first filename, after which we
+    # should complete on all files, since after the first one other files may
+    # be arguments to the input script.
+
+    if any(magic_run_re.match(c) for c in comps):
+        matches =  [f.replace('\\','/') + ('/' if isdir(f) else '')
+                            for f in lglob(relpath+'*')]
+    else:
+        dirs = [f.replace('\\','/') + "/" for f in lglob(relpath+'*') if isdir(f)]
+        pys =  [f.replace('\\','/')
+                for f in lglob(relpath+'*.py') + lglob(relpath+'*.ipy') +
+                lglob(relpath+'*.ipynb') + lglob(relpath + '*.pyw')]
+
+        matches = dirs + pys
+
+    #print('run comp:', dirs+pys) # dbg
+    return [compress_user(p, tilde_expand, tilde_val) for p in matches]
+
+
+def cd_completer(self, event):
+    """Completer function for cd, which only returns directories."""
+    ip = get_ipython()
+    relpath = event.symbol
+
+    #print(event) # dbg
+    if event.line.endswith('-b') or ' -b ' in event.line:
+        # return only bookmark completions
+        bkms = self.db.get('bookmarks', None)
+        if bkms:
+            return bkms.keys()
+        else:
+            return []
+
+    if event.symbol == '-':
+        width_dh = str(len(str(len(ip.user_ns['_dh']) + 1)))
+        # jump in directory history by number
+        fmt = '-%0' + width_dh +'d [%s]'
+        ents = [ fmt % (i,s) for i,s in enumerate(ip.user_ns['_dh'])]
+        if len(ents) > 1:
+            return ents
+        return []
+
+    if event.symbol.startswith('--'):
+        return ["--" + os.path.basename(d) for d in ip.user_ns['_dh']]
+
+    # Expand ~ in path and normalize directory separators.
+    relpath, tilde_expand, tilde_val = expand_user(relpath)
+    relpath = relpath.replace('\\','/')
+
+    found = []
+    for d in [f.replace('\\','/') + '/' for f in glob.glob(relpath+'*')
+              if os.path.isdir(f)]:
+        if ' ' in d:
+            # we don't want to deal with any of that, complex code
+            # for this is elsewhere
+            raise TryNext
+
+        found.append(d)
+
+    if not found:
+        if os.path.isdir(relpath):
+            return [compress_user(relpath, tilde_expand, tilde_val)]
+
+        # if no completions so far, try bookmarks
+        bks = self.db.get('bookmarks',{})
+        bkmatches = [s for s in bks if s.startswith(event.symbol)]
+        if bkmatches:
+            return bkmatches
+
+        raise TryNext
+
+    return [compress_user(p, tilde_expand, tilde_val) for p in found]
+
+def reset_completer(self, event):
+    "A completer for %reset magic"
+    return '-f -s in out array dhist'.split()

openalex_env_map/lib/python3.10/site-packages/IPython/core/crashhandler.py

@@ -0,0 +1,248 @@
+# encoding: utf-8
+"""sys.excepthook for IPython itself, leaves a detailed report on disk.
+
+Authors:
+
+* Fernando Perez
+* Brian E. Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2001-2007 Fernando Perez. <[email protected]>
+#  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__
+        
+        # Report tracebacks shouldn't use color in general (safer for users)
+        color_scheme = 'NoColor'
+
+        # Use this ONLY for developer debugging (keep commented out for release)
+        # color_scheme = 'Linux'   # dbg
+        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(
+            color_scheme=color_scheme,
+            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)
+

openalex_env_map/lib/python3.10/site-packages/IPython/core/debugger.py

@@ -0,0 +1,1136 @@
+"""
+Pdb debugger class.
+
+
+This is an extension to PDB which adds a number of new features.
+Note that there is also the `IPython.terminal.debugger` class which provides UI
+improvements.
+
+We also strongly recommend to use this via the `ipdb` package, which provides
+extra configuration options.
+
+Among other things, this subclass of PDB:
+ - supports many IPython magics like pdef/psource
+ - hide frames in tracebacks based on `__tracebackhide__`
+ - allows to skip frames based on `__debuggerskip__`
+
+
+Global Configuration
+--------------------
+
+The IPython debugger will by read the global ``~/.pdbrc`` file.
+That is to say you can list all commands supported by ipdb in your `~/.pdbrc`
+configuration file, to globally configure pdb.
+
+Example::
+
+   # ~/.pdbrc
+   skip_predicates debuggerskip false
+   skip_hidden false
+   context 25
+
+Features
+--------
+
+The IPython debugger can hide and skip frames when printing or moving through
+the stack. This can have a performance impact, so can be configures.
+
+The skipping and hiding frames are configurable via the `skip_predicates`
+command.
+
+By default, frames from readonly files will be hidden, frames containing
+``__tracebackhide__ = True`` will be hidden.
+
+Frames containing ``__debuggerskip__`` will be stepped over, frames whose parent
+frames value of ``__debuggerskip__`` is ``True`` will also be skipped.
+
+    >>> def helpers_helper():
+    ...     pass
+    ...
+    ... def helper_1():
+    ...     print("don't step in me")
+    ...     helpers_helpers() # will be stepped over unless breakpoint set.
+    ...
+    ...
+    ... def helper_2():
+    ...     print("in me neither")
+    ...
+
+One can define a decorator that wraps a function between the two helpers:
+
+    >>> def pdb_skipped_decorator(function):
+    ...
+    ...
+    ...     def wrapped_fn(*args, **kwargs):
+    ...         __debuggerskip__ = True
+    ...         helper_1()
+    ...         __debuggerskip__ = False
+    ...         result = function(*args, **kwargs)
+    ...         __debuggerskip__ = True
+    ...         helper_2()
+    ...         # setting __debuggerskip__ to False again is not necessary
+    ...         return result
+    ...
+    ...     return wrapped_fn
+
+When decorating a function, ipdb will directly step into ``bar()`` by
+default:
+
+    >>> @foo_decorator
+    ... def bar(x, y):
+    ...     return x * y
+
+
+You can toggle the behavior with
+
+    ipdb> skip_predicates debuggerskip false
+
+or configure it in your ``.pdbrc``
+
+
+
+License
+-------
+
+Modified from the standard pdb.Pdb class to avoid including readline, so that
+the command line completion of other programs which include this isn't
+damaged.
+
+In the future, this class will be expanded with improvements over the standard
+pdb.
+
+The original code in this file is mainly lifted out of cmd.py in Python 2.2,
+with minor changes. Licensing should therefore be under the standard Python
+terms.  For details on the PSF (Python Software Foundation) standard license,
+see:
+
+https://docs.python.org/2/license.html
+
+
+All the changes since then are under the same license as IPython.
+
+"""
+
+#*****************************************************************************
+#
+#       This file is licensed under the PSF license.
+#
+#       Copyright (C) 2001 Python Software Foundation, www.python.org
+#       Copyright (C) 2005-2006 Fernando Perez. <[email protected]>
+#
+#
+#*****************************************************************************
+
+from __future__ import annotations
+
+import inspect
+import linecache
+import os
+import re
+import sys
+from contextlib import contextmanager
+from functools import lru_cache
+
+from IPython import get_ipython
+from IPython.core.excolors import exception_colors
+from IPython.utils import PyColorize, coloransi, py3compat
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # otherwise circular import
+    from IPython.core.interactiveshell import InteractiveShell
+
+# skip module docstests
+__skip_doctest__ = True
+
+prompt = 'ipdb> '
+
+# We have to check this directly from sys.argv, config struct not yet available
+from pdb import Pdb as OldPdb
+
+# Allow the set_trace code to operate outside of an ipython instance, even if
+# it does so with some limitations.  The rest of this support is implemented in
+# the Tracer constructor.
+
+DEBUGGERSKIP = "__debuggerskip__"
+
+
+# this has been implemented in Pdb in Python 3.13 (https://github.com/python/cpython/pull/106676
+# on lower python versions, we backported the feature.
+CHAIN_EXCEPTIONS = sys.version_info < (3, 13)
+
+
+def make_arrow(pad):
+    """generate the leading arrow in front of traceback or debugger"""
+    if pad >= 2:
+        return '-'*(pad-2) + '> '
+    elif pad == 1:
+        return '>'
+    return ''
+
+
+def BdbQuit_excepthook(et, ev, tb, excepthook=None):
+    """Exception hook which handles `BdbQuit` exceptions.
+
+    All other exceptions are processed using the `excepthook`
+    parameter.
+    """
+    raise ValueError(
+        "`BdbQuit_excepthook` is deprecated since version 5.1. It is still around only because it is still imported by ipdb.",
+    )
+
+
+RGX_EXTRA_INDENT = re.compile(r'(?<=\n)\s+')
+
+
+def strip_indentation(multiline_string):
+    return RGX_EXTRA_INDENT.sub('', multiline_string)
+
+
+def decorate_fn_with_doc(new_fn, old_fn, additional_text=""):
+    """Make new_fn have old_fn's doc string. This is particularly useful
+    for the ``do_...`` commands that hook into the help system.
+    Adapted from from a comp.lang.python posting
+    by Duncan Booth."""
+    def wrapper(*args, **kw):
+        return new_fn(*args, **kw)
+    if old_fn.__doc__:
+        wrapper.__doc__ = strip_indentation(old_fn.__doc__) + additional_text
+    return wrapper
+
+
+class Pdb(OldPdb):
+    """Modified Pdb class, does not load readline.
+
+    for a standalone version that uses prompt_toolkit, see
+    `IPython.terminal.debugger.TerminalPdb` and
+    `IPython.terminal.debugger.set_trace()`
+
+
+    This debugger can hide and skip frames that are tagged according to some predicates.
+    See the `skip_predicates` commands.
+
+    """
+
+    shell: InteractiveShell
+
+    if CHAIN_EXCEPTIONS:
+        MAX_CHAINED_EXCEPTION_DEPTH = 999
+
+    default_predicates = {
+        "tbhide": True,
+        "readonly": False,
+        "ipython_internal": True,
+        "debuggerskip": True,
+    }
+
+    def __init__(self, completekey=None, stdin=None, stdout=None, context=5, **kwargs):
+        """Create a new IPython debugger.
+
+        Parameters
+        ----------
+        completekey : default None
+            Passed to pdb.Pdb.
+        stdin : default None
+            Passed to pdb.Pdb.
+        stdout : default None
+            Passed to pdb.Pdb.
+        context : int
+            Number of lines of source code context to show when
+            displaying stacktrace information.
+        **kwargs
+            Passed to pdb.Pdb.
+
+        Notes
+        -----
+        The possibilities are python version dependent, see the python
+        docs for more info.
+        """
+
+        # Parent constructor:
+        try:
+            self.context = int(context)
+            if self.context <= 0:
+                raise ValueError("Context must be a positive integer")
+        except (TypeError, ValueError) as e:
+                raise ValueError("Context must be a positive integer") from e
+
+        # `kwargs` ensures full compatibility with stdlib's `pdb.Pdb`.
+        OldPdb.__init__(self, completekey, stdin, stdout, **kwargs)
+
+        # IPython changes...
+        self.shell = get_ipython()
+
+        if self.shell is None:
+            save_main = sys.modules['__main__']
+            # No IPython instance running, we must create one
+            from IPython.terminal.interactiveshell import \
+                TerminalInteractiveShell
+            self.shell = TerminalInteractiveShell.instance()
+            # needed by any code which calls __import__("__main__") after
+            # the debugger was entered. See also #9941.
+            sys.modules["__main__"] = save_main
+
+
+        color_scheme = self.shell.colors
+
+        self.aliases = {}
+
+        # Create color table: we copy the default one from the traceback
+        # module and add a few attributes needed for debugging
+        self.color_scheme_table = exception_colors()
+
+        # shorthands
+        C = coloransi.TermColors
+        cst = self.color_scheme_table
+
+
+        # Add a python parser so we can syntax highlight source while
+        # debugging.
+        self.parser = PyColorize.Parser(style=color_scheme)
+        self.set_colors(color_scheme)
+
+        # Set the prompt - the default prompt is '(Pdb)'
+        self.prompt = prompt
+        self.skip_hidden = True
+        self.report_skipped = True
+
+        # list of predicates we use to skip frames
+        self._predicates = self.default_predicates
+
+        if CHAIN_EXCEPTIONS:
+            self._chained_exceptions = tuple()
+            self._chained_exception_index = 0
+
+    #
+    def set_colors(self, scheme):
+        """Shorthand access to the color table scheme selector method."""
+        self.color_scheme_table.set_active_scheme(scheme)
+        self.parser.style = scheme
+
+    def set_trace(self, frame=None):
+        if frame is None:
+            frame = sys._getframe().f_back
+        self.initial_frame = frame
+        return super().set_trace(frame)
+
+    def _hidden_predicate(self, frame):
+        """
+        Given a frame return whether it it should be hidden or not by IPython.
+        """
+
+        if self._predicates["readonly"]:
+            fname = frame.f_code.co_filename
+            # we need to check for file existence and interactively define
+            # function would otherwise appear as RO.
+            if os.path.isfile(fname) and not os.access(fname, os.W_OK):
+                return True
+
+        if self._predicates["tbhide"]:
+            if frame in (self.curframe, getattr(self, "initial_frame", None)):
+                return False
+            frame_locals = self._get_frame_locals(frame)
+            if "__tracebackhide__" not in frame_locals:
+                return False
+            return frame_locals["__tracebackhide__"]
+        return False
+
+    def hidden_frames(self, stack):
+        """
+        Given an index in the stack return whether it should be skipped.
+
+        This is used in up/down and where to skip frames.
+        """
+        # The f_locals dictionary is updated from the actual frame
+        # locals whenever the .f_locals accessor is called, so we
+        # avoid calling it here to preserve self.curframe_locals.
+        # Furthermore, there is no good reason to hide the current frame.
+        ip_hide = [self._hidden_predicate(s[0]) for s in stack]
+        ip_start = [i for i, s in enumerate(ip_hide) if s == "__ipython_bottom__"]
+        if ip_start and self._predicates["ipython_internal"]:
+            ip_hide = [h if i > ip_start[0] else True for (i, h) in enumerate(ip_hide)]
+        return ip_hide
+
+    if CHAIN_EXCEPTIONS:
+
+        def _get_tb_and_exceptions(self, tb_or_exc):
+            """
+            Given a tracecack or an exception, return a tuple of chained exceptions
+            and current traceback to inspect.
+            This will deal with selecting the right ``__cause__`` or ``__context__``
+            as well as handling cycles, and return a flattened list of exceptions we
+            can jump to with do_exceptions.
+            """
+            _exceptions = []
+            if isinstance(tb_or_exc, BaseException):
+                traceback, current = tb_or_exc.__traceback__, tb_or_exc
+
+                while current is not None:
+                    if current in _exceptions:
+                        break
+                    _exceptions.append(current)
+                    if current.__cause__ is not None:
+                        current = current.__cause__
+                    elif (
+                        current.__context__ is not None
+                        and not current.__suppress_context__
+                    ):
+                        current = current.__context__
+
+                    if len(_exceptions) >= self.MAX_CHAINED_EXCEPTION_DEPTH:
+                        self.message(
+                            f"More than {self.MAX_CHAINED_EXCEPTION_DEPTH}"
+                            " chained exceptions found, not all exceptions"
+                            "will be browsable with `exceptions`."
+                        )
+                        break
+            else:
+                traceback = tb_or_exc
+            return tuple(reversed(_exceptions)), traceback
+
+        @contextmanager
+        def _hold_exceptions(self, exceptions):
+            """
+            Context manager to ensure proper cleaning of exceptions references
+            When given a chained exception instead of a traceback,
+            pdb may hold references to many objects which may leak memory.
+            We use this context manager to make sure everything is properly cleaned
+            """
+            try:
+                self._chained_exceptions = exceptions
+                self._chained_exception_index = len(exceptions) - 1
+                yield
+            finally:
+                # we can't put those in forget as otherwise they would
+                # be cleared on exception change
+                self._chained_exceptions = tuple()
+                self._chained_exception_index = 0
+
+        def do_exceptions(self, arg):
+            """exceptions [number]
+            List or change current exception in an exception chain.
+            Without arguments, list all the current exception in the exception
+            chain. Exceptions will be numbered, with the current exception indicated
+            with an arrow.
+            If given an integer as argument, switch to the exception at that index.
+            """
+            if not self._chained_exceptions:
+                self.message(
+                    "Did not find chained exceptions. To move between"
+                    " exceptions, pdb/post_mortem must be given an exception"
+                    " object rather than a traceback."
+                )
+                return
+            if not arg:
+                for ix, exc in enumerate(self._chained_exceptions):
+                    prompt = ">" if ix == self._chained_exception_index else " "
+                    rep = repr(exc)
+                    if len(rep) > 80:
+                        rep = rep[:77] + "..."
+                    indicator = (
+                        "  -"
+                        if self._chained_exceptions[ix].__traceback__ is None
+                        else f"{ix:>3}"
+                    )
+                    self.message(f"{prompt} {indicator} {rep}")
+            else:
+                try:
+                    number = int(arg)
+                except ValueError:
+                    self.error("Argument must be an integer")
+                    return
+                if 0 <= number < len(self._chained_exceptions):
+                    if self._chained_exceptions[number].__traceback__ is None:
+                        self.error(
+                            "This exception does not have a traceback, cannot jump to it"
+                        )
+                        return
+
+                    self._chained_exception_index = number
+                    self.setup(None, self._chained_exceptions[number].__traceback__)
+                    self.print_stack_entry(self.stack[self.curindex])
+                else:
+                    self.error("No exception with that number")
+
+    def interaction(self, frame, tb_or_exc):
+        try:
+            if CHAIN_EXCEPTIONS:
+                # this context manager is part of interaction in 3.13
+                _chained_exceptions, tb = self._get_tb_and_exceptions(tb_or_exc)
+                if isinstance(tb_or_exc, BaseException):
+                    assert tb is not None, "main exception must have a traceback"
+                with self._hold_exceptions(_chained_exceptions):
+                    OldPdb.interaction(self, frame, tb)
+            else:
+                OldPdb.interaction(self, frame, tb_or_exc)
+
+        except KeyboardInterrupt:
+            self.stdout.write("\n" + self.shell.get_exception_only())
+
+    def precmd(self, line):
+        """Perform useful escapes on the command before it is executed."""
+
+        if line.endswith("??"):
+            line = "pinfo2 " + line[:-2]
+        elif line.endswith("?"):
+            line = "pinfo " + line[:-1]
+
+        line = super().precmd(line)
+
+        return line
+
+    def new_do_quit(self, arg):
+        return OldPdb.do_quit(self, arg)
+
+    do_q = do_quit = decorate_fn_with_doc(new_do_quit, OldPdb.do_quit)
+
+    def print_stack_trace(self, context=None):
+        Colors = self.color_scheme_table.active_colors
+        ColorsNormal = Colors.Normal
+        if context is None:
+            context = self.context
+        try:
+            context = int(context)
+            if context <= 0:
+                raise ValueError("Context must be a positive integer")
+        except (TypeError, ValueError) as e:
+                raise ValueError("Context must be a positive integer") from e
+        try:
+            skipped = 0
+            for hidden, frame_lineno in zip(self.hidden_frames(self.stack), self.stack):
+                if hidden and self.skip_hidden:
+                    skipped += 1
+                    continue
+                if skipped:
+                    print(
+                        f"{Colors.excName}    [... skipping {skipped} hidden frame(s)]{ColorsNormal}\n"
+                    )
+                    skipped = 0
+                self.print_stack_entry(frame_lineno, context=context)
+            if skipped:
+                print(
+                    f"{Colors.excName}    [... skipping {skipped} hidden frame(s)]{ColorsNormal}\n"
+                )
+        except KeyboardInterrupt:
+            pass
+
+    def print_stack_entry(self, frame_lineno, prompt_prefix='\n-> ',
+                          context=None):
+        if context is None:
+            context = self.context
+        try:
+            context = int(context)
+            if context <= 0:
+                raise ValueError("Context must be a positive integer")
+        except (TypeError, ValueError) as e:
+                raise ValueError("Context must be a positive integer") from e
+        print(self.format_stack_entry(frame_lineno, '', context), file=self.stdout)
+
+        # vds: >>
+        frame, lineno = frame_lineno
+        filename = frame.f_code.co_filename
+        self.shell.hooks.synchronize_with_editor(filename, lineno, 0)
+        # vds: <<
+
+    def _get_frame_locals(self, frame):
+        """ "
+        Accessing f_local of current frame reset the namespace, so we want to avoid
+        that or the following can happen
+
+        ipdb> foo
+        "old"
+        ipdb> foo = "new"
+        ipdb> foo
+        "new"
+        ipdb> where
+        ipdb> foo
+        "old"
+
+        So if frame is self.current_frame we instead return self.curframe_locals
+
+        """
+        if frame is getattr(self, "curframe", None):
+            return self.curframe_locals
+        else:
+            return frame.f_locals
+
+    def format_stack_entry(self, frame_lineno, lprefix=': ', context=None):
+        if context is None:
+            context = self.context
+        try:
+            context = int(context)
+            if context <= 0:
+                print("Context must be a positive integer", file=self.stdout)
+        except (TypeError, ValueError):
+                print("Context must be a positive integer", file=self.stdout)
+
+        import reprlib
+
+        ret = []
+
+        Colors = self.color_scheme_table.active_colors
+        ColorsNormal = Colors.Normal
+        tpl_link = "%s%%s%s" % (Colors.filenameEm, ColorsNormal)
+        tpl_call = "%s%%s%s%%s%s" % (Colors.vName, Colors.valEm, ColorsNormal)
+        tpl_line = "%%s%s%%s %s%%s" % (Colors.lineno, ColorsNormal)
+        tpl_line_em = "%%s%s%%s %s%%s%s" % (Colors.linenoEm, Colors.line, ColorsNormal)
+
+        frame, lineno = frame_lineno
+
+        return_value = ''
+        loc_frame = self._get_frame_locals(frame)
+        if "__return__" in loc_frame:
+            rv = loc_frame["__return__"]
+            # return_value += '->'
+            return_value += reprlib.repr(rv) + "\n"
+        ret.append(return_value)
+
+        #s = filename + '(' + `lineno` + ')'
+        filename = self.canonic(frame.f_code.co_filename)
+        link = tpl_link % py3compat.cast_unicode(filename)
+
+        if frame.f_code.co_name:
+            func = frame.f_code.co_name
+        else:
+            func = "<lambda>"
+
+        call = ""
+        if func != "?":
+            if "__args__" in loc_frame:
+                args = reprlib.repr(loc_frame["__args__"])
+            else:
+                args = '()'
+            call = tpl_call % (func, args)
+
+        # The level info should be generated in the same format pdb uses, to
+        # avoid breaking the pdbtrack functionality of python-mode in *emacs.
+        if frame is self.curframe:
+            ret.append('> ')
+        else:
+            ret.append("  ")
+        ret.append("%s(%s)%s\n" % (link, lineno, call))
+
+        start = lineno - 1 - context//2
+        lines = linecache.getlines(filename)
+        start = min(start, len(lines) - context)
+        start = max(start, 0)
+        lines = lines[start : start + context]
+
+        for i, line in enumerate(lines):
+            show_arrow = start + 1 + i == lineno
+            linetpl = (frame is self.curframe or show_arrow) and tpl_line_em or tpl_line
+            ret.append(
+                self.__format_line(
+                    linetpl, filename, start + 1 + i, line, arrow=show_arrow
+                )
+            )
+        return "".join(ret)
+
+    def __format_line(self, tpl_line, filename, lineno, line, arrow=False):
+        bp_mark = ""
+        bp_mark_color = ""
+
+        new_line, err = self.parser.format2(line, 'str')
+        if not err:
+            line = new_line
+
+        bp = None
+        if lineno in self.get_file_breaks(filename):
+            bps = self.get_breaks(filename, lineno)
+            bp = bps[-1]
+
+        if bp:
+            Colors = self.color_scheme_table.active_colors
+            bp_mark = str(bp.number)
+            bp_mark_color = Colors.breakpoint_enabled
+            if not bp.enabled:
+                bp_mark_color = Colors.breakpoint_disabled
+
+        numbers_width = 7
+        if arrow:
+            # This is the line with the error
+            pad = numbers_width - len(str(lineno)) - len(bp_mark)
+            num = '%s%s' % (make_arrow(pad), str(lineno))
+        else:
+            num = '%*s' % (numbers_width - len(bp_mark), str(lineno))
+
+        return tpl_line % (bp_mark_color + bp_mark, num, line)
+
+    def print_list_lines(self, filename, first, last):
+        """The printing (as opposed to the parsing part of a 'list'
+        command."""
+        try:
+            Colors = self.color_scheme_table.active_colors
+            ColorsNormal = Colors.Normal
+            tpl_line = '%%s%s%%s %s%%s' % (Colors.lineno, ColorsNormal)
+            tpl_line_em = '%%s%s%%s %s%%s%s' % (Colors.linenoEm, Colors.line, ColorsNormal)
+            src = []
+            if filename == "<string>" and hasattr(self, "_exec_filename"):
+                filename = self._exec_filename
+
+            for lineno in range(first, last+1):
+                line = linecache.getline(filename, lineno)
+                if not line:
+                    break
+
+                if lineno == self.curframe.f_lineno:
+                    line = self.__format_line(
+                        tpl_line_em, filename, lineno, line, arrow=True
+                    )
+                else:
+                    line = self.__format_line(
+                        tpl_line, filename, lineno, line, arrow=False
+                    )
+
+                src.append(line)
+                self.lineno = lineno
+
+            print(''.join(src), file=self.stdout)
+
+        except KeyboardInterrupt:
+            pass
+
+    def do_skip_predicates(self, args):
+        """
+        Turn on/off individual predicates as to whether a frame should be hidden/skip.
+
+        The global option to skip (or not) hidden frames is set with skip_hidden
+
+        To change the value of a predicate
+
+            skip_predicates key [true|false]
+
+        Call without arguments to see the current values.
+
+        To permanently change the value of an option add the corresponding
+        command to your ``~/.pdbrc`` file. If you are programmatically using the
+        Pdb instance you can also change the ``default_predicates`` class
+        attribute.
+        """
+        if not args.strip():
+            print("current predicates:")
+            for p, v in self._predicates.items():
+                print("   ", p, ":", v)
+            return
+        type_value = args.strip().split(" ")
+        if len(type_value) != 2:
+            print(
+                f"Usage: skip_predicates <type> <value>, with <type> one of {set(self._predicates.keys())}"
+            )
+            return
+
+        type_, value = type_value
+        if type_ not in self._predicates:
+            print(f"{type_!r} not in {set(self._predicates.keys())}")
+            return
+        if value.lower() not in ("true", "yes", "1", "no", "false", "0"):
+            print(
+                f"{value!r} is invalid - use one of ('true', 'yes', '1', 'no', 'false', '0')"
+            )
+            return
+
+        self._predicates[type_] = value.lower() in ("true", "yes", "1")
+        if not any(self._predicates.values()):
+            print(
+                "Warning, all predicates set to False, skip_hidden may not have any effects."
+            )
+
+    def do_skip_hidden(self, arg):
+        """
+        Change whether or not we should skip frames with the
+        __tracebackhide__ attribute.
+        """
+        if not arg.strip():
+            print(
+                f"skip_hidden = {self.skip_hidden}, use 'yes','no', 'true', or 'false' to change."
+            )
+        elif arg.strip().lower() in ("true", "yes"):
+            self.skip_hidden = True
+        elif arg.strip().lower() in ("false", "no"):
+            self.skip_hidden = False
+        if not any(self._predicates.values()):
+            print(
+                "Warning, all predicates set to False, skip_hidden may not have any effects."
+            )
+
+    def do_list(self, arg):
+        """Print lines of code from the current stack frame
+        """
+        self.lastcmd = 'list'
+        last = None
+        if arg and arg != ".":
+            try:
+                x = eval(arg, {}, {})
+                if type(x) == type(()):
+                    first, last = x
+                    first = int(first)
+                    last = int(last)
+                    if last < first:
+                        # Assume it's a count
+                        last = first + last
+                else:
+                    first = max(1, int(x) - 5)
+            except:
+                print('*** Error in argument:', repr(arg), file=self.stdout)
+                return
+        elif self.lineno is None or arg == ".":
+            first = max(1, self.curframe.f_lineno - 5)
+        else:
+            first = self.lineno + 1
+        if last is None:
+            last = first + 10
+        self.print_list_lines(self.curframe.f_code.co_filename, first, last)
+
+        # vds: >>
+        lineno = first
+        filename = self.curframe.f_code.co_filename
+        self.shell.hooks.synchronize_with_editor(filename, lineno, 0)
+        # vds: <<
+
+    do_l = do_list
+
+    def getsourcelines(self, obj):
+        lines, lineno = inspect.findsource(obj)
+        if inspect.isframe(obj) and obj.f_globals is self._get_frame_locals(obj):
+            # must be a module frame: do not try to cut a block out of it
+            return lines, 1
+        elif inspect.ismodule(obj):
+            return lines, 1
+        return inspect.getblock(lines[lineno:]), lineno+1
+
+    def do_longlist(self, arg):
+        """Print lines of code from the current stack frame.
+
+        Shows more lines than 'list' does.
+        """
+        self.lastcmd = 'longlist'
+        try:
+            lines, lineno = self.getsourcelines(self.curframe)
+        except OSError as err:
+            self.error(err)
+            return
+        last = lineno + len(lines)
+        self.print_list_lines(self.curframe.f_code.co_filename, lineno, last)
+    do_ll = do_longlist
+
+    def do_debug(self, arg):
+        """debug code
+        Enter a recursive debugger that steps through the code
+        argument (which is an arbitrary expression or statement to be
+        executed in the current environment).
+        """
+        trace_function = sys.gettrace()
+        sys.settrace(None)
+        globals = self.curframe.f_globals
+        locals = self.curframe_locals
+        p = self.__class__(completekey=self.completekey,
+                           stdin=self.stdin, stdout=self.stdout)
+        p.use_rawinput = self.use_rawinput
+        p.prompt = "(%s) " % self.prompt.strip()
+        self.message("ENTERING RECURSIVE DEBUGGER")
+        sys.call_tracing(p.run, (arg, globals, locals))
+        self.message("LEAVING RECURSIVE DEBUGGER")
+        sys.settrace(trace_function)
+        self.lastcmd = p.lastcmd
+
+    def do_pdef(self, arg):
+        """Print the call signature for any callable object.
+
+        The debugger interface to %pdef"""
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("pdef")(arg, namespaces=namespaces)
+
+    def do_pdoc(self, arg):
+        """Print the docstring for an object.
+
+        The debugger interface to %pdoc."""
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("pdoc")(arg, namespaces=namespaces)
+
+    def do_pfile(self, arg):
+        """Print (or run through pager) the file where an object is defined.
+
+        The debugger interface to %pfile.
+        """
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("pfile")(arg, namespaces=namespaces)
+
+    def do_pinfo(self, arg):
+        """Provide detailed information about an object.
+
+        The debugger interface to %pinfo, i.e., obj?."""
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("pinfo")(arg, namespaces=namespaces)
+
+    def do_pinfo2(self, arg):
+        """Provide extra detailed information about an object.
+
+        The debugger interface to %pinfo2, i.e., obj??."""
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("pinfo2")(arg, namespaces=namespaces)
+
+    def do_psource(self, arg):
+        """Print (or run through pager) the source code for an object."""
+        namespaces = [
+            ("Locals", self.curframe_locals),
+            ("Globals", self.curframe.f_globals),
+        ]
+        self.shell.find_line_magic("psource")(arg, namespaces=namespaces)
+
+    def do_where(self, arg):
+        """w(here)
+        Print a stack trace, with the most recent frame at the bottom.
+        An arrow indicates the "current frame", which determines the
+        context of most commands. 'bt' is an alias for this command.
+
+        Take a number as argument as an (optional) number of context line to
+        print"""
+        if arg:
+            try:
+                context = int(arg)
+            except ValueError as err:
+                self.error(err)
+                return
+            self.print_stack_trace(context)
+        else:
+            self.print_stack_trace()
+
+    do_w = do_where
+
+    def break_anywhere(self, frame):
+        """
+        _stop_in_decorator_internals is overly restrictive, as we may still want
+        to trace function calls, so we need to also update break_anywhere so
+        that is we don't `stop_here`, because of debugger skip, we may still
+        stop at any point inside the function
+
+        """
+
+        sup = super().break_anywhere(frame)
+        if sup:
+            return sup
+        if self._predicates["debuggerskip"]:
+            if DEBUGGERSKIP in frame.f_code.co_varnames:
+                return True
+            if frame.f_back and self._get_frame_locals(frame.f_back).get(DEBUGGERSKIP):
+                return True
+        return False
+
+    def _is_in_decorator_internal_and_should_skip(self, frame):
+        """
+        Utility to tell us whether we are in a decorator internal and should stop.
+
+        """
+        # if we are disabled don't skip
+        if not self._predicates["debuggerskip"]:
+            return False
+
+        return self._cachable_skip(frame)
+
+    @lru_cache(1024)
+    def _cached_one_parent_frame_debuggerskip(self, frame):
+        """
+        Cache looking up for DEBUGGERSKIP on parent frame.
+
+        This should speedup walking through deep frame when one of the highest
+        one does have a debugger skip.
+
+        This is likely to introduce fake positive though.
+        """
+        while getattr(frame, "f_back", None):
+            frame = frame.f_back
+            if self._get_frame_locals(frame).get(DEBUGGERSKIP):
+                return True
+        return None
+
+    @lru_cache(1024)
+    def _cachable_skip(self, frame):
+        # if frame is tagged, skip by default.
+        if DEBUGGERSKIP in frame.f_code.co_varnames:
+            return True
+
+        # if one of the parent frame value set to True skip as well.
+        if self._cached_one_parent_frame_debuggerskip(frame):
+            return True
+
+        return False
+
+    def stop_here(self, frame):
+        if self._is_in_decorator_internal_and_should_skip(frame) is True:
+            return False
+
+        hidden = False
+        if self.skip_hidden:
+            hidden = self._hidden_predicate(frame)
+        if hidden:
+            if self.report_skipped:
+                Colors = self.color_scheme_table.active_colors
+                ColorsNormal = Colors.Normal
+                print(
+                    f"{Colors.excName}    [... skipped 1 hidden frame]{ColorsNormal}\n"
+                )
+        return super().stop_here(frame)
+
+    def do_up(self, arg):
+        """u(p) [count]
+        Move the current frame count (default one) levels up in the
+        stack trace (to an older frame).
+
+        Will skip hidden frames.
+        """
+        # modified version of upstream that skips
+        # frames with __tracebackhide__
+        if self.curindex == 0:
+            self.error("Oldest frame")
+            return
+        try:
+            count = int(arg or 1)
+        except ValueError:
+            self.error("Invalid frame count (%s)" % arg)
+            return
+        skipped = 0
+        if count < 0:
+            _newframe = 0
+        else:
+            counter = 0
+            hidden_frames = self.hidden_frames(self.stack)
+            for i in range(self.curindex - 1, -1, -1):
+                if hidden_frames[i] and self.skip_hidden:
+                    skipped += 1
+                    continue
+                counter += 1
+                if counter >= count:
+                    break
+            else:
+                # if no break occurred.
+                self.error(
+                    "all frames above hidden, use `skip_hidden False` to get get into those."
+                )
+                return
+
+            Colors = self.color_scheme_table.active_colors
+            ColorsNormal = Colors.Normal
+            _newframe = i
+        self._select_frame(_newframe)
+        if skipped:
+            print(
+                f"{Colors.excName}    [... skipped {skipped} hidden frame(s)]{ColorsNormal}\n"
+            )
+
+    def do_down(self, arg):
+        """d(own) [count]
+        Move the current frame count (default one) levels down in the
+        stack trace (to a newer frame).
+
+        Will skip hidden frames.
+        """
+        if self.curindex + 1 == len(self.stack):
+            self.error("Newest frame")
+            return
+        try:
+            count = int(arg or 1)
+        except ValueError:
+            self.error("Invalid frame count (%s)" % arg)
+            return
+        if count < 0:
+            _newframe = len(self.stack) - 1
+        else:
+            counter = 0
+            skipped = 0
+            hidden_frames = self.hidden_frames(self.stack)
+            for i in range(self.curindex + 1, len(self.stack)):
+                if hidden_frames[i] and self.skip_hidden:
+                    skipped += 1
+                    continue
+                counter += 1
+                if counter >= count:
+                    break
+            else:
+                self.error(
+                    "all frames below hidden, use `skip_hidden False` to get get into those."
+                )
+                return
+
+            Colors = self.color_scheme_table.active_colors
+            ColorsNormal = Colors.Normal
+            if skipped:
+                print(
+                    f"{Colors.excName}    [... skipped {skipped} hidden frame(s)]{ColorsNormal}\n"
+                )
+            _newframe = i
+
+        self._select_frame(_newframe)
+
+    do_d = do_down
+    do_u = do_up
+
+    def do_context(self, context):
+        """context number_of_lines
+        Set the number of lines of source code to show when displaying
+        stacktrace information.
+        """
+        try:
+            new_context = int(context)
+            if new_context <= 0:
+                raise ValueError()
+            self.context = new_context
+        except ValueError:
+            self.error(
+                f"The 'context' command requires a positive integer argument (current value {self.context})."
+            )
+
+
+class InterruptiblePdb(Pdb):
+    """Version of debugger where KeyboardInterrupt exits the debugger altogether."""
+
+    def cmdloop(self, intro=None):
+        """Wrap cmdloop() such that KeyboardInterrupt stops the debugger."""
+        try:
+            return OldPdb.cmdloop(self, intro=intro)
+        except KeyboardInterrupt:
+            self.stop_here = lambda frame: False
+            self.do_quit("")
+            sys.settrace(None)
+            self.quitting = False
+            raise
+
+    def _cmdloop(self):
+        while True:
+            try:
+                # keyboard interrupts allow for an easy way to cancel
+                # the current command, so allow them during interactive input
+                self.allow_kbdint = True
+                self.cmdloop()
+                self.allow_kbdint = False
+                break
+            except KeyboardInterrupt:
+                self.message('--KeyboardInterrupt--')
+                raise
+
+
+def set_trace(frame=None, header=None):
+    """
+    Start debugging from `frame`.
+
+    If frame is not specified, debugging starts from caller's frame.
+    """
+    pdb = Pdb()
+    if header is not None:
+        pdb.message(header)
+    pdb.set_trace(frame or sys._getframe().f_back)

openalex_env_map/lib/python3.10/site-packages/IPython/core/display.py

@@ -0,0 +1,1373 @@
+# -*- coding: utf-8 -*-
+"""Top-level display functions for displaying object in different formats."""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+
+from binascii import b2a_base64, hexlify
+import html
+import json
+import mimetypes
+import os
+import struct
+import warnings
+from copy import deepcopy
+from os.path import splitext
+from pathlib import Path, PurePath
+
+from typing import Optional
+
+from IPython.testing.skipdoctest import skip_doctest
+from . import display_functions
+
+
+__all__ = [
+    "display_pretty",
+    "display_html",
+    "display_markdown",
+    "display_svg",
+    "display_png",
+    "display_jpeg",
+    "display_webp",
+    "display_latex",
+    "display_json",
+    "display_javascript",
+    "display_pdf",
+    "DisplayObject",
+    "TextDisplayObject",
+    "Pretty",
+    "HTML",
+    "Markdown",
+    "Math",
+    "Latex",
+    "SVG",
+    "ProgressBar",
+    "JSON",
+    "GeoJSON",
+    "Javascript",
+    "Image",
+    "set_matplotlib_formats",
+    "set_matplotlib_close",
+    "Video",
+]
+
+_deprecated_names = ["display", "clear_output", "publish_display_data", "update_display", "DisplayHandle"]
+
+__all__ = __all__ + _deprecated_names
+
+
+# ----- warn to import from IPython.display -----
+
+from warnings import warn
+
+
+def __getattr__(name):
+    if name in _deprecated_names:
+        warn(
+            f"Importing {name} from IPython.core.display is deprecated since IPython 7.14, please import from IPython.display",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(display_functions, name)
+
+    if name in globals().keys():
+        return globals()[name]
+    else:
+        raise AttributeError(f"module {__name__} has no attribute {name}")
+
+
+#-----------------------------------------------------------------------------
+# utility functions
+#-----------------------------------------------------------------------------
+
+def _safe_exists(path):
+    """Check path, but don't let exceptions raise"""
+    try:
+        return os.path.exists(path)
+    except Exception:
+        return False
+
+
+def _display_mimetype(mimetype, objs, raw=False, metadata=None):
+    """internal implementation of all display_foo methods
+
+    Parameters
+    ----------
+    mimetype : str
+        The mimetype to be published (e.g. 'image/png')
+    *objs : object
+        The Python objects to display, or if raw=True raw text data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    if metadata:
+        metadata = {mimetype: metadata}
+    if raw:
+        # turn list of pngdata into list of { 'image/png': pngdata }
+        objs = [ {mimetype: obj} for obj in objs ]
+    display_functions.display(*objs, raw=raw, metadata=metadata, include=[mimetype])
+
+#-----------------------------------------------------------------------------
+# Main functions
+#-----------------------------------------------------------------------------
+
+
+def display_pretty(*objs, **kwargs):
+    """Display the pretty (default) representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw text data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('text/plain', objs, **kwargs)
+
+
+def display_html(*objs, **kwargs):
+    """Display the HTML representation of an object.
+
+    Note: If raw=False and the object does not have a HTML
+    representation, no HTML will be shown.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw HTML data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('text/html', objs, **kwargs)
+
+
+def display_markdown(*objs, **kwargs):
+    """Displays the Markdown representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw markdown data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+
+    _display_mimetype('text/markdown', objs, **kwargs)
+
+
+def display_svg(*objs, **kwargs):
+    """Display the SVG representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw svg data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('image/svg+xml', objs, **kwargs)
+
+
+def display_png(*objs, **kwargs):
+    """Display the PNG representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw png data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('image/png', objs, **kwargs)
+
+
+def display_jpeg(*objs, **kwargs):
+    """Display the JPEG representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw JPEG data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('image/jpeg', objs, **kwargs)
+
+
+def display_webp(*objs, **kwargs):
+    """Display the WEBP representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw JPEG data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype("image/webp", objs, **kwargs)
+
+
+def display_latex(*objs, **kwargs):
+    """Display the LaTeX representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw latex data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('text/latex', objs, **kwargs)
+
+
+def display_json(*objs, **kwargs):
+    """Display the JSON representation of an object.
+
+    Note that not many frontends support displaying JSON.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw json data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('application/json', objs, **kwargs)
+
+
+def display_javascript(*objs, **kwargs):
+    """Display the Javascript representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw javascript data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('application/javascript', objs, **kwargs)
+
+
+def display_pdf(*objs, **kwargs):
+    """Display the PDF representation of an object.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display, or if raw=True raw javascript data to
+        display.
+    raw : bool
+        Are the data objects raw data or Python objects that need to be
+        formatted before display? [default: False]
+    metadata : dict (optional)
+        Metadata to be associated with the specific mimetype output.
+    """
+    _display_mimetype('application/pdf', objs, **kwargs)
+
+
+#-----------------------------------------------------------------------------
+# Smart classes
+#-----------------------------------------------------------------------------
+
+
+class DisplayObject(object):
+    """An object that wraps data to be displayed."""
+
+    _read_flags = 'r'
+    _show_mem_addr = False
+    metadata = None
+
+    def __init__(self, data=None, url=None, filename=None, metadata=None):
+        """Create a display object given raw data.
+
+        When this object is returned by an expression or passed to the
+        display function, it will result in the data being displayed
+        in the frontend. The MIME type of the data should match the
+        subclasses used, so the Png subclass should be used for 'image/png'
+        data. If the data is a URL, the data will first be downloaded
+        and then displayed.
+
+        Parameters
+        ----------
+        data : unicode, str or bytes
+            The raw data or a URL or file to load the data from
+        url : unicode
+            A URL to download the data from.
+        filename : unicode
+            Path to a local file to load the data from.
+        metadata : dict
+            Dict of metadata associated to be the object when displayed
+        """
+        if isinstance(data, (Path, PurePath)):
+            data = str(data)
+
+        if data is not None and isinstance(data, str):
+            if data.startswith('http') and url is None:
+                url = data
+                filename = None
+                data = None
+            elif _safe_exists(data) and filename is None:
+                url = None
+                filename = data
+                data = None
+
+        self.url = url
+        self.filename = filename
+        # because of @data.setter methods in
+        # subclasses ensure url and filename are set
+        # before assigning to self.data
+        self.data = data
+
+        if metadata is not None:
+            self.metadata = metadata
+        elif self.metadata is None:
+            self.metadata = {}
+
+        self.reload()
+        self._check_data()
+
+    def __repr__(self):
+        if not self._show_mem_addr:
+            cls = self.__class__
+            r = "<%s.%s object>" % (cls.__module__, cls.__name__)
+        else:
+            r = super(DisplayObject, self).__repr__()
+        return r
+
+    def _check_data(self):
+        """Override in subclasses if there's something to check."""
+        pass
+
+    def _data_and_metadata(self):
+        """shortcut for returning metadata with shape information, if defined"""
+        if self.metadata:
+            return self.data, deepcopy(self.metadata)
+        else:
+            return self.data
+
+    def reload(self):
+        """Reload the raw data from file or URL."""
+        if self.filename is not None:
+            encoding = None if "b" in self._read_flags else "utf-8"
+            with open(self.filename, self._read_flags, encoding=encoding) as f:
+                self.data = f.read()
+        elif self.url is not None:
+            # Deferred import
+            from urllib.request import urlopen
+            response = urlopen(self.url)
+            data = response.read()
+            # extract encoding from header, if there is one:
+            encoding = None
+            if 'content-type' in response.headers:
+                for sub in response.headers['content-type'].split(';'):
+                    sub = sub.strip()
+                    if sub.startswith('charset'):
+                        encoding = sub.split('=')[-1].strip()
+                        break
+            if 'content-encoding' in response.headers:
+                # TODO: do deflate?
+                if 'gzip' in response.headers['content-encoding']:
+                    import gzip
+                    from io import BytesIO
+
+                    # assume utf-8 if encoding is not specified
+                    with gzip.open(
+                        BytesIO(data), "rt", encoding=encoding or "utf-8"
+                    ) as fp:
+                        encoding = None
+                        data = fp.read()
+
+            # decode data, if an encoding was specified
+            # We only touch self.data once since
+            # subclasses such as SVG have @data.setter methods
+            # that transform self.data into ... well svg.
+            if encoding:
+                self.data = data.decode(encoding, 'replace')
+            else:
+                self.data = data
+
+
+class TextDisplayObject(DisplayObject):
+    """Create a text display object given raw data.
+
+    Parameters
+    ----------
+    data : str or unicode
+        The raw data or a URL or file to load the data from.
+    url : unicode
+        A URL to download the data from.
+    filename : unicode
+        Path to a local file to load the data from.
+    metadata : dict
+        Dict of metadata associated to be the object when displayed
+    """
+    def _check_data(self):
+        if self.data is not None and not isinstance(self.data, str):
+            raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data))
+
+class Pretty(TextDisplayObject):
+
+    def _repr_pretty_(self, pp, cycle):
+        return pp.text(self.data)
+
+
+class HTML(TextDisplayObject):
+
+    def __init__(self, data=None, url=None, filename=None, metadata=None):
+        def warn():
+            if not data:
+                return False
+
+            #
+            # Avoid calling lower() on the entire data, because it could be a
+            # long string and we're only interested in its beginning and end.
+            #
+            prefix = data[:10].lower()
+            suffix = data[-10:].lower()
+            return prefix.startswith("<iframe ") and suffix.endswith("</iframe>")
+
+        if warn():
+            warnings.warn("Consider using IPython.display.IFrame instead")
+        super(HTML, self).__init__(data=data, url=url, filename=filename, metadata=metadata)
+
+    def _repr_html_(self):
+        return self._data_and_metadata()
+
+    def __html__(self):
+        """
+        This method exists to inform other HTML-using modules (e.g. Markupsafe,
+        htmltag, etc) that this object is HTML and does not need things like
+        special characters (<>&) escaped.
+        """
+        return self._repr_html_()
+
+
+class Markdown(TextDisplayObject):
+
+    def _repr_markdown_(self):
+        return self._data_and_metadata()
+
+
+class Math(TextDisplayObject):
+
+    def _repr_latex_(self):
+        s = r"$\displaystyle %s$" % self.data.strip('$')
+        if self.metadata:
+            return s, deepcopy(self.metadata)
+        else:
+            return s
+
+
+class Latex(TextDisplayObject):
+
+    def _repr_latex_(self):
+        return self._data_and_metadata()
+
+
+class SVG(DisplayObject):
+    """Embed an SVG into the display.
+
+    Note if you just want to view a svg image via a URL use `:class:Image` with
+    a url=URL keyword argument.
+    """
+
+    _read_flags = 'rb'
+    # wrap data in a property, which extracts the <svg> tag, discarding
+    # document headers
+    _data: Optional[str] = None
+
+    @property
+    def data(self):
+        return self._data
+
+    @data.setter
+    def data(self, svg):
+        if svg is None:
+            self._data = None
+            return
+        # parse into dom object
+        from xml.dom import minidom
+        x = minidom.parseString(svg)
+        # get svg tag (should be 1)
+        found_svg = x.getElementsByTagName('svg')
+        if found_svg:
+            svg = found_svg[0].toxml()
+        else:
+            # fallback on the input, trust the user
+            # but this is probably an error.
+            pass
+        if isinstance(svg, bytes):
+            self._data = svg.decode(errors="replace")
+        else:
+            self._data = svg
+
+    def _repr_svg_(self):
+        return self._data_and_metadata()
+
+class ProgressBar(DisplayObject):
+    """Progressbar supports displaying a progressbar like element
+    """
+    def __init__(self, total):
+        """Creates a new progressbar
+
+        Parameters
+        ----------
+        total : int
+            maximum size of the progressbar
+        """
+        self.total = total
+        self._progress = 0
+        self.html_width = '60ex'
+        self.text_width = 60
+        self._display_id = hexlify(os.urandom(8)).decode('ascii')
+
+    def __repr__(self):
+        fraction = self.progress / self.total
+        filled = '=' * int(fraction * self.text_width)
+        rest = ' ' * (self.text_width - len(filled))
+        return '[{}{}] {}/{}'.format(
+            filled, rest,
+            self.progress, self.total,
+        )
+
+    def _repr_html_(self):
+        return "<progress style='width:{}' max='{}' value='{}'></progress>".format(
+            self.html_width, self.total, self.progress)
+
+    def display(self):
+        display_functions.display(self, display_id=self._display_id)
+
+    def update(self):
+        display_functions.display(self, display_id=self._display_id, update=True)
+
+    @property
+    def progress(self):
+        return self._progress
+
+    @progress.setter
+    def progress(self, value):
+        self._progress = value
+        self.update()
+
+    def __iter__(self):
+        self.display()
+        self._progress = -1 # First iteration is 0
+        return self
+
+    def __next__(self):
+        """Returns current value and increments display by one."""
+        self.progress += 1
+        if self.progress < self.total:
+            return self.progress
+        else:
+            raise StopIteration()
+
+class JSON(DisplayObject):
+    """JSON expects a JSON-able dict or list
+
+    not an already-serialized JSON string.
+
+    Scalar types (None, number, string) are not allowed, only dict or list containers.
+    """
+    # wrap data in a property, which warns about passing already-serialized JSON
+    _data = None
+    def __init__(self, data=None, url=None, filename=None, expanded=False, metadata=None, root='root', **kwargs):
+        """Create a JSON display object given raw data.
+
+        Parameters
+        ----------
+        data : dict or list
+            JSON data to display. Not an already-serialized JSON string.
+            Scalar types (None, number, string) are not allowed, only dict
+            or list containers.
+        url : unicode
+            A URL to download the data from.
+        filename : unicode
+            Path to a local file to load the data from.
+        expanded : boolean
+            Metadata to control whether a JSON display component is expanded.
+        metadata : dict
+            Specify extra metadata to attach to the json display object.
+        root : str
+            The name of the root element of the JSON tree
+        """
+        self.metadata = {
+            'expanded': expanded,
+            'root': root,
+        }
+        if metadata:
+            self.metadata.update(metadata)
+        if kwargs:
+            self.metadata.update(kwargs)
+        super(JSON, self).__init__(data=data, url=url, filename=filename)
+
+    def _check_data(self):
+        if self.data is not None and not isinstance(self.data, (dict, list)):
+            raise TypeError("%s expects JSONable dict or list, not %r" % (self.__class__.__name__, self.data))
+
+    @property
+    def data(self):
+        return self._data
+
+    @data.setter
+    def data(self, data):
+        if isinstance(data, (Path, PurePath)):
+            data = str(data)
+
+        if isinstance(data, str):
+            if self.filename is None and self.url is None:
+                warnings.warn("JSON expects JSONable dict or list, not JSON strings")
+            data = json.loads(data)
+        self._data = data
+
+    def _data_and_metadata(self):
+        return self.data, self.metadata
+
+    def _repr_json_(self):
+        return self._data_and_metadata()
+
+
+_css_t = """var link = document.createElement("link");
+	link.rel = "stylesheet";
+	link.type = "text/css";
+	link.href = "%s";
+	document.head.appendChild(link);
+"""
+
+_lib_t1 = """new Promise(function(resolve, reject) {
+	var script = document.createElement("script");
+	script.onload = resolve;
+	script.onerror = reject;
+	script.src = "%s";
+	document.head.appendChild(script);
+}).then(() => {
+"""
+
+_lib_t2 = """
+});"""
+
+class GeoJSON(JSON):
+    """GeoJSON expects JSON-able dict
+
+    not an already-serialized JSON string.
+
+    Scalar types (None, number, string) are not allowed, only dict containers.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Create a GeoJSON display object given raw data.
+
+        Parameters
+        ----------
+        data : dict or list
+            VegaLite data. Not an already-serialized JSON string.
+            Scalar types (None, number, string) are not allowed, only dict
+            or list containers.
+        url_template : string
+            Leaflet TileLayer URL template: http://leafletjs.com/reference.html#url-template
+        layer_options : dict
+            Leaflet TileLayer options: http://leafletjs.com/reference.html#tilelayer-options
+        url : unicode
+            A URL to download the data from.
+        filename : unicode
+            Path to a local file to load the data from.
+        metadata : dict
+            Specify extra metadata to attach to the json display object.
+
+        Examples
+        --------
+        The following will display an interactive map of Mars with a point of
+        interest on frontend that do support GeoJSON display.
+
+            >>> from IPython.display import GeoJSON
+
+            >>> GeoJSON(data={
+            ...     "type": "Feature",
+            ...     "geometry": {
+            ...         "type": "Point",
+            ...         "coordinates": [-81.327, 296.038]
+            ...     }
+            ... },
+            ... url_template="http://s3-eu-west-1.amazonaws.com/whereonmars.cartodb.net/{basemap_id}/{z}/{x}/{y}.png",
+            ... layer_options={
+            ...     "basemap_id": "celestia_mars-shaded-16k_global",
+            ...     "attribution" : "Celestia/praesepe",
+            ...     "minZoom" : 0,
+            ...     "maxZoom" : 18,
+            ... })
+            <IPython.core.display.GeoJSON object>
+
+        In the terminal IPython, you will only see the text representation of
+        the GeoJSON object.
+
+        """
+
+        super(GeoJSON, self).__init__(*args, **kwargs)
+
+
+    def _ipython_display_(self):
+        bundle = {
+            'application/geo+json': self.data,
+            'text/plain': '<IPython.display.GeoJSON object>'
+        }
+        metadata = {
+            'application/geo+json': self.metadata
+        }
+        display_functions.display(bundle, metadata=metadata, raw=True)
+
+class Javascript(TextDisplayObject):
+
+    def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
+        """Create a Javascript display object given raw data.
+
+        When this object is returned by an expression or passed to the
+        display function, it will result in the data being displayed
+        in the frontend. If the data is a URL, the data will first be
+        downloaded and then displayed.
+
+        In the Notebook, the containing element will be available as `element`,
+        and jQuery will be available.  Content appended to `element` will be
+        visible in the output area.
+
+        Parameters
+        ----------
+        data : unicode, str or bytes
+            The Javascript source code or a URL to download it from.
+        url : unicode
+            A URL to download the data from.
+        filename : unicode
+            Path to a local file to load the data from.
+        lib : list or str
+            A sequence of Javascript library URLs to load asynchronously before
+            running the source code. The full URLs of the libraries should
+            be given. A single Javascript library URL can also be given as a
+            string.
+        css : list or str
+            A sequence of css files to load before running the source code.
+            The full URLs of the css files should be given. A single css URL
+            can also be given as a string.
+        """
+        if isinstance(lib, str):
+            lib = [lib]
+        elif lib is None:
+            lib = []
+        if isinstance(css, str):
+            css = [css]
+        elif css is None:
+            css = []
+        if not isinstance(lib, (list,tuple)):
+            raise TypeError('expected sequence, got: %r' % lib)
+        if not isinstance(css, (list,tuple)):
+            raise TypeError('expected sequence, got: %r' % css)
+        self.lib = lib
+        self.css = css
+        super(Javascript, self).__init__(data=data, url=url, filename=filename)
+
+    def _repr_javascript_(self):
+        r = ''
+        for c in self.css:
+            r += _css_t % c
+        for l in self.lib:
+            r += _lib_t1 % l
+        r += self.data
+        r += _lib_t2*len(self.lib)
+        return r
+
+
+# constants for identifying png/jpeg/gif/webp data
+_PNG = b"\x89PNG\r\n\x1a\n"
+_JPEG = b"\xff\xd8"
+_GIF1 = b"GIF87a"
+_GIF2 = b"GIF89a"
+_WEBP = b"WEBP"
+
+
+def _pngxy(data):
+    """read the (width, height) from a PNG header"""
+    ihdr = data.index(b'IHDR')
+    # next 8 bytes are width/height
+    return struct.unpack('>ii', data[ihdr+4:ihdr+12])
+
+
+def _jpegxy(data):
+    """read the (width, height) from a JPEG header"""
+    # adapted from http://www.64lines.com/jpeg-width-height
+
+    idx = 4
+    while True:
+        block_size = struct.unpack('>H', data[idx:idx+2])[0]
+        idx = idx + block_size
+        if data[idx:idx+2] == b'\xFF\xC0':
+            # found Start of Frame
+            iSOF = idx
+            break
+        else:
+            # read another block
+            idx += 2
+
+    h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
+    return w, h
+
+
+def _gifxy(data):
+    """read the (width, height) from a GIF header"""
+    return struct.unpack('<HH', data[6:10])
+
+
+def _webpxy(data):
+    """read the (width, height) from a WEBP header"""
+    if data[12:16] == b"VP8 ":
+        width, height = struct.unpack("<HH", data[24:30])
+        width = width & 0x3FFF
+        height = height & 0x3FFF
+        return (width, height)
+    elif data[12:16] == b"VP8L":
+        size_info = struct.unpack("<I", data[21:25])[0]
+        width = 1 + ((size_info & 0x3F) << 8) | (size_info >> 24)
+        height = 1 + (
+            (((size_info >> 8) & 0xF) << 10)
+            | (((size_info >> 14) & 0x3FC) << 2)
+            | ((size_info >> 22) & 0x3)
+        )
+        return (width, height)
+    else:
+        raise ValueError("Not a valid WEBP header")
+
+
+class Image(DisplayObject):
+
+    _read_flags = "rb"
+    _FMT_JPEG = "jpeg"
+    _FMT_PNG = "png"
+    _FMT_GIF = "gif"
+    _FMT_WEBP = "webp"
+    _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG, _FMT_GIF, _FMT_WEBP]
+    _MIMETYPES = {
+        _FMT_PNG: "image/png",
+        _FMT_JPEG: "image/jpeg",
+        _FMT_GIF: "image/gif",
+        _FMT_WEBP: "image/webp",
+    }
+
+    def __init__(
+        self,
+        data=None,
+        url=None,
+        filename=None,
+        format=None,
+        embed=None,
+        width=None,
+        height=None,
+        retina=False,
+        unconfined=False,
+        metadata=None,
+        alt=None,
+    ):
+        """Create a PNG/JPEG/GIF/WEBP image object given raw data.
+
+        When this object is returned by an input cell or passed to the
+        display function, it will result in the image being displayed
+        in the frontend.
+
+        Parameters
+        ----------
+        data : unicode, str or bytes
+            The raw image data or a URL or filename to load the data from.
+            This always results in embedded image data.
+
+        url : unicode
+            A URL to download the data from. If you specify `url=`,
+            the image data will not be embedded unless you also specify `embed=True`.
+
+        filename : unicode
+            Path to a local file to load the data from.
+            Images from a file are always embedded.
+
+        format : unicode
+            The format of the image data (png/jpeg/jpg/gif/webp). If a filename or URL is given
+            for format will be inferred from the filename extension.
+
+        embed : bool
+            Should the image data be embedded using a data URI (True) or be
+            loaded using an <img> tag. Set this to True if you want the image
+            to be viewable later with no internet connection in the notebook.
+
+            Default is `True`, unless the keyword argument `url` is set, then
+            default value is `False`.
+
+            Note that QtConsole is not able to display images if `embed` is set to `False`
+
+        width : int
+            Width in pixels to which to constrain the image in html
+
+        height : int
+            Height in pixels to which to constrain the image in html
+
+        retina : bool
+            Automatically set the width and height to half of the measured
+            width and height.
+            This only works for embedded images because it reads the width/height
+            from image data.
+            For non-embedded images, you can just set the desired display width
+            and height directly.
+
+        unconfined : bool
+            Set unconfined=True to disable max-width confinement of the image.
+
+        metadata : dict
+            Specify extra metadata to attach to the image.
+
+        alt : unicode
+            Alternative text for the image, for use by screen readers.
+
+        Examples
+        --------
+        embedded image data, works in qtconsole and notebook
+        when passed positionally, the first arg can be any of raw image data,
+        a URL, or a filename from which to load image data.
+        The result is always embedding image data for inline images.
+
+        >>> Image('https://www.google.fr/images/srpr/logo3w.png') # doctest: +SKIP
+        <IPython.core.display.Image object>
+
+        >>> Image('/path/to/image.jpg')
+        <IPython.core.display.Image object>
+
+        >>> Image(b'RAW_PNG_DATA...')
+        <IPython.core.display.Image object>
+
+        Specifying Image(url=...) does not embed the image data,
+        it only generates ``<img>`` tag with a link to the source.
+        This will not work in the qtconsole or offline.
+
+        >>> Image(url='https://www.google.fr/images/srpr/logo3w.png')
+        <IPython.core.display.Image object>
+
+        """
+        if isinstance(data, (Path, PurePath)):
+            data = str(data)
+
+        if filename is not None:
+            ext = self._find_ext(filename)
+        elif url is not None:
+            ext = self._find_ext(url)
+        elif data is None:
+            raise ValueError("No image data found. Expecting filename, url, or data.")
+        elif isinstance(data, str) and (
+            data.startswith('http') or _safe_exists(data)
+        ):
+            ext = self._find_ext(data)
+        else:
+            ext = None
+
+        if format is None:
+            if ext is not None:
+                if ext == u'jpg' or ext == u'jpeg':
+                    format = self._FMT_JPEG
+                elif ext == u'png':
+                    format = self._FMT_PNG
+                elif ext == u'gif':
+                    format = self._FMT_GIF
+                elif ext == "webp":
+                    format = self._FMT_WEBP
+                else:
+                    format = ext.lower()
+            elif isinstance(data, bytes):
+                # infer image type from image data header,
+                # only if format has not been specified.
+                if data[:2] == _JPEG:
+                    format = self._FMT_JPEG
+                elif data[:8] == _PNG:
+                    format = self._FMT_PNG
+                elif data[8:12] == _WEBP:
+                    format = self._FMT_WEBP
+                elif data[:6] == _GIF1 or data[:6] == _GIF2:
+                    format = self._FMT_GIF
+
+        # failed to detect format, default png
+        if format is None:
+            format = self._FMT_PNG
+
+        if format.lower() == 'jpg':
+            # jpg->jpeg
+            format = self._FMT_JPEG
+
+        self.format = format.lower()
+        self.embed = embed if embed is not None else (url is None)
+
+        if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
+            raise ValueError("Cannot embed the '%s' image format" % (self.format))
+        if self.embed:
+            self._mimetype = self._MIMETYPES.get(self.format)
+
+        self.width = width
+        self.height = height
+        self.retina = retina
+        self.unconfined = unconfined
+        self.alt = alt
+        super(Image, self).__init__(data=data, url=url, filename=filename,
+                metadata=metadata)
+
+        if self.width is None and self.metadata.get('width', {}):
+            self.width = metadata['width']
+
+        if self.height is None and self.metadata.get('height', {}):
+            self.height = metadata['height']
+
+        if self.alt is None and self.metadata.get("alt", {}):
+            self.alt = metadata["alt"]
+
+        if retina:
+            self._retina_shape()
+
+
+    def _retina_shape(self):
+        """load pixel-doubled width and height from image data"""
+        if not self.embed:
+            return
+        if self.format == self._FMT_PNG:
+            w, h = _pngxy(self.data)
+        elif self.format == self._FMT_JPEG:
+            w, h = _jpegxy(self.data)
+        elif self.format == self._FMT_GIF:
+            w, h = _gifxy(self.data)
+        else:
+            # retina only supports png
+            return
+        self.width = w // 2
+        self.height = h // 2
+
+    def reload(self):
+        """Reload the raw data from file or URL."""
+        if self.embed:
+            super(Image,self).reload()
+            if self.retina:
+                self._retina_shape()
+
+    def _repr_html_(self):
+        if not self.embed:
+            width = height = klass = alt = ""
+            if self.width:
+                width = ' width="%d"' % self.width
+            if self.height:
+                height = ' height="%d"' % self.height
+            if self.unconfined:
+                klass = ' class="unconfined"'
+            if self.alt:
+                alt = ' alt="%s"' % html.escape(self.alt)
+            return '<img src="{url}"{width}{height}{klass}{alt}/>'.format(
+                url=self.url,
+                width=width,
+                height=height,
+                klass=klass,
+                alt=alt,
+            )
+
+    def _repr_mimebundle_(self, include=None, exclude=None):
+        """Return the image as a mimebundle
+
+        Any new mimetype support should be implemented here.
+        """
+        if self.embed:
+            mimetype = self._mimetype
+            data, metadata = self._data_and_metadata(always_both=True)
+            if metadata:
+                metadata = {mimetype: metadata}
+            return {mimetype: data}, metadata
+        else:
+            return {'text/html': self._repr_html_()}
+
+    def _data_and_metadata(self, always_both=False):
+        """shortcut for returning metadata with shape information, if defined"""
+        try:
+            b64_data = b2a_base64(self.data, newline=False).decode("ascii")
+        except TypeError as e:
+            raise FileNotFoundError(
+                "No such file or directory: '%s'" % (self.data)) from e
+        md = {}
+        if self.metadata:
+            md.update(self.metadata)
+        if self.width:
+            md['width'] = self.width
+        if self.height:
+            md['height'] = self.height
+        if self.unconfined:
+            md['unconfined'] = self.unconfined
+        if self.alt:
+            md["alt"] = self.alt
+        if md or always_both:
+            return b64_data, md
+        else:
+            return b64_data
+
+    def _repr_png_(self):
+        if self.embed and self.format == self._FMT_PNG:
+            return self._data_and_metadata()
+
+    def _repr_jpeg_(self):
+        if self.embed and self.format == self._FMT_JPEG:
+            return self._data_and_metadata()
+
+    def _find_ext(self, s):
+        base, ext = splitext(s)
+
+        if not ext:
+            return base
+
+        # `splitext` includes leading period, so we skip it
+        return ext[1:].lower()
+
+
+class Video(DisplayObject):
+
+    def __init__(self, data=None, url=None, filename=None, embed=False,
+                 mimetype=None, width=None, height=None, html_attributes="controls"):
+        """Create a video object given raw data or an URL.
+
+        When this object is returned by an input cell or passed to the
+        display function, it will result in the video being displayed
+        in the frontend.
+
+        Parameters
+        ----------
+        data : unicode, str or bytes
+            The raw video data or a URL or filename to load the data from.
+            Raw data will require passing ``embed=True``.
+
+        url : unicode
+            A URL for the video. If you specify ``url=``,
+            the image data will not be embedded.
+
+        filename : unicode
+            Path to a local file containing the video.
+            Will be interpreted as a local URL unless ``embed=True``.
+
+        embed : bool
+            Should the video be embedded using a data URI (True) or be
+            loaded using a <video> tag (False).
+
+            Since videos are large, embedding them should be avoided, if possible.
+            You must confirm embedding as your intention by passing ``embed=True``.
+
+            Local files can be displayed with URLs without embedding the content, via::
+
+                Video('./video.mp4')
+
+        mimetype : unicode
+            Specify the mimetype for embedded videos.
+            Default will be guessed from file extension, if available.
+
+        width : int
+            Width in pixels to which to constrain the video in HTML.
+            If not supplied, defaults to the width of the video.
+
+        height : int
+            Height in pixels to which to constrain the video in html.
+            If not supplied, defaults to the height of the video.
+
+        html_attributes : str
+            Attributes for the HTML ``<video>`` block.
+            Default: ``"controls"`` to get video controls.
+            Other examples: ``"controls muted"`` for muted video with controls,
+            ``"loop autoplay"`` for looping autoplaying video without controls.
+
+        Examples
+        --------
+        ::
+
+            Video('https://archive.org/download/Sita_Sings_the_Blues/Sita_Sings_the_Blues_small.mp4')
+            Video('path/to/video.mp4')
+            Video('path/to/video.mp4', embed=True)
+            Video('path/to/video.mp4', embed=True, html_attributes="controls muted autoplay")
+            Video(b'raw-videodata', embed=True)
+        """
+        if isinstance(data, (Path, PurePath)):
+            data = str(data)
+
+        if url is None and isinstance(data, str) and data.startswith(('http:', 'https:')):
+            url = data
+            data = None
+        elif data is not None and os.path.exists(data):
+            filename = data
+            data = None
+
+        if data and not embed:
+            msg = ''.join([
+                "To embed videos, you must pass embed=True ",
+                "(this may make your notebook files huge)\n",
+                "Consider passing Video(url='...')",
+            ])
+            raise ValueError(msg)
+
+        self.mimetype = mimetype
+        self.embed = embed
+        self.width = width
+        self.height = height
+        self.html_attributes = html_attributes
+        super(Video, self).__init__(data=data, url=url, filename=filename)
+
+    def _repr_html_(self):
+        width = height = ''
+        if self.width:
+            width = ' width="%d"' % self.width
+        if self.height:
+            height = ' height="%d"' % self.height
+
+        # External URLs and potentially local files are not embedded into the
+        # notebook output.
+        if not self.embed:
+            url = self.url if self.url is not None else self.filename
+            output = """<video src="{0}" {1} {2} {3}>
+      Your browser does not support the <code>video</code> element.
+    </video>""".format(url, self.html_attributes, width, height)
+            return output
+
+        # Embedded videos are base64-encoded.
+        mimetype = self.mimetype
+        if self.filename is not None:
+            if not mimetype:
+                mimetype, _ = mimetypes.guess_type(self.filename)
+
+            with open(self.filename, 'rb') as f:
+                video = f.read()
+        else:
+            video = self.data
+        if isinstance(video, str):
+            # unicode input is already b64-encoded
+            b64_video = video
+        else:
+            b64_video = b2a_base64(video, newline=False).decode("ascii").rstrip()
+
+        output = """<video {0} {1} {2}>
+ <source src="data:{3};base64,{4}" type="{3}">
+ Your browser does not support the video tag.
+ </video>""".format(self.html_attributes, width, height, mimetype, b64_video)
+        return output
+
+    def reload(self):
+        # TODO
+        pass
+
+
+@skip_doctest
+def set_matplotlib_formats(*formats, **kwargs):
+    """
+    .. deprecated:: 7.23
+
+       use `matplotlib_inline.backend_inline.set_matplotlib_formats()`
+
+    Select figure formats for the inline backend. Optionally pass quality for JPEG.
+
+    For example, this enables PNG and JPEG output with a JPEG quality of 90%::
+
+        In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
+
+    To set this in your config files use the following::
+
+        c.InlineBackend.figure_formats = {'png', 'jpeg'}
+        c.InlineBackend.print_figure_kwargs.update({'quality' : 90})
+
+    Parameters
+    ----------
+    *formats : strs
+        One or more figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
+    **kwargs
+        Keyword args will be relayed to ``figure.canvas.print_figure``.
+    """
+    warnings.warn(
+        "`set_matplotlib_formats` is deprecated since IPython 7.23, directly "
+        "use `matplotlib_inline.backend_inline.set_matplotlib_formats()`",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    from matplotlib_inline.backend_inline import (
+        set_matplotlib_formats as set_matplotlib_formats_orig,
+    )
+
+    set_matplotlib_formats_orig(*formats, **kwargs)
+
+@skip_doctest
+def set_matplotlib_close(close=True):
+    """
+    .. deprecated:: 7.23
+
+        use `matplotlib_inline.backend_inline.set_matplotlib_close()`
+
+    Set whether the inline backend closes all figures automatically or not.
+
+    By default, the inline backend used in the IPython Notebook will close all
+    matplotlib figures automatically after each cell is run. This means that
+    plots in different cells won't interfere. Sometimes, you may want to make
+    a plot in one cell and then refine it in later cells. This can be accomplished
+    by::
+
+        In [1]: set_matplotlib_close(False)
+
+    To set this in your config files use the following::
+
+        c.InlineBackend.close_figures = False
+
+    Parameters
+    ----------
+    close : bool
+        Should all matplotlib figures be automatically closed after each cell is
+        run?
+    """
+    warnings.warn(
+        "`set_matplotlib_close` is deprecated since IPython 7.23, directly "
+        "use `matplotlib_inline.backend_inline.set_matplotlib_close()`",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    from matplotlib_inline.backend_inline import (
+        set_matplotlib_close as set_matplotlib_close_orig,
+    )
+
+    set_matplotlib_close_orig(close)

openalex_env_map/lib/python3.10/site-packages/IPython/core/display_functions.py

@@ -0,0 +1,391 @@
+# -*- coding: utf-8 -*-
+"""Top-level display functions for displaying object in different formats."""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+
+from binascii import b2a_hex
+import os
+import sys
+import warnings
+
+__all__ = ['display', 'clear_output', 'publish_display_data', 'update_display', 'DisplayHandle']
+
+#-----------------------------------------------------------------------------
+# utility functions
+#-----------------------------------------------------------------------------
+
+
+def _merge(d1, d2):
+    """Like update, but merges sub-dicts instead of clobbering at the top level.
+
+    Updates d1 in-place
+    """
+
+    if not isinstance(d2, dict) or not isinstance(d1, dict):
+        return d2
+    for key, value in d2.items():
+        d1[key] = _merge(d1.get(key), value)
+    return d1
+
+
+#-----------------------------------------------------------------------------
+# Main functions
+#-----------------------------------------------------------------------------
+
+class _Sentinel:
+    def __repr__(self):
+        return "<deprecated>"
+
+
+_sentinel = _Sentinel()
+
+# use * to indicate transient is keyword-only
+def publish_display_data(
+    data, metadata=None, source=_sentinel, *, transient=None, **kwargs
+):
+    """Publish data and metadata to all frontends.
+
+    See the ``display_data`` message in the messaging documentation for
+    more details about this message type.
+
+    Keys of data and metadata can be any mime-type.
+
+    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. mime-type keys matching those in data can be used
+        to specify metadata about particular representations.
+    source : str, deprecated
+        Unused.
+    transient : dict, keyword-only
+        A dictionary of transient data, such as display_id.
+    """
+    from IPython.core.interactiveshell import InteractiveShell
+
+    if source is not _sentinel:
+        warnings.warn(
+            "The `source` parameter emit a  deprecation warning since"
+            " IPython 8.0, it had no effects for a long time and will "
+            " be removed in future versions.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    display_pub = InteractiveShell.instance().display_pub
+
+    # only pass transient if supplied,
+    # to avoid errors with older ipykernel.
+    # TODO: We could check for ipykernel version and provide a detailed upgrade message.
+    if transient:
+        kwargs['transient'] = transient
+
+    display_pub.publish(
+        data=data,
+        metadata=metadata,
+        **kwargs
+    )
+
+
+def _new_id():
+    """Generate a new random text id with urandom"""
+    return b2a_hex(os.urandom(16)).decode('ascii')
+
+
+def display(
+    *objs,
+    include=None,
+    exclude=None,
+    metadata=None,
+    transient=None,
+    display_id=None,
+    raw=False,
+    clear=False,
+    **kwargs,
+):
+    """Display a Python object in all frontends.
+
+    By default all representations will be computed and sent to the frontends.
+    Frontends can decide which representation is used and how.
+
+    In terminal IPython this will be similar to using :func:`print`, for use in richer
+    frontends see Jupyter notebook examples with rich display logic.
+
+    Parameters
+    ----------
+    *objs : object
+        The Python objects to display.
+    raw : bool, optional
+        Are the objects to be displayed already mimetype-keyed dicts of raw display data,
+        or Python objects that need to be formatted before display? [default: False]
+    include : list, tuple or set, optional
+        A list of format type strings (MIME types) to include in the
+        format data dict. If this is set *only* the format types included
+        in this list will be computed.
+    exclude : list, tuple or set, optional
+        A list of format type strings (MIME types) to exclude in the format
+        data dict. If this is set all format types will be computed,
+        except for those included in this argument.
+    metadata : dict, optional
+        A dictionary of metadata to associate with the output.
+        mime-type keys in this dictionary will be associated with the individual
+        representation formats, if they exist.
+    transient : dict, optional
+        A dictionary of transient data to associate with the output.
+        Data in this dict should not be persisted to files (e.g. notebooks).
+    display_id : str, bool optional
+        Set an id for the display.
+        This id can be used for updating this display area later via update_display.
+        If given as `True`, generate a new `display_id`
+    clear : bool, optional
+        Should the output area be cleared before displaying anything? If True,
+        this will wait for additional output before clearing. [default: False]
+    **kwargs : additional keyword-args, optional
+        Additional keyword-arguments are passed through to the display publisher.
+
+    Returns
+    -------
+    handle: DisplayHandle
+        Returns a handle on updatable displays for use with :func:`update_display`,
+        if `display_id` is given. Returns :any:`None` if no `display_id` is given
+        (default).
+
+    Examples
+    --------
+    >>> class Json(object):
+    ...     def __init__(self, json):
+    ...         self.json = json
+    ...     def _repr_pretty_(self, pp, cycle):
+    ...         import json
+    ...         pp.text(json.dumps(self.json, indent=2))
+    ...     def __repr__(self):
+    ...         return str(self.json)
+    ...
+
+    >>> d = Json({1:2, 3: {4:5}})
+
+    >>> print(d)
+    {1: 2, 3: {4: 5}}
+
+    >>> display(d)
+    {
+      "1": 2,
+      "3": {
+        "4": 5
+      }
+    }
+
+    >>> def int_formatter(integer, pp, cycle):
+    ...     pp.text('I'*integer)
+
+    >>> plain = get_ipython().display_formatter.formatters['text/plain']
+    >>> plain.for_type(int, int_formatter)
+    <function _repr_pprint at 0x...>
+    >>> display(7-5)
+    II
+
+    >>> del plain.type_printers[int]
+    >>> display(7-5)
+    2
+
+    See Also
+    --------
+    :func:`update_display`
+
+    Notes
+    -----
+    In Python, objects can declare their textual representation using the
+    `__repr__` method. IPython expands on this idea and allows objects to declare
+    other, rich representations including:
+
+      - HTML
+      - JSON
+      - PNG
+      - JPEG
+      - SVG
+      - LaTeX
+
+    A single object can declare some or all of these representations; all are
+    handled by IPython's display system.
+
+    The main idea of the first approach is that you have to implement special
+    display methods when you define your class, one for each representation you
+    want to use. Here is a list of the names of the special methods and the
+    values they must return:
+
+      - `_repr_html_`: return raw HTML as a string, or a tuple (see below).
+      - `_repr_json_`: return a JSONable dict, or a tuple (see below).
+      - `_repr_jpeg_`: return raw JPEG data, or a tuple (see below).
+      - `_repr_png_`: return raw PNG data, or a tuple (see below).
+      - `_repr_svg_`: return raw SVG data as a string, or a tuple (see below).
+      - `_repr_latex_`: return LaTeX commands in a string surrounded by "$",
+                        or a tuple (see below).
+      - `_repr_mimebundle_`: return a full mimebundle containing the mapping
+                             from all mimetypes to data.
+                             Use this for any mime-type not listed above.
+
+    The above functions may also return the object's metadata alonside the
+    data.  If the metadata is available, the functions will return a tuple
+    containing the data and metadata, in that order.  If there is no metadata
+    available, then the functions will return the data only.
+
+    When you are directly writing your own classes, you can adapt them for
+    display in IPython by following the above approach. But in practice, you
+    often need to work with existing classes that you can't easily modify.
+
+    You can refer to the documentation on integrating with the display system in
+    order to register custom formatters for already existing types
+    (:ref:`integrating_rich_display`).
+
+    .. versionadded:: 5.4 display available without import
+    .. versionadded:: 6.1 display available without import
+
+    Since IPython 5.4 and 6.1 :func:`display` is automatically made available to
+    the user without import. If you are using display in a document that might
+    be used in a pure python context or with older version of IPython, use the
+    following import at the top of your file::
+
+        from IPython.display import display
+
+    """
+    from IPython.core.interactiveshell import InteractiveShell
+
+    if not InteractiveShell.initialized():
+        # Directly print objects.
+        print(*objs)
+        return
+
+    if transient is None:
+        transient = {}
+    if metadata is None:
+        metadata={}
+    if display_id:
+        if display_id is True:
+            display_id = _new_id()
+        transient['display_id'] = display_id
+    if kwargs.get('update') and 'display_id' not in transient:
+        raise TypeError('display_id required for update_display')
+    if transient:
+        kwargs['transient'] = transient
+
+    if not objs and display_id:
+        # if given no objects, but still a request for a display_id,
+        # we assume the user wants to insert an empty output that
+        # can be updated later
+        objs = [{}]
+        raw = True
+
+    if not raw:
+        format = InteractiveShell.instance().display_formatter.format
+
+    if clear:
+        clear_output(wait=True)
+
+    for obj in objs:
+        if raw:
+            publish_display_data(data=obj, metadata=metadata, **kwargs)
+        else:
+            format_dict, md_dict = format(obj, include=include, exclude=exclude)
+            if not format_dict:
+                # nothing to display (e.g. _ipython_display_ took over)
+                continue
+            if metadata:
+                # kwarg-specified metadata gets precedence
+                _merge(md_dict, metadata)
+            publish_display_data(data=format_dict, metadata=md_dict, **kwargs)
+    if display_id:
+        return DisplayHandle(display_id)
+
+
+# use * for keyword-only display_id arg
+def update_display(obj, *, display_id, **kwargs):
+    """Update an existing display by id
+
+    Parameters
+    ----------
+    obj
+        The object with which to update the display
+    display_id : keyword-only
+        The id of the display to update
+
+    See Also
+    --------
+    :func:`display`
+    """
+    kwargs['update'] = True
+    display(obj, display_id=display_id, **kwargs)
+
+
+class DisplayHandle(object):
+    """A handle on an updatable display
+
+    Call `.update(obj)` to display a new object.
+
+    Call `.display(obj`) to add a new instance of this display,
+    and update existing instances.
+
+    See Also
+    --------
+
+        :func:`display`, :func:`update_display`
+
+    """
+
+    def __init__(self, display_id=None):
+        if display_id is None:
+            display_id = _new_id()
+        self.display_id = display_id
+
+    def __repr__(self):
+        return "<%s display_id=%s>" % (self.__class__.__name__, self.display_id)
+
+    def display(self, obj, **kwargs):
+        """Make a new display with my id, updating existing instances.
+
+        Parameters
+        ----------
+        obj
+            object to display
+        **kwargs
+            additional keyword arguments passed to display
+        """
+        display(obj, display_id=self.display_id, **kwargs)
+
+    def update(self, obj, **kwargs):
+        """Update existing displays with my id
+
+        Parameters
+        ----------
+        obj
+            object to display
+        **kwargs
+            additional keyword arguments passed to update_display
+        """
+        update_display(obj, display_id=self.display_id, **kwargs)
+
+
+def clear_output(wait=False):
+    """Clear the output of the current cell receiving output.
+
+    Parameters
+    ----------
+    wait : bool [default: false]
+        Wait to clear the output until new output is available to replace it."""
+    from IPython.core.interactiveshell import InteractiveShell
+    if InteractiveShell.initialized():
+        InteractiveShell.instance().display_pub.clear_output(wait)
+    else:
+        print('\033[2K\r', end='')
+        sys.stdout.flush()
+        print('\033[2K\r', end='')
+        sys.stderr.flush()

openalex_env_map/lib/python3.10/site-packages/IPython/core/display_trap.py

@@ -0,0 +1,70 @@
+# encoding: utf-8
+"""
+A context manager for handling sys.displayhook.
+
+Authors:
+
+* Robert Kern
+* Brian Granger
+"""
+
+#-----------------------------------------------------------------------------
+#  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
+
+from traitlets.config.configurable import Configurable
+from traitlets import Any
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+
+class DisplayTrap(Configurable):
+    """Object to manage sys.displayhook.
+
+    This came from IPython.core.kernel.display_hook, but is simplified
+    (no callbacks or formatters) until more of the core is refactored.
+    """
+
+    hook = Any()
+
+    def __init__(self, hook=None):
+        super(DisplayTrap, self).__init__(hook=hook, config=None)
+        self.old_hook = None
+        # We define this to track if a single BuiltinTrap is nested.
+        # Only turn off the trap when the outermost call to __exit__ is made.
+        self._nested_level = 0
+
+    def __enter__(self):
+        if self._nested_level == 0:
+            self.set()
+        self._nested_level += 1
+        return self
+
+    def __exit__(self, type, value, traceback):
+        if self._nested_level == 1:
+            self.unset()
+        self._nested_level -= 1
+        # Returning False will cause exceptions to propagate
+        return False
+
+    def set(self):
+        """Set the hook."""
+        if sys.displayhook is not self.hook:
+            self.old_hook = sys.displayhook
+            sys.displayhook = self.hook
+
+    def unset(self):
+        """Unset the hook."""
+        sys.displayhook = self.old_hook
+

openalex_env_map/lib/python3.10/site-packages/IPython/core/displayhook.py

@@ -0,0 +1,336 @@
+# -*- coding: utf-8 -*-
+"""Displayhook for IPython.
+
+This defines a callable class that IPython uses for `sys.displayhook`.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import builtins as builtin_mod
+import sys
+import io as _io
+import tokenize
+
+from traitlets.config.configurable import Configurable
+from traitlets import Instance, Float
+from warnings import warn
+
+# TODO: Move the various attributes (cache_size, [others now moved]). Some
+# of these are also attributes of InteractiveShell. They should be on ONE object
+# only and the other objects should ask that one object for their values.
+
+class DisplayHook(Configurable):
+    """The custom IPython displayhook to replace sys.displayhook.
+
+    This class does many things, but the basic idea is that it is a callable
+    that gets called anytime user code returns a value.
+    """
+
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC',
+                     allow_none=True)
+    exec_result = Instance('IPython.core.interactiveshell.ExecutionResult',
+                           allow_none=True)
+    cull_fraction = Float(0.2)
+
+    def __init__(self, shell=None, cache_size=1000, **kwargs):
+        super(DisplayHook, self).__init__(shell=shell, **kwargs)
+        cache_size_min = 3
+        if cache_size <= 0:
+            self.do_full_cache = 0
+            cache_size = 0
+        elif cache_size < cache_size_min:
+            self.do_full_cache = 0
+            cache_size = 0
+            warn('caching was disabled (min value for cache size is %s).' %
+                 cache_size_min,stacklevel=3)
+        else:
+            self.do_full_cache = 1
+
+        self.cache_size = cache_size
+
+        # we need a reference to the user-level namespace
+        self.shell = shell
+        
+        self._,self.__,self.___ = '','',''
+
+        # these are deliberately global:
+        to_user_ns = {'_':self._,'__':self.__,'___':self.___}
+        self.shell.user_ns.update(to_user_ns)
+
+    @property
+    def prompt_count(self):
+        return self.shell.execution_count
+
+    #-------------------------------------------------------------------------
+    # Methods used in __call__. Override these methods to modify the behavior
+    # of the displayhook.
+    #-------------------------------------------------------------------------
+
+    def check_for_underscore(self):
+        """Check if the user has set the '_' variable by hand."""
+        # If something injected a '_' variable in __builtin__, delete
+        # ipython's automatic one so we don't clobber that.  gettext() in
+        # particular uses _, so we need to stay away from it.
+        if '_' in builtin_mod.__dict__:
+            try:
+                user_value = self.shell.user_ns['_']
+                if user_value is not self._:
+                    return
+                del self.shell.user_ns['_']
+            except KeyError:
+                pass
+
+    def quiet(self):
+        """Should we silence the display hook because of ';'?"""
+        # do not print output if input ends in ';'
+        
+        try:
+            cell = self.shell.history_manager.input_hist_parsed[-1]
+        except IndexError:
+            # some uses of ipshellembed may fail here
+            return False
+        
+        return self.semicolon_at_end_of_expression(cell)
+
+    @staticmethod
+    def semicolon_at_end_of_expression(expression):
+        """Parse Python expression and detects whether last token is ';'"""
+
+        sio = _io.StringIO(expression)
+        tokens = list(tokenize.generate_tokens(sio.readline))
+
+        for token in reversed(tokens):
+            if token[0] in (tokenize.ENDMARKER, tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT):
+                continue
+            if (token[0] == tokenize.OP) and (token[1] == ';'):
+                return True
+            else:
+                return False
+
+    def start_displayhook(self):
+        """Start the displayhook, initializing resources."""
+        pass
+
+    def write_output_prompt(self):
+        """Write the output prompt.
+
+        The default implementation simply writes the prompt to
+        ``sys.stdout``.
+        """
+        # Use write, not print which adds an extra space.
+        sys.stdout.write(self.shell.separate_out)
+        outprompt = 'Out[{}]: '.format(self.shell.execution_count)
+        if self.do_full_cache:
+            sys.stdout.write(outprompt)
+
+    def compute_format_data(self, result):
+        """Compute format data of the object to be displayed.
+
+        The format data is a generalization of the :func:`repr` of an object.
+        In the default implementation the format data is a :class:`dict` of
+        key value pair where the keys are valid MIME types and the values
+        are JSON'able data structure containing the raw data for that MIME
+        type. It is up to frontends to determine pick a MIME to to use and
+        display that data in an appropriate manner.
+
+        This method only computes the format data for the object and should
+        NOT actually print or write that to a stream.
+
+        Parameters
+        ----------
+        result : object
+            The Python object passed to the display hook, whose format will be
+            computed.
+
+        Returns
+        -------
+        (format_dict, md_dict) : dict
+            format_dict is a :class:`dict` whose keys are valid MIME types and values are
+            JSON'able raw data for that MIME type. It is recommended that
+            all return values of this should always include the "text/plain"
+            MIME type representation of the object.
+            md_dict is a :class:`dict` with the same MIME type keys
+            of metadata associated with each output.
+
+        """
+        return self.shell.display_formatter.format(result)
+
+    # This can be set to True by the write_output_prompt method in a subclass
+    prompt_end_newline = False
+
+    def write_format_data(self, format_dict, md_dict=None) -> None:
+        """Write the format data dict to the frontend.
+
+        This default version of this method simply writes the plain text
+        representation of the object to ``sys.stdout``. Subclasses should
+        override this method to send the entire `format_dict` to the
+        frontends.
+
+        Parameters
+        ----------
+        format_dict : dict
+            The format dict for the object passed to `sys.displayhook`.
+        md_dict : dict (optional)
+            The metadata dict to be associated with the display data.
+        """
+        if 'text/plain' not in format_dict:
+            # nothing to do
+            return
+        # We want to print because we want to always make sure we have a
+        # newline, even if all the prompt separators are ''. This is the
+        # standard IPython behavior.
+        result_repr = format_dict['text/plain']
+        if '\n' in result_repr:
+            # So that multi-line strings line up with the left column of
+            # the screen, instead of having the output prompt mess up
+            # their first line.
+            # We use the prompt template instead of the expanded prompt
+            # because the expansion may add ANSI escapes that will interfere
+            # with our ability to determine whether or not we should add
+            # a newline.
+            if not self.prompt_end_newline:
+                # But avoid extraneous empty lines.
+                result_repr = '\n' + result_repr
+
+        try:
+            print(result_repr)
+        except UnicodeEncodeError:
+            # If a character is not supported by the terminal encoding replace
+            # it with its \u or \x representation
+            print(result_repr.encode(sys.stdout.encoding,'backslashreplace').decode(sys.stdout.encoding))
+
+    def update_user_ns(self, result):
+        """Update user_ns with various things like _, __, _1, etc."""
+
+        # Avoid recursive reference when displaying _oh/Out
+        if self.cache_size and result is not self.shell.user_ns['_oh']:
+            if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
+                self.cull_cache()
+
+            # Don't overwrite '_' and friends if '_' is in __builtin__
+            # (otherwise we cause buggy behavior for things like gettext). and
+            # do not overwrite _, __ or ___ if one of these has been assigned
+            # by the user.
+            update_unders = True
+            for unders in ['_'*i for i in range(1,4)]:
+                if not unders in self.shell.user_ns:
+                    continue
+                if getattr(self, unders) is not self.shell.user_ns.get(unders):
+                    update_unders = False
+
+            self.___ = self.__
+            self.__ = self._
+            self._ = result
+
+            if ('_' not in builtin_mod.__dict__) and (update_unders):
+                self.shell.push({'_':self._,
+                                 '__':self.__,
+                                '___':self.___}, interactive=False)
+
+            # hackish access to top-level  namespace to create _1,_2... dynamically
+            to_main = {}
+            if self.do_full_cache:
+                new_result = '_%s' % self.prompt_count
+                to_main[new_result] = result
+                self.shell.push(to_main, interactive=False)
+                self.shell.user_ns['_oh'][self.prompt_count] = result
+
+    def fill_exec_result(self, result):
+        if self.exec_result is not None:
+            self.exec_result.result = result
+
+    def log_output(self, format_dict):
+        """Log the output."""
+        if 'text/plain' not in format_dict:
+            # nothing to do
+            return
+        if self.shell.logger.log_output:
+            self.shell.logger.log_write(format_dict['text/plain'], 'output')
+        self.shell.history_manager.output_hist_reprs[self.prompt_count] = \
+                                                    format_dict['text/plain']
+
+    def finish_displayhook(self):
+        """Finish up all displayhook activities."""
+        sys.stdout.write(self.shell.separate_out2)
+        sys.stdout.flush()
+
+    def __call__(self, result=None):
+        """Printing with history cache management.
+
+        This is invoked every time the interpreter needs to print, and is
+        activated by setting the variable sys.displayhook to it.
+        """
+        self.check_for_underscore()
+        if result is not None and not self.quiet():
+            self.start_displayhook()
+            self.write_output_prompt()
+            format_dict, md_dict = self.compute_format_data(result)
+            self.update_user_ns(result)
+            self.fill_exec_result(result)
+            if format_dict:
+                self.write_format_data(format_dict, md_dict)
+                self.log_output(format_dict)
+            self.finish_displayhook()
+
+    def cull_cache(self):
+        """Output cache is full, cull the oldest entries"""
+        oh = self.shell.user_ns.get('_oh', {})
+        sz = len(oh)
+        cull_count = max(int(sz * self.cull_fraction), 2)
+        warn('Output cache limit (currently {sz} entries) hit.\n'
+             'Flushing oldest {cull_count} entries.'.format(sz=sz, cull_count=cull_count))
+        
+        for i, n in enumerate(sorted(oh)):
+            if i >= cull_count:
+                break
+            self.shell.user_ns.pop('_%i' % n, None)
+            oh.pop(n, None)
+        
+
+    def flush(self):
+        if not self.do_full_cache:
+            raise ValueError("You shouldn't have reached the cache flush "
+                             "if full caching is not enabled!")
+        # delete auto-generated vars from global namespace
+
+        for n in range(1,self.prompt_count + 1):
+            key = '_'+repr(n)
+            try:
+                del self.shell.user_ns_hidden[key]
+            except KeyError:
+                pass
+            try:
+                del self.shell.user_ns[key]
+            except KeyError:
+                pass
+        # In some embedded circumstances, the user_ns doesn't have the
+        # '_oh' key set up.
+        oh = self.shell.user_ns.get('_oh', None)
+        if oh is not None:
+            oh.clear()
+
+        # Release our own references to objects:
+        self._, self.__, self.___ = '', '', ''
+
+        if '_' not in builtin_mod.__dict__:
+            self.shell.user_ns.update({'_':self._,'__':self.__,'___':self.___})
+        import gc
+        # TODO: Is this really needed?
+        # IronPython blocks here forever
+        if sys.platform != "cli":
+            gc.collect()
+
+
+class CapturingDisplayHook(object):
+    def __init__(self, shell, outputs=None):
+        self.shell = shell
+        if outputs is None:
+            outputs = []
+        self.outputs = outputs
+
+    def __call__(self, result=None):
+        if result is None:
+            return
+        format_dict, md_dict = self.shell.display_formatter.format(result)
+        self.outputs.append({ 'data': format_dict, 'metadata': md_dict })

openalex_env_map/lib/python3.10/site-packages/IPython/core/displaypub.py

@@ -0,0 +1,149 @@
+"""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
+
+import typing as t
+
+# -----------------------------------------------------------------------------
+# Main payload class
+#-----------------------------------------------------------------------------
+
+
+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
+        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)
+
+    # use * to indicate transient, update are keyword-only
+    def publish(self, data, metadata=None, source=None, *, 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.
+        """
+
+        handlers: t.Dict = {}
+        if self.shell is not None:
+            handlers = getattr(self.shell, "mime_renderers", {})
+
+        for mime, handler in handlers.items():
+            if mime in data:
+                handler(data[mime], metadata.get(mime, None))
+                return
+
+        if 'text/plain' in data:
+            print(data['text/plain'])
+
+    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()

openalex_env_map/lib/python3.10/site-packages/IPython/core/error.py

@@ -0,0 +1,60 @@
+# encoding: utf-8
+"""
+Global exception classes for IPython.core.
+
+Authors:
+
+* Brian Granger
+* Fernando Perez
+* Min Ragan-Kelley
+
+Notes
+-----
+"""
+
+#-----------------------------------------------------------------------------
+#  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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Exception classes
+#-----------------------------------------------------------------------------
+
+class IPythonCoreError(Exception):
+    pass
+
+
+class TryNext(IPythonCoreError):
+    """Try next hook exception.
+
+    Raise this in your hook function to indicate that the next hook handler
+    should be used to handle the operation.
+    """
+
+class UsageError(IPythonCoreError):
+    """Error in magic function arguments, etc.
+
+    Something that probably won't warrant a full traceback, but should
+    nevertheless interrupt a macro / batch file.
+    """
+
+class StdinNotImplementedError(IPythonCoreError, NotImplementedError):
+    """raw_input was requested in a context where it is not supported
+
+    For use in IPython kernels, where only some frontends may support
+    stdin requests.
+    """
+
+class InputRejected(Exception):
+    """Input rejected by ast transformer.
+
+    Raise this in your NodeTransformer to indicate that InteractiveShell should
+    not execute the supplied input.
+    """

openalex_env_map/lib/python3.10/site-packages/IPython/core/events.py

@@ -0,0 +1,158 @@
+"""Infrastructure for registering and firing callbacks on application events.
+
+Unlike :mod:`IPython.core.hooks`, which lets end users set single functions to
+be called at specific times, or a collection of alternative methods to try,
+callbacks are designed to be used by extension authors. A number of callbacks
+can be registered for the same event without needing to be aware of one another.
+
+The functions defined in this module are no-ops indicating the names of available
+events and the arguments which will be passed to them.
+
+.. note::
+
+   This API is experimental in IPython 2.0, and may be revised in future versions.
+"""
+
+
+class EventManager(object):
+    """Manage a collection of events and a sequence of callbacks for each.
+    
+    This is attached to :class:`~IPython.core.interactiveshell.InteractiveShell`
+    instances as an ``events`` attribute.
+    
+    .. note::
+
+       This API is experimental in IPython 2.0, and may be revised in future versions.
+    """
+
+    def __init__(self, shell, available_events, print_on_error=True):
+        """Initialise the :class:`CallbackManager`.
+
+        Parameters
+        ----------
+        shell
+            The :class:`~IPython.core.interactiveshell.InteractiveShell` instance
+        available_events
+            An iterable of names for callback events.
+        print_on_error:
+            A boolean flag to set whether the EventManager will print a warning which a event errors.
+        """
+        self.shell = shell
+        self.callbacks = {n:[] for n in available_events}
+        self.print_on_error = print_on_error
+    
+    def register(self, event, function):
+        """Register a new event callback.
+
+        Parameters
+        ----------
+        event : str
+            The event for which to register this callback.
+        function : callable
+            A function to be called on the given event. It should take the same
+            parameters as the appropriate callback prototype.
+
+        Raises
+        ------
+        TypeError
+            If ``function`` is not callable.
+        KeyError
+            If ``event`` is not one of the known events.
+        """
+        if not callable(function):
+            raise TypeError('Need a callable, got %r' % function)
+        if function not in self.callbacks[event]:
+            self.callbacks[event].append(function)
+    
+    def unregister(self, event, function):
+        """Remove a callback from the given event."""
+        if function in self.callbacks[event]:
+            return self.callbacks[event].remove(function)
+
+        raise ValueError('Function {!r} is not registered as a {} callback'.format(function, event))
+
+    def trigger(self, event, *args, **kwargs):
+        """Call callbacks for ``event``.
+
+        Any additional arguments are passed to all callbacks registered for this
+        event. Exceptions raised by callbacks are caught, and a message printed.
+        """
+        for func in self.callbacks[event][:]:
+            try:
+                func(*args, **kwargs)
+            except (Exception, KeyboardInterrupt):
+                if self.print_on_error:
+                    print(
+                        "Error in callback {} (for {}), with arguments args {},kwargs {}:".format(
+                            func, event, args, kwargs
+                        )
+                    )
+                self.shell.showtraceback()
+
+# event_name -> prototype mapping
+available_events = {}
+
+def _define_event(callback_function):
+    available_events[callback_function.__name__] = callback_function
+    return callback_function
+
+# ------------------------------------------------------------------------------
+# Callback prototypes
+#
+# No-op functions which describe the names of available events and the
+# signatures of callbacks for those events.
+# ------------------------------------------------------------------------------
+
+@_define_event
+def pre_execute():
+    """Fires before code is executed in response to user/frontend action.
+
+    This includes comm and widget messages and silent execution, as well as user
+    code cells.
+    """
+    pass
+
+@_define_event
+def pre_run_cell(info):
+    """Fires before user-entered code runs.
+
+    Parameters
+    ----------
+    info : :class:`~IPython.core.interactiveshell.ExecutionInfo`
+        An object containing information used for the code execution.
+    """
+    pass
+
+@_define_event
+def post_execute():
+    """Fires after code is executed in response to user/frontend action.
+
+    This includes comm and widget messages and silent execution, as well as user
+    code cells.
+    """
+    pass
+
+@_define_event
+def post_run_cell(result):
+    """Fires after user-entered code runs.
+
+    Parameters
+    ----------
+    result : :class:`~IPython.core.interactiveshell.ExecutionResult`
+        The object which will be returned as the execution result.
+    """
+    pass
+
+@_define_event
+def shell_initialized(ip):
+    """Fires after initialisation of :class:`~IPython.core.interactiveshell.InteractiveShell`.
+
+    This is before extensions and startup scripts are loaded, so it can only be
+    set by subclassing.
+
+    Parameters
+    ----------
+    ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
+        The newly initialised shell.
+    """
+    pass

openalex_env_map/lib/python3.10/site-packages/IPython/core/excolors.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""
+Color schemes for exception handling code in IPython.
+"""
+
+import os
+
+#*****************************************************************************
+#       Copyright (C) 2005-2006 Fernando Perez <[email protected]>
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#*****************************************************************************
+
+from IPython.utils.coloransi import ColorSchemeTable, TermColors, ColorScheme
+
+def exception_colors():
+    """Return a color table with fields for exception reporting.
+
+    The table is an instance of ColorSchemeTable with schemes added for
+    'Neutral', 'Linux', 'LightBG' and 'NoColor' and fields for exception handling filled
+    in.
+
+    Examples:
+
+    >>> ec = exception_colors()
+    >>> ec.active_scheme_name
+    ''
+    >>> print(ec.active_colors)
+    None
+
+    Now we activate a color scheme:
+    >>> ec.set_active_scheme('NoColor')
+    >>> ec.active_scheme_name
+    'NoColor'
+    >>> sorted(ec.active_colors.keys())
+    ['Normal', 'breakpoint_disabled', 'breakpoint_enabled', 'caret', 'em',
+    'excName', 'filename', 'filenameEm', 'line', 'lineno', 'linenoEm', 'name',
+    'nameEm', 'normalEm', 'prompt', 'topline', 'vName', 'val', 'valEm']
+
+    """
+
+    ex_colors = ColorSchemeTable()
+
+    # Populate it with color schemes
+    C = TermColors  # shorthand and local lookup
+    ex_colors.add_scheme(
+        ColorScheme(
+            "NoColor",
+            {
+                # The color to be used for the top line
+                "topline": C.NoColor,
+
+                # The colors to be used in the traceback
+                "filename": C.NoColor,
+                "lineno": C.NoColor,
+                "name": C.NoColor,
+                "vName": C.NoColor,
+                "val": C.NoColor,
+                "em": C.NoColor,
+
+                # Emphasized colors for the last frame of the traceback
+                "normalEm": C.NoColor,
+                "filenameEm": C.NoColor,
+                "linenoEm": C.NoColor,
+                "nameEm": C.NoColor,
+                "valEm": C.NoColor,
+
+                # Colors for printing the exception
+                "excName": C.NoColor,
+                "line": C.NoColor,
+                "caret": C.NoColor,
+                "Normal": C.NoColor,
+                # debugger
+                "prompt": C.NoColor,
+                "breakpoint_enabled": C.NoColor,
+                "breakpoint_disabled": C.NoColor,
+            },
+        )
+    )
+
+    # make some schemes as instances so we can copy them for modification easily
+    ex_colors.add_scheme(
+        ColorScheme(
+            "Linux",
+            {
+                # The color to be used for the top line
+                "topline": C.LightRed,
+                # The colors to be used in the traceback
+                "filename": C.Green,
+                "lineno": C.Green,
+                "name": C.Purple,
+                "vName": C.Cyan,
+                "val": C.Green,
+                "em": C.LightCyan,
+                # Emphasized colors for the last frame of the traceback
+                "normalEm": C.LightCyan,
+                "filenameEm": C.LightGreen,
+                "linenoEm": C.LightGreen,
+                "nameEm": C.LightPurple,
+                "valEm": C.LightBlue,
+                # Colors for printing the exception
+                "excName": C.LightRed,
+                "line": C.Yellow,
+                "caret": C.White,
+                "Normal": C.Normal,
+                # debugger
+                "prompt": C.Green,
+                "breakpoint_enabled": C.LightRed,
+                "breakpoint_disabled": C.Red,
+            },
+        )
+    )
+
+    # For light backgrounds, swap dark/light colors
+    ex_colors.add_scheme(
+        ColorScheme(
+            "LightBG",
+            {
+                # The color to be used for the top line
+                "topline": C.Red,
+
+                # The colors to be used in the traceback
+                "filename": C.LightGreen,
+                "lineno": C.LightGreen,
+                "name": C.LightPurple,
+                "vName": C.Cyan,
+                "val": C.LightGreen,
+                "em": C.Cyan,
+
+                # Emphasized colors for the last frame of the traceback
+                "normalEm": C.Cyan,
+                "filenameEm": C.Green,
+                "linenoEm": C.Green,
+                "nameEm": C.Purple,
+                "valEm": C.Blue,
+
+                # Colors for printing the exception
+                "excName": C.Red,
+                # "line": C.Brown,  # brown often is displayed as yellow
+                "line": C.Red,
+                "caret": C.Normal,
+                "Normal": C.Normal,
+                # debugger
+                "prompt": C.Blue,
+                "breakpoint_enabled": C.LightRed,
+                "breakpoint_disabled": C.Red,
+            },
+        )
+    )
+
+    ex_colors.add_scheme(
+        ColorScheme(
+            "Neutral",
+            {
+                # The color to be used for the top line
+                "topline": C.Red,
+                # The colors to be used in the traceback
+                "filename": C.LightGreen,
+                "lineno": C.LightGreen,
+                "name": C.LightPurple,
+                "vName": C.Cyan,
+                "val": C.LightGreen,
+                "em": C.Cyan,
+                # Emphasized colors for the last frame of the traceback
+                "normalEm": C.Cyan,
+                "filenameEm": C.Green,
+                "linenoEm": C.Green,
+                "nameEm": C.Purple,
+                "valEm": C.Blue,
+                # Colors for printing the exception
+                "excName": C.Red,
+                # line = C.Brown,  # brown often is displayed as yellow
+                "line": C.Red,
+                "caret": C.Normal,
+                "Normal": C.Normal,
+                # debugger
+                "prompt": C.Blue,
+                "breakpoint_enabled": C.LightRed,
+                "breakpoint_disabled": C.Red,
+            },
+        )
+    )
+
+    # Hack: the 'neutral' colours are not very visible on a dark background on
+    # Windows. Since Windows command prompts have a dark background by default, and
+    # relatively few users are likely to alter that, we will use the 'Linux' colours,
+    # designed for a dark background, as the default on Windows.
+    if os.name == "nt":
+        ex_colors.add_scheme(ex_colors['Linux'].copy('Neutral'))
+
+    return ex_colors

openalex_env_map/lib/python3.10/site-packages/IPython/core/extensions.py

@@ -0,0 +1,135 @@
+# encoding: utf-8
+"""A class for managing IPython extensions."""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import os
+import os.path
+import sys
+from importlib import import_module, reload
+
+from traitlets.config.configurable import Configurable
+from IPython.utils.path import ensure_dir_exists
+from traitlets import Instance
+
+
+#-----------------------------------------------------------------------------
+# Main class
+#-----------------------------------------------------------------------------
+
+BUILTINS_EXTS = {"storemagic": False, "autoreload": False}
+
+
+class ExtensionManager(Configurable):
+    """A class to manage IPython extensions.
+
+    An IPython extension is an importable Python module that has
+    a function with the signature::
+
+        def load_ipython_extension(ipython):
+            # Do things with ipython
+
+    This function is called after your extension is imported and the
+    currently active :class:`InteractiveShell` instance is passed as
+    the only argument.  You can do anything you want with IPython at
+    that point, including defining new magic and aliases, adding new
+    components, etc.
+
+    You can also optionally define an :func:`unload_ipython_extension(ipython)`
+    function, which will be called if the user unloads or reloads the extension.
+    The extension manager will only call :func:`load_ipython_extension` again
+    if the extension is reloaded.
+
+    You can put your extension modules anywhere you want, as long as
+    they can be imported by Python's standard import mechanism.
+    """
+
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
+
+    def __init__(self, shell=None, **kwargs):
+        super(ExtensionManager, self).__init__(shell=shell, **kwargs)
+        self.loaded = set()
+
+    def load_extension(self, module_str: str):
+        """Load an IPython extension by its module name.
+
+        Returns the string "already loaded" if the extension is already loaded,
+        "no load function" if the module doesn't have a load_ipython_extension
+        function, or None if it succeeded.
+        """
+        try:
+            return self._load_extension(module_str)
+        except ModuleNotFoundError:
+            if module_str in BUILTINS_EXTS:
+                BUILTINS_EXTS[module_str] = True
+                return self._load_extension("IPython.extensions." + module_str)
+            raise
+
+    def _load_extension(self, module_str: str):
+        if module_str in self.loaded:
+            return "already loaded"
+
+        assert self.shell is not None
+
+        with self.shell.builtin_trap:
+            if module_str not in sys.modules:
+                mod = import_module(module_str)
+            mod = sys.modules[module_str]
+            if self._call_load_ipython_extension(mod):
+                self.loaded.add(module_str)
+            else:
+                return "no load function"
+
+    def unload_extension(self, module_str: str):
+        """Unload an IPython extension by its module name.
+
+        This function looks up the extension's name in ``sys.modules`` and
+        simply calls ``mod.unload_ipython_extension(self)``.
+
+        Returns the string "no unload function" if the extension doesn't define
+        a function to unload itself, "not loaded" if the extension isn't loaded,
+        otherwise None.
+        """
+        if BUILTINS_EXTS.get(module_str, False) is True:
+            module_str = "IPython.extensions." + module_str
+        if module_str not in self.loaded:
+            return "not loaded"
+
+        if module_str in sys.modules:
+            mod = sys.modules[module_str]
+            if self._call_unload_ipython_extension(mod):
+                self.loaded.discard(module_str)
+            else:
+                return "no unload function"
+
+    def reload_extension(self, module_str: str):
+        """Reload an IPython extension by calling reload.
+
+        If the module has not been loaded before,
+        :meth:`InteractiveShell.load_extension` is called. Otherwise
+        :func:`reload` is called and then the :func:`load_ipython_extension`
+        function of the module, if it exists is called.
+        """
+
+        if BUILTINS_EXTS.get(module_str, False) is True:
+            module_str = "IPython.extensions." + module_str
+
+        if (module_str in self.loaded) and (module_str in sys.modules):
+            self.unload_extension(module_str)
+            mod = sys.modules[module_str]
+            reload(mod)
+            if self._call_load_ipython_extension(mod):
+                self.loaded.add(module_str)
+        else:
+            self.load_extension(module_str)
+
+    def _call_load_ipython_extension(self, mod):
+        if hasattr(mod, 'load_ipython_extension'):
+            mod.load_ipython_extension(self.shell)
+            return True
+
+    def _call_unload_ipython_extension(self, mod):
+        if hasattr(mod, 'unload_ipython_extension'):
+            mod.unload_ipython_extension(self.shell)
+            return True

openalex_env_map/lib/python3.10/site-packages/IPython/core/formatters.py

@@ -0,0 +1,1090 @@
+# -*- coding: utf-8 -*-
+"""Display formatters.
+
+This module defines the base instances in order to implement custom
+formatters/mimetypes
+got objects:
+
+As we want to see internal IPython working we are going to use the following
+function to diaply objects instead of the normal print or display method:
+
+    >>> ip = get_ipython()
+    >>> ip.display_formatter.format(...)
+    ({'text/plain': 'Ellipsis'}, {})
+
+This return a tuple with the mimebumdle for the current object, and the
+associated metadata.
+
+
+We can now define our own formatter and register it:
+
+
+    >>> from IPython.core.formatters import BaseFormatter, FormatterABC
+
+
+    >>> class LLMFormatter(BaseFormatter):
+    ...
+    ...     format_type = 'x-vendor/llm'
+    ...     print_method = '_repr_llm_'
+    ...     _return_type = (dict, str)
+
+    >>> llm_formatter = LLMFormatter(parent=ip.display_formatter)
+
+    >>> ip.display_formatter.formatters[LLMFormatter.format_type] = llm_formatter
+
+Now any class that define `_repr_llm_` will return a x-vendor/llm as part of
+it's display data:
+
+    >>> class A:
+    ...
+    ...     def _repr_llm_(self, *kwargs):
+    ...         return 'This a A'
+    ...
+
+    >>> ip.display_formatter.format(A())
+    ({'text/plain': '<IPython.core.formatters.A at ...>', 'x-vendor/llm': 'This a A'}, {})
+
+As usual, you can register methods for third party types (see
+:ref:`third_party_formatting`)
+
+    >>> def llm_int(obj):
+    ...      return 'This is the integer %s, in between %s and %s'%(obj, obj-1, obj+1)
+
+    >>> llm_formatter.for_type(int, llm_int)
+
+    >>> ip.display_formatter.format(42)
+    ({'text/plain': '42', 'x-vendor/llm': 'This is the integer 42, in between 41 and 43'}, {})
+
+
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.core.formatters
+   :parts: 3
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import abc
+import sys
+import traceback
+import warnings
+from io import StringIO
+
+from decorator import decorator
+
+from traitlets.config.configurable import Configurable
+from .getipython import get_ipython
+from ..utils.sentinel import Sentinel
+from ..utils.dir2 import get_real_method
+from ..lib import pretty
+from traitlets import (
+    Bool, Dict, Integer, Unicode, CUnicode, ObjectName, List,
+    ForwardDeclaredInstance,
+    default, observe,
+)
+
+from typing import Any
+
+
+class DisplayFormatter(Configurable):
+
+    active_types = List(Unicode(),
+        help="""List of currently active mime-types to display.
+        You can use this to set a white-list for formats to display.
+
+        Most users will not need to change this value.
+        """,
+    ).tag(config=True)
+
+    @default('active_types')
+    def _active_types_default(self):
+        return self.format_types
+
+    @observe('active_types')
+    def _active_types_changed(self, change):
+        for key, formatter in self.formatters.items():
+            if key in change['new']:
+                formatter.enabled = True
+            else:
+                formatter.enabled = False
+
+    ipython_display_formatter = ForwardDeclaredInstance("FormatterABC")  # type: ignore
+
+    @default("ipython_display_formatter")
+    def _default_formatter(self):
+        return IPythonDisplayFormatter(parent=self)
+
+    mimebundle_formatter = ForwardDeclaredInstance("FormatterABC")  # type: ignore
+
+    @default("mimebundle_formatter")
+    def _default_mime_formatter(self):
+        return MimeBundleFormatter(parent=self)
+
+    # A dict of formatter whose keys are format types (MIME types) and whose
+    # values are subclasses of BaseFormatter.
+    formatters = Dict()
+
+    @default("formatters")
+    def _formatters_default(self):
+        """Activate the default formatters."""
+        formatter_classes = [
+            PlainTextFormatter,
+            HTMLFormatter,
+            MarkdownFormatter,
+            SVGFormatter,
+            PNGFormatter,
+            PDFFormatter,
+            JPEGFormatter,
+            LatexFormatter,
+            JSONFormatter,
+            JavascriptFormatter
+        ]
+        d = {}
+        for cls in formatter_classes:
+            f = cls(parent=self)
+            d[f.format_type] = f
+        return d
+
+    def format(self, obj, include=None, exclude=None):
+        """Return a format data dict for an object.
+
+        By default all format types will be computed.
+
+        The following MIME types are usually implemented:
+
+        * text/plain
+        * text/html
+        * text/markdown
+        * text/latex
+        * application/json
+        * application/javascript
+        * application/pdf
+        * image/png
+        * image/jpeg
+        * image/svg+xml
+
+        Parameters
+        ----------
+        obj : object
+            The Python object whose format data will be computed.
+        include : list, tuple or set; optional
+            A list of format type strings (MIME types) to include in the
+            format data dict. If this is set *only* the format types included
+            in this list will be computed.
+        exclude : list, tuple or set; optional
+            A list of format type string (MIME types) to exclude in the format
+            data dict. If this is set all format types will be computed,
+            except for those included in this argument.
+            Mimetypes present in exclude will take precedence over the ones in include
+
+        Returns
+        -------
+        (format_dict, metadata_dict) : tuple of two dicts
+            format_dict is a dictionary of key/value pairs, one of each format that was
+            generated for the object. The keys are the format types, which
+            will usually be MIME type strings and the values and JSON'able
+            data structure containing the raw data for the representation in
+            that format.
+
+            metadata_dict is a dictionary of metadata about each mime-type output.
+            Its keys will be a strict subset of the keys in format_dict.
+
+        Notes
+        -----
+            If an object implement `_repr_mimebundle_` as well as various
+            `_repr_*_`, the data returned by `_repr_mimebundle_` will take
+            precedence and the corresponding `_repr_*_` for this mimetype will
+            not be called.
+
+        """
+        format_dict = {}
+        md_dict = {}
+
+        if self.ipython_display_formatter(obj):
+            # object handled itself, don't proceed
+            return {}, {}
+
+        format_dict, md_dict = self.mimebundle_formatter(obj, include=include, exclude=exclude)
+
+        if format_dict or md_dict:
+            if include:
+                format_dict = {k:v for k,v in format_dict.items() if k in include}
+                md_dict = {k:v for k,v in md_dict.items() if k in include}
+            if exclude:
+                format_dict = {k:v for k,v in format_dict.items() if k not in exclude}
+                md_dict = {k:v for k,v in md_dict.items() if k not in exclude}
+
+        for format_type, formatter in self.formatters.items():
+            if format_type in format_dict:
+                # already got it from mimebundle, maybe don't render again.
+                # exception: manually registered per-mime renderer
+                # check priority:
+                # 1. user-registered per-mime formatter
+                # 2. mime-bundle (user-registered or repr method)
+                # 3. default per-mime formatter (e.g. repr method)
+                try:
+                    formatter.lookup(obj)
+                except KeyError:
+                    # no special formatter, use mime-bundle-provided value
+                    continue
+            if include and format_type not in include:
+                continue
+            if exclude and format_type in exclude:
+                continue
+
+            md = None
+            try:
+                data = formatter(obj)
+            except:
+                # FIXME: log the exception
+                raise
+
+            # formatters can return raw data or (data, metadata)
+            if isinstance(data, tuple) and len(data) == 2:
+                data, md = data
+
+            if data is not None:
+                format_dict[format_type] = data
+            if md is not None:
+                md_dict[format_type] = md
+        return format_dict, md_dict
+
+    @property
+    def format_types(self):
+        """Return the format types (MIME types) of the active formatters."""
+        return list(self.formatters.keys())
+
+
+#-----------------------------------------------------------------------------
+# Formatters for specific format types (text, html, svg, etc.)
+#-----------------------------------------------------------------------------
+
+
+def _safe_repr(obj):
+    """Try to return a repr of an object
+
+    always returns a string, at least.
+    """
+    try:
+        return repr(obj)
+    except Exception as e:
+        return "un-repr-able object (%r)" % e
+
+
+class FormatterWarning(UserWarning):
+    """Warning class for errors in formatters"""
+
+@decorator
+def catch_format_error(method, self, *args, **kwargs):
+    """show traceback on failed format call"""
+    try:
+        r = method(self, *args, **kwargs)
+    except NotImplementedError:
+        # don't warn on NotImplementedErrors
+        return self._check_return(None, args[0])
+    except Exception:
+        exc_info = sys.exc_info()
+        ip = get_ipython()
+        if ip is not None:
+            ip.showtraceback(exc_info)
+        else:
+            traceback.print_exception(*exc_info)
+        return self._check_return(None, args[0])
+    return self._check_return(r, args[0])
+
+
+class FormatterABC(metaclass=abc.ABCMeta):
+    """ Abstract base class for Formatters.
+
+    A formatter is a callable class that is responsible for computing the
+    raw format data for a particular format type (MIME type). For example,
+    an HTML formatter would have a format type of `text/html` and would return
+    the HTML representation of the object when called.
+    """
+
+    # The format type of the data returned, usually a MIME type.
+    format_type = 'text/plain'
+
+    # Is the formatter enabled...
+    enabled = True
+
+    @abc.abstractmethod
+    def __call__(self, obj):
+        """Return a JSON'able representation of the object.
+
+        If the object cannot be formatted by this formatter,
+        warn and return None.
+        """
+        return repr(obj)
+
+
+def _mod_name_key(typ):
+    """Return a (__module__, __name__) tuple for a type.
+
+    Used as key in Formatter.deferred_printers.
+    """
+    module = getattr(typ, '__module__', None)
+    name = getattr(typ, '__name__', None)
+    return (module, name)
+
+
+def _get_type(obj):
+    """Return the type of an instance (old and new-style)"""
+    return getattr(obj, '__class__', None) or type(obj)
+
+
+_raise_key_error = Sentinel(
+    "_raise_key_error",
+    __name__,
+    """
+Special value to raise a KeyError
+
+Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
+""",
+)
+
+
+class BaseFormatter(Configurable):
+    """A base formatter class that is configurable.
+
+    This formatter should usually be used as the base class of all formatters.
+    It is a traited :class:`Configurable` class and includes an extensible
+    API for users to determine how their objects are formatted. The following
+    logic is used to find a function to format an given object.
+
+    1. The object is introspected to see if it has a method with the name
+       :attr:`print_method`. If is does, that object is passed to that method
+       for formatting.
+    2. If no print method is found, three internal dictionaries are consulted
+       to find print method: :attr:`singleton_printers`, :attr:`type_printers`
+       and :attr:`deferred_printers`.
+
+    Users should use these dictionaries to register functions that will be
+    used to compute the format data for their objects (if those objects don't
+    have the special print methods). The easiest way of using these
+    dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
+    methods.
+
+    If no function/callable is found to compute the format data, ``None`` is
+    returned and this format type is not used.
+    """
+
+    format_type = Unicode("text/plain")
+    _return_type: Any = str
+
+    enabled = Bool(True).tag(config=True)
+
+    print_method = ObjectName('__repr__')
+
+    # The singleton printers.
+    # Maps the IDs of the builtin singleton objects to the format functions.
+    singleton_printers = Dict().tag(config=True)
+
+    # The type-specific printers.
+    # Map type objects to the format functions.
+    type_printers = Dict().tag(config=True)
+
+    # The deferred-import type-specific printers.
+    # Map (modulename, classname) pairs to the format functions.
+    deferred_printers = Dict().tag(config=True)
+
+    @catch_format_error
+    def __call__(self, obj):
+        """Compute the format for an object."""
+        if self.enabled:
+            # lookup registered printer
+            try:
+                printer = self.lookup(obj)
+            except KeyError:
+                pass
+            else:
+                return printer(obj)
+            # Finally look for special method names
+            method = get_real_method(obj, self.print_method)
+            if method is not None:
+                return method()
+            return None
+        else:
+            return None
+
+    def __contains__(self, typ):
+        """map in to lookup_by_type"""
+        try:
+            self.lookup_by_type(typ)
+        except KeyError:
+            return False
+        else:
+            return True
+
+    def _check_return(self, r, obj):
+        """Check that a return value is appropriate
+
+        Return the value if so, None otherwise, warning if invalid.
+        """
+        if r is None or isinstance(r, self._return_type) or \
+            (isinstance(r, tuple) and r and isinstance(r[0], self._return_type)):
+            return r
+        else:
+            warnings.warn(
+                "%s formatter returned invalid type %s (expected %s) for object: %s" % \
+                (self.format_type, type(r), self._return_type, _safe_repr(obj)),
+                FormatterWarning
+            )
+
+    def lookup(self, obj):
+        """Look up the formatter for a given instance.
+
+        Parameters
+        ----------
+        obj : object instance
+
+        Returns
+        -------
+        f : callable
+            The registered formatting callable for the type.
+
+        Raises
+        ------
+        KeyError if the type has not been registered.
+        """
+        # look for singleton first
+        obj_id = id(obj)
+        if obj_id in self.singleton_printers:
+            return self.singleton_printers[obj_id]
+        # then lookup by type
+        return self.lookup_by_type(_get_type(obj))
+
+    def lookup_by_type(self, typ):
+        """Look up the registered formatter for a type.
+
+        Parameters
+        ----------
+        typ : type or '__module__.__name__' string for a type
+
+        Returns
+        -------
+        f : callable
+            The registered formatting callable for the type.
+
+        Raises
+        ------
+        KeyError if the type has not been registered.
+        """
+        if isinstance(typ, str):
+            typ_key = tuple(typ.rsplit('.',1))
+            if typ_key not in self.deferred_printers:
+                # We may have it cached in the type map. We will have to
+                # iterate over all of the types to check.
+                for cls in self.type_printers:
+                    if _mod_name_key(cls) == typ_key:
+                        return self.type_printers[cls]
+            else:
+                return self.deferred_printers[typ_key]
+        else:
+            for cls in pretty._get_mro(typ):
+                if cls in self.type_printers or self._in_deferred_types(cls):
+                    return self.type_printers[cls]
+
+        # If we have reached here, the lookup failed.
+        raise KeyError("No registered printer for {0!r}".format(typ))
+
+    def for_type(self, typ, func=None):
+        """Add a format function for a given type.
+
+        Parameters
+        ----------
+        typ : type or '__module__.__name__' string for a type
+            The class of the object that will be formatted using `func`.
+
+        func : callable
+            A callable for computing the format data.
+            `func` will be called with the object to be formatted,
+            and will return the raw data in this formatter's format.
+            Subclasses may use a different call signature for the
+            `func` argument.
+
+            If `func` is None or not specified, there will be no change,
+            only returning the current value.
+
+        Returns
+        -------
+        oldfunc : callable
+            The currently registered callable.
+            If you are registering a new formatter,
+            this will be the previous value (to enable restoring later).
+        """
+        # if string given, interpret as 'pkg.module.class_name'
+        if isinstance(typ, str):
+            type_module, type_name = typ.rsplit('.', 1)
+            return self.for_type_by_name(type_module, type_name, func)
+
+        try:
+            oldfunc = self.lookup_by_type(typ)
+        except KeyError:
+            oldfunc = None
+
+        if func is not None:
+            self.type_printers[typ] = func
+
+        return oldfunc
+
+    def for_type_by_name(self, type_module, type_name, func=None):
+        """Add a format function for a type specified by the full dotted
+        module and name of the type, rather than the type of the object.
+
+        Parameters
+        ----------
+        type_module : str
+            The full dotted name of the module the type is defined in, like
+            ``numpy``.
+
+        type_name : str
+            The name of the type (the class name), like ``dtype``
+
+        func : callable
+            A callable for computing the format data.
+            `func` will be called with the object to be formatted,
+            and will return the raw data in this formatter's format.
+            Subclasses may use a different call signature for the
+            `func` argument.
+
+            If `func` is None or unspecified, there will be no change,
+            only returning the current value.
+
+        Returns
+        -------
+        oldfunc : callable
+            The currently registered callable.
+            If you are registering a new formatter,
+            this will be the previous value (to enable restoring later).
+        """
+        key = (type_module, type_name)
+
+        try:
+            oldfunc = self.lookup_by_type("%s.%s" % key)
+        except KeyError:
+            oldfunc = None
+
+        if func is not None:
+            self.deferred_printers[key] = func
+        return oldfunc
+
+    def pop(self, typ, default=_raise_key_error):
+        """Pop a formatter for the given type.
+
+        Parameters
+        ----------
+        typ : type or '__module__.__name__' string for a type
+        default : object
+            value to be returned if no formatter is registered for typ.
+
+        Returns
+        -------
+        obj : object
+            The last registered object for the type.
+
+        Raises
+        ------
+        KeyError if the type is not registered and default is not specified.
+        """
+
+        if isinstance(typ, str):
+            typ_key = tuple(typ.rsplit('.',1))
+            if typ_key not in self.deferred_printers:
+                # We may have it cached in the type map. We will have to
+                # iterate over all of the types to check.
+                for cls in self.type_printers:
+                    if _mod_name_key(cls) == typ_key:
+                        old = self.type_printers.pop(cls)
+                        break
+                else:
+                    old = default
+            else:
+                old = self.deferred_printers.pop(typ_key)
+        else:
+            if typ in self.type_printers:
+                old = self.type_printers.pop(typ)
+            else:
+                old = self.deferred_printers.pop(_mod_name_key(typ), default)
+        if old is _raise_key_error:
+            raise KeyError("No registered value for {0!r}".format(typ))
+        return old
+
+    def _in_deferred_types(self, cls):
+        """
+        Check if the given class is specified in the deferred type registry.
+
+        Successful matches will be moved to the regular type registry for future use.
+        """
+        mod = getattr(cls, '__module__', None)
+        name = getattr(cls, '__name__', None)
+        key = (mod, name)
+        if key in self.deferred_printers:
+            # Move the printer over to the regular registry.
+            printer = self.deferred_printers.pop(key)
+            self.type_printers[cls] = printer
+            return True
+        return False
+
+
+class PlainTextFormatter(BaseFormatter):
+    """The default pretty-printer.
+
+    This uses :mod:`IPython.lib.pretty` to compute the format data of
+    the object. If the object cannot be pretty printed, :func:`repr` is used.
+    See the documentation of :mod:`IPython.lib.pretty` for details on
+    how to write pretty printers.  Here is a simple example::
+
+        def dtype_pprinter(obj, p, cycle):
+            if cycle:
+                return p.text('dtype(...)')
+            if hasattr(obj, 'fields'):
+                if obj.fields is None:
+                    p.text(repr(obj))
+                else:
+                    p.begin_group(7, 'dtype([')
+                    for i, field in enumerate(obj.descr):
+                        if i > 0:
+                            p.text(',')
+                            p.breakable()
+                        p.pretty(field)
+                    p.end_group(7, '])')
+    """
+
+    # The format type of data returned.
+    format_type = Unicode('text/plain')
+
+    # This subclass ignores this attribute as it always need to return
+    # something.
+    enabled = Bool(True).tag(config=False)
+
+    max_seq_length = Integer(pretty.MAX_SEQ_LENGTH,
+        help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
+
+        Set to 0 to disable truncation.
+        """,
+    ).tag(config=True)
+
+    # Look for a _repr_pretty_ methods to use for pretty printing.
+    print_method = ObjectName('_repr_pretty_')
+
+    # Whether to pretty-print or not.
+    pprint = Bool(True).tag(config=True)
+
+    # Whether to be verbose or not.
+    verbose = Bool(False).tag(config=True)
+
+    # The maximum width.
+    max_width = Integer(79).tag(config=True)
+
+    # The newline character.
+    newline = Unicode('\n').tag(config=True)
+
+    # format-string for pprinting floats
+    float_format = Unicode('%r')
+    # setter for float precision, either int or direct format-string
+    float_precision = CUnicode('').tag(config=True)
+
+    @observe('float_precision')
+    def _float_precision_changed(self, change):
+        """float_precision changed, set float_format accordingly.
+
+        float_precision can be set by int or str.
+        This will set float_format, after interpreting input.
+        If numpy has been imported, numpy print precision will also be set.
+
+        integer `n` sets format to '%.nf', otherwise, format set directly.
+
+        An empty string returns to defaults (repr for float, 8 for numpy).
+
+        This parameter can be set via the '%precision' magic.
+        """
+        new = change['new']
+        if '%' in new:
+            # got explicit format string
+            fmt = new
+            try:
+                fmt%3.14159
+            except Exception as e:
+                raise ValueError("Precision must be int or format string, not %r"%new) from e
+        elif new:
+            # otherwise, should be an int
+            try:
+                i = int(new)
+                assert i >= 0
+            except ValueError as e:
+                raise ValueError("Precision must be int or format string, not %r"%new) from e
+            except AssertionError as e:
+                raise ValueError("int precision must be non-negative, not %r"%i) from e
+
+            fmt = '%%.%if'%i
+            if 'numpy' in sys.modules:
+                # set numpy precision if it has been imported
+                import numpy
+                numpy.set_printoptions(precision=i)
+        else:
+            # default back to repr
+            fmt = '%r'
+            if 'numpy' in sys.modules:
+                import numpy
+                # numpy default is 8
+                numpy.set_printoptions(precision=8)
+        self.float_format = fmt
+
+    # Use the default pretty printers from IPython.lib.pretty.
+    @default('singleton_printers')
+    def _singleton_printers_default(self):
+        return pretty._singleton_pprinters.copy()
+
+    @default('type_printers')
+    def _type_printers_default(self):
+        d = pretty._type_pprinters.copy()
+        d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
+        # if NumPy is used, set precision for its float64 type
+        if "numpy" in sys.modules:
+            import numpy
+
+            d[numpy.float64] = lambda obj, p, cycle: p.text(self.float_format % obj)
+        return d
+
+    @default('deferred_printers')
+    def _deferred_printers_default(self):
+        return pretty._deferred_type_pprinters.copy()
+
+    #### FormatterABC interface ####
+
+    @catch_format_error
+    def __call__(self, obj):
+        """Compute the pretty representation of the object."""
+        if not self.pprint:
+            return repr(obj)
+        else:
+            stream = StringIO()
+            printer = pretty.RepresentationPrinter(stream, self.verbose,
+                self.max_width, self.newline,
+                max_seq_length=self.max_seq_length,
+                singleton_pprinters=self.singleton_printers,
+                type_pprinters=self.type_printers,
+                deferred_pprinters=self.deferred_printers)
+            printer.pretty(obj)
+            printer.flush()
+            return stream.getvalue()
+
+
+class HTMLFormatter(BaseFormatter):
+    """An HTML formatter.
+
+    To define the callables that compute the HTML representation of your
+    objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be a valid HTML snippet that
+    could be injected into an existing DOM. It should *not* include the
+    ```<html>`` or ```<body>`` tags.
+    """
+    format_type = Unicode('text/html')
+
+    print_method = ObjectName('_repr_html_')
+
+
+class MarkdownFormatter(BaseFormatter):
+    """A Markdown formatter.
+
+    To define the callables that compute the Markdown representation of your
+    objects, define a :meth:`_repr_markdown_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be a valid Markdown.
+    """
+    format_type = Unicode('text/markdown')
+
+    print_method = ObjectName('_repr_markdown_')
+
+class SVGFormatter(BaseFormatter):
+    """An SVG formatter.
+
+    To define the callables that compute the SVG representation of your
+    objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be valid SVG enclosed in
+    ```<svg>``` tags, that could be injected into an existing DOM. It should
+    *not* include the ```<html>`` or ```<body>`` tags.
+    """
+    format_type = Unicode('image/svg+xml')
+
+    print_method = ObjectName('_repr_svg_')
+
+
+class PNGFormatter(BaseFormatter):
+    """A PNG formatter.
+
+    To define the callables that compute the PNG representation of your
+    objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be raw PNG data, *not*
+    base64 encoded.
+    """
+    format_type = Unicode('image/png')
+
+    print_method = ObjectName('_repr_png_')
+
+    _return_type = (bytes, str)
+
+
+class JPEGFormatter(BaseFormatter):
+    """A JPEG formatter.
+
+    To define the callables that compute the JPEG representation of your
+    objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be raw JPEG data, *not*
+    base64 encoded.
+    """
+    format_type = Unicode('image/jpeg')
+
+    print_method = ObjectName('_repr_jpeg_')
+
+    _return_type = (bytes, str)
+
+
+class LatexFormatter(BaseFormatter):
+    """A LaTeX formatter.
+
+    To define the callables that compute the LaTeX representation of your
+    objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be a valid LaTeX equation,
+    enclosed in either ```$```, ```$$``` or another LaTeX equation
+    environment.
+    """
+    format_type = Unicode('text/latex')
+
+    print_method = ObjectName('_repr_latex_')
+
+
+class JSONFormatter(BaseFormatter):
+    """A JSON string formatter.
+
+    To define the callables that compute the JSONable representation of
+    your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be a JSONable list or dict.
+    JSON scalars (None, number, string) are not allowed, only dict or list containers.
+    """
+    format_type = Unicode('application/json')
+    _return_type = (list, dict)
+
+    print_method = ObjectName('_repr_json_')
+
+    def _check_return(self, r, obj):
+        """Check that a return value is appropriate
+
+        Return the value if so, None otherwise, warning if invalid.
+        """
+        if r is None:
+            return
+        md = None
+        if isinstance(r, tuple):
+            # unpack data, metadata tuple for type checking on first element
+            r, md = r
+
+        assert not isinstance(
+            r, str
+        ), "JSON-as-string has been deprecated since IPython < 3"
+
+        if md is not None:
+            # put the tuple back together
+            r = (r, md)
+        return super(JSONFormatter, self)._check_return(r, obj)
+
+
+class JavascriptFormatter(BaseFormatter):
+    """A Javascript formatter.
+
+    To define the callables that compute the Javascript representation of
+    your objects, define a :meth:`_repr_javascript_` method or use the
+    :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
+    that handle this.
+
+    The return value of this formatter should be valid Javascript code and
+    should *not* be enclosed in ```<script>``` tags.
+    """
+    format_type = Unicode('application/javascript')
+
+    print_method = ObjectName('_repr_javascript_')
+
+
+class PDFFormatter(BaseFormatter):
+    """A PDF formatter.
+
+    To define the callables that compute the PDF representation of your
+    objects, define a :meth:`_repr_pdf_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    The return value of this formatter should be raw PDF data, *not*
+    base64 encoded.
+    """
+    format_type = Unicode('application/pdf')
+
+    print_method = ObjectName('_repr_pdf_')
+
+    _return_type = (bytes, str)
+
+class IPythonDisplayFormatter(BaseFormatter):
+    """An escape-hatch Formatter for objects that know how to display themselves.
+
+    To define the callables that compute the representation of your
+    objects, define a :meth:`_ipython_display_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this. Unlike mime-type displays, this method should not return anything,
+    instead calling any appropriate display methods itself.
+
+    This display formatter has highest priority.
+    If it fires, no other display formatter will be called.
+
+    Prior to IPython 6.1, `_ipython_display_` was the only way to display custom mime-types
+    without registering a new Formatter.
+
+    IPython 6.1 introduces `_repr_mimebundle_` for displaying custom mime-types,
+    so `_ipython_display_` should only be used for objects that require unusual
+    display patterns, such as multiple display calls.
+    """
+    print_method = ObjectName('_ipython_display_')
+    _return_type = (type(None), bool)
+
+    @catch_format_error
+    def __call__(self, obj):
+        """Compute the format for an object."""
+        if self.enabled:
+            # lookup registered printer
+            try:
+                printer = self.lookup(obj)
+            except KeyError:
+                pass
+            else:
+                printer(obj)
+                return True
+            # Finally look for special method names
+            method = get_real_method(obj, self.print_method)
+            if method is not None:
+                method()
+                return True
+
+
+class MimeBundleFormatter(BaseFormatter):
+    """A Formatter for arbitrary mime-types.
+
+    Unlike other `_repr_<mimetype>_` methods,
+    `_repr_mimebundle_` should return mime-bundle data,
+    either the mime-keyed `data` dictionary or the tuple `(data, metadata)`.
+    Any mime-type is valid.
+
+    To define the callables that compute the mime-bundle representation of your
+    objects, define a :meth:`_repr_mimebundle_` method or use the :meth:`for_type`
+    or :meth:`for_type_by_name` methods to register functions that handle
+    this.
+
+    .. versionadded:: 6.1
+    """
+    print_method = ObjectName('_repr_mimebundle_')
+    _return_type = dict
+
+    def _check_return(self, r, obj):
+        r = super(MimeBundleFormatter, self)._check_return(r, obj)
+        # always return (data, metadata):
+        if r is None:
+            return {}, {}
+        if not isinstance(r, tuple):
+            return r, {}
+        return r
+
+    @catch_format_error
+    def __call__(self, obj, include=None, exclude=None):
+        """Compute the format for an object.
+
+        Identical to parent's method but we pass extra parameters to the method.
+
+        Unlike other _repr_*_ `_repr_mimebundle_` should allow extra kwargs, in
+        particular `include` and `exclude`.
+        """
+        if self.enabled:
+            # lookup registered printer
+            try:
+                printer = self.lookup(obj)
+            except KeyError:
+                pass
+            else:
+                return printer(obj)
+            # Finally look for special method names
+            method = get_real_method(obj, self.print_method)
+
+            if method is not None:
+                return method(include=include, exclude=exclude)
+            return None
+        else:
+            return None
+
+
+FormatterABC.register(BaseFormatter)
+FormatterABC.register(PlainTextFormatter)
+FormatterABC.register(HTMLFormatter)
+FormatterABC.register(MarkdownFormatter)
+FormatterABC.register(SVGFormatter)
+FormatterABC.register(PNGFormatter)
+FormatterABC.register(PDFFormatter)
+FormatterABC.register(JPEGFormatter)
+FormatterABC.register(LatexFormatter)
+FormatterABC.register(JSONFormatter)
+FormatterABC.register(JavascriptFormatter)
+FormatterABC.register(IPythonDisplayFormatter)
+FormatterABC.register(MimeBundleFormatter)
+
+
+def format_display_data(obj, include=None, exclude=None):
+    """Return a format data dict for an object.
+
+    By default all format types will be computed.
+
+    Parameters
+    ----------
+    obj : object
+        The Python object whose format data will be computed.
+
+    Returns
+    -------
+    format_dict : dict
+        A dictionary of key/value pairs, one or each format that was
+        generated for the object. The keys are the format types, which
+        will usually be MIME type strings and the values and JSON'able
+        data structure containing the raw data for the representation in
+        that format.
+    include : list or tuple, optional
+        A list of format type strings (MIME types) to include in the
+        format data dict. If this is set *only* the format types included
+        in this list will be computed.
+    exclude : list or tuple, optional
+        A list of format type string (MIME types) to exclude in the format
+        data dict. If this is set all format types will be computed,
+        except for those included in this argument.
+    """
+    from .interactiveshell import InteractiveShell
+
+    return InteractiveShell.instance().display_formatter.format(
+        obj,
+        include,
+        exclude
+    )

openalex_env_map/lib/python3.10/site-packages/IPython/core/getipython.py

@@ -0,0 +1,24 @@
+# encoding: utf-8
+"""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()

openalex_env_map/lib/python3.10/site-packages/IPython/core/guarded_eval.py

@@ -0,0 +1,895 @@
+from inspect import isclass, signature, Signature
+from typing import (
+    Annotated,
+    AnyStr,
+    Callable,
+    Dict,
+    Literal,
+    NamedTuple,
+    NewType,
+    Optional,
+    Protocol,
+    Set,
+    Sequence,
+    Tuple,
+    Type,
+    TypeGuard,
+    Union,
+    get_args,
+    get_origin,
+    is_typeddict,
+)
+import ast
+import builtins
+import collections
+import operator
+import sys
+from functools import cached_property
+from dataclasses import dataclass, field
+from types import MethodDescriptorType, ModuleType
+
+from IPython.utils.decorators import undoc
+
+
+if sys.version_info < (3, 11):
+    from typing_extensions import Self, LiteralString
+else:
+    from typing import Self, LiteralString
+
+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
+    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.
+
+    Raises:
+    * `KeyError` if module is removed not found, and
+    * `AttributeError` if access path does not match an exported object
+    """
+    member_type = sys.modules[module_name]
+    for attr in access_path:
+        member_type = getattr(member_type, attr)
+    return member_type
+
+
+def _has_original_dunder_external(
+    value,
+    module_name: str,
+    access_path: Sequence[str],
+    method_name: str,
+):
+    if module_name 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 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 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
+    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
+
+
+@undoc
+@dataclass
+class SelectivePolicy(EvaluationPolicy):
+    allowed_getitem: Set[InstancesHaveGetItem] = field(default_factory=set)
+    allowed_getitem_external: Set[Tuple[str, ...]] = field(default_factory=set)
+
+    allowed_getattr: Set[MayHaveGetattr] = field(default_factory=set)
+    allowed_getattr_external: Set[Tuple[str, ...]] = field(default_factory=set)
+
+    allowed_operations: Set = field(default_factory=set)
+    allowed_operations_external: Set[Tuple[str, ...]] = field(default_factory=set)
+
+    _operation_methods_cache: Dict[str, Set[Callable]] = field(
+        default_factory=dict, init=False
+    )
+
+    def can_get_attr(self, value, attr):
+        has_original_attribute = _has_original_dunder(
+            value,
+            allowed_types=self.allowed_getattr,
+            allowed_methods=self._getattribute_methods,
+            allowed_external=self.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=self.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 self.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."""
+        return _has_original_dunder(
+            value,
+            allowed_types=self.allowed_getitem,
+            allowed_methods=self._getitem_methods,
+            allowed_external=self.allowed_getitem_external,
+            method_name="__getitem__",
+        )
+
+    def can_operate(self, dunders: Tuple[str, ...], a, b=None):
+        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=self.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."""
+
+
+class EvaluationContext(NamedTuple):
+    #: Local namespace
+    locals: dict
+    #: Global namespace
+    globals: dict
+    #: Evaluation policy identifier
+    evaluation: Literal["forbidden", "minimal", "limited", "unsafe", "dangerous"] = (
+        "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
+
+
+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 = EvaluationContext(**{**context._asdict(), **{"locals": locals_}})
+
+    if context.evaluation == "dangerous":
+        return eval(code, context.globals, context.locals)
+
+    expression = ast.parse(code, mode="eval")
+
+    return eval_node(expression, 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__",),
+}
+
+
+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 or {}
+        self.items = items or {}
+
+    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 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 = EVALUATION_POLICIES[context.evaluation]
+    if node is None:
+        return None
+    if isinstance(node, ast.Expression):
+        return eval_node(node.body, context)
+    if isinstance(node, ast.BinOp):
+        left = eval_node(node.left, context)
+        right = eval_node(node.right, 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):
+                return getattr(value, dunders[0])()
+            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):
+        value = eval_node(node.value, context)
+        if policy.can_get_attr(value, node.attr):
+            return getattr(value, node.attr)
+        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) and not node.keywords:
+            args = [eval_node(arg, context) for arg in node.args]
+            return func(*args)
+        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:
+            return_type = _eval_return_type(func, node, context)
+            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",
+        )
+    raise ValueError("Unhandled node", ast.dump(node))
+
+
+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, sig, func, node, context)
+    return NOT_EVALUATED
+
+
+def _resolve_annotation(
+    annotation,
+    sig: Signature,
+    func: Callable,
+    node: ast.Call,
+    context: EvaluationContext,
+):
+    """Resolve annotation created by user with `typing` module and custom objects."""
+    annotation = (
+        _eval_node_name(annotation, context)
+        if isinstance(annotation, str)
+        else annotation
+    )
+    origin = get_origin(annotation)
+    if annotation is Self 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
+        for i, (key, value) in enumerate(sig.parameters.items()):
+            if value.annotation is AnyStr:
+                index = i
+                break
+        if index is not None and index < len(node.args):
+            return eval_node(node.args[index], context)
+    elif origin is TypeGuard:
+        return bool()
+    elif origin is Union:
+        attributes = [
+            attr
+            for type_arg in get_args(annotation)
+            for attr in dir(_resolve_annotation(type_arg, sig, func, node, context))
+        ]
+        return _Duck(attributes=dict.fromkeys(attributes))
+    elif is_typeddict(annotation):
+        return _Duck(
+            attributes=dict.fromkeys(dir(dict())),
+            items={
+                k: _resolve_annotation(v, sig, func, node, context)
+                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, sig, func, node, context)
+    elif isinstance(annotation, NewType):
+        return _eval_or_create_duck(annotation.__supertype__, node, context)
+    elif isinstance(annotation, TypeAliasType):
+        return _eval_or_create_duck(annotation.__value__, node, context)
+    else:
+        return _eval_or_create_duck(annotation, node, context)
+
+
+def _eval_node_name(node_id: str, context: EvaluationContext):
+    policy = EVALUATION_POLICIES[context.evaluation]
+    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 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, node: ast.Call, context: EvaluationContext):
+    policy = EVALUATION_POLICIES[context.evaluation]
+    # if allow-listed builtin is on type annotation, instantiate it
+    if policy.can_call(duck_type) and not node.keywords:
+        args = [eval_node(arg, context) for arg in node.args]
+        return duck_type(*args)
+    # 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,
+    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())
+
+NUMERICS = {int, float, complex}
+
+ALLOWED_CALLS = {
+    bytes,
+    *_list_methods(bytes),
+    dict,
+    *_list_methods(dict, dict_non_mutating_methods),
+    dict_keys.isdisjoint,
+    list,
+    *_list_methods(list, list_non_mutating_methods),
+    set,
+    *_list_methods(set, set_non_mutating_methods),
+    frozenset,
+    *_list_methods(frozenset),
+    range,
+    str,
+    *_list_methods(str),
+    tuple,
+    *_list_methods(tuple),
+    *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.defaultdict,
+    *_list_methods(collections.defaultdict, dict_non_mutating_methods),
+    collections.OrderedDict,
+    *_list_methods(collections.OrderedDict, dict_non_mutating_methods),
+    collections.UserDict,
+    *_list_methods(collections.UserDict, dict_non_mutating_methods),
+    collections.UserList,
+    *_list_methods(collections.UserList, list_non_mutating_methods),
+    collections.UserString,
+    *_list_methods(collections.UserString, dir(str)),
+    collections.Counter,
+    *_list_methods(collections.Counter, dict_non_mutating_methods),
+    collections.Counter.elements,
+    collections.Counter.most_common,
+}
+
+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,
+        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",
+]

openalex_env_map/lib/python3.10/site-packages/IPython/core/history.py

@@ -0,0 +1,989 @@
+""" History related magics and functionality """
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+
+import atexit
+import datetime
+import re
+import sqlite3
+import threading
+from pathlib import Path
+
+from decorator import decorator
+from traitlets import (
+    Any,
+    Bool,
+    Dict,
+    Instance,
+    Integer,
+    List,
+    TraitError,
+    Unicode,
+    Union,
+    default,
+    observe,
+)
+from traitlets.config.configurable import LoggingConfigurable
+
+from IPython.paths import locate_profile
+from IPython.utils.decorators import undoc
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+@undoc
+class DummyDB(object):
+    """Dummy DB that will act as a black hole for history.
+
+    Only used in the absence of sqlite"""
+    def execute(*args, **kwargs):
+        return []
+
+    def commit(self, *args, **kwargs):
+        pass
+
+    def __enter__(self, *args, **kwargs):
+        pass
+
+    def __exit__(self, *args, **kwargs):
+        pass
+
+
+@decorator
+def only_when_enabled(f, self, *a, **kw):
+    """Decorator: return an empty list in the absence of sqlite."""
+    if not self.enabled:
+        return []
+    else:
+        return f(self, *a, **kw)
+
+
+# use 16kB as threshold for whether a corrupt history db should be saved
+# that should be at least 100 entries or so
+_SAVE_DB_SIZE = 16384
+
+@decorator
+def catch_corrupt_db(f, self, *a, **kw):
+    """A decorator which wraps HistoryAccessor method calls to catch errors from
+    a corrupt SQLite database, move the old database out of the way, and create
+    a new one.
+
+    We avoid clobbering larger databases because this may be triggered due to filesystem issues,
+    not just a corrupt file.
+    """
+    try:
+        return f(self, *a, **kw)
+    except (sqlite3.DatabaseError, sqlite3.OperationalError) as e:
+        self._corrupt_db_counter += 1
+        self.log.error("Failed to open SQLite history %s (%s).", self.hist_file, e)
+        if self.hist_file != ':memory:':
+            if self._corrupt_db_counter > self._corrupt_db_limit:
+                self.hist_file = ':memory:'
+                self.log.error("Failed to load history too many times, history will not be saved.")
+            elif self.hist_file.is_file():
+                # move the file out of the way
+                base = str(self.hist_file.parent / self.hist_file.stem)
+                ext = self.hist_file.suffix
+                size = self.hist_file.stat().st_size
+                if size >= _SAVE_DB_SIZE:
+                    # if there's significant content, avoid clobbering
+                    now = datetime.datetime.now().isoformat().replace(':', '.')
+                    newpath = base + '-corrupt-' + now + ext
+                    # don't clobber previous corrupt backups
+                    for i in range(100):
+                        if not Path(newpath).exists():
+                            break
+                        else:
+                            newpath = base + '-corrupt-' + now + (u'-%i' % i) + ext
+                else:
+                    # not much content, possibly empty; don't worry about clobbering
+                    # maybe we should just delete it?
+                    newpath = base + '-corrupt' + ext
+                self.hist_file.rename(newpath)
+                self.log.error("History file was moved to %s and a new file created.", newpath)
+            self.init_db()
+            return []
+        else:
+            # Failed with :memory:, something serious is wrong
+            raise
+
+
+class HistoryAccessorBase(LoggingConfigurable):
+    """An abstract class for History Accessors """
+
+    def get_tail(self, n=10, raw=True, output=False, include_latest=False):
+        raise NotImplementedError
+
+    def search(self, pattern="*", raw=True, search_raw=True,
+               output=False, n=None, unique=False):
+        raise NotImplementedError
+
+    def get_range(self, session, start=1, stop=None, raw=True,output=False):
+        raise NotImplementedError
+
+    def get_range_by_str(self, rangestr, raw=True, output=False):
+        raise NotImplementedError
+
+
+class HistoryAccessor(HistoryAccessorBase):
+    """Access the history database without adding to it.
+
+    This is intended for use by standalone history tools. IPython shells use
+    HistoryManager, below, which is a subclass of this."""
+
+    # counter for init_db retries, so we don't keep trying over and over
+    _corrupt_db_counter = 0
+     # after two failures, fallback on :memory:
+    _corrupt_db_limit = 2
+
+    # String holding the path to the history file
+    hist_file = Union(
+        [Instance(Path), Unicode()],
+        help="""Path to file to use for SQLite history database.
+
+        By default, IPython will put the history database in the IPython
+        profile directory.  If you would rather share one history among
+        profiles, you can set this value in each, so that they are consistent.
+
+        Due to an issue with fcntl, SQLite is known to misbehave on some NFS
+        mounts.  If you see IPython hanging, try setting this to something on a
+        local disk, e.g::
+
+            ipython --HistoryManager.hist_file=/tmp/ipython_hist.sqlite
+
+        you can also use the specific value `:memory:` (including the colon
+        at both end but not the back ticks), to avoid creating an history file.
+
+        """,
+    ).tag(config=True)
+
+    enabled = Bool(True,
+        help="""enable the SQLite history
+
+        set enabled=False to disable the SQLite history,
+        in which case there will be no stored history, no SQLite connection,
+        and no background saving thread.  This may be necessary in some
+        threaded environments where IPython is embedded.
+        """,
+    ).tag(config=True)
+
+    connection_options = Dict(
+        help="""Options for configuring the SQLite connection
+
+        These options are passed as keyword args to sqlite3.connect
+        when establishing database connections.
+        """
+    ).tag(config=True)
+
+    @default("connection_options")
+    def _default_connection_options(self):
+        return dict(check_same_thread=False)
+
+    # The SQLite database
+    db = Any()
+    @observe('db')
+    def _db_changed(self, change):
+        """validate the db, since it can be an Instance of two different types"""
+        new = change['new']
+        connection_types = (DummyDB, sqlite3.Connection)
+        if not isinstance(new, connection_types):
+            msg = "%s.db must be sqlite3 Connection or DummyDB, not %r" % \
+                    (self.__class__.__name__, new)
+            raise TraitError(msg)
+
+    def __init__(self, profile="default", hist_file="", **traits):
+        """Create a new history accessor.
+
+        Parameters
+        ----------
+        profile : str
+            The name of the profile from which to open history.
+        hist_file : str
+            Path to an SQLite history database stored by IPython. If specified,
+            hist_file overrides profile.
+        config : :class:`~traitlets.config.loader.Config`
+            Config object. hist_file can also be set through this.
+        """
+        super(HistoryAccessor, self).__init__(**traits)
+        # defer setting hist_file from kwarg until after init,
+        # otherwise the default kwarg value would clobber any value
+        # set by config
+        if hist_file:
+            self.hist_file = hist_file
+
+        try:
+            self.hist_file
+        except TraitError:
+            # No one has set the hist_file, yet.
+            self.hist_file = self._get_hist_file_name(profile)
+
+        self.init_db()
+
+    def _get_hist_file_name(self, profile='default'):
+        """Find the history file for the given profile name.
+
+        This is overridden by the HistoryManager subclass, to use the shell's
+        active profile.
+
+        Parameters
+        ----------
+        profile : str
+            The name of a profile which has a history file.
+        """
+        return Path(locate_profile(profile)) / "history.sqlite"
+
+    @catch_corrupt_db
+    def init_db(self):
+        """Connect to the database, and create tables if necessary."""
+        if not self.enabled:
+            self.db = DummyDB()
+            return
+
+        # use detect_types so that timestamps return datetime objects
+        kwargs = dict(detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
+        kwargs.update(self.connection_options)
+        self.db = sqlite3.connect(str(self.hist_file), **kwargs)
+        with self.db:
+            self.db.execute(
+                """CREATE TABLE IF NOT EXISTS sessions (session integer
+                            primary key autoincrement, start timestamp,
+                            end timestamp, num_cmds integer, remark text)"""
+            )
+            self.db.execute(
+                """CREATE TABLE IF NOT EXISTS history
+                    (session integer, line integer, source text, source_raw text,
+                    PRIMARY KEY (session, line))"""
+            )
+            # Output history is optional, but ensure the table's there so it can be
+            # enabled later.
+            self.db.execute(
+                """CREATE TABLE IF NOT EXISTS output_history
+                            (session integer, line integer, output text,
+                            PRIMARY KEY (session, line))"""
+            )
+        # success! reset corrupt db count
+        self._corrupt_db_counter = 0
+
+    def writeout_cache(self):
+        """Overridden by HistoryManager to dump the cache before certain
+        database lookups."""
+        pass
+
+    ## -------------------------------
+    ## Methods for retrieving history:
+    ## -------------------------------
+    def _run_sql(self, sql, params, raw=True, output=False, latest=False):
+        """Prepares and runs an SQL query for the history database.
+
+        Parameters
+        ----------
+        sql : str
+            Any filtering expressions to go after SELECT ... FROM ...
+        params : tuple
+            Parameters passed to the SQL query (to replace "?")
+        raw, output : bool
+            See :meth:`get_range`
+        latest : bool
+            Select rows with max (session, line)
+
+        Returns
+        -------
+        Tuples as :meth:`get_range`
+        """
+        toget = 'source_raw' if raw else 'source'
+        sqlfrom = "history"
+        if output:
+            sqlfrom = "history LEFT JOIN output_history USING (session, line)"
+            toget = "history.%s, output_history.output" % toget
+        if latest:
+            toget += ", MAX(session * 128 * 1024 + line)"
+        this_querry = "SELECT session, line, %s FROM %s " % (toget, sqlfrom) + sql
+        cur = self.db.execute(this_querry, params)
+        if latest:
+            cur = (row[:-1] for row in cur)
+        if output:    # Regroup into 3-tuples, and parse JSON
+            return ((ses, lin, (inp, out)) for ses, lin, inp, out in cur)
+        return cur
+
+    @only_when_enabled
+    @catch_corrupt_db
+    def get_session_info(self, session):
+        """Get info about a session.
+
+        Parameters
+        ----------
+        session : int
+            Session number to retrieve.
+
+        Returns
+        -------
+        session_id : int
+            Session ID number
+        start : datetime
+            Timestamp for the start of the session.
+        end : datetime
+            Timestamp for the end of the session, or None if IPython crashed.
+        num_cmds : int
+            Number of commands run, or None if IPython crashed.
+        remark : unicode
+            A manually set description.
+        """
+        query = "SELECT * from sessions where session == ?"
+        return self.db.execute(query, (session,)).fetchone()
+
+    @catch_corrupt_db
+    def get_last_session_id(self):
+        """Get the last session ID currently in the database.
+
+        Within IPython, this should be the same as the value stored in
+        :attr:`HistoryManager.session_number`.
+        """
+        for record in self.get_tail(n=1, include_latest=True):
+            return record[0]
+
+    @catch_corrupt_db
+    def get_tail(self, n=10, raw=True, output=False, include_latest=False):
+        """Get the last n lines from the history database.
+
+        Parameters
+        ----------
+        n : int
+            The number of lines to get
+        raw, output : bool
+            See :meth:`get_range`
+        include_latest : bool
+            If False (default), n+1 lines are fetched, and the latest one
+            is discarded. This is intended to be used where the function
+            is called by a user command, which it should not return.
+
+        Returns
+        -------
+        Tuples as :meth:`get_range`
+        """
+        self.writeout_cache()
+        if not include_latest:
+            n += 1
+        cur = self._run_sql(
+            "ORDER BY session DESC, line DESC LIMIT ?", (n,), raw=raw, output=output
+        )
+        if not include_latest:
+            return reversed(list(cur)[1:])
+        return reversed(list(cur))
+
+    @catch_corrupt_db
+    def search(self, pattern="*", raw=True, search_raw=True,
+               output=False, n=None, unique=False):
+        """Search the database using unix glob-style matching (wildcards
+        * and ?).
+
+        Parameters
+        ----------
+        pattern : str
+            The wildcarded pattern to match when searching
+        search_raw : bool
+            If True, search the raw input, otherwise, the parsed input
+        raw, output : bool
+            See :meth:`get_range`
+        n : None or int
+            If an integer is given, it defines the limit of
+            returned entries.
+        unique : bool
+            When it is true, return only unique entries.
+
+        Returns
+        -------
+        Tuples as :meth:`get_range`
+        """
+        tosearch = "source_raw" if search_raw else "source"
+        if output:
+            tosearch = "history." + tosearch
+        self.writeout_cache()
+        sqlform = "WHERE %s GLOB ?" % tosearch
+        params = (pattern,)
+        if unique:
+            sqlform += ' GROUP BY {0}'.format(tosearch)
+        if n is not None:
+            sqlform += " ORDER BY session DESC, line DESC LIMIT ?"
+            params += (n,)
+        elif unique:
+            sqlform += " ORDER BY session, line"
+        cur = self._run_sql(sqlform, params, raw=raw, output=output, latest=unique)
+        if n is not None:
+            return reversed(list(cur))
+        return cur
+
+    @catch_corrupt_db
+    def get_range(self, session, start=1, stop=None, raw=True,output=False):
+        """Retrieve input by session.
+
+        Parameters
+        ----------
+        session : int
+            Session number to retrieve.
+        start : int
+            First line to retrieve.
+        stop : int
+            End of line range (excluded from output itself). If None, retrieve
+            to the end of the session.
+        raw : bool
+            If True, return untranslated input
+        output : bool
+            If True, attempt to include output. This will be 'real' Python
+            objects for the current session, or text reprs from previous
+            sessions if db_log_output was enabled at the time. Where no output
+            is found, None is used.
+
+        Returns
+        -------
+        entries
+            An iterator over the desired lines. Each line is a 3-tuple, either
+            (session, line, input) if output is False, or
+            (session, line, (input, output)) if output is True.
+        """
+        if stop:
+            lineclause = "line >= ? AND line < ?"
+            params = (session, start, stop)
+        else:
+            lineclause = "line>=?"
+            params = (session, start)
+
+        return self._run_sql("WHERE session==? AND %s" % lineclause,
+                                    params, raw=raw, output=output)
+
+    def get_range_by_str(self, rangestr, raw=True, output=False):
+        """Get lines of history from a string of ranges, as used by magic
+        commands %hist, %save, %macro, etc.
+
+        Parameters
+        ----------
+        rangestr : str
+            A string specifying ranges, e.g. "5 ~2/1-4". If empty string is used,
+            this will return everything from current session's history.
+
+            See the documentation of :func:`%history` for the full details.
+
+        raw, output : bool
+            As :meth:`get_range`
+
+        Returns
+        -------
+        Tuples as :meth:`get_range`
+        """
+        for sess, s, e in extract_hist_ranges(rangestr):
+            for line in self.get_range(sess, s, e, raw=raw, output=output):
+                yield line
+
+
+class HistoryManager(HistoryAccessor):
+    """A class to organize all history-related functionality in one place.
+    """
+    # Public interface
+
+    # An instance of the IPython shell we are attached to
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC',
+                     allow_none=True)
+    # Lists to hold processed and raw history. These start with a blank entry
+    # so that we can index them starting from 1
+    input_hist_parsed = List([""])
+    input_hist_raw = List([""])
+    # A list of directories visited during session
+    dir_hist: List = List()
+
+    @default("dir_hist")
+    def _dir_hist_default(self):
+        try:
+            return [Path.cwd()]
+        except OSError:
+            return []
+
+    # A dict of output history, keyed with ints from the shell's
+    # execution count.
+    output_hist = Dict()
+    # The text/plain repr of outputs.
+    output_hist_reprs = Dict()
+
+    # The number of the current session in the history database
+    session_number = Integer()
+
+    db_log_output = Bool(False,
+        help="Should the history database include output? (default: no)"
+    ).tag(config=True)
+    db_cache_size = Integer(0,
+        help="Write to database every x commands (higher values save disk access & power).\n"
+        "Values of 1 or less effectively disable caching."
+    ).tag(config=True)
+    # The input and output caches
+    db_input_cache: List = List()
+    db_output_cache: List = List()
+
+    # History saving in separate thread
+    save_thread = Instance('IPython.core.history.HistorySavingThread',
+                           allow_none=True)
+    save_flag = Instance(threading.Event, allow_none=True)
+
+    # Private interface
+    # Variables used to store the three last inputs from the user.  On each new
+    # history update, we populate the user's namespace with these, shifted as
+    # necessary.
+    _i00 = Unicode("")
+    _i = Unicode("")
+    _ii = Unicode("")
+    _iii = Unicode("")
+
+    # A regex matching all forms of the exit command, so that we don't store
+    # them in the history (it's annoying to rewind the first entry and land on
+    # an exit call).
+    _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
+
+    def __init__(self, shell=None, config=None, **traits):
+        """Create a new history manager associated with a shell instance.
+        """
+        super(HistoryManager, self).__init__(shell=shell, config=config,
+            **traits)
+        self.save_flag = threading.Event()
+        self.db_input_cache_lock = threading.Lock()
+        self.db_output_cache_lock = threading.Lock()
+
+        try:
+            self.new_session()
+        except sqlite3.OperationalError:
+            self.log.error("Failed to create history session in %s. History will not be saved.",
+                self.hist_file, exc_info=True)
+            self.hist_file = ':memory:'
+
+        if self.enabled and self.hist_file != ':memory:':
+            self.save_thread = HistorySavingThread(self)
+            try:
+                self.save_thread.start()
+            except RuntimeError:
+                self.log.error(
+                    "Failed to start history saving thread. History will not be saved.",
+                    exc_info=True,
+                )
+                self.hist_file = ":memory:"
+
+    def _get_hist_file_name(self, profile=None):
+        """Get default history file name based on the Shell's profile.
+
+        The profile parameter is ignored, but must exist for compatibility with
+        the parent class."""
+        profile_dir = self.shell.profile_dir.location
+        return Path(profile_dir) / "history.sqlite"
+
+    @only_when_enabled
+    def new_session(self, conn=None):
+        """Get a new session number."""
+        if conn is None:
+            conn = self.db
+
+        with conn:
+            cur = conn.execute(
+                """INSERT INTO sessions VALUES (NULL, ?, NULL,
+                            NULL, '') """,
+                (datetime.datetime.now().isoformat(" "),),
+            )
+            self.session_number = cur.lastrowid
+
+    def end_session(self):
+        """Close the database session, filling in the end time and line count."""
+        self.writeout_cache()
+        with self.db:
+            self.db.execute(
+                """UPDATE sessions SET end=?, num_cmds=? WHERE
+                            session==?""",
+                (
+                    datetime.datetime.now().isoformat(" "),
+                    len(self.input_hist_parsed) - 1,
+                    self.session_number,
+                ),
+            )
+        self.session_number = 0
+
+    def name_session(self, name):
+        """Give the current session a name in the history database."""
+        with self.db:
+            self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
+                            (name, self.session_number))
+
+    def reset(self, new_session=True):
+        """Clear the session history, releasing all object references, and
+        optionally open a new session."""
+        self.output_hist.clear()
+        # The directory history can't be completely empty
+        self.dir_hist[:] = [Path.cwd()]
+
+        if new_session:
+            if self.session_number:
+                self.end_session()
+            self.input_hist_parsed[:] = [""]
+            self.input_hist_raw[:] = [""]
+            self.new_session()
+
+    # ------------------------------
+    # Methods for retrieving history
+    # ------------------------------
+    def get_session_info(self, session=0):
+        """Get info about a session.
+
+        Parameters
+        ----------
+        session : int
+            Session number to retrieve. The current session is 0, and negative
+            numbers count back from current session, so -1 is the previous session.
+
+        Returns
+        -------
+        session_id : int
+            Session ID number
+        start : datetime
+            Timestamp for the start of the session.
+        end : datetime
+            Timestamp for the end of the session, or None if IPython crashed.
+        num_cmds : int
+            Number of commands run, or None if IPython crashed.
+        remark : unicode
+            A manually set description.
+        """
+        if session <= 0:
+            session += self.session_number
+
+        return super(HistoryManager, self).get_session_info(session=session)
+
+    @catch_corrupt_db
+    def get_tail(self, n=10, raw=True, output=False, include_latest=False):
+        """Get the last n lines from the history database.
+
+        Most recent entry last.
+
+        Completion will be reordered so that that the last ones are when
+        possible from current session.
+
+        Parameters
+        ----------
+        n : int
+            The number of lines to get
+        raw, output : bool
+            See :meth:`get_range`
+        include_latest : bool
+            If False (default), n+1 lines are fetched, and the latest one
+            is discarded. This is intended to be used where the function
+            is called by a user command, which it should not return.
+
+        Returns
+        -------
+        Tuples as :meth:`get_range`
+        """
+        self.writeout_cache()
+        if not include_latest:
+            n += 1
+        # cursor/line/entry
+        this_cur = list(
+            self._run_sql(
+                "WHERE session == ? ORDER BY line DESC LIMIT ?  ",
+                (self.session_number, n),
+                raw=raw,
+                output=output,
+            )
+        )
+        other_cur = list(
+            self._run_sql(
+                "WHERE session != ? ORDER BY session DESC, line DESC LIMIT ?",
+                (self.session_number, n),
+                raw=raw,
+                output=output,
+            )
+        )
+
+        everything = this_cur + other_cur
+
+        everything = everything[:n]
+
+        if not include_latest:
+            return list(everything)[:0:-1]
+        return list(everything)[::-1]
+
+    def _get_range_session(self, start=1, stop=None, raw=True, output=False):
+        """Get input and output history from the current session. Called by
+        get_range, and takes similar parameters."""
+        input_hist = self.input_hist_raw if raw else self.input_hist_parsed
+
+        n = len(input_hist)
+        if start < 0:
+            start += n
+        if not stop or (stop > n):
+            stop = n
+        elif stop < 0:
+            stop += n
+
+        for i in range(start, stop):
+            if output:
+                line = (input_hist[i], self.output_hist_reprs.get(i))
+            else:
+                line = input_hist[i]
+            yield (0, i, line)
+
+    def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
+        """Retrieve input by session.
+
+        Parameters
+        ----------
+        session : int
+            Session number to retrieve. The current session is 0, and negative
+            numbers count back from current session, so -1 is previous session.
+        start : int
+            First line to retrieve.
+        stop : int
+            End of line range (excluded from output itself). If None, retrieve
+            to the end of the session.
+        raw : bool
+            If True, return untranslated input
+        output : bool
+            If True, attempt to include output. This will be 'real' Python
+            objects for the current session, or text reprs from previous
+            sessions if db_log_output was enabled at the time. Where no output
+            is found, None is used.
+
+        Returns
+        -------
+        entries
+            An iterator over the desired lines. Each line is a 3-tuple, either
+            (session, line, input) if output is False, or
+            (session, line, (input, output)) if output is True.
+        """
+        if session <= 0:
+            session += self.session_number
+        if session==self.session_number:          # Current session
+            return self._get_range_session(start, stop, raw, output)
+        return super(HistoryManager, self).get_range(session, start, stop, raw,
+                                                     output)
+
+    ## ----------------------------
+    ## Methods for storing history:
+    ## ----------------------------
+    def store_inputs(self, line_num, source, source_raw=None):
+        """Store source and raw input in history and create input cache
+        variables ``_i*``.
+
+        Parameters
+        ----------
+        line_num : int
+            The prompt number of this input.
+        source : str
+            Python input.
+        source_raw : str, optional
+            If given, this is the raw input without any IPython transformations
+            applied to it.  If not given, ``source`` is used.
+        """
+        if source_raw is None:
+            source_raw = source
+        source = source.rstrip('\n')
+        source_raw = source_raw.rstrip('\n')
+
+        # do not store exit/quit commands
+        if self._exit_re.match(source_raw.strip()):
+            return
+
+        self.input_hist_parsed.append(source)
+        self.input_hist_raw.append(source_raw)
+
+        with self.db_input_cache_lock:
+            self.db_input_cache.append((line_num, source, source_raw))
+            # Trigger to flush cache and write to DB.
+            if len(self.db_input_cache) >= self.db_cache_size:
+                self.save_flag.set()
+
+        # update the auto _i variables
+        self._iii = self._ii
+        self._ii = self._i
+        self._i = self._i00
+        self._i00 = source_raw
+
+        # hackish access to user namespace to create _i1,_i2... dynamically
+        new_i = '_i%s' % line_num
+        to_main = {'_i': self._i,
+                   '_ii': self._ii,
+                   '_iii': self._iii,
+                   new_i : self._i00 }
+
+        if self.shell is not None:
+            self.shell.push(to_main, interactive=False)
+
+    def store_output(self, line_num):
+        """If database output logging is enabled, this saves all the
+        outputs from the indicated prompt number to the database. It's
+        called by run_cell after code has been executed.
+
+        Parameters
+        ----------
+        line_num : int
+            The line number from which to save outputs
+        """
+        if (not self.db_log_output) or (line_num not in self.output_hist_reprs):
+            return
+        output = self.output_hist_reprs[line_num]
+
+        with self.db_output_cache_lock:
+            self.db_output_cache.append((line_num, output))
+        if self.db_cache_size <= 1:
+            self.save_flag.set()
+
+    def _writeout_input_cache(self, conn):
+        with conn:
+            for line in self.db_input_cache:
+                conn.execute("INSERT INTO history VALUES (?, ?, ?, ?)",
+                                (self.session_number,)+line)
+
+    def _writeout_output_cache(self, conn):
+        with conn:
+            for line in self.db_output_cache:
+                conn.execute("INSERT INTO output_history VALUES (?, ?, ?)",
+                                (self.session_number,)+line)
+
+    @only_when_enabled
+    def writeout_cache(self, conn=None):
+        """Write any entries in the cache to the database."""
+        if conn is None:
+            conn = self.db
+
+        with self.db_input_cache_lock:
+            try:
+                self._writeout_input_cache(conn)
+            except sqlite3.IntegrityError:
+                self.new_session(conn)
+                print("ERROR! Session/line number was not unique in",
+                      "database. History logging moved to new session",
+                                                self.session_number)
+                try:
+                    # Try writing to the new session. If this fails, don't
+                    # recurse
+                    self._writeout_input_cache(conn)
+                except sqlite3.IntegrityError:
+                    pass
+            finally:
+                self.db_input_cache = []
+
+        with self.db_output_cache_lock:
+            try:
+                self._writeout_output_cache(conn)
+            except sqlite3.IntegrityError:
+                print("!! Session/line number for output was not unique",
+                      "in database. Output will not be stored.")
+            finally:
+                self.db_output_cache = []
+
+
+class HistorySavingThread(threading.Thread):
+    """This thread takes care of writing history to the database, so that
+    the UI isn't held up while that happens.
+
+    It waits for the HistoryManager's save_flag to be set, then writes out
+    the history cache. The main thread is responsible for setting the flag when
+    the cache size reaches a defined threshold."""
+    daemon = True
+    stop_now = False
+    enabled = True
+    def __init__(self, history_manager):
+        super(HistorySavingThread, self).__init__(name="IPythonHistorySavingThread")
+        self.history_manager = history_manager
+        self.enabled = history_manager.enabled
+
+    @only_when_enabled
+    def run(self):
+        atexit.register(self.stop)
+        # We need a separate db connection per thread:
+        try:
+            self.db = sqlite3.connect(
+                str(self.history_manager.hist_file),
+                **self.history_manager.connection_options,
+            )
+            while True:
+                self.history_manager.save_flag.wait()
+                if self.stop_now:
+                    self.db.close()
+                    return
+                self.history_manager.save_flag.clear()
+                self.history_manager.writeout_cache(self.db)
+        except Exception as e:
+            print(("The history saving thread hit an unexpected error (%s)."
+                   "History will not be written to the database.") % repr(e))
+        finally:
+            atexit.unregister(self.stop)
+
+    def stop(self):
+        """This can be called from the main thread to safely stop this thread.
+
+        Note that it does not attempt to write out remaining history before
+        exiting. That should be done by calling the HistoryManager's
+        end_session method."""
+        self.stop_now = True
+        self.history_manager.save_flag.set()
+        self.join()
+
+
+# To match, e.g. ~5/8-~2/3
+range_re = re.compile(r"""
+((?P<startsess>~?\d+)/)?
+(?P<start>\d+)?
+((?P<sep>[\-:])
+ ((?P<endsess>~?\d+)/)?
+ (?P<end>\d+))?
+$""", re.VERBOSE)
+
+
+def extract_hist_ranges(ranges_str):
+    """Turn a string of history ranges into 3-tuples of (session, start, stop).
+
+    Empty string results in a `[(0, 1, None)]`, i.e. "everything from current
+    session".
+
+    Examples
+    --------
+    >>> list(extract_hist_ranges("~8/5-~7/4 2"))
+    [(-8, 5, None), (-7, 1, 5), (0, 2, 3)]
+    """
+    if ranges_str == "":
+        yield (0, 1, None)  # Everything from current session
+        return
+
+    for range_str in ranges_str.split():
+        rmatch = range_re.match(range_str)
+        if not rmatch:
+            continue
+        start = rmatch.group("start")
+        if start:
+            start = int(start)
+            end = rmatch.group("end")
+            # If no end specified, get (a, a + 1)
+            end = int(end) if end else start + 1
+        else:  # start not specified
+            if not rmatch.group('startsess'):  # no startsess
+                continue
+            start = 1
+            end = None  # provide the entire session hist
+
+        if rmatch.group("sep") == "-":       # 1-3 == 1:4 --> [1, 2, 3]
+            end += 1
+        startsess = rmatch.group("startsess") or "0"
+        endsess = rmatch.group("endsess") or startsess
+        startsess = int(startsess.replace("~","-"))
+        endsess = int(endsess.replace("~","-"))
+        assert endsess >= startsess, "start session must be earlier than end session"
+
+        if endsess == startsess:
+            yield (startsess, start, end)
+            continue
+        # Multiple sessions in one range:
+        yield (startsess, start, None)
+        for sess in range(startsess+1, endsess):
+            yield (sess, 1, None)
+        yield (endsess, 1, end)
+
+
+def _format_lineno(session, line):
+    """Helper function to format line numbers properly."""
+    if session == 0:
+        return str(line)
+    return "%s#%s" % (session, line)

openalex_env_map/lib/python3.10/site-packages/IPython/core/historyapp.py

@@ -0,0 +1,158 @@
+# encoding: utf-8
+"""
+An application for managing IPython history.
+
+To be invoked as the `ipython history` subcommand.
+"""
+
+import sqlite3
+from pathlib import Path
+
+from traitlets.config.application import Application
+from .application import BaseIPythonApplication
+from traitlets import Bool, Int, Dict
+from ..utils.io import ask_yes_no
+
+trim_hist_help = """Trim the IPython history database to the last 1000 entries.
+
+This actually copies the last 1000 entries to a new database, and then replaces
+the old file with the new. Use the `--keep=` argument to specify a number
+other than 1000.
+"""
+
+clear_hist_help = """Clear the IPython history database, deleting all entries.
+
+Because this is a destructive operation, IPython will prompt the user if they
+really want to do this. Passing a `-f` flag will force clearing without a
+prompt.
+
+This is an handy alias to `ipython history trim --keep=0`
+"""
+
+
+class HistoryTrim(BaseIPythonApplication):
+    description = trim_hist_help
+
+    backup = Bool(False, help="Keep the old history file as history.sqlite.<N>").tag(
+        config=True
+    )
+
+    keep = Int(1000, help="Number of recent lines to keep in the database.").tag(
+        config=True
+    )
+
+    flags = Dict(  # type: ignore
+        dict(backup=({"HistoryTrim": {"backup": True}}, backup.help))
+    )
+
+    aliases = Dict(dict(keep="HistoryTrim.keep"))  # type: ignore
+
+    def start(self):
+        profile_dir = Path(self.profile_dir.location)
+        hist_file = profile_dir / "history.sqlite"
+        con = sqlite3.connect(hist_file)
+
+        # Grab the recent history from the current database.
+        inputs = list(con.execute('SELECT session, line, source, source_raw FROM '
+                                'history ORDER BY session DESC, line DESC LIMIT ?', (self.keep+1,)))
+        if len(inputs) <= self.keep:
+            print("There are already at most %d entries in the history database." % self.keep)
+            print("Not doing anything. Use --keep= argument to keep fewer entries")
+            return
+        
+        print("Trimming history to the most recent %d entries." % self.keep)
+        
+        inputs.pop() # Remove the extra element we got to check the length.
+        inputs.reverse()
+        if inputs:
+            first_session = inputs[0][0]
+            outputs = list(con.execute('SELECT session, line, output FROM '
+                                       'output_history WHERE session >= ?', (first_session,)))
+            sessions = list(con.execute('SELECT session, start, end, num_cmds, remark FROM '
+                                        'sessions WHERE session >= ?', (first_session,)))
+        con.close()
+        
+        # Create the new history database.
+        new_hist_file = profile_dir / "history.sqlite.new"
+        i = 0
+        while new_hist_file.exists():
+            # Make sure we don't interfere with an existing file.
+            i += 1
+            new_hist_file = profile_dir / ("history.sqlite.new" + str(i))
+        new_db = sqlite3.connect(new_hist_file)
+        new_db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
+                            primary key autoincrement, start timestamp,
+                            end timestamp, num_cmds integer, remark text)""")
+        new_db.execute("""CREATE TABLE IF NOT EXISTS history
+                        (session integer, line integer, source text, source_raw text,
+                        PRIMARY KEY (session, line))""")
+        new_db.execute("""CREATE TABLE IF NOT EXISTS output_history
+                        (session integer, line integer, output text,
+                        PRIMARY KEY (session, line))""")
+        new_db.commit()
+
+
+        if inputs:
+            with new_db:
+                # Add the recent history into the new database.
+                new_db.executemany('insert into sessions values (?,?,?,?,?)', sessions)
+                new_db.executemany('insert into history values (?,?,?,?)', inputs)
+                new_db.executemany('insert into output_history values (?,?,?)', outputs)
+        new_db.close()
+
+        if self.backup:
+            i = 1
+            backup_hist_file = profile_dir / ("history.sqlite.old.%d" % i)
+            while backup_hist_file.exists():
+                i += 1
+                backup_hist_file = profile_dir / ("history.sqlite.old.%d" % i)
+            hist_file.rename(backup_hist_file)
+            print("Backed up longer history file to", backup_hist_file)
+        else:
+            hist_file.unlink()
+
+        new_hist_file.rename(hist_file)
+
+
+class HistoryClear(HistoryTrim):
+    description = clear_hist_help
+    keep = Int(0, help="Number of recent lines to keep in the database.")
+
+    force = Bool(False, help="Don't prompt user for confirmation").tag(config=True)
+
+    flags = Dict(  # type: ignore
+        dict(
+            force=({"HistoryClear": {"force": True}}, force.help),
+            f=({"HistoryTrim": {"force": True}}, force.help),
+        )
+    )
+    aliases = Dict()  # type: ignore
+
+    def start(self):
+        if self.force or ask_yes_no(
+            "Really delete all ipython history? ", default="no", interrupt="no"
+        ):
+            HistoryTrim.start(self)
+
+
+class HistoryApp(Application):
+    name = "ipython-history"
+    description = "Manage the IPython history database."
+
+    subcommands = Dict(dict(
+        trim = (HistoryTrim, HistoryTrim.description.splitlines()[0]),
+        clear = (HistoryClear, HistoryClear.description.splitlines()[0]),
+    ))
+
+    def start(self):
+        if self.subapp is None:
+            print(
+                "No subcommand specified. Must specify one of: "
+                + ", ".join(map(repr, self.subcommands))
+                + ".\n"
+            )
+            self.print_description()
+            self.print_subcommands()
+            self.exit(1)
+        else:
+            return self.subapp.start()

openalex_env_map/lib/python3.10/site-packages/IPython/core/hooks.py

@@ -0,0 +1,173 @@
+"""Hooks for IPython.
+
+In Python, it is possible to overwrite any method of any object if you really
+want to.  But IPython exposes a few 'hooks', methods which are *designed* to
+be overwritten by users for customization purposes.  This module defines the
+default versions of all such hooks, which get used by IPython if not
+overridden by the user.
+
+Hooks are simple functions, but they should be declared with ``self`` as their
+first argument, because when activated they are registered into IPython as
+instance methods. The self argument will be the IPython running instance
+itself, so hooks have full access to the entire IPython object.
+
+If you wish to define a new hook and activate it, you can make an :doc:`extension
+</config/extensions/index>` or a :ref:`startup script <startup_files>`. For
+example, you could use a startup file like this::
+
+    import os
+
+    def calljed(self,filename, linenum):
+        "My editor hook calls the jed editor directly."
+        print("Calling my own editor, jed ...")
+        if os.system('jed +%d %s' % (linenum,filename)) != 0:
+            raise TryNext()
+
+    def load_ipython_extension(ip):
+        ip.set_hook('editor', calljed)
+
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2005 Fernando Perez. <[email protected]>
+#
+#  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 subprocess
+import sys
+
+from .error import TryNext
+
+# List here all the default hooks.  For now it's just the editor functions
+# but over time we'll move here all the public API for user-accessible things.
+
+__all__ = [
+    "editor",
+    "synchronize_with_editor",
+    "show_in_pager",
+    "pre_prompt_hook",
+    "clipboard_get",
+]
+
+deprecated = {'pre_run_code_hook': "a callback for the 'pre_execute' or 'pre_run_cell' event",
+              'late_startup_hook': "a callback for the 'shell_initialized' event",
+              'shutdown_hook': "the atexit module",
+             }
+
+def editor(self, filename, linenum=None, wait=True):
+    """Open the default editor at the given filename and linenumber.
+
+    This is IPython's default editor hook, you can use it as an example to
+    write your own modified one.  To set your own editor function as the
+    new editor hook, call ip.set_hook('editor',yourfunc)."""
+
+    # IPython configures a default editor at startup by reading $EDITOR from
+    # the environment, and falling back on vi (unix) or notepad (win32).
+    editor = self.editor
+
+    # marker for at which line to open the file (for existing objects)
+    if linenum is None or editor=='notepad':
+        linemark = ''
+    else:
+        linemark = '+%d' % int(linenum)
+
+    # Enclose in quotes if necessary and legal
+    if ' ' in editor and os.path.isfile(editor) and editor[0] != '"':
+        editor = '"%s"' % editor
+
+    # Call the actual editor
+    proc = subprocess.Popen('%s %s %s' % (editor, linemark, filename),
+                            shell=True)
+    if wait and proc.wait() != 0:
+        raise TryNext()
+
+
+def synchronize_with_editor(self, filename, linenum, column):
+        pass
+
+
+class CommandChainDispatcher:
+    """ Dispatch calls to a chain of commands until some func can handle it
+
+    Usage: instantiate, execute "add" to add commands (with optional
+    priority), execute normally via f() calling mechanism.
+
+    """
+    def __init__(self,commands=None):
+        if commands is None:
+            self.chain = []
+        else:
+            self.chain = commands
+
+
+    def __call__(self,*args, **kw):
+        """ Command chain is called just like normal func.
+
+        This will call all funcs in chain with the same args as were given to
+        this function, and return the result of first func that didn't raise
+        TryNext"""
+        last_exc = TryNext()
+        for prio,cmd in self.chain:
+            # print("prio",prio,"cmd",cmd)  # dbg
+            try:
+                return cmd(*args, **kw)
+            except TryNext as exc:
+                last_exc = exc
+        # if no function will accept it, raise TryNext up to the caller
+        raise last_exc
+
+    def __str__(self):
+        return str(self.chain)
+
+    def add(self, func, priority=0):
+        """ Add a func to the cmd chain with given priority """
+        self.chain.append((priority, func))
+        self.chain.sort(key=lambda x: x[0])
+
+    def __iter__(self):
+        """ Return all objects in chain.
+
+        Handy if the objects are not callable.
+        """
+        return iter(self.chain)
+
+
+def show_in_pager(self, data, start, screen_lines):
+    """ Run a string through pager """
+    # raising TryNext here will use the default paging functionality
+    raise TryNext
+
+
+def pre_prompt_hook(self):
+    """ Run before displaying the next prompt
+
+    Use this e.g. to display output from asynchronous operations (in order
+    to not mess up text entry)
+    """
+
+    return None
+
+
+def clipboard_get(self):
+    """ Get text from the clipboard.
+    """
+    from ..lib.clipboard import (
+        osx_clipboard_get,
+        tkinter_clipboard_get,
+        win32_clipboard_get,
+        wayland_clipboard_get,
+    )
+    if sys.platform == 'win32':
+        chain = [win32_clipboard_get, tkinter_clipboard_get]
+    elif sys.platform == 'darwin':
+        chain = [osx_clipboard_get, tkinter_clipboard_get]
+    else:
+        chain = [wayland_clipboard_get, tkinter_clipboard_get]
+    dispatcher = CommandChainDispatcher()
+    for func in chain:
+        dispatcher.add(func)
+    text = dispatcher()
+    return text

openalex_env_map/lib/python3.10/site-packages/IPython/core/inputsplitter.py

@@ -0,0 +1,799 @@
+"""DEPRECATED: Input handling and transformation machinery.
+
+This module was deprecated in IPython 7.0, in favour of inputtransformer2.
+
+The first class in this module, :class:`InputSplitter`, is designed to tell when
+input from a line-oriented frontend is complete and should be executed, and when
+the user should be prompted for another line of code instead. The name 'input
+splitter' is largely for historical reasons.
+
+A companion, :class:`IPythonInputSplitter`, provides the same functionality but
+with full support for the extended IPython syntax (magics, system calls, etc).
+The code to actually do these transformations is in :mod:`IPython.core.inputtransformer`.
+:class:`IPythonInputSplitter` feeds the raw code to the transformers in order
+and stores the results.
+
+For more details, see the class docstrings below.
+"""
+
+from __future__ import annotations
+
+from warnings import warn
+
+warn('IPython.core.inputsplitter is deprecated since IPython 7 in favor of `IPython.core.inputtransformer2`',
+     DeprecationWarning)
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+import ast
+import codeop
+import io
+import re
+import sys
+import tokenize
+import warnings
+
+from typing import List, Tuple, Union, Optional, TYPE_CHECKING
+from types import CodeType
+
+from IPython.core.inputtransformer import (leading_indent,
+                                           classic_prompt,
+                                           ipy_prompt,
+                                           cellmagic,
+                                           assemble_logical_lines,
+                                           help_end,
+                                           escaped_commands,
+                                           assign_from_magic,
+                                           assign_from_system,
+                                           assemble_python_lines,
+                                           )
+from IPython.utils import tokenutil
+
+# These are available in this module for backwards compatibility.
+from IPython.core.inputtransformer import (ESC_SHELL, ESC_SH_CAP, ESC_HELP,
+                                        ESC_HELP2, ESC_MAGIC, ESC_MAGIC2,
+                                        ESC_QUOTE, ESC_QUOTE2, ESC_PAREN, ESC_SEQUENCES)
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+#-----------------------------------------------------------------------------
+# Utilities
+#-----------------------------------------------------------------------------
+
+# FIXME: These are general-purpose utilities that later can be moved to the
+# general ward.  Kept here for now because we're being very strict about test
+# coverage with this code, and this lets us ensure that we keep 100% coverage
+# while developing.
+
+# compiled regexps for autoindent management
+dedent_re = re.compile('|'.join([
+    r'^\s+raise(\s.*)?$', # raise statement (+ space + other stuff, maybe)
+    r'^\s+raise\([^\)]*\).*$', # wacky raise with immediate open paren
+    r'^\s+return(\s.*)?$', # normal return (+ space + other stuff, maybe)
+    r'^\s+return\([^\)]*\).*$', # wacky return with immediate open paren
+    r'^\s+pass\s*$', # pass (optionally followed by trailing spaces)
+    r'^\s+break\s*$', # break (optionally followed by trailing spaces)
+    r'^\s+continue\s*$', # continue (optionally followed by trailing spaces)
+]))
+ini_spaces_re = re.compile(r'^([ \t\r\f\v]+)')
+
+# regexp to match pure comment lines so we don't accidentally insert 'if 1:'
+# before pure comments
+comment_line_re = re.compile(r'^\s*\#')
+
+
+def num_ini_spaces(s):
+    """Return the number of initial spaces in a string.
+
+    Note that tabs are counted as a single space.  For now, we do *not* support
+    mixing of tabs and spaces in the user's input.
+
+    Parameters
+    ----------
+    s : string
+
+    Returns
+    -------
+    n : int
+    """
+    warnings.warn(
+        "`num_ini_spaces` is Pending Deprecation since IPython 8.17."
+        "It is considered for removal in in future version. "
+        "Please open an issue if you believe it should be kept.",
+        stacklevel=2,
+        category=PendingDeprecationWarning,
+    )
+    ini_spaces = ini_spaces_re.match(s)
+    if ini_spaces:
+        return ini_spaces.end()
+    else:
+        return 0
+
+# Fake token types for partial_tokenize:
+INCOMPLETE_STRING = tokenize.N_TOKENS
+IN_MULTILINE_STATEMENT = tokenize.N_TOKENS + 1
+
+# The 2 classes below have the same API as TokenInfo, but don't try to look up
+# a token type name that they won't find.
+class IncompleteString:
+    type = exact_type = INCOMPLETE_STRING
+    def __init__(self, s, start, end, line):
+        self.s = s
+        self.start = start
+        self.end = end
+        self.line = line
+
+class InMultilineStatement:
+    type = exact_type = IN_MULTILINE_STATEMENT
+    def __init__(self, pos, line):
+        self.s = ''
+        self.start = self.end = pos
+        self.line = line
+
+def partial_tokens(s):
+    """Iterate over tokens from a possibly-incomplete string of code.
+
+    This adds two special token types: INCOMPLETE_STRING and
+    IN_MULTILINE_STATEMENT. These can only occur as the last token yielded, and
+    represent the two main ways for code to be incomplete.
+    """
+    readline = io.StringIO(s).readline
+    token = tokenize.TokenInfo(tokenize.NEWLINE, '', (1, 0), (1, 0), '')
+    try:
+        for token in tokenutil.generate_tokens_catch_errors(readline):
+            yield token
+    except tokenize.TokenError as e:
+        # catch EOF error
+        lines = s.splitlines(keepends=True)
+        end = len(lines), len(lines[-1])
+        if 'multi-line string' in e.args[0]:
+            l, c = start = token.end
+            s = lines[l-1][c:] + ''.join(lines[l:])
+            yield IncompleteString(s, start, end, lines[-1])
+        elif 'multi-line statement' in e.args[0]:
+            yield InMultilineStatement(end, lines[-1])
+        else:
+            raise
+
+def find_next_indent(code) -> int:
+    """Find the number of spaces for the next line of indentation"""
+    tokens = list(partial_tokens(code))
+    if tokens[-1].type == tokenize.ENDMARKER:
+        tokens.pop()
+    if not tokens:
+        return 0
+
+    while tokens[-1].type in {
+        tokenize.DEDENT,
+        tokenize.NEWLINE,
+        tokenize.COMMENT,
+        tokenize.ERRORTOKEN,
+    }:
+        tokens.pop()
+
+    # Starting in Python 3.12, the tokenize module adds implicit newlines at the end
+    # of input. We need to remove those if we're in a multiline statement
+    if tokens[-1].type == IN_MULTILINE_STATEMENT:
+        while tokens[-2].type in {tokenize.NL}:
+            tokens.pop(-2)
+
+
+    if tokens[-1].type == INCOMPLETE_STRING:
+        # Inside a multiline string
+        return 0
+
+    # Find the indents used before
+    prev_indents = [0]
+    def _add_indent(n):
+        if n != prev_indents[-1]:
+            prev_indents.append(n)
+
+    tokiter = iter(tokens)
+    for tok in tokiter:
+        if tok.type in {tokenize.INDENT, tokenize.DEDENT}:
+            _add_indent(tok.end[1])
+        elif (tok.type == tokenize.NL):
+            try:
+                _add_indent(next(tokiter).start[1])
+            except StopIteration:
+                break
+
+    last_indent = prev_indents.pop()
+
+    # If we've just opened a multiline statement (e.g. 'a = ['), indent more
+    if tokens[-1].type == IN_MULTILINE_STATEMENT:
+        if tokens[-2].exact_type in {tokenize.LPAR, tokenize.LSQB, tokenize.LBRACE}:
+            return last_indent + 4
+        return last_indent
+
+    if tokens[-1].exact_type == tokenize.COLON:
+        # Line ends with colon - indent
+        return last_indent + 4
+
+    if last_indent:
+        # Examine the last line for dedent cues - statements like return or
+        # raise which normally end a block of code.
+        last_line_starts = 0
+        for i, tok in enumerate(tokens):
+            if tok.type == tokenize.NEWLINE:
+                last_line_starts = i + 1
+
+        last_line_tokens = tokens[last_line_starts:]
+        names = [t.string for t in last_line_tokens if t.type == tokenize.NAME]
+        if names and names[0] in {'raise', 'return', 'pass', 'break', 'continue'}:
+            # Find the most recent indentation less than the current level
+            for indent in reversed(prev_indents):
+                if indent < last_indent:
+                    return indent
+
+    return last_indent
+
+
+def last_blank(src):
+    """Determine if the input source ends in a blank.
+
+    A blank is either a newline or a line consisting of whitespace.
+
+    Parameters
+    ----------
+    src : string
+        A single or multiline string.
+    """
+    if not src: return False
+    ll  = src.splitlines()[-1]
+    return (ll == '') or ll.isspace()
+
+
+last_two_blanks_re = re.compile(r'\n\s*\n\s*$', re.MULTILINE)
+last_two_blanks_re2 = re.compile(r'.+\n\s*\n\s+$', re.MULTILINE)
+
+def last_two_blanks(src):
+    """Determine if the input source ends in two blanks.
+
+    A blank is either a newline or a line consisting of whitespace.
+
+    Parameters
+    ----------
+    src : string
+        A single or multiline string.
+    """
+    if not src: return False
+    # The logic here is tricky: I couldn't get a regexp to work and pass all
+    # the tests, so I took a different approach: split the source by lines,
+    # grab the last two and prepend '###\n' as a stand-in for whatever was in
+    # the body before the last two lines.  Then, with that structure, it's
+    # possible to analyze with two regexps.  Not the most elegant solution, but
+    # it works.  If anyone tries to change this logic, make sure to validate
+    # the whole test suite first!
+    new_src = '\n'.join(['###\n'] + src.splitlines()[-2:])
+    return (bool(last_two_blanks_re.match(new_src)) or
+            bool(last_two_blanks_re2.match(new_src)) )
+
+
+def remove_comments(src):
+    """Remove all comments from input source.
+
+    Note: comments are NOT recognized inside of strings!
+
+    Parameters
+    ----------
+    src : string
+        A single or multiline input string.
+
+    Returns
+    -------
+    String with all Python comments removed.
+    """
+
+    return re.sub('#.*', '', src)
+
+
+def get_input_encoding():
+    """Return the default standard input encoding.
+
+    If sys.stdin has no encoding, 'ascii' is returned."""
+    # There are strange environments for which sys.stdin.encoding is None. We
+    # ensure that a valid encoding is returned.
+    encoding = getattr(sys.stdin, 'encoding', None)
+    if encoding is None:
+        encoding = 'ascii'
+    return encoding
+
+#-----------------------------------------------------------------------------
+# Classes and functions for normal Python syntax handling
+#-----------------------------------------------------------------------------
+
+class InputSplitter(object):
+    r"""An object that can accumulate lines of Python source before execution.
+
+    This object is designed to be fed python source line-by-line, using
+    :meth:`push`. It will return on each push whether the currently pushed
+    code could be executed already. In addition, it provides a method called
+    :meth:`push_accepts_more` that can be used to query whether more input
+    can be pushed into a single interactive block.
+
+    This is a simple example of how an interactive terminal-based client can use
+    this tool::
+
+        isp = InputSplitter()
+        while isp.push_accepts_more():
+            indent = ' '*isp.indent_spaces
+            prompt = '>>> ' + indent
+            line = indent + raw_input(prompt)
+            isp.push(line)
+        print('Input source was:\n', isp.source_reset())
+    """
+    # A cache for storing the current indentation
+    # The first value stores the most recently processed source input
+    # The second value is the number of spaces for the current indentation 
+    # If self.source matches the first value, the second value is a valid
+    # current indentation. Otherwise, the cache is invalid and the indentation
+    # must be recalculated.
+    _indent_spaces_cache: Union[Tuple[None, None], Tuple[str, int]] = None, None
+    # String, indicating the default input encoding.  It is computed by default
+    # at initialization time via get_input_encoding(), but it can be reset by a
+    # client with specific knowledge of the encoding.
+    encoding = ''
+    # String where the current full source input is stored, properly encoded.
+    # Reading this attribute is the normal way of querying the currently pushed
+    # source code, that has been properly encoded.
+    source: str = ""
+    # Code object corresponding to the current source.  It is automatically
+    # synced to the source, so it can be queried at any time to obtain the code
+    # object; it will be None if the source doesn't compile to valid Python.
+    code: Optional[CodeType] = None
+
+    # Private attributes
+
+    # List with lines of input accumulated so far
+    _buffer: List[str]
+    # Command compiler
+    _compile: codeop.CommandCompiler
+    # Boolean indicating whether the current block is complete
+    _is_complete: Optional[bool] = None
+    # Boolean indicating whether the current block has an unrecoverable syntax error
+    _is_invalid: bool = False
+
+    def __init__(self) -> None:
+        """Create a new InputSplitter instance."""
+        self._buffer = []
+        self._compile = codeop.CommandCompiler()
+        self.encoding = get_input_encoding()
+
+    def reset(self):
+        """Reset the input buffer and associated state."""
+        self._buffer[:] = []
+        self.source = ''
+        self.code = None
+        self._is_complete = False
+        self._is_invalid = False
+
+    def source_reset(self):
+        """Return the input source and perform a full reset.
+        """
+        out = self.source
+        self.reset()
+        return out
+
+    def check_complete(self, source):
+        """Return whether a block of code is ready to execute, or should be continued
+
+        This is a non-stateful API, and will reset the state of this InputSplitter.
+
+        Parameters
+        ----------
+        source : string
+            Python input code, which can be multiline.
+
+        Returns
+        -------
+        status : str
+            One of 'complete', 'incomplete', or 'invalid' if source is not a
+            prefix of valid code.
+        indent_spaces : int or None
+            The number of spaces by which to indent the next line of code. If
+            status is not 'incomplete', this is None.
+        """
+        self.reset()
+        try:
+            self.push(source)
+        except SyntaxError:
+            # Transformers in IPythonInputSplitter can raise SyntaxError,
+            # which push() will not catch.
+            return 'invalid', None
+        else:
+            if self._is_invalid:
+                return 'invalid', None
+            elif self.push_accepts_more():
+                return 'incomplete', self.get_indent_spaces()
+            else:
+                return 'complete', None
+        finally:
+            self.reset()
+
+    def push(self, lines:str) -> bool:
+        """Push one or more lines of input.
+
+        This stores the given lines and returns a status code indicating
+        whether the code forms a complete Python block or not.
+
+        Any exceptions generated in compilation are swallowed, but if an
+        exception was produced, the method returns True.
+
+        Parameters
+        ----------
+        lines : string
+            One or more lines of Python input.
+
+        Returns
+        -------
+        is_complete : boolean
+            True if the current input source (the result of the current input
+            plus prior inputs) forms a complete Python execution block.  Note that
+            this value is also stored as a private attribute (``_is_complete``), so it
+            can be queried at any time.
+        """
+        assert isinstance(lines, str)
+        self._store(lines)
+        source = self.source
+
+        # Before calling _compile(), reset the code object to None so that if an
+        # exception is raised in compilation, we don't mislead by having
+        # inconsistent code/source attributes.
+        self.code, self._is_complete = None, None
+        self._is_invalid = False
+
+        # Honor termination lines properly
+        if source.endswith('\\\n'):
+            return False
+
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter('error', SyntaxWarning)
+                self.code = self._compile(source, symbol="exec")
+        # Invalid syntax can produce any of a number of different errors from
+        # inside the compiler, so we have to catch them all.  Syntax errors
+        # immediately produce a 'ready' block, so the invalid Python can be
+        # sent to the kernel for evaluation with possible ipython
+        # special-syntax conversion.
+        except (SyntaxError, OverflowError, ValueError, TypeError,
+                MemoryError, SyntaxWarning):
+            self._is_complete = True
+            self._is_invalid = True
+        else:
+            # Compilation didn't produce any exceptions (though it may not have
+            # given a complete code object)
+            self._is_complete = self.code is not None
+
+        return self._is_complete
+
+    def push_accepts_more(self):
+        """Return whether a block of interactive input can accept more input.
+
+        This method is meant to be used by line-oriented frontends, who need to
+        guess whether a block is complete or not based solely on prior and
+        current input lines.  The InputSplitter considers it has a complete
+        interactive block and will not accept more input when either:
+
+        * A SyntaxError is raised
+
+        * The code is complete and consists of a single line or a single
+          non-compound statement
+
+        * The code is complete and has a blank line at the end
+
+        If the current input produces a syntax error, this method immediately
+        returns False but does *not* raise the syntax error exception, as
+        typically clients will want to send invalid syntax to an execution
+        backend which might convert the invalid syntax into valid Python via
+        one of the dynamic IPython mechanisms.
+        """
+
+        # With incomplete input, unconditionally accept more
+        # A syntax error also sets _is_complete to True - see push()
+        if not self._is_complete:
+            #print("Not complete")  # debug
+            return True
+        
+        # The user can make any (complete) input execute by leaving a blank line
+        last_line = self.source.splitlines()[-1]
+        if (not last_line) or last_line.isspace():
+            #print("Blank line")  # debug
+            return False
+        
+        # If there's just a single line or AST node, and we're flush left, as is
+        # the case after a simple statement such as 'a=1', we want to execute it
+        # straight away.
+        if self.get_indent_spaces() == 0:
+            if len(self.source.splitlines()) <= 1:
+                return False
+            
+            try:
+                code_ast = ast.parse("".join(self._buffer))
+            except Exception:
+                #print("Can't parse AST")  # debug
+                return False
+            else:
+                if len(code_ast.body) == 1 and \
+                                    not hasattr(code_ast.body[0], 'body'):
+                    #print("Simple statement")  # debug
+                    return False
+
+        # General fallback - accept more code
+        return True
+
+    def get_indent_spaces(self) -> int:
+        sourcefor, n = self._indent_spaces_cache
+        if sourcefor == self.source:
+            assert n is not None
+            return n
+
+        # self.source always has a trailing newline
+        n = find_next_indent(self.source[:-1])
+        self._indent_spaces_cache = (self.source, n)
+        return n
+
+    # Backwards compatibility. I think all code that used .indent_spaces was
+    # inside IPython, but we can leave this here until IPython 7 in case any
+    # other modules are using it. -TK, November 2017
+    indent_spaces = property(get_indent_spaces)
+
+    def _store(self, lines, buffer=None, store='source'):
+        """Store one or more lines of input.
+
+        If input lines are not newline-terminated, a newline is automatically
+        appended."""
+
+        if buffer is None:
+            buffer = self._buffer
+
+        if lines.endswith('\n'):
+            buffer.append(lines)
+        else:
+            buffer.append(lines+'\n')
+        setattr(self, store, self._set_source(buffer))
+
+    def _set_source(self, buffer):
+        return u''.join(buffer)
+
+
+class IPythonInputSplitter(InputSplitter):
+    """An input splitter that recognizes all of IPython's special syntax."""
+
+    # String with raw, untransformed input.
+    source_raw = ''
+    
+    # Flag to track when a transformer has stored input that it hasn't given
+    # back yet.
+    transformer_accumulating = False
+    
+    # Flag to track when assemble_python_lines has stored input that it hasn't
+    # given back yet.
+    within_python_line = False
+
+    # Private attributes
+
+    # List with lines of raw input accumulated so far.
+    _buffer_raw: List[str]
+
+    def __init__(self, line_input_checker=True, physical_line_transforms=None,
+                    logical_line_transforms=None, python_line_transforms=None):
+        super(IPythonInputSplitter, self).__init__()
+        self._buffer_raw = []
+        self._validate = True
+        
+        if physical_line_transforms is not None:
+            self.physical_line_transforms = physical_line_transforms
+        else:
+            self.physical_line_transforms = [
+                                             leading_indent(),
+                                             classic_prompt(),
+                                             ipy_prompt(),
+                                             cellmagic(end_on_blank_line=line_input_checker),
+                                            ]
+        
+        self.assemble_logical_lines = assemble_logical_lines()
+        if logical_line_transforms is not None:
+            self.logical_line_transforms = logical_line_transforms
+        else:
+            self.logical_line_transforms = [
+                                            help_end(),
+                                            escaped_commands(),
+                                            assign_from_magic(),
+                                            assign_from_system(),
+                                           ]
+        
+        self.assemble_python_lines = assemble_python_lines()
+        if python_line_transforms is not None:
+            self.python_line_transforms = python_line_transforms
+        else:
+            # We don't use any of these at present
+            self.python_line_transforms = []
+    
+    @property
+    def transforms(self):
+        "Quick access to all transformers."
+        return self.physical_line_transforms + \
+            [self.assemble_logical_lines] + self.logical_line_transforms + \
+            [self.assemble_python_lines]  + self.python_line_transforms
+    
+    @property
+    def transforms_in_use(self):
+        """Transformers, excluding logical line transformers if we're in a
+        Python line."""
+        t = self.physical_line_transforms[:]
+        if not self.within_python_line:
+            t += [self.assemble_logical_lines] + self.logical_line_transforms
+        return t + [self.assemble_python_lines] + self.python_line_transforms
+
+    def reset(self):
+        """Reset the input buffer and associated state."""
+        super(IPythonInputSplitter, self).reset()
+        self._buffer_raw[:] = []
+        self.source_raw = ''
+        self.transformer_accumulating = False
+        self.within_python_line = False
+
+        for t in self.transforms:
+            try:
+                t.reset()
+            except SyntaxError:
+                # Nothing that calls reset() expects to handle transformer
+                # errors
+                pass
+
+    def flush_transformers(self: Self):
+        def _flush(transform, outs: List[str]):
+            """yield transformed lines
+
+            always strings, never None
+
+            transform: the current transform
+            outs: an iterable of previously transformed inputs.
+                 Each may be multiline, which will be passed
+                 one line at a time to transform.
+            """
+            for out in outs:
+                for line in out.splitlines():
+                    # push one line at a time
+                    tmp = transform.push(line)
+                    if tmp is not None:
+                        yield tmp
+            
+            # reset the transform
+            tmp = transform.reset()
+            if tmp is not None:
+                yield tmp
+
+        out: List[str] = []
+        for t in self.transforms_in_use:
+            out = _flush(t, out)
+        
+        out = list(out)
+        if out:
+            self._store('\n'.join(out))
+
+    def raw_reset(self):
+        """Return raw input only and perform a full reset.
+        """
+        out = self.source_raw
+        self.reset()
+        return out
+    
+    def source_reset(self):
+        try:
+            self.flush_transformers()
+            return self.source
+        finally:
+            self.reset()
+
+    def push_accepts_more(self):
+        if self.transformer_accumulating:
+            return True
+        else:
+            return super(IPythonInputSplitter, self).push_accepts_more()
+
+    def transform_cell(self, cell):
+        """Process and translate a cell of input.
+        """
+        self.reset()
+        try:
+            self.push(cell)
+            self.flush_transformers()
+            return self.source
+        finally:
+            self.reset()
+
+    def push(self, lines:str) -> bool:
+        """Push one or more lines of IPython input.
+
+        This stores the given lines and returns a status code indicating
+        whether the code forms a complete Python block or not, after processing
+        all input lines for special IPython syntax.
+
+        Any exceptions generated in compilation are swallowed, but if an
+        exception was produced, the method returns True.
+
+        Parameters
+        ----------
+        lines : string
+            One or more lines of Python input.
+
+        Returns
+        -------
+        is_complete : boolean
+            True if the current input source (the result of the current input
+            plus prior inputs) forms a complete Python execution block.  Note that
+            this value is also stored as a private attribute (_is_complete), so it
+            can be queried at any time.
+        """
+        assert isinstance(lines, str)
+        # We must ensure all input is pure unicode
+        # ''.splitlines() --> [], but we need to push the empty line to transformers
+        lines_list = lines.splitlines()
+        if not lines_list:
+            lines_list = ['']
+
+        # Store raw source before applying any transformations to it.  Note
+        # that this must be done *after* the reset() call that would otherwise
+        # flush the buffer.
+        self._store(lines, self._buffer_raw, 'source_raw')
+
+        transformed_lines_list = []
+        for line in lines_list:
+            transformed = self._transform_line(line)
+            if transformed is not None:
+                transformed_lines_list.append(transformed)
+
+        if transformed_lines_list:
+            transformed_lines = '\n'.join(transformed_lines_list)
+            return super(IPythonInputSplitter, self).push(transformed_lines)
+        else:
+            # Got nothing back from transformers - they must be waiting for
+            # more input.
+            return False
+
+    def _transform_line(self, line):
+        """Push a line of input code through the various transformers.
+
+        Returns any output from the transformers, or None if a transformer
+        is accumulating lines.
+
+        Sets self.transformer_accumulating as a side effect.
+        """
+        def _accumulating(dbg):
+            #print(dbg)
+            self.transformer_accumulating = True
+            return None
+
+        for transformer in self.physical_line_transforms:
+            line = transformer.push(line)
+            if line is None:
+                return _accumulating(transformer)
+
+        if not self.within_python_line:
+            line = self.assemble_logical_lines.push(line)
+            if line is None:
+                return _accumulating('acc logical line')
+
+            for transformer in self.logical_line_transforms:
+                line = transformer.push(line)
+                if line is None:
+                    return _accumulating(transformer)
+
+        line = self.assemble_python_lines.push(line)
+        if line is None:
+            self.within_python_line = True
+            return _accumulating('acc python line')
+        else:
+            self.within_python_line = False
+
+        for transformer in self.python_line_transforms:
+            line = transformer.push(line)
+            if line is None:
+                return _accumulating(transformer)
+
+        #print("transformers clear") #debug
+        self.transformer_accumulating = False
+        return line
+

openalex_env_map/lib/python3.10/site-packages/IPython/core/inputtransformer.py

@@ -0,0 +1,577 @@
+"""DEPRECATED: Input transformer classes to support IPython special syntax.
+
+This module was deprecated in IPython 7.0, in favour of inputtransformer2.
+
+This includes the machinery to recognise and transform ``%magic`` commands,
+``!system`` commands, ``help?`` querying, prompt stripping, and so forth.
+"""
+import abc
+import functools
+import re
+import tokenize
+import warnings
+from tokenize import untokenize, TokenError
+from io import StringIO
+
+from IPython.core.splitinput import LineInfo
+from IPython.utils import tokenutil
+
+#-----------------------------------------------------------------------------
+# Globals
+#-----------------------------------------------------------------------------
+
+# The escape sequences that define the syntax transformations IPython will
+# apply to user input.  These can NOT be just changed here: many regular
+# expressions and other parts of the code may use their hardcoded values, and
+# for all intents and purposes they constitute the 'IPython syntax', so they
+# should be considered fixed.
+
+ESC_SHELL  = '!'     # Send line to underlying system shell
+ESC_SH_CAP = '!!'    # Send line to system shell and capture output
+ESC_HELP   = '?'     # Find information about object
+ESC_HELP2  = '??'    # Find extra-detailed information about object
+ESC_MAGIC  = '%'     # Call magic function
+ESC_MAGIC2 = '%%'    # Call cell-magic function
+ESC_QUOTE  = ','     # Split args on whitespace, quote each as string and call
+ESC_QUOTE2 = ';'     # Quote all args as a single string, call
+ESC_PAREN  = '/'     # Call first argument with rest of line as arguments
+
+ESC_SEQUENCES = [ESC_SHELL, ESC_SH_CAP, ESC_HELP ,\
+                 ESC_HELP2, ESC_MAGIC, ESC_MAGIC2,\
+                 ESC_QUOTE, ESC_QUOTE2, ESC_PAREN ]
+
+
+class InputTransformer(metaclass=abc.ABCMeta):
+    """Abstract base class for line-based input transformers."""
+
+    def __init__(self):
+        warnings.warn(
+            "`InputTransformer` has been deprecated since IPython 7.0"
+            " and emit a warnig since IPython 8.31, it"
+            " will be removed in the future",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    @abc.abstractmethod
+    def push(self, line):
+        """Send a line of input to the transformer, returning the transformed
+        input or None if the transformer is waiting for more input.
+
+        Must be overridden by subclasses.
+
+        Implementations may raise ``SyntaxError`` if the input is invalid. No
+        other exceptions may be raised.
+        """
+        pass
+    
+    @abc.abstractmethod
+    def reset(self):
+        """Return, transformed any lines that the transformer has accumulated,
+        and reset its internal state.
+
+        Must be overridden by subclasses.
+        """
+        pass
+    
+    @classmethod
+    def wrap(cls, func):
+        """Can be used by subclasses as a decorator, to return a factory that
+        will allow instantiation with the decorated object.
+        """
+        @functools.wraps(func)
+        def transformer_factory(**kwargs):
+            return cls(func, **kwargs)  # type: ignore [call-arg]
+
+        return transformer_factory
+
+class StatelessInputTransformer(InputTransformer):
+    """Wrapper for a stateless input transformer implemented as a function."""
+    def __init__(self, func):
+        super().__init__()
+        warnings.warn(
+            "`StatelessInputTransformer` has been deprecated since IPython 7.0"
+            " and emit a warnig since IPython 8.31, it"
+            " will be removed in the future",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.func = func
+    
+    def __repr__(self):
+        return "StatelessInputTransformer(func={0!r})".format(self.func)
+    
+    def push(self, line):
+        """Send a line of input to the transformer, returning the
+        transformed input."""
+        return self.func(line)
+    
+    def reset(self):
+        """No-op - exists for compatibility."""
+        pass
+
+class CoroutineInputTransformer(InputTransformer):
+    """Wrapper for an input transformer implemented as a coroutine."""
+    def __init__(self, coro, **kwargs):
+        # Prime it
+        super().__init__()
+        warnings.warn(
+            "`CoroutineInputTransformer` has been deprecated since IPython 7.0"
+            " and emit a warnig since IPython 8.31, it"
+            " will be removed in the future",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.coro = coro(**kwargs)
+        next(self.coro)
+    
+    def __repr__(self):
+        return "CoroutineInputTransformer(coro={0!r})".format(self.coro)
+    
+    def push(self, line):
+        """Send a line of input to the transformer, returning the
+        transformed input or None if the transformer is waiting for more
+        input.
+        """
+        return self.coro.send(line)
+    
+    def reset(self):
+        """Return, transformed any lines that the transformer has
+        accumulated, and reset its internal state.
+        """
+        return self.coro.send(None)
+
+class TokenInputTransformer(InputTransformer):
+    """Wrapper for a token-based input transformer.
+    
+    func should accept a list of tokens (5-tuples, see tokenize docs), and
+    return an iterable which can be passed to tokenize.untokenize().
+    """
+    def __init__(self, func):
+        warnings.warn(
+            "`CoroutineInputTransformer` has been deprecated since IPython 7.0"
+            " and emit a warnig since IPython 8.31, it"
+            " will be removed in the future",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.func = func
+        self.buf = []
+        self.reset_tokenizer()
+
+    def reset_tokenizer(self):
+        it = iter(self.buf)
+        self.tokenizer = tokenutil.generate_tokens_catch_errors(it.__next__)
+
+    def push(self, line):
+        self.buf.append(line + '\n')
+        if all(l.isspace() for l in self.buf):
+            return self.reset()
+
+        tokens = []
+        stop_at_NL = False
+        try:
+            for intok in self.tokenizer:
+                tokens.append(intok)
+                t = intok[0]
+                if t == tokenize.NEWLINE or (stop_at_NL and t == tokenize.NL):
+                    # Stop before we try to pull a line we don't have yet
+                    break
+                elif t == tokenize.ERRORTOKEN:
+                    stop_at_NL = True
+        except TokenError:
+            # Multi-line statement - stop and try again with the next line
+            self.reset_tokenizer()
+            return None
+        
+        return self.output(tokens)
+    
+    def output(self, tokens):
+        self.buf.clear()
+        self.reset_tokenizer()
+        return untokenize(self.func(tokens)).rstrip('\n')
+    
+    def reset(self):
+        l = ''.join(self.buf)
+        self.buf.clear()
+        self.reset_tokenizer()
+        if l:
+            return l.rstrip('\n')
+
+class assemble_python_lines(TokenInputTransformer):
+    def __init__(self):
+        super().__init__(None)
+    
+    def output(self, tokens):
+        return self.reset()
+
+@CoroutineInputTransformer.wrap
+def assemble_logical_lines():
+    r"""Join lines following explicit line continuations (\)"""
+    line = ''
+    while True:
+        line = (yield line)
+        if not line or line.isspace():
+            continue
+        
+        parts = []
+        while line is not None:
+            if line.endswith('\\') and (not has_comment(line)):
+                parts.append(line[:-1])
+                line = (yield None) # Get another line
+            else:
+                parts.append(line)
+                break
+        
+        # Output
+        line = ''.join(parts)
+
+# Utilities
+def _make_help_call(target: str, esc: str, lspace: str) -> str:
+    """Prepares a pinfo(2)/psearch call from a target name and the escape
+    (i.e. ? or ??)"""
+    method  = 'pinfo2' if esc == '??' \
+                else 'psearch' if '*' in target \
+                else 'pinfo'
+    arg = " ".join([method, target])
+    #Prepare arguments for get_ipython().run_line_magic(magic_name, magic_args)
+    t_magic_name, _, t_magic_arg_s = arg.partition(' ')
+    t_magic_name = t_magic_name.lstrip(ESC_MAGIC)
+    return "%sget_ipython().run_line_magic(%r, %r)" % (
+        lspace,
+        t_magic_name,
+        t_magic_arg_s,
+    )
+
+
+# These define the transformations for the different escape characters.
+def _tr_system(line_info: LineInfo):
+    "Translate lines escaped with: !"
+    cmd = line_info.line.lstrip().lstrip(ESC_SHELL)
+    return '%sget_ipython().system(%r)' % (line_info.pre, cmd)
+
+
+def _tr_system2(line_info: LineInfo):
+    "Translate lines escaped with: !!"
+    cmd = line_info.line.lstrip()[2:]
+    return '%sget_ipython().getoutput(%r)' % (line_info.pre, cmd)
+
+
+def _tr_help(line_info: LineInfo):
+    "Translate lines escaped with: ?/??"
+    # A naked help line should just fire the intro help screen
+    if not line_info.line[1:]:
+        return 'get_ipython().show_usage()'
+
+    return _make_help_call(line_info.ifun, line_info.esc, line_info.pre)
+
+
+def _tr_magic(line_info: LineInfo):
+    "Translate lines escaped with: %"
+    tpl = '%sget_ipython().run_line_magic(%r, %r)'
+    if line_info.line.startswith(ESC_MAGIC2):
+        return line_info.line
+    cmd = ' '.join([line_info.ifun, line_info.the_rest]).strip()
+    #Prepare arguments for get_ipython().run_line_magic(magic_name, magic_args)
+    t_magic_name, _, t_magic_arg_s = cmd.partition(' ')
+    t_magic_name = t_magic_name.lstrip(ESC_MAGIC)
+    return tpl % (line_info.pre, t_magic_name, t_magic_arg_s)
+
+
+def _tr_quote(line_info: LineInfo):
+    "Translate lines escaped with: ,"
+    return '%s%s("%s")' % (line_info.pre, line_info.ifun,
+                         '", "'.join(line_info.the_rest.split()) )
+
+
+def _tr_quote2(line_info: LineInfo):
+    "Translate lines escaped with: ;"
+    return '%s%s("%s")' % (line_info.pre, line_info.ifun,
+                           line_info.the_rest)
+
+
+def _tr_paren(line_info: LineInfo):
+    "Translate lines escaped with: /"
+    return '%s%s(%s)' % (line_info.pre, line_info.ifun,
+                         ", ".join(line_info.the_rest.split()))
+
+tr = { ESC_SHELL  : _tr_system,
+       ESC_SH_CAP : _tr_system2,
+       ESC_HELP   : _tr_help,
+       ESC_HELP2  : _tr_help,
+       ESC_MAGIC  : _tr_magic,
+       ESC_QUOTE  : _tr_quote,
+       ESC_QUOTE2 : _tr_quote2,
+       ESC_PAREN  : _tr_paren }
+
+@StatelessInputTransformer.wrap
+def escaped_commands(line: str):
+    """Transform escaped commands - %magic, !system, ?help + various autocalls."""
+    if not line or line.isspace():
+        return line
+    lineinf = LineInfo(line)
+    if lineinf.esc not in tr:
+        return line
+    
+    return tr[lineinf.esc](lineinf)
+
+_initial_space_re = re.compile(r'\s*')
+
+_help_end_re = re.compile(r"""(%{0,2}
+                              (?!\d)[\w*]+            # Variable name
+                              (\.(?!\d)[\w*]+)*       # .etc.etc
+                              )
+                              (\?\??)$                # ? or ??
+                              """,
+                              re.VERBOSE)
+
+# Extra pseudotokens for multiline strings and data structures
+_MULTILINE_STRING = object()
+_MULTILINE_STRUCTURE = object()
+
+def _line_tokens(line):
+    """Helper for has_comment and ends_in_comment_or_string."""
+    readline = StringIO(line).readline
+    toktypes = set()
+    try:
+        for t in tokenutil.generate_tokens_catch_errors(readline):
+            toktypes.add(t[0])
+    except TokenError as e:
+        # There are only two cases where a TokenError is raised.
+        if 'multi-line string' in e.args[0]:
+            toktypes.add(_MULTILINE_STRING)
+        else:
+            toktypes.add(_MULTILINE_STRUCTURE)
+    return toktypes
+
+def has_comment(src):
+    """Indicate whether an input line has (i.e. ends in, or is) a comment.
+
+    This uses tokenize, so it can distinguish comments from # inside strings.
+
+    Parameters
+    ----------
+    src : string
+        A single line input string.
+
+    Returns
+    -------
+    comment : bool
+        True if source has a comment.
+    """
+    return (tokenize.COMMENT in _line_tokens(src))
+
+def ends_in_comment_or_string(src):
+    """Indicates whether or not an input line ends in a comment or within
+    a multiline string.
+
+    Parameters
+    ----------
+    src : string
+        A single line input string.
+
+    Returns
+    -------
+    comment : bool
+        True if source ends in a comment or multiline string.
+    """
+    toktypes = _line_tokens(src)
+    return (tokenize.COMMENT in toktypes) or (_MULTILINE_STRING in toktypes)
+        
+
+@StatelessInputTransformer.wrap
+def help_end(line: str):
+    """Translate lines with ?/?? at the end"""
+    m = _help_end_re.search(line)
+    if m is None or ends_in_comment_or_string(line):
+        return line
+    target = m.group(1)
+    esc = m.group(3)
+    match = _initial_space_re.match(line)
+    assert match is not None
+    lspace = match.group(0)
+
+    return _make_help_call(target, esc, lspace)
+
+
+@CoroutineInputTransformer.wrap
+def cellmagic(end_on_blank_line: bool = False):
+    """Captures & transforms cell magics.
+
+    After a cell magic is started, this stores up any lines it gets until it is
+    reset (sent None).
+    """
+    tpl = 'get_ipython().run_cell_magic(%r, %r, %r)'
+    cellmagic_help_re = re.compile(r'%%\w+\?')
+    line = ''
+    while True:
+        line = (yield line)
+        # consume leading empty lines
+        while not line:
+            line = (yield line)
+        
+        if not line.startswith(ESC_MAGIC2):
+            # This isn't a cell magic, idle waiting for reset then start over
+            while line is not None:
+                line = (yield line)
+            continue
+        
+        if cellmagic_help_re.match(line):
+            # This case will be handled by help_end
+            continue
+        
+        first = line
+        body = []
+        line = (yield None)
+        while (line is not None) and \
+                                ((line.strip() != '') or not end_on_blank_line):
+            body.append(line)
+            line = (yield None)
+        
+        # Output
+        magic_name, _, first = first.partition(' ')
+        magic_name = magic_name.lstrip(ESC_MAGIC2)
+        line = tpl % (magic_name, first, u'\n'.join(body))
+
+
+def _strip_prompts(prompt_re, initial_re=None, turnoff_re=None):
+    """Remove matching input prompts from a block of input.
+
+    Parameters
+    ----------
+    prompt_re : regular expression
+        A regular expression matching any input prompt (including continuation)
+    initial_re : regular expression, optional
+        A regular expression matching only the initial prompt, but not continuation.
+        If no initial expression is given, prompt_re will be used everywhere.
+        Used mainly for plain Python prompts, where the continuation prompt
+        ``...`` is a valid Python expression in Python 3, so shouldn't be stripped.
+
+    Notes
+    -----
+    If `initial_re` and `prompt_re differ`,
+    only `initial_re` will be tested against the first line.
+    If any prompt is found on the first two lines,
+    prompts will be stripped from the rest of the block.
+    """
+    if initial_re is None:
+        initial_re = prompt_re
+    line = ''
+    while True:
+        line = (yield line)
+        
+        # First line of cell
+        if line is None:
+            continue
+        out, n1 = initial_re.subn('', line, count=1)
+        if turnoff_re and not n1:
+            if turnoff_re.match(line):
+                # We're in e.g. a cell magic; disable this transformer for
+                # the rest of the cell.
+                while line is not None:
+                    line = (yield line)
+                continue
+
+        line = (yield out)
+        
+        if line is None:
+            continue
+        # check for any prompt on the second line of the cell,
+        # because people often copy from just after the first prompt,
+        # so we might not see it in the first line.
+        out, n2 = prompt_re.subn('', line, count=1)
+        line = (yield out)
+        
+        if n1 or n2:
+            # Found a prompt in the first two lines - check for it in
+            # the rest of the cell as well.
+            while line is not None:
+                line = (yield prompt_re.sub('', line, count=1))
+        
+        else:
+            # Prompts not in input - wait for reset
+            while line is not None:
+                line = (yield line)
+
+@CoroutineInputTransformer.wrap
+def classic_prompt():
+    """Strip the >>>/... prompts of the Python interactive shell."""
+    # FIXME: non-capturing version (?:...) usable?
+    prompt_re = re.compile(r'^(>>>|\.\.\.)( |$)')
+    initial_re = re.compile(r'^>>>( |$)')
+    # Any %magic/!system is IPython syntax, so we needn't look for >>> prompts
+    turnoff_re = re.compile(r'^[%!]')
+    return _strip_prompts(prompt_re, initial_re, turnoff_re)
+
+@CoroutineInputTransformer.wrap
+def ipy_prompt():
+    """Strip IPython's In [1]:/...: prompts."""
+    # FIXME: non-capturing version (?:...) usable?
+    prompt_re = re.compile(r'^(In \[\d+\]: |\s*\.{3,}: ?)')
+    # Disable prompt stripping inside cell magics
+    turnoff_re = re.compile(r'^%%')
+    return _strip_prompts(prompt_re, turnoff_re=turnoff_re)
+
+
+@CoroutineInputTransformer.wrap
+def leading_indent():
+    """Remove leading indentation.
+
+    If the first line starts with a spaces or tabs, the same whitespace will be
+    removed from each following line until it is reset.
+    """
+    space_re = re.compile(r'^[ \t]+')
+    line = ''
+    while True:
+        line = (yield line)
+        
+        if line is None:
+            continue
+        
+        m = space_re.match(line)
+        if m:
+            space = m.group(0)
+            while line is not None:
+                if line.startswith(space):
+                    line = line[len(space):]
+                line = (yield line)
+        else:
+            # No leading spaces - wait for reset
+            while line is not None:
+                line = (yield line)
+
+
+_assign_pat = \
+r'''(?P<lhs>(\s*)
+    ([\w\.]+)                # Initial identifier
+    (\s*,\s*
+        \*?[\w\.]+)*         # Further identifiers for unpacking
+    \s*?,?                   # Trailing comma
+    )
+    \s*=\s*
+'''
+
+assign_system_re = re.compile(r'{}!\s*(?P<cmd>.*)'.format(_assign_pat), re.VERBOSE)
+assign_system_template = '%s = get_ipython().getoutput(%r)'
+@StatelessInputTransformer.wrap
+def assign_from_system(line):
+    """Transform assignment from system commands (e.g. files = !ls)"""
+    m = assign_system_re.match(line)
+    if m is None:
+        return line
+    
+    return assign_system_template % m.group('lhs', 'cmd')
+
+assign_magic_re = re.compile(r'{}%\s*(?P<cmd>.*)'.format(_assign_pat), re.VERBOSE)
+assign_magic_template = '%s = get_ipython().run_line_magic(%r, %r)'
+@StatelessInputTransformer.wrap
+def assign_from_magic(line):
+    """Transform assignment from magic commands (e.g. a = %who_ls)"""
+    m = assign_magic_re.match(line)
+    if m is None:
+        return line
+    #Prepare arguments for get_ipython().run_line_magic(magic_name, magic_args)
+    m_lhs, m_cmd = m.group('lhs', 'cmd')
+    t_magic_name, _, t_magic_arg_s = m_cmd.partition(' ')
+    t_magic_name = t_magic_name.lstrip(ESC_MAGIC)
+    return assign_magic_template % (m_lhs, t_magic_name, t_magic_arg_s)

openalex_env_map/lib/python3.10/site-packages/IPython/core/inputtransformer2.py

@@ -0,0 +1,830 @@
+"""Input transformer machinery to support IPython special syntax.
+
+This includes the machinery to recognise and transform ``%magic`` commands,
+``!system`` commands, ``help?`` querying, prompt stripping, and so forth.
+
+Added: IPython 7.0. Replaces inputsplitter and inputtransformer which were
+deprecated in 7.0.
+"""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import ast
+from codeop import CommandCompiler, Compile
+import re
+import sys
+import tokenize
+from typing import List, Tuple, Optional, Any
+import warnings
+
+from IPython.utils import tokenutil
+
+_indent_re = re.compile(r'^[ \t]+')
+
+def leading_empty_lines(lines):
+    """Remove leading empty lines
+
+    If the leading lines are empty or contain only whitespace, they will be
+    removed.
+    """
+    if not lines:
+        return lines
+    for i, line in enumerate(lines):
+        if line and not line.isspace():
+            return lines[i:]
+    return lines
+
+def leading_indent(lines):
+    """Remove leading indentation.
+
+    If the first line starts with a spaces or tabs, the same whitespace will be
+    removed from each following line in the cell.
+    """
+    if not lines:
+        return lines
+    m = _indent_re.match(lines[0])
+    if not m:
+        return lines
+    space = m.group(0)
+    n = len(space)
+    return [l[n:] if l.startswith(space) else l
+            for l in lines]
+
+class PromptStripper:
+    """Remove matching input prompts from a block of input.
+
+    Parameters
+    ----------
+    prompt_re : regular expression
+        A regular expression matching any input prompt (including continuation,
+        e.g. ``...``)
+    initial_re : regular expression, optional
+        A regular expression matching only the initial prompt, but not continuation.
+        If no initial expression is given, prompt_re will be used everywhere.
+        Used mainly for plain Python prompts (``>>>``), where the continuation prompt
+        ``...`` is a valid Python expression in Python 3, so shouldn't be stripped.
+
+    Notes
+    -----
+
+    If initial_re and prompt_re differ,
+    only initial_re will be tested against the first line.
+    If any prompt is found on the first two lines,
+    prompts will be stripped from the rest of the block.
+    """
+    def __init__(self, prompt_re, initial_re=None):
+        self.prompt_re = prompt_re
+        self.initial_re = initial_re or prompt_re
+
+    def _strip(self, lines):
+        return [self.prompt_re.sub('', l, count=1) for l in lines]
+
+    def __call__(self, lines):
+        if not lines:
+            return lines
+        if self.initial_re.match(lines[0]) or \
+                (len(lines) > 1 and self.prompt_re.match(lines[1])):
+            return self._strip(lines)
+        return lines
+
+classic_prompt = PromptStripper(
+    prompt_re=re.compile(r'^(>>>|\.\.\.)( |$)'),
+    initial_re=re.compile(r'^>>>( |$)')
+)
+
+ipython_prompt = PromptStripper(
+    re.compile(
+        r"""
+        ^(                         # Match from the beginning of a line, either:
+
+                                   # 1. First-line prompt:
+        ((\[nav\]|\[ins\])?\ )?    # Vi editing mode prompt, if it's there
+        In\                        # The 'In' of the prompt, with a space
+        \[\d+\]:                   # Command index, as displayed in the prompt
+        \                          # With a mandatory trailing space
+
+        |                          # ... or ...
+
+                                   # 2. The three dots of the multiline prompt
+        \s*                        # All leading whitespace characters
+        \.{3,}:                    # The three (or more) dots
+        \ ?                        # With an optional trailing space
+
+        )
+        """,
+        re.VERBOSE,
+    )
+)
+
+
+def cell_magic(lines):
+    if not lines or not lines[0].startswith('%%'):
+        return lines
+    if re.match(r'%%\w+\?', lines[0]):
+        # This case will be handled by help_end
+        return lines
+    magic_name, _, first_line = lines[0][2:].rstrip().partition(' ')
+    body = ''.join(lines[1:])
+    return ['get_ipython().run_cell_magic(%r, %r, %r)\n'
+            % (magic_name, first_line, body)]
+
+
+def _find_assign_op(token_line) -> Optional[int]:
+    """Get the index of the first assignment in the line ('=' not inside brackets)
+
+    Note: We don't try to support multiple special assignment (a = b = %foo)
+    """
+    paren_level = 0
+    for i, ti in enumerate(token_line):
+        s = ti.string
+        if s == '=' and paren_level == 0:
+            return i
+        if s in {'(','[','{'}:
+            paren_level += 1
+        elif s in {')', ']', '}'}:
+            if paren_level > 0:
+                paren_level -= 1
+    return None
+
+def find_end_of_continued_line(lines, start_line: int):
+    """Find the last line of a line explicitly extended using backslashes.
+
+    Uses 0-indexed line numbers.
+    """
+    end_line = start_line
+    while lines[end_line].endswith('\\\n'):
+        end_line += 1
+        if end_line >= len(lines):
+            break
+    return end_line
+
+def assemble_continued_line(lines, start: Tuple[int, int], end_line: int):
+    r"""Assemble a single line from multiple continued line pieces
+
+    Continued lines are lines ending in ``\``, and the line following the last
+    ``\`` in the block.
+
+    For example, this code continues over multiple lines::
+
+        if (assign_ix is not None) \
+             and (len(line) >= assign_ix + 2) \
+             and (line[assign_ix+1].string == '%') \
+             and (line[assign_ix+2].type == tokenize.NAME):
+
+    This statement contains four continued line pieces.
+    Assembling these pieces into a single line would give::
+
+        if (assign_ix is not None) and (len(line) >= assign_ix + 2) and (line[...
+
+    This uses 0-indexed line numbers. *start* is (lineno, colno).
+
+    Used to allow ``%magic`` and ``!system`` commands to be continued over
+    multiple lines.
+    """
+    parts = [lines[start[0]][start[1]:]] + lines[start[0]+1:end_line+1]
+    return ' '.join([p.rstrip()[:-1] for p in parts[:-1]]  # Strip backslash+newline
+                    + [parts[-1].rstrip()])         # Strip newline from last line
+
+class TokenTransformBase:
+    """Base class for transformations which examine tokens.
+
+    Special syntax should not be transformed when it occurs inside strings or
+    comments. This is hard to reliably avoid with regexes. The solution is to
+    tokenise the code as Python, and recognise the special syntax in the tokens.
+
+    IPython's special syntax is not valid Python syntax, so tokenising may go
+    wrong after the special syntax starts. These classes therefore find and
+    transform *one* instance of special syntax at a time into regular Python
+    syntax. After each transformation, tokens are regenerated to find the next
+    piece of special syntax.
+
+    Subclasses need to implement one class method (find)
+    and one regular method (transform).
+
+    The priority attribute can select which transformation to apply if multiple
+    transformers match in the same place. Lower numbers have higher priority.
+    This allows "%magic?" to be turned into a help call rather than a magic call.
+    """
+    # Lower numbers -> higher priority (for matches in the same location)
+    priority = 10
+
+    def sortby(self):
+        return self.start_line, self.start_col, self.priority
+
+    def __init__(self, start):
+        self.start_line = start[0] - 1   # Shift from 1-index to 0-index
+        self.start_col = start[1]
+
+    @classmethod
+    def find(cls, tokens_by_line):
+        """Find one instance of special syntax in the provided tokens.
+
+        Tokens are grouped into logical lines for convenience,
+        so it is easy to e.g. look at the first token of each line.
+        *tokens_by_line* is a list of lists of tokenize.TokenInfo objects.
+
+        This should return an instance of its class, pointing to the start
+        position it has found, or None if it found no match.
+        """
+        raise NotImplementedError
+
+    def transform(self, lines: List[str]):
+        """Transform one instance of special syntax found by ``find()``
+
+        Takes a list of strings representing physical lines,
+        returns a similar list of transformed lines.
+        """
+        raise NotImplementedError
+
+class MagicAssign(TokenTransformBase):
+    """Transformer for assignments from magics (a = %foo)"""
+    @classmethod
+    def find(cls, tokens_by_line):
+        """Find the first magic assignment (a = %foo) in the cell.
+        """
+        for line in tokens_by_line:
+            assign_ix = _find_assign_op(line)
+            if (assign_ix is not None) \
+                    and (len(line) >= assign_ix + 2) \
+                    and (line[assign_ix+1].string == '%') \
+                    and (line[assign_ix+2].type == tokenize.NAME):
+                return cls(line[assign_ix+1].start)
+
+    def transform(self, lines: List[str]):
+        """Transform a magic assignment found by the ``find()`` classmethod.
+        """
+        start_line, start_col = self.start_line, self.start_col
+        lhs = lines[start_line][:start_col]
+        end_line = find_end_of_continued_line(lines, start_line)
+        rhs = assemble_continued_line(lines, (start_line, start_col), end_line)
+        assert rhs.startswith('%'), rhs
+        magic_name, _, args = rhs[1:].partition(' ')
+
+        lines_before = lines[:start_line]
+        call = "get_ipython().run_line_magic({!r}, {!r})".format(magic_name, args)
+        new_line = lhs + call + '\n'
+        lines_after = lines[end_line+1:]
+
+        return lines_before + [new_line] + lines_after
+
+
+class SystemAssign(TokenTransformBase):
+    """Transformer for assignments from system commands (a = !foo)"""
+    @classmethod
+    def find_pre_312(cls, tokens_by_line):
+        for line in tokens_by_line:
+            assign_ix = _find_assign_op(line)
+            if (assign_ix is not None) \
+                    and not line[assign_ix].line.strip().startswith('=') \
+                    and (len(line) >= assign_ix + 2) \
+                    and (line[assign_ix + 1].type == tokenize.ERRORTOKEN):
+                ix = assign_ix + 1
+
+                while ix < len(line) and line[ix].type == tokenize.ERRORTOKEN:
+                    if line[ix].string == '!':
+                        return cls(line[ix].start)
+                    elif not line[ix].string.isspace():
+                        break
+                    ix += 1
+
+    @classmethod
+    def find_post_312(cls, tokens_by_line):
+        for line in tokens_by_line:
+            assign_ix = _find_assign_op(line)
+            if (
+                (assign_ix is not None)
+                and not line[assign_ix].line.strip().startswith("=")
+                and (len(line) >= assign_ix + 2)
+                and (line[assign_ix + 1].type == tokenize.OP)
+                and (line[assign_ix + 1].string == "!")
+            ):
+                return cls(line[assign_ix + 1].start)
+
+    @classmethod
+    def find(cls, tokens_by_line):
+        """Find the first system assignment (a = !foo) in the cell."""
+        if sys.version_info < (3, 12):
+            return cls.find_pre_312(tokens_by_line)
+        return cls.find_post_312(tokens_by_line)
+
+    def transform(self, lines: List[str]):
+        """Transform a system assignment found by the ``find()`` classmethod.
+        """
+        start_line, start_col = self.start_line, self.start_col
+
+        lhs = lines[start_line][:start_col]
+        end_line = find_end_of_continued_line(lines, start_line)
+        rhs = assemble_continued_line(lines, (start_line, start_col), end_line)
+        assert rhs.startswith('!'), rhs
+        cmd = rhs[1:]
+
+        lines_before = lines[:start_line]
+        call = "get_ipython().getoutput({!r})".format(cmd)
+        new_line = lhs + call + '\n'
+        lines_after = lines[end_line + 1:]
+
+        return lines_before + [new_line] + lines_after
+
+# The escape sequences that define the syntax transformations IPython will
+# apply to user input.  These can NOT be just changed here: many regular
+# expressions and other parts of the code may use their hardcoded values, and
+# for all intents and purposes they constitute the 'IPython syntax', so they
+# should be considered fixed.
+
+ESC_SHELL  = '!'     # Send line to underlying system shell
+ESC_SH_CAP = '!!'    # Send line to system shell and capture output
+ESC_HELP   = '?'     # Find information about object
+ESC_HELP2  = '??'    # Find extra-detailed information about object
+ESC_MAGIC  = '%'     # Call magic function
+ESC_MAGIC2 = '%%'    # Call cell-magic function
+ESC_QUOTE  = ','     # Split args on whitespace, quote each as string and call
+ESC_QUOTE2 = ';'     # Quote all args as a single string, call
+ESC_PAREN  = '/'     # Call first argument with rest of line as arguments
+
+ESCAPE_SINGLES = {'!', '?', '%', ',', ';', '/'}
+ESCAPE_DOUBLES = {'!!', '??'}  # %% (cell magic) is handled separately
+
+def _make_help_call(target, esc):
+    """Prepares a pinfo(2)/psearch call from a target name and the escape
+    (i.e. ? or ??)"""
+    method  = 'pinfo2' if esc == '??' \
+                else 'psearch' if '*' in target \
+                else 'pinfo'
+    arg = " ".join([method, target])
+    #Prepare arguments for get_ipython().run_line_magic(magic_name, magic_args)
+    t_magic_name, _, t_magic_arg_s = arg.partition(' ')
+    t_magic_name = t_magic_name.lstrip(ESC_MAGIC)
+    return "get_ipython().run_line_magic(%r, %r)" % (t_magic_name, t_magic_arg_s)
+
+
+def _tr_help(content):
+    """Translate lines escaped with: ?
+
+    A naked help line should fire the intro help screen (shell.show_usage())
+    """
+    if not content:
+        return 'get_ipython().show_usage()'
+
+    return _make_help_call(content, '?')
+
+def _tr_help2(content):
+    """Translate lines escaped with: ??
+
+    A naked help line should fire the intro help screen (shell.show_usage())
+    """
+    if not content:
+        return 'get_ipython().show_usage()'
+
+    return _make_help_call(content, '??')
+
+def _tr_magic(content):
+    "Translate lines escaped with a percent sign: %"
+    name, _, args = content.partition(' ')
+    return 'get_ipython().run_line_magic(%r, %r)' % (name, args)
+
+def _tr_quote(content):
+    "Translate lines escaped with a comma: ,"
+    name, _, args = content.partition(' ')
+    return '%s("%s")' % (name, '", "'.join(args.split()) )
+
+def _tr_quote2(content):
+    "Translate lines escaped with a semicolon: ;"
+    name, _, args = content.partition(' ')
+    return '%s("%s")' % (name, args)
+
+def _tr_paren(content):
+    "Translate lines escaped with a slash: /"
+    name, _, args = content.partition(" ")
+    if name == "":
+        raise SyntaxError(f'"{ESC_SHELL}" must be followed by a callable name')
+
+    return '%s(%s)' % (name, ", ".join(args.split()))
+
+tr = { ESC_SHELL  : 'get_ipython().system({!r})'.format,
+       ESC_SH_CAP : 'get_ipython().getoutput({!r})'.format,
+       ESC_HELP   : _tr_help,
+       ESC_HELP2  : _tr_help2,
+       ESC_MAGIC  : _tr_magic,
+       ESC_QUOTE  : _tr_quote,
+       ESC_QUOTE2 : _tr_quote2,
+       ESC_PAREN  : _tr_paren }
+
+class EscapedCommand(TokenTransformBase):
+    """Transformer for escaped commands like %foo, !foo, or /foo"""
+    @classmethod
+    def find(cls, tokens_by_line):
+        """Find the first escaped command (%foo, !foo, etc.) in the cell.
+        """
+        for line in tokens_by_line:
+            if not line:
+                continue
+            ix = 0
+            ll = len(line)
+            while ll > ix and line[ix].type in {tokenize.INDENT, tokenize.DEDENT}:
+                ix += 1
+            if ix >= ll:
+                continue
+            if line[ix].string in ESCAPE_SINGLES:
+                return cls(line[ix].start)
+
+    def transform(self, lines):
+        """Transform an escaped line found by the ``find()`` classmethod.
+        """
+        start_line, start_col = self.start_line, self.start_col
+
+        indent = lines[start_line][:start_col]
+        end_line = find_end_of_continued_line(lines, start_line)
+        line = assemble_continued_line(lines, (start_line, start_col), end_line)
+
+        if len(line) > 1 and line[:2] in ESCAPE_DOUBLES:
+            escape, content = line[:2], line[2:]
+        else:
+            escape, content = line[:1], line[1:]
+
+        if escape in tr:
+            call = tr[escape](content)
+        else:
+            call = ''
+
+        lines_before = lines[:start_line]
+        new_line = indent + call + '\n'
+        lines_after = lines[end_line + 1:]
+
+        return lines_before + [new_line] + lines_after
+
+
+_help_end_re = re.compile(
+    r"""(%{0,2}
+    (?!\d)[\w*]+            # Variable name
+    (\.(?!\d)[\w*]+|\[-?[0-9]+\])*       # .etc.etc or [0], we only support literal integers.
+    )
+    (\?\??)$                # ? or ??
+    """,
+    re.VERBOSE,
+)
+
+
+class HelpEnd(TokenTransformBase):
+    """Transformer for help syntax: obj? and obj??"""
+    # This needs to be higher priority (lower number) than EscapedCommand so
+    # that inspecting magics (%foo?) works.
+    priority = 5
+
+    def __init__(self, start, q_locn):
+        super().__init__(start)
+        self.q_line = q_locn[0] - 1  # Shift from 1-indexed to 0-indexed
+        self.q_col = q_locn[1]
+
+    @classmethod
+    def find(cls, tokens_by_line):
+        """Find the first help command (foo?) in the cell.
+        """
+        for line in tokens_by_line:
+            # Last token is NEWLINE; look at last but one
+            if len(line) > 2 and line[-2].string == '?':
+                # Find the first token that's not INDENT/DEDENT
+                ix = 0
+                while line[ix].type in {tokenize.INDENT, tokenize.DEDENT}:
+                    ix += 1
+                return cls(line[ix].start, line[-2].start)
+
+    def transform(self, lines):
+        """Transform a help command found by the ``find()`` classmethod.
+        """
+
+        piece = "".join(lines[self.start_line : self.q_line + 1])
+        indent, content = piece[: self.start_col], piece[self.start_col :]
+        lines_before = lines[: self.start_line]
+        lines_after = lines[self.q_line + 1 :]
+
+        m = _help_end_re.search(content)
+        if not m:
+            raise SyntaxError(content)
+        assert m is not None, content
+        target = m.group(1)
+        esc = m.group(3)
+
+
+        call = _make_help_call(target, esc)
+        new_line = indent + call + '\n'
+
+        return lines_before + [new_line] + lines_after
+
+def make_tokens_by_line(lines:List[str]):
+    """Tokenize a series of lines and group tokens by line.
+
+    The tokens for a multiline Python string or expression are grouped as one
+    line. All lines except the last lines should keep their line ending ('\\n',
+    '\\r\\n') for this to properly work. Use `.splitlines(keeplineending=True)`
+    for example when passing block of text to this function.
+
+    """
+    # NL tokens are used inside multiline expressions, but also after blank
+    # lines or comments. This is intentional - see https://bugs.python.org/issue17061
+    # We want to group the former case together but split the latter, so we
+    # track parentheses level, similar to the internals of tokenize.
+
+    #   reexported from token on 3.7+
+    NEWLINE, NL = tokenize.NEWLINE, tokenize.NL  # type: ignore
+    tokens_by_line: List[List[Any]] = [[]]
+    if len(lines) > 1 and not lines[0].endswith(("\n", "\r", "\r\n", "\x0b", "\x0c")):
+        warnings.warn(
+            "`make_tokens_by_line` received a list of lines which do not have lineending markers ('\\n', '\\r', '\\r\\n', '\\x0b', '\\x0c'), behavior will be unspecified",
+            stacklevel=2,
+        )
+    parenlev = 0
+    try:
+        for token in tokenutil.generate_tokens_catch_errors(
+            iter(lines).__next__, extra_errors_to_catch=["expected EOF"]
+        ):
+            tokens_by_line[-1].append(token)
+            if (token.type == NEWLINE) \
+                    or ((token.type == NL) and (parenlev <= 0)):
+                tokens_by_line.append([])
+            elif token.string in {'(', '[', '{'}:
+                parenlev += 1
+            elif token.string in {')', ']', '}'}:
+                if parenlev > 0:
+                    parenlev -= 1
+    except tokenize.TokenError:
+        # Input ended in a multiline string or expression. That's OK for us.
+        pass
+
+
+    if not tokens_by_line[-1]:
+        tokens_by_line.pop()
+
+
+    return tokens_by_line
+
+
+def has_sunken_brackets(tokens: List[tokenize.TokenInfo]):
+    """Check if the depth of brackets in the list of tokens drops below 0"""
+    parenlev = 0
+    for token in tokens:
+        if token.string in {"(", "[", "{"}:
+            parenlev += 1
+        elif token.string in {")", "]", "}"}:
+            parenlev -= 1
+            if parenlev < 0:
+                return True
+    return False
+
+
+def show_linewise_tokens(s: str):
+    """For investigation and debugging"""
+    warnings.warn(
+        "show_linewise_tokens is deprecated since IPython 8.6",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if not s.endswith("\n"):
+        s += "\n"
+    lines = s.splitlines(keepends=True)
+    for line in make_tokens_by_line(lines):
+        print("Line -------")
+        for tokinfo in line:
+            print(" ", tokinfo)
+
+# Arbitrary limit to prevent getting stuck in infinite loops
+TRANSFORM_LOOP_LIMIT = 500
+
+class TransformerManager:
+    """Applies various transformations to a cell or code block.
+
+    The key methods for external use are ``transform_cell()``
+    and ``check_complete()``.
+    """
+    def __init__(self):
+        self.cleanup_transforms = [
+            leading_empty_lines,
+            leading_indent,
+            classic_prompt,
+            ipython_prompt,
+        ]
+        self.line_transforms = [
+            cell_magic,
+        ]
+        self.token_transformers = [
+            MagicAssign,
+            SystemAssign,
+            EscapedCommand,
+            HelpEnd,
+        ]
+
+    def do_one_token_transform(self, lines):
+        """Find and run the transform earliest in the code.
+
+        Returns (changed, lines).
+
+        This method is called repeatedly until changed is False, indicating
+        that all available transformations are complete.
+
+        The tokens following IPython special syntax might not be valid, so
+        the transformed code is retokenised every time to identify the next
+        piece of special syntax. Hopefully long code cells are mostly valid
+        Python, not using lots of IPython special syntax, so this shouldn't be
+        a performance issue.
+        """
+        tokens_by_line = make_tokens_by_line(lines)
+        candidates = []
+        for transformer_cls in self.token_transformers:
+            transformer = transformer_cls.find(tokens_by_line)
+            if transformer:
+                candidates.append(transformer)
+
+        if not candidates:
+            # Nothing to transform
+            return False, lines
+        ordered_transformers = sorted(candidates, key=TokenTransformBase.sortby)
+        for transformer in ordered_transformers:
+            try:
+                return True, transformer.transform(lines)
+            except SyntaxError:
+                pass
+        return False, lines
+
+    def do_token_transforms(self, lines):
+        for _ in range(TRANSFORM_LOOP_LIMIT):
+            changed, lines = self.do_one_token_transform(lines)
+            if not changed:
+                return lines
+
+        raise RuntimeError("Input transformation still changing after "
+                           "%d iterations. Aborting." % TRANSFORM_LOOP_LIMIT)
+
+    def transform_cell(self, cell: str) -> str:
+        """Transforms a cell of input code"""
+        if not cell.endswith('\n'):
+            cell += '\n'  # Ensure the cell has a trailing newline
+        lines = cell.splitlines(keepends=True)
+        for transform in self.cleanup_transforms + self.line_transforms:
+            lines = transform(lines)
+
+        lines = self.do_token_transforms(lines)
+        return ''.join(lines)
+
+    def check_complete(self, cell: str):
+        """Return whether a block of code is ready to execute, or should be continued
+
+        Parameters
+        ----------
+        cell : string
+            Python input code, which can be multiline.
+
+        Returns
+        -------
+        status : str
+            One of 'complete', 'incomplete', or 'invalid' if source is not a
+            prefix of valid code.
+        indent_spaces : int or None
+            The number of spaces by which to indent the next line of code. If
+            status is not 'incomplete', this is None.
+        """
+        # Remember if the lines ends in a new line.
+        ends_with_newline = False
+        for character in reversed(cell):
+            if character == '\n':
+                ends_with_newline = True
+                break
+            elif character.strip():
+                break
+            else:
+                continue
+
+        if not ends_with_newline:
+            # Append an newline for consistent tokenization
+            # See https://bugs.python.org/issue33899
+            cell += '\n'
+
+        lines = cell.splitlines(keepends=True)
+
+        if not lines:
+            return 'complete', None
+
+        for line in reversed(lines):
+            if not line.strip():
+                continue
+            elif line.strip("\n").endswith("\\"):
+                return "incomplete", find_last_indent(lines)
+            else:
+                break
+
+        try:
+            for transform in self.cleanup_transforms:
+                if not getattr(transform, 'has_side_effects', False):
+                    lines = transform(lines)
+        except SyntaxError:
+            return 'invalid', None
+
+        if lines[0].startswith('%%'):
+            # Special case for cell magics - completion marked by blank line
+            if lines[-1].strip():
+                return 'incomplete', find_last_indent(lines)
+            else:
+                return 'complete', None
+
+        try:
+            for transform in self.line_transforms:
+                if not getattr(transform, 'has_side_effects', False):
+                    lines = transform(lines)
+            lines = self.do_token_transforms(lines)
+        except SyntaxError:
+            return 'invalid', None
+
+        tokens_by_line = make_tokens_by_line(lines)
+
+        # Bail if we got one line and there are more closing parentheses than
+        # the opening ones
+        if (
+            len(lines) == 1
+            and tokens_by_line
+            and has_sunken_brackets(tokens_by_line[0])
+        ):
+            return "invalid", None
+
+        if not tokens_by_line:
+            return 'incomplete', find_last_indent(lines)
+
+        if (
+            tokens_by_line[-1][-1].type != tokenize.ENDMARKER
+            and tokens_by_line[-1][-1].type != tokenize.ERRORTOKEN
+        ):
+            # We're in a multiline string or expression
+            return 'incomplete', find_last_indent(lines)
+
+        newline_types = {tokenize.NEWLINE, tokenize.COMMENT, tokenize.ENDMARKER} # type: ignore
+
+        # Pop the last line which only contains DEDENTs and ENDMARKER
+        last_token_line = None
+        if {t.type for t in tokens_by_line[-1]} in [
+            {tokenize.DEDENT, tokenize.ENDMARKER},
+            {tokenize.ENDMARKER}
+        ] and len(tokens_by_line) > 1:
+            last_token_line = tokens_by_line.pop()
+
+        while tokens_by_line[-1] and tokens_by_line[-1][-1].type in newline_types:
+            tokens_by_line[-1].pop()
+
+        if not tokens_by_line[-1]:
+            return 'incomplete', find_last_indent(lines)
+
+        if tokens_by_line[-1][-1].string == ':':
+            # The last line starts a block (e.g. 'if foo:')
+            ix = 0
+            while tokens_by_line[-1][ix].type in {tokenize.INDENT, tokenize.DEDENT}:
+                ix += 1
+
+            indent = tokens_by_line[-1][ix].start[1]
+            return 'incomplete', indent + 4
+
+        if tokens_by_line[-1][0].line.endswith('\\'):
+            return 'incomplete', None
+
+        # At this point, our checks think the code is complete (or invalid).
+        # We'll use codeop.compile_command to check this with the real parser
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter('error', SyntaxWarning)
+                res = compile_command(''.join(lines), symbol='exec')
+        except (SyntaxError, OverflowError, ValueError, TypeError,
+                MemoryError, SyntaxWarning):
+            return 'invalid', None
+        else:
+            if res is None:
+                return 'incomplete', find_last_indent(lines)
+
+        if last_token_line and last_token_line[0].type == tokenize.DEDENT:
+            if ends_with_newline:
+                return 'complete', None
+            return 'incomplete', find_last_indent(lines)
+
+        # If there's a blank line at the end, assume we're ready to execute
+        if not lines[-1].strip():
+            return 'complete', None
+
+        return 'complete', None
+
+
+def find_last_indent(lines):
+    m = _indent_re.match(lines[-1])
+    if not m:
+        return 0
+    return len(m.group(0).replace('\t', ' '*4))
+
+
+class MaybeAsyncCompile(Compile):
+    def __init__(self, extra_flags=0):
+        super().__init__()
+        self.flags |= extra_flags
+
+
+class MaybeAsyncCommandCompiler(CommandCompiler):
+    def __init__(self, extra_flags=0):
+        self.compiler = MaybeAsyncCompile(extra_flags=extra_flags)
+
+
+_extra_flags = ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
+
+compile_command = MaybeAsyncCommandCompiler(extra_flags=_extra_flags)

openalex_env_map/lib/python3.10/site-packages/IPython/core/latex_symbols.py

@@ -0,0 +1,1301 @@
+# encoding: utf-8
+
+# DO NOT EDIT THIS FILE BY HAND.
+
+# To update this file, run the script /tools/gen_latex_symbols.py using Python 3
+
+# This file is autogenerated from the file:
+# https://raw.githubusercontent.com/JuliaLang/julia/master/base/latex_symbols.jl
+# This original list is filtered to remove any unicode characters that are not valid
+# Python identifiers.
+
+latex_symbols = {
+
+    "\\euler" : "ℯ",
+    "\\^a" : "ᵃ",
+    "\\^b" : "ᵇ",
+    "\\^c" : "ᶜ",
+    "\\^d" : "ᵈ",
+    "\\^e" : "ᵉ",
+    "\\^f" : "ᶠ",
+    "\\^g" : "ᵍ",
+    "\\^h" : "ʰ",
+    "\\^i" : "ⁱ",
+    "\\^j" : "ʲ",
+    "\\^k" : "ᵏ",
+    "\\^l" : "ˡ",
+    "\\^m" : "ᵐ",
+    "\\^n" : "ⁿ",
+    "\\^o" : "ᵒ",
+    "\\^p" : "ᵖ",
+    "\\^r" : "ʳ",
+    "\\^s" : "ˢ",
+    "\\^t" : "ᵗ",
+    "\\^u" : "ᵘ",
+    "\\^v" : "ᵛ",
+    "\\^w" : "ʷ",
+    "\\^x" : "ˣ",
+    "\\^y" : "ʸ",
+    "\\^z" : "ᶻ",
+    "\\^A" : "ᴬ",
+    "\\^B" : "ᴮ",
+    "\\^D" : "ᴰ",
+    "\\^E" : "ᴱ",
+    "\\^G" : "ᴳ",
+    "\\^H" : "ᴴ",
+    "\\^I" : "ᴵ",
+    "\\^J" : "ᴶ",
+    "\\^K" : "ᴷ",
+    "\\^L" : "ᴸ",
+    "\\^M" : "ᴹ",
+    "\\^N" : "ᴺ",
+    "\\^O" : "ᴼ",
+    "\\^P" : "ᴾ",
+    "\\^R" : "ᴿ",
+    "\\^T" : "ᵀ",
+    "\\^U" : "ᵁ",
+    "\\^V" : "ⱽ",
+    "\\^W" : "ᵂ",
+    "\\^alpha" : "ᵅ",
+    "\\^beta" : "ᵝ",
+    "\\^gamma" : "ᵞ",
+    "\\^delta" : "ᵟ",
+    "\\^epsilon" : "ᵋ",
+    "\\^theta" : "ᶿ",
+    "\\^iota" : "ᶥ",
+    "\\^phi" : "ᵠ",
+    "\\^chi" : "ᵡ",
+    "\\^Phi" : "ᶲ",
+    "\\_a" : "ₐ",
+    "\\_e" : "ₑ",
+    "\\_h" : "ₕ",
+    "\\_i" : "ᵢ",
+    "\\_j" : "ⱼ",
+    "\\_k" : "ₖ",
+    "\\_l" : "ₗ",
+    "\\_m" : "ₘ",
+    "\\_n" : "ₙ",
+    "\\_o" : "ₒ",
+    "\\_p" : "ₚ",
+    "\\_r" : "ᵣ",
+    "\\_s" : "ₛ",
+    "\\_t" : "ₜ",
+    "\\_u" : "ᵤ",
+    "\\_v" : "ᵥ",
+    "\\_x" : "ₓ",
+    "\\_schwa" : "ₔ",
+    "\\_beta" : "ᵦ",
+    "\\_gamma" : "ᵧ",
+    "\\_rho" : "ᵨ",
+    "\\_phi" : "ᵩ",
+    "\\_chi" : "ᵪ",
+    "\\hbar" : "ħ",
+    "\\sout" : "̶",
+    "\\ordfeminine" : "ª",
+    "\\cdotp" : "·",
+    "\\ordmasculine" : "º",
+    "\\AA" : "Å",
+    "\\AE" : "Æ",
+    "\\DH" : "Ð",
+    "\\O" : "Ø",
+    "\\TH" : "Þ",
+    "\\ss" : "ß",
+    "\\aa" : "å",
+    "\\ae" : "æ",
+    "\\eth" : "ð",
+    "\\dh" : "ð",
+    "\\o" : "ø",
+    "\\th" : "þ",
+    "\\DJ" : "Đ",
+    "\\dj" : "đ",
+    "\\imath" : "ı",
+    "\\jmath" : "ȷ",
+    "\\L" : "Ł",
+    "\\l" : "ł",
+    "\\NG" : "Ŋ",
+    "\\ng" : "ŋ",
+    "\\OE" : "Œ",
+    "\\oe" : "œ",
+    "\\hvlig" : "ƕ",
+    "\\nrleg" : "ƞ",
+    "\\doublepipe" : "ǂ",
+    "\\trna" : "ɐ",
+    "\\trnsa" : "ɒ",
+    "\\openo" : "ɔ",
+    "\\rtld" : "ɖ",
+    "\\schwa" : "ə",
+    "\\varepsilon" : "ε",
+    "\\pgamma" : "ɣ",
+    "\\pbgam" : "ɤ",
+    "\\trnh" : "ɥ",
+    "\\btdl" : "ɬ",
+    "\\rtll" : "ɭ",
+    "\\trnm" : "ɯ",
+    "\\trnmlr" : "ɰ",
+    "\\ltlmr" : "ɱ",
+    "\\ltln" : "ɲ",
+    "\\rtln" : "ɳ",
+    "\\clomeg" : "ɷ",
+    "\\ltphi" : "ɸ",
+    "\\trnr" : "ɹ",
+    "\\trnrl" : "ɺ",
+    "\\rttrnr" : "ɻ",
+    "\\rl" : "ɼ",
+    "\\rtlr" : "ɽ",
+    "\\fhr" : "ɾ",
+    "\\rtls" : "ʂ",
+    "\\esh" : "ʃ",
+    "\\trnt" : "ʇ",
+    "\\rtlt" : "ʈ",
+    "\\pupsil" : "ʊ",
+    "\\pscrv" : "ʋ",
+    "\\invv" : "ʌ",
+    "\\invw" : "ʍ",
+    "\\trny" : "ʎ",
+    "\\rtlz" : "ʐ",
+    "\\yogh" : "ʒ",
+    "\\glst" : "ʔ",
+    "\\reglst" : "ʕ",
+    "\\inglst" : "ʖ",
+    "\\turnk" : "ʞ",
+    "\\dyogh" : "ʤ",
+    "\\tesh" : "ʧ",
+    "\\rasp" : "ʼ",
+    "\\verts" : "ˈ",
+    "\\verti" : "ˌ",
+    "\\lmrk" : "ː",
+    "\\hlmrk" : "ˑ",
+    "\\grave" : "̀",
+    "\\acute" : "́",
+    "\\hat" : "̂",
+    "\\tilde" : "̃",
+    "\\bar" : "̄",
+    "\\breve" : "̆",
+    "\\dot" : "̇",
+    "\\ddot" : "̈",
+    "\\ocirc" : "̊",
+    "\\H" : "̋",
+    "\\check" : "̌",
+    "\\palh" : "̡",
+    "\\rh" : "̢",
+    "\\c" : "̧",
+    "\\k" : "̨",
+    "\\sbbrg" : "̪",
+    "\\strike" : "̶",
+    "\\Alpha" : "Α",
+    "\\Beta" : "Β",
+    "\\Gamma" : "Γ",
+    "\\Delta" : "Δ",
+    "\\Epsilon" : "Ε",
+    "\\Zeta" : "Ζ",
+    "\\Eta" : "Η",
+    "\\Theta" : "Θ",
+    "\\Iota" : "Ι",
+    "\\Kappa" : "Κ",
+    "\\Lambda" : "Λ",
+    "\\Xi" : "Ξ",
+    "\\Pi" : "Π",
+    "\\Rho" : "Ρ",
+    "\\Sigma" : "Σ",
+    "\\Tau" : "Τ",
+    "\\Upsilon" : "Υ",
+    "\\Phi" : "Φ",
+    "\\Chi" : "Χ",
+    "\\Psi" : "Ψ",
+    "\\Omega" : "Ω",
+    "\\alpha" : "α",
+    "\\beta" : "β",
+    "\\gamma" : "γ",
+    "\\delta" : "δ",
+    "\\zeta" : "ζ",
+    "\\eta" : "η",
+    "\\theta" : "θ",
+    "\\iota" : "ι",
+    "\\kappa" : "κ",
+    "\\lambda" : "λ",
+    "\\mu" : "μ",
+    "\\nu" : "ν",
+    "\\xi" : "ξ",
+    "\\pi" : "π",
+    "\\rho" : "ρ",
+    "\\varsigma" : "ς",
+    "\\sigma" : "σ",
+    "\\tau" : "τ",
+    "\\upsilon" : "υ",
+    "\\varphi" : "φ",
+    "\\chi" : "χ",
+    "\\psi" : "ψ",
+    "\\omega" : "ω",
+    "\\vartheta" : "ϑ",
+    "\\phi" : "ϕ",
+    "\\varpi" : "ϖ",
+    "\\Stigma" : "Ϛ",
+    "\\Digamma" : "Ϝ",
+    "\\digamma" : "ϝ",
+    "\\Koppa" : "Ϟ",
+    "\\Sampi" : "Ϡ",
+    "\\varkappa" : "ϰ",
+    "\\varrho" : "ϱ",
+    "\\varTheta" : "ϴ",
+    "\\epsilon" : "ϵ",
+    "\\dddot" : "⃛",
+    "\\ddddot" : "⃜",
+    "\\hslash" : "ℏ",
+    "\\Im" : "ℑ",
+    "\\ell" : "ℓ",
+    "\\wp" : "℘",
+    "\\Re" : "ℜ",
+    "\\aleph" : "ℵ",
+    "\\beth" : "ℶ",
+    "\\gimel" : "ℷ",
+    "\\daleth" : "ℸ",
+    "\\bbPi" : "ℿ",
+    "\\Zbar" : "Ƶ",
+    "\\overbar" : "̅",
+    "\\ovhook" : "̉",
+    "\\candra" : "̐",
+    "\\oturnedcomma" : "̒",
+    "\\ocommatopright" : "̕",
+    "\\droang" : "̚",
+    "\\wideutilde" : "̰",
+    "\\not" : "̸",
+    "\\upMu" : "Μ",
+    "\\upNu" : "Ν",
+    "\\upOmicron" : "Ο",
+    "\\upepsilon" : "ε",
+    "\\upomicron" : "ο",
+    "\\upvarbeta" : "ϐ",
+    "\\upoldKoppa" : "Ϙ",
+    "\\upoldkoppa" : "ϙ",
+    "\\upstigma" : "ϛ",
+    "\\upkoppa" : "ϟ",
+    "\\upsampi" : "ϡ",
+    "\\tieconcat" : "⁀",
+    "\\leftharpoonaccent" : "⃐",
+    "\\rightharpoonaccent" : "⃑",
+    "\\vertoverlay" : "⃒",
+    "\\overleftarrow" : "⃖",
+    "\\vec" : "⃗",
+    "\\overleftrightarrow" : "⃡",
+    "\\annuity" : "⃧",
+    "\\threeunderdot" : "⃨",
+    "\\widebridgeabove" : "⃩",
+    "\\bbC" : "ℂ",
+    "\\eulermascheroni" : "ℇ",
+    "\\scrg" : "ℊ",
+    "\\scrH" : "ℋ",
+    "\\frakH" : "ℌ",
+    "\\bbH" : "ℍ",
+    "\\planck" : "ℎ",
+    "\\scrI" : "ℐ",
+    "\\scrL" : "ℒ",
+    "\\bbN" : "ℕ",
+    "\\bbP" : "ℙ",
+    "\\bbQ" : "ℚ",
+    "\\scrR" : "ℛ",
+    "\\bbR" : "ℝ",
+    "\\bbZ" : "ℤ",
+    "\\frakZ" : "ℨ",
+    "\\Angstrom" : "Å",
+    "\\scrB" : "ℬ",
+    "\\frakC" : "ℭ",
+    "\\scre" : "ℯ",
+    "\\scrE" : "ℰ",
+    "\\scrF" : "ℱ",
+    "\\Finv" : "Ⅎ",
+    "\\scrM" : "ℳ",
+    "\\scro" : "ℴ",
+    "\\bbgamma" : "ℽ",
+    "\\bbGamma" : "ℾ",
+    "\\bbiD" : "ⅅ",
+    "\\bbid" : "ⅆ",
+    "\\bbie" : "ⅇ",
+    "\\bbii" : "ⅈ",
+    "\\bbij" : "ⅉ",
+    "\\bfA" : "𝐀",
+    "\\bfB" : "𝐁",
+    "\\bfC" : "𝐂",
+    "\\bfD" : "𝐃",
+    "\\bfE" : "𝐄",
+    "\\bfF" : "𝐅",
+    "\\bfG" : "𝐆",
+    "\\bfH" : "𝐇",
+    "\\bfI" : "𝐈",
+    "\\bfJ" : "𝐉",
+    "\\bfK" : "𝐊",
+    "\\bfL" : "𝐋",
+    "\\bfM" : "𝐌",
+    "\\bfN" : "𝐍",
+    "\\bfO" : "𝐎",
+    "\\bfP" : "𝐏",
+    "\\bfQ" : "𝐐",
+    "\\bfR" : "𝐑",
+    "\\bfS" : "𝐒",
+    "\\bfT" : "𝐓",
+    "\\bfU" : "𝐔",
+    "\\bfV" : "𝐕",
+    "\\bfW" : "𝐖",
+    "\\bfX" : "𝐗",
+    "\\bfY" : "𝐘",
+    "\\bfZ" : "𝐙",
+    "\\bfa" : "𝐚",
+    "\\bfb" : "𝐛",
+    "\\bfc" : "𝐜",
+    "\\bfd" : "𝐝",
+    "\\bfe" : "𝐞",
+    "\\bff" : "𝐟",
+    "\\bfg" : "𝐠",
+    "\\bfh" : "𝐡",
+    "\\bfi" : "𝐢",
+    "\\bfj" : "𝐣",
+    "\\bfk" : "𝐤",
+    "\\bfl" : "𝐥",
+    "\\bfm" : "𝐦",
+    "\\bfn" : "𝐧",
+    "\\bfo" : "𝐨",
+    "\\bfp" : "𝐩",
+    "\\bfq" : "𝐪",
+    "\\bfr" : "𝐫",
+    "\\bfs" : "𝐬",
+    "\\bft" : "𝐭",
+    "\\bfu" : "𝐮",
+    "\\bfv" : "𝐯",
+    "\\bfw" : "𝐰",
+    "\\bfx" : "𝐱",
+    "\\bfy" : "𝐲",
+    "\\bfz" : "𝐳",
+    "\\itA" : "𝐴",
+    "\\itB" : "𝐵",
+    "\\itC" : "𝐶",
+    "\\itD" : "𝐷",
+    "\\itE" : "𝐸",
+    "\\itF" : "𝐹",
+    "\\itG" : "𝐺",
+    "\\itH" : "𝐻",
+    "\\itI" : "𝐼",
+    "\\itJ" : "𝐽",
+    "\\itK" : "𝐾",
+    "\\itL" : "𝐿",
+    "\\itM" : "𝑀",
+    "\\itN" : "𝑁",
+    "\\itO" : "𝑂",
+    "\\itP" : "𝑃",
+    "\\itQ" : "𝑄",
+    "\\itR" : "𝑅",
+    "\\itS" : "𝑆",
+    "\\itT" : "𝑇",
+    "\\itU" : "𝑈",
+    "\\itV" : "𝑉",
+    "\\itW" : "𝑊",
+    "\\itX" : "𝑋",
+    "\\itY" : "𝑌",
+    "\\itZ" : "𝑍",
+    "\\ita" : "𝑎",
+    "\\itb" : "𝑏",
+    "\\itc" : "𝑐",
+    "\\itd" : "𝑑",
+    "\\ite" : "𝑒",
+    "\\itf" : "𝑓",
+    "\\itg" : "𝑔",
+    "\\iti" : "𝑖",
+    "\\itj" : "𝑗",
+    "\\itk" : "𝑘",
+    "\\itl" : "𝑙",
+    "\\itm" : "𝑚",
+    "\\itn" : "𝑛",
+    "\\ito" : "𝑜",
+    "\\itp" : "𝑝",
+    "\\itq" : "𝑞",
+    "\\itr" : "𝑟",
+    "\\its" : "𝑠",
+    "\\itt" : "𝑡",
+    "\\itu" : "𝑢",
+    "\\itv" : "𝑣",
+    "\\itw" : "𝑤",
+    "\\itx" : "𝑥",
+    "\\ity" : "𝑦",
+    "\\itz" : "𝑧",
+    "\\biA" : "𝑨",
+    "\\biB" : "𝑩",
+    "\\biC" : "𝑪",
+    "\\biD" : "𝑫",
+    "\\biE" : "𝑬",
+    "\\biF" : "𝑭",
+    "\\biG" : "𝑮",
+    "\\biH" : "𝑯",
+    "\\biI" : "𝑰",
+    "\\biJ" : "𝑱",
+    "\\biK" : "𝑲",
+    "\\biL" : "𝑳",
+    "\\biM" : "𝑴",
+    "\\biN" : "𝑵",
+    "\\biO" : "𝑶",
+    "\\biP" : "𝑷",
+    "\\biQ" : "𝑸",
+    "\\biR" : "𝑹",
+    "\\biS" : "𝑺",
+    "\\biT" : "𝑻",
+    "\\biU" : "𝑼",
+    "\\biV" : "𝑽",
+    "\\biW" : "𝑾",
+    "\\biX" : "𝑿",
+    "\\biY" : "𝒀",
+    "\\biZ" : "𝒁",
+    "\\bia" : "𝒂",
+    "\\bib" : "𝒃",
+    "\\bic" : "𝒄",
+    "\\bid" : "𝒅",
+    "\\bie" : "𝒆",
+    "\\bif" : "𝒇",
+    "\\big" : "𝒈",
+    "\\bih" : "𝒉",
+    "\\bii" : "𝒊",
+    "\\bij" : "𝒋",
+    "\\bik" : "𝒌",
+    "\\bil" : "𝒍",
+    "\\bim" : "𝒎",
+    "\\bin" : "𝒏",
+    "\\bio" : "𝒐",
+    "\\bip" : "𝒑",
+    "\\biq" : "𝒒",
+    "\\bir" : "𝒓",
+    "\\bis" : "𝒔",
+    "\\bit" : "𝒕",
+    "\\biu" : "𝒖",
+    "\\biv" : "𝒗",
+    "\\biw" : "𝒘",
+    "\\bix" : "𝒙",
+    "\\biy" : "𝒚",
+    "\\biz" : "𝒛",
+    "\\scrA" : "𝒜",
+    "\\scrC" : "𝒞",
+    "\\scrD" : "𝒟",
+    "\\scrG" : "𝒢",
+    "\\scrJ" : "𝒥",
+    "\\scrK" : "𝒦",
+    "\\scrN" : "𝒩",
+    "\\scrO" : "𝒪",
+    "\\scrP" : "𝒫",
+    "\\scrQ" : "𝒬",
+    "\\scrS" : "𝒮",
+    "\\scrT" : "𝒯",
+    "\\scrU" : "𝒰",
+    "\\scrV" : "𝒱",
+    "\\scrW" : "𝒲",
+    "\\scrX" : "𝒳",
+    "\\scrY" : "𝒴",
+    "\\scrZ" : "𝒵",
+    "\\scra" : "𝒶",
+    "\\scrb" : "𝒷",
+    "\\scrc" : "𝒸",
+    "\\scrd" : "𝒹",
+    "\\scrf" : "𝒻",
+    "\\scrh" : "𝒽",
+    "\\scri" : "𝒾",
+    "\\scrj" : "𝒿",
+    "\\scrk" : "𝓀",
+    "\\scrm" : "𝓂",
+    "\\scrn" : "𝓃",
+    "\\scrp" : "𝓅",
+    "\\scrq" : "𝓆",
+    "\\scrr" : "𝓇",
+    "\\scrs" : "𝓈",
+    "\\scrt" : "𝓉",
+    "\\scru" : "𝓊",
+    "\\scrv" : "𝓋",
+    "\\scrw" : "𝓌",
+    "\\scrx" : "𝓍",
+    "\\scry" : "𝓎",
+    "\\scrz" : "𝓏",
+    "\\bscrA" : "𝓐",
+    "\\bscrB" : "𝓑",
+    "\\bscrC" : "𝓒",
+    "\\bscrD" : "𝓓",
+    "\\bscrE" : "𝓔",
+    "\\bscrF" : "𝓕",
+    "\\bscrG" : "𝓖",
+    "\\bscrH" : "𝓗",
+    "\\bscrI" : "𝓘",
+    "\\bscrJ" : "𝓙",
+    "\\bscrK" : "𝓚",
+    "\\bscrL" : "𝓛",
+    "\\bscrM" : "𝓜",
+    "\\bscrN" : "𝓝",
+    "\\bscrO" : "𝓞",
+    "\\bscrP" : "𝓟",
+    "\\bscrQ" : "𝓠",
+    "\\bscrR" : "𝓡",
+    "\\bscrS" : "𝓢",
+    "\\bscrT" : "𝓣",
+    "\\bscrU" : "𝓤",
+    "\\bscrV" : "𝓥",
+    "\\bscrW" : "𝓦",
+    "\\bscrX" : "𝓧",
+    "\\bscrY" : "𝓨",
+    "\\bscrZ" : "𝓩",
+    "\\bscra" : "𝓪",
+    "\\bscrb" : "𝓫",
+    "\\bscrc" : "𝓬",
+    "\\bscrd" : "𝓭",
+    "\\bscre" : "𝓮",
+    "\\bscrf" : "𝓯",
+    "\\bscrg" : "𝓰",
+    "\\bscrh" : "𝓱",
+    "\\bscri" : "𝓲",
+    "\\bscrj" : "𝓳",
+    "\\bscrk" : "𝓴",
+    "\\bscrl" : "𝓵",
+    "\\bscrm" : "𝓶",
+    "\\bscrn" : "𝓷",
+    "\\bscro" : "𝓸",
+    "\\bscrp" : "𝓹",
+    "\\bscrq" : "𝓺",
+    "\\bscrr" : "𝓻",
+    "\\bscrs" : "𝓼",
+    "\\bscrt" : "𝓽",
+    "\\bscru" : "𝓾",
+    "\\bscrv" : "𝓿",
+    "\\bscrw" : "𝔀",
+    "\\bscrx" : "𝔁",
+    "\\bscry" : "𝔂",
+    "\\bscrz" : "𝔃",
+    "\\frakA" : "𝔄",
+    "\\frakB" : "𝔅",
+    "\\frakD" : "𝔇",
+    "\\frakE" : "𝔈",
+    "\\frakF" : "𝔉",
+    "\\frakG" : "𝔊",
+    "\\frakJ" : "𝔍",
+    "\\frakK" : "𝔎",
+    "\\frakL" : "𝔏",
+    "\\frakM" : "𝔐",
+    "\\frakN" : "𝔑",
+    "\\frakO" : "𝔒",
+    "\\frakP" : "𝔓",
+    "\\frakQ" : "𝔔",
+    "\\frakS" : "𝔖",
+    "\\frakT" : "𝔗",
+    "\\frakU" : "𝔘",
+    "\\frakV" : "𝔙",
+    "\\frakW" : "𝔚",
+    "\\frakX" : "𝔛",
+    "\\frakY" : "𝔜",
+    "\\fraka" : "𝔞",
+    "\\frakb" : "𝔟",
+    "\\frakc" : "𝔠",
+    "\\frakd" : "𝔡",
+    "\\frake" : "𝔢",
+    "\\frakf" : "𝔣",
+    "\\frakg" : "𝔤",
+    "\\frakh" : "𝔥",
+    "\\fraki" : "𝔦",
+    "\\frakj" : "𝔧",
+    "\\frakk" : "𝔨",
+    "\\frakl" : "𝔩",
+    "\\frakm" : "𝔪",
+    "\\frakn" : "𝔫",
+    "\\frako" : "𝔬",
+    "\\frakp" : "𝔭",
+    "\\frakq" : "𝔮",
+    "\\frakr" : "𝔯",
+    "\\fraks" : "𝔰",
+    "\\frakt" : "𝔱",
+    "\\fraku" : "𝔲",
+    "\\frakv" : "𝔳",
+    "\\frakw" : "𝔴",
+    "\\frakx" : "𝔵",
+    "\\fraky" : "𝔶",
+    "\\frakz" : "𝔷",
+    "\\bbA" : "𝔸",
+    "\\bbB" : "𝔹",
+    "\\bbD" : "𝔻",
+    "\\bbE" : "𝔼",
+    "\\bbF" : "𝔽",
+    "\\bbG" : "𝔾",
+    "\\bbI" : "𝕀",
+    "\\bbJ" : "𝕁",
+    "\\bbK" : "𝕂",
+    "\\bbL" : "𝕃",
+    "\\bbM" : "𝕄",
+    "\\bbO" : "𝕆",
+    "\\bbS" : "𝕊",
+    "\\bbT" : "𝕋",
+    "\\bbU" : "𝕌",
+    "\\bbV" : "𝕍",
+    "\\bbW" : "𝕎",
+    "\\bbX" : "𝕏",
+    "\\bbY" : "𝕐",
+    "\\bba" : "𝕒",
+    "\\bbb" : "𝕓",
+    "\\bbc" : "𝕔",
+    "\\bbd" : "𝕕",
+    "\\bbe" : "𝕖",
+    "\\bbf" : "𝕗",
+    "\\bbg" : "𝕘",
+    "\\bbh" : "𝕙",
+    "\\bbi" : "𝕚",
+    "\\bbj" : "𝕛",
+    "\\bbk" : "𝕜",
+    "\\bbl" : "𝕝",
+    "\\bbm" : "𝕞",
+    "\\bbn" : "𝕟",
+    "\\bbo" : "𝕠",
+    "\\bbp" : "𝕡",
+    "\\bbq" : "𝕢",
+    "\\bbr" : "𝕣",
+    "\\bbs" : "𝕤",
+    "\\bbt" : "𝕥",
+    "\\bbu" : "𝕦",
+    "\\bbv" : "𝕧",
+    "\\bbw" : "𝕨",
+    "\\bbx" : "𝕩",
+    "\\bby" : "𝕪",
+    "\\bbz" : "𝕫",
+    "\\bfrakA" : "𝕬",
+    "\\bfrakB" : "𝕭",
+    "\\bfrakC" : "𝕮",
+    "\\bfrakD" : "𝕯",
+    "\\bfrakE" : "𝕰",
+    "\\bfrakF" : "𝕱",
+    "\\bfrakG" : "𝕲",
+    "\\bfrakH" : "𝕳",
+    "\\bfrakI" : "𝕴",
+    "\\bfrakJ" : "𝕵",
+    "\\bfrakK" : "𝕶",
+    "\\bfrakL" : "𝕷",
+    "\\bfrakM" : "𝕸",
+    "\\bfrakN" : "𝕹",
+    "\\bfrakO" : "𝕺",
+    "\\bfrakP" : "𝕻",
+    "\\bfrakQ" : "𝕼",
+    "\\bfrakR" : "𝕽",
+    "\\bfrakS" : "𝕾",
+    "\\bfrakT" : "𝕿",
+    "\\bfrakU" : "𝖀",
+    "\\bfrakV" : "𝖁",
+    "\\bfrakW" : "𝖂",
+    "\\bfrakX" : "𝖃",
+    "\\bfrakY" : "𝖄",
+    "\\bfrakZ" : "𝖅",
+    "\\bfraka" : "𝖆",
+    "\\bfrakb" : "𝖇",
+    "\\bfrakc" : "𝖈",
+    "\\bfrakd" : "𝖉",
+    "\\bfrake" : "𝖊",
+    "\\bfrakf" : "𝖋",
+    "\\bfrakg" : "𝖌",
+    "\\bfrakh" : "𝖍",
+    "\\bfraki" : "𝖎",
+    "\\bfrakj" : "𝖏",
+    "\\bfrakk" : "𝖐",
+    "\\bfrakl" : "𝖑",
+    "\\bfrakm" : "𝖒",
+    "\\bfrakn" : "𝖓",
+    "\\bfrako" : "𝖔",
+    "\\bfrakp" : "𝖕",
+    "\\bfrakq" : "𝖖",
+    "\\bfrakr" : "𝖗",
+    "\\bfraks" : "𝖘",
+    "\\bfrakt" : "𝖙",
+    "\\bfraku" : "𝖚",
+    "\\bfrakv" : "𝖛",
+    "\\bfrakw" : "𝖜",
+    "\\bfrakx" : "𝖝",
+    "\\bfraky" : "𝖞",
+    "\\bfrakz" : "𝖟",
+    "\\sansA" : "𝖠",
+    "\\sansB" : "𝖡",
+    "\\sansC" : "𝖢",
+    "\\sansD" : "𝖣",
+    "\\sansE" : "𝖤",
+    "\\sansF" : "𝖥",
+    "\\sansG" : "𝖦",
+    "\\sansH" : "𝖧",
+    "\\sansI" : "𝖨",
+    "\\sansJ" : "𝖩",
+    "\\sansK" : "𝖪",
+    "\\sansL" : "𝖫",
+    "\\sansM" : "𝖬",
+    "\\sansN" : "𝖭",
+    "\\sansO" : "𝖮",
+    "\\sansP" : "𝖯",
+    "\\sansQ" : "𝖰",
+    "\\sansR" : "𝖱",
+    "\\sansS" : "𝖲",
+    "\\sansT" : "𝖳",
+    "\\sansU" : "𝖴",
+    "\\sansV" : "𝖵",
+    "\\sansW" : "𝖶",
+    "\\sansX" : "𝖷",
+    "\\sansY" : "𝖸",
+    "\\sansZ" : "𝖹",
+    "\\sansa" : "𝖺",
+    "\\sansb" : "𝖻",
+    "\\sansc" : "𝖼",
+    "\\sansd" : "𝖽",
+    "\\sanse" : "𝖾",
+    "\\sansf" : "𝖿",
+    "\\sansg" : "𝗀",
+    "\\sansh" : "𝗁",
+    "\\sansi" : "𝗂",
+    "\\sansj" : "𝗃",
+    "\\sansk" : "𝗄",
+    "\\sansl" : "𝗅",
+    "\\sansm" : "𝗆",
+    "\\sansn" : "𝗇",
+    "\\sanso" : "𝗈",
+    "\\sansp" : "𝗉",
+    "\\sansq" : "𝗊",
+    "\\sansr" : "𝗋",
+    "\\sanss" : "𝗌",
+    "\\sanst" : "𝗍",
+    "\\sansu" : "𝗎",
+    "\\sansv" : "𝗏",
+    "\\sansw" : "𝗐",
+    "\\sansx" : "𝗑",
+    "\\sansy" : "𝗒",
+    "\\sansz" : "𝗓",
+    "\\bsansA" : "𝗔",
+    "\\bsansB" : "𝗕",
+    "\\bsansC" : "𝗖",
+    "\\bsansD" : "𝗗",
+    "\\bsansE" : "𝗘",
+    "\\bsansF" : "𝗙",
+    "\\bsansG" : "𝗚",
+    "\\bsansH" : "𝗛",
+    "\\bsansI" : "𝗜",
+    "\\bsansJ" : "𝗝",
+    "\\bsansK" : "𝗞",
+    "\\bsansL" : "𝗟",
+    "\\bsansM" : "𝗠",
+    "\\bsansN" : "𝗡",
+    "\\bsansO" : "𝗢",
+    "\\bsansP" : "𝗣",
+    "\\bsansQ" : "𝗤",
+    "\\bsansR" : "𝗥",
+    "\\bsansS" : "𝗦",
+    "\\bsansT" : "𝗧",
+    "\\bsansU" : "𝗨",
+    "\\bsansV" : "𝗩",
+    "\\bsansW" : "𝗪",
+    "\\bsansX" : "𝗫",
+    "\\bsansY" : "𝗬",
+    "\\bsansZ" : "𝗭",
+    "\\bsansa" : "𝗮",
+    "\\bsansb" : "𝗯",
+    "\\bsansc" : "𝗰",
+    "\\bsansd" : "𝗱",
+    "\\bsanse" : "𝗲",
+    "\\bsansf" : "𝗳",
+    "\\bsansg" : "𝗴",
+    "\\bsansh" : "𝗵",
+    "\\bsansi" : "𝗶",
+    "\\bsansj" : "𝗷",
+    "\\bsansk" : "𝗸",
+    "\\bsansl" : "𝗹",
+    "\\bsansm" : "𝗺",
+    "\\bsansn" : "𝗻",
+    "\\bsanso" : "𝗼",
+    "\\bsansp" : "𝗽",
+    "\\bsansq" : "𝗾",
+    "\\bsansr" : "𝗿",
+    "\\bsanss" : "𝘀",
+    "\\bsanst" : "𝘁",
+    "\\bsansu" : "𝘂",
+    "\\bsansv" : "𝘃",
+    "\\bsansw" : "𝘄",
+    "\\bsansx" : "𝘅",
+    "\\bsansy" : "𝘆",
+    "\\bsansz" : "𝘇",
+    "\\isansA" : "𝘈",
+    "\\isansB" : "𝘉",
+    "\\isansC" : "𝘊",
+    "\\isansD" : "𝘋",
+    "\\isansE" : "𝘌",
+    "\\isansF" : "𝘍",
+    "\\isansG" : "𝘎",
+    "\\isansH" : "𝘏",
+    "\\isansI" : "𝘐",
+    "\\isansJ" : "𝘑",
+    "\\isansK" : "𝘒",
+    "\\isansL" : "𝘓",
+    "\\isansM" : "𝘔",
+    "\\isansN" : "𝘕",
+    "\\isansO" : "𝘖",
+    "\\isansP" : "𝘗",
+    "\\isansQ" : "𝘘",
+    "\\isansR" : "𝘙",
+    "\\isansS" : "𝘚",
+    "\\isansT" : "𝘛",
+    "\\isansU" : "𝘜",
+    "\\isansV" : "𝘝",
+    "\\isansW" : "𝘞",
+    "\\isansX" : "𝘟",
+    "\\isansY" : "𝘠",
+    "\\isansZ" : "𝘡",
+    "\\isansa" : "𝘢",
+    "\\isansb" : "𝘣",
+    "\\isansc" : "𝘤",
+    "\\isansd" : "𝘥",
+    "\\isanse" : "𝘦",
+    "\\isansf" : "𝘧",
+    "\\isansg" : "𝘨",
+    "\\isansh" : "𝘩",
+    "\\isansi" : "𝘪",
+    "\\isansj" : "𝘫",
+    "\\isansk" : "𝘬",
+    "\\isansl" : "𝘭",
+    "\\isansm" : "𝘮",
+    "\\isansn" : "𝘯",
+    "\\isanso" : "𝘰",
+    "\\isansp" : "𝘱",
+    "\\isansq" : "𝘲",
+    "\\isansr" : "𝘳",
+    "\\isanss" : "𝘴",
+    "\\isanst" : "𝘵",
+    "\\isansu" : "𝘶",
+    "\\isansv" : "𝘷",
+    "\\isansw" : "𝘸",
+    "\\isansx" : "𝘹",
+    "\\isansy" : "𝘺",
+    "\\isansz" : "𝘻",
+    "\\bisansA" : "𝘼",
+    "\\bisansB" : "𝘽",
+    "\\bisansC" : "𝘾",
+    "\\bisansD" : "𝘿",
+    "\\bisansE" : "𝙀",
+    "\\bisansF" : "𝙁",
+    "\\bisansG" : "𝙂",
+    "\\bisansH" : "𝙃",
+    "\\bisansI" : "𝙄",
+    "\\bisansJ" : "𝙅",
+    "\\bisansK" : "𝙆",
+    "\\bisansL" : "𝙇",
+    "\\bisansM" : "𝙈",
+    "\\bisansN" : "𝙉",
+    "\\bisansO" : "𝙊",
+    "\\bisansP" : "𝙋",
+    "\\bisansQ" : "𝙌",
+    "\\bisansR" : "𝙍",
+    "\\bisansS" : "𝙎",
+    "\\bisansT" : "𝙏",
+    "\\bisansU" : "𝙐",
+    "\\bisansV" : "𝙑",
+    "\\bisansW" : "𝙒",
+    "\\bisansX" : "𝙓",
+    "\\bisansY" : "𝙔",
+    "\\bisansZ" : "𝙕",
+    "\\bisansa" : "𝙖",
+    "\\bisansb" : "𝙗",
+    "\\bisansc" : "𝙘",
+    "\\bisansd" : "𝙙",
+    "\\bisanse" : "𝙚",
+    "\\bisansf" : "𝙛",
+    "\\bisansg" : "𝙜",
+    "\\bisansh" : "𝙝",
+    "\\bisansi" : "𝙞",
+    "\\bisansj" : "𝙟",
+    "\\bisansk" : "𝙠",
+    "\\bisansl" : "𝙡",
+    "\\bisansm" : "𝙢",
+    "\\bisansn" : "𝙣",
+    "\\bisanso" : "𝙤",
+    "\\bisansp" : "𝙥",
+    "\\bisansq" : "𝙦",
+    "\\bisansr" : "𝙧",
+    "\\bisanss" : "𝙨",
+    "\\bisanst" : "𝙩",
+    "\\bisansu" : "𝙪",
+    "\\bisansv" : "𝙫",
+    "\\bisansw" : "𝙬",
+    "\\bisansx" : "𝙭",
+    "\\bisansy" : "𝙮",
+    "\\bisansz" : "𝙯",
+    "\\ttA" : "𝙰",
+    "\\ttB" : "𝙱",
+    "\\ttC" : "𝙲",
+    "\\ttD" : "𝙳",
+    "\\ttE" : "𝙴",
+    "\\ttF" : "𝙵",
+    "\\ttG" : "𝙶",
+    "\\ttH" : "𝙷",
+    "\\ttI" : "𝙸",
+    "\\ttJ" : "𝙹",
+    "\\ttK" : "𝙺",
+    "\\ttL" : "𝙻",
+    "\\ttM" : "𝙼",
+    "\\ttN" : "𝙽",
+    "\\ttO" : "𝙾",
+    "\\ttP" : "𝙿",
+    "\\ttQ" : "𝚀",
+    "\\ttR" : "𝚁",
+    "\\ttS" : "𝚂",
+    "\\ttT" : "𝚃",
+    "\\ttU" : "𝚄",
+    "\\ttV" : "𝚅",
+    "\\ttW" : "𝚆",
+    "\\ttX" : "𝚇",
+    "\\ttY" : "𝚈",
+    "\\ttZ" : "𝚉",
+    "\\tta" : "𝚊",
+    "\\ttb" : "𝚋",
+    "\\ttc" : "𝚌",
+    "\\ttd" : "𝚍",
+    "\\tte" : "𝚎",
+    "\\ttf" : "𝚏",
+    "\\ttg" : "𝚐",
+    "\\tth" : "𝚑",
+    "\\tti" : "𝚒",
+    "\\ttj" : "𝚓",
+    "\\ttk" : "𝚔",
+    "\\ttl" : "𝚕",
+    "\\ttm" : "𝚖",
+    "\\ttn" : "𝚗",
+    "\\tto" : "𝚘",
+    "\\ttp" : "𝚙",
+    "\\ttq" : "𝚚",
+    "\\ttr" : "𝚛",
+    "\\tts" : "𝚜",
+    "\\ttt" : "𝚝",
+    "\\ttu" : "𝚞",
+    "\\ttv" : "𝚟",
+    "\\ttw" : "𝚠",
+    "\\ttx" : "𝚡",
+    "\\tty" : "𝚢",
+    "\\ttz" : "𝚣",
+    "\\bfAlpha" : "𝚨",
+    "\\bfBeta" : "𝚩",
+    "\\bfGamma" : "𝚪",
+    "\\bfDelta" : "𝚫",
+    "\\bfEpsilon" : "𝚬",
+    "\\bfZeta" : "𝚭",
+    "\\bfEta" : "𝚮",
+    "\\bfTheta" : "𝚯",
+    "\\bfIota" : "𝚰",
+    "\\bfKappa" : "𝚱",
+    "\\bfLambda" : "𝚲",
+    "\\bfMu" : "𝚳",
+    "\\bfNu" : "𝚴",
+    "\\bfXi" : "𝚵",
+    "\\bfOmicron" : "𝚶",
+    "\\bfPi" : "𝚷",
+    "\\bfRho" : "𝚸",
+    "\\bfvarTheta" : "𝚹",
+    "\\bfSigma" : "𝚺",
+    "\\bfTau" : "𝚻",
+    "\\bfUpsilon" : "𝚼",
+    "\\bfPhi" : "𝚽",
+    "\\bfChi" : "𝚾",
+    "\\bfPsi" : "𝚿",
+    "\\bfOmega" : "𝛀",
+    "\\bfalpha" : "𝛂",
+    "\\bfbeta" : "𝛃",
+    "\\bfgamma" : "𝛄",
+    "\\bfdelta" : "𝛅",
+    "\\bfepsilon" : "𝛆",
+    "\\bfzeta" : "𝛇",
+    "\\bfeta" : "𝛈",
+    "\\bftheta" : "𝛉",
+    "\\bfiota" : "𝛊",
+    "\\bfkappa" : "𝛋",
+    "\\bflambda" : "𝛌",
+    "\\bfmu" : "𝛍",
+    "\\bfnu" : "𝛎",
+    "\\bfxi" : "𝛏",
+    "\\bfomicron" : "𝛐",
+    "\\bfpi" : "𝛑",
+    "\\bfrho" : "𝛒",
+    "\\bfvarsigma" : "𝛓",
+    "\\bfsigma" : "𝛔",
+    "\\bftau" : "𝛕",
+    "\\bfupsilon" : "𝛖",
+    "\\bfvarphi" : "𝛗",
+    "\\bfchi" : "𝛘",
+    "\\bfpsi" : "𝛙",
+    "\\bfomega" : "𝛚",
+    "\\bfvarepsilon" : "𝛜",
+    "\\bfvartheta" : "𝛝",
+    "\\bfvarkappa" : "𝛞",
+    "\\bfphi" : "𝛟",
+    "\\bfvarrho" : "𝛠",
+    "\\bfvarpi" : "𝛡",
+    "\\itAlpha" : "𝛢",
+    "\\itBeta" : "𝛣",
+    "\\itGamma" : "𝛤",
+    "\\itDelta" : "𝛥",
+    "\\itEpsilon" : "𝛦",
+    "\\itZeta" : "𝛧",
+    "\\itEta" : "𝛨",
+    "\\itTheta" : "𝛩",
+    "\\itIota" : "𝛪",
+    "\\itKappa" : "𝛫",
+    "\\itLambda" : "𝛬",
+    "\\itMu" : "𝛭",
+    "\\itNu" : "𝛮",
+    "\\itXi" : "𝛯",
+    "\\itOmicron" : "𝛰",
+    "\\itPi" : "𝛱",
+    "\\itRho" : "𝛲",
+    "\\itvarTheta" : "𝛳",
+    "\\itSigma" : "𝛴",
+    "\\itTau" : "𝛵",
+    "\\itUpsilon" : "𝛶",
+    "\\itPhi" : "𝛷",
+    "\\itChi" : "𝛸",
+    "\\itPsi" : "𝛹",
+    "\\itOmega" : "𝛺",
+    "\\italpha" : "𝛼",
+    "\\itbeta" : "𝛽",
+    "\\itgamma" : "𝛾",
+    "\\itdelta" : "𝛿",
+    "\\itepsilon" : "𝜀",
+    "\\itzeta" : "𝜁",
+    "\\iteta" : "𝜂",
+    "\\ittheta" : "𝜃",
+    "\\itiota" : "𝜄",
+    "\\itkappa" : "𝜅",
+    "\\itlambda" : "𝜆",
+    "\\itmu" : "𝜇",
+    "\\itnu" : "𝜈",
+    "\\itxi" : "𝜉",
+    "\\itomicron" : "𝜊",
+    "\\itpi" : "𝜋",
+    "\\itrho" : "𝜌",
+    "\\itvarsigma" : "𝜍",
+    "\\itsigma" : "𝜎",
+    "\\ittau" : "𝜏",
+    "\\itupsilon" : "𝜐",
+    "\\itphi" : "𝜑",
+    "\\itchi" : "𝜒",
+    "\\itpsi" : "𝜓",
+    "\\itomega" : "𝜔",
+    "\\itvarepsilon" : "𝜖",
+    "\\itvartheta" : "𝜗",
+    "\\itvarkappa" : "𝜘",
+    "\\itvarphi" : "𝜙",
+    "\\itvarrho" : "𝜚",
+    "\\itvarpi" : "𝜛",
+    "\\biAlpha" : "𝜜",
+    "\\biBeta" : "𝜝",
+    "\\biGamma" : "𝜞",
+    "\\biDelta" : "𝜟",
+    "\\biEpsilon" : "𝜠",
+    "\\biZeta" : "𝜡",
+    "\\biEta" : "𝜢",
+    "\\biTheta" : "𝜣",
+    "\\biIota" : "𝜤",
+    "\\biKappa" : "𝜥",
+    "\\biLambda" : "𝜦",
+    "\\biMu" : "𝜧",
+    "\\biNu" : "𝜨",
+    "\\biXi" : "𝜩",
+    "\\biOmicron" : "𝜪",
+    "\\biPi" : "𝜫",
+    "\\biRho" : "𝜬",
+    "\\bivarTheta" : "𝜭",
+    "\\biSigma" : "𝜮",
+    "\\biTau" : "𝜯",
+    "\\biUpsilon" : "𝜰",
+    "\\biPhi" : "𝜱",
+    "\\biChi" : "𝜲",
+    "\\biPsi" : "𝜳",
+    "\\biOmega" : "𝜴",
+    "\\bialpha" : "𝜶",
+    "\\bibeta" : "𝜷",
+    "\\bigamma" : "𝜸",
+    "\\bidelta" : "𝜹",
+    "\\biepsilon" : "𝜺",
+    "\\bizeta" : "𝜻",
+    "\\bieta" : "𝜼",
+    "\\bitheta" : "𝜽",
+    "\\biiota" : "𝜾",
+    "\\bikappa" : "𝜿",
+    "\\bilambda" : "𝝀",
+    "\\bimu" : "𝝁",
+    "\\binu" : "𝝂",
+    "\\bixi" : "𝝃",
+    "\\biomicron" : "𝝄",
+    "\\bipi" : "𝝅",
+    "\\birho" : "𝝆",
+    "\\bivarsigma" : "𝝇",
+    "\\bisigma" : "𝝈",
+    "\\bitau" : "𝝉",
+    "\\biupsilon" : "𝝊",
+    "\\biphi" : "𝝋",
+    "\\bichi" : "𝝌",
+    "\\bipsi" : "𝝍",
+    "\\biomega" : "𝝎",
+    "\\bivarepsilon" : "𝝐",
+    "\\bivartheta" : "𝝑",
+    "\\bivarkappa" : "𝝒",
+    "\\bivarphi" : "𝝓",
+    "\\bivarrho" : "𝝔",
+    "\\bivarpi" : "𝝕",
+    "\\bsansAlpha" : "𝝖",
+    "\\bsansBeta" : "𝝗",
+    "\\bsansGamma" : "𝝘",
+    "\\bsansDelta" : "𝝙",
+    "\\bsansEpsilon" : "𝝚",
+    "\\bsansZeta" : "𝝛",
+    "\\bsansEta" : "𝝜",
+    "\\bsansTheta" : "𝝝",
+    "\\bsansIota" : "𝝞",
+    "\\bsansKappa" : "𝝟",
+    "\\bsansLambda" : "𝝠",
+    "\\bsansMu" : "𝝡",
+    "\\bsansNu" : "𝝢",
+    "\\bsansXi" : "𝝣",
+    "\\bsansOmicron" : "𝝤",
+    "\\bsansPi" : "𝝥",
+    "\\bsansRho" : "𝝦",
+    "\\bsansvarTheta" : "𝝧",
+    "\\bsansSigma" : "𝝨",
+    "\\bsansTau" : "𝝩",
+    "\\bsansUpsilon" : "𝝪",
+    "\\bsansPhi" : "𝝫",
+    "\\bsansChi" : "𝝬",
+    "\\bsansPsi" : "𝝭",
+    "\\bsansOmega" : "𝝮",
+    "\\bsansalpha" : "𝝰",
+    "\\bsansbeta" : "𝝱",
+    "\\bsansgamma" : "𝝲",
+    "\\bsansdelta" : "𝝳",
+    "\\bsansepsilon" : "𝝴",
+    "\\bsanszeta" : "𝝵",
+    "\\bsanseta" : "𝝶",
+    "\\bsanstheta" : "𝝷",
+    "\\bsansiota" : "𝝸",
+    "\\bsanskappa" : "𝝹",
+    "\\bsanslambda" : "𝝺",
+    "\\bsansmu" : "𝝻",
+    "\\bsansnu" : "𝝼",
+    "\\bsansxi" : "𝝽",
+    "\\bsansomicron" : "𝝾",
+    "\\bsanspi" : "𝝿",
+    "\\bsansrho" : "𝞀",
+    "\\bsansvarsigma" : "𝞁",
+    "\\bsanssigma" : "𝞂",
+    "\\bsanstau" : "𝞃",
+    "\\bsansupsilon" : "𝞄",
+    "\\bsansphi" : "𝞅",
+    "\\bsanschi" : "𝞆",
+    "\\bsanspsi" : "𝞇",
+    "\\bsansomega" : "𝞈",
+    "\\bsansvarepsilon" : "𝞊",
+    "\\bsansvartheta" : "𝞋",
+    "\\bsansvarkappa" : "𝞌",
+    "\\bsansvarphi" : "𝞍",
+    "\\bsansvarrho" : "𝞎",
+    "\\bsansvarpi" : "𝞏",
+    "\\bisansAlpha" : "𝞐",
+    "\\bisansBeta" : "𝞑",
+    "\\bisansGamma" : "𝞒",
+    "\\bisansDelta" : "𝞓",
+    "\\bisansEpsilon" : "𝞔",
+    "\\bisansZeta" : "𝞕",
+    "\\bisansEta" : "𝞖",
+    "\\bisansTheta" : "𝞗",
+    "\\bisansIota" : "𝞘",
+    "\\bisansKappa" : "𝞙",
+    "\\bisansLambda" : "𝞚",
+    "\\bisansMu" : "𝞛",
+    "\\bisansNu" : "𝞜",
+    "\\bisansXi" : "𝞝",
+    "\\bisansOmicron" : "𝞞",
+    "\\bisansPi" : "𝞟",
+    "\\bisansRho" : "𝞠",
+    "\\bisansvarTheta" : "𝞡",
+    "\\bisansSigma" : "𝞢",
+    "\\bisansTau" : "𝞣",
+    "\\bisansUpsilon" : "𝞤",
+    "\\bisansPhi" : "𝞥",
+    "\\bisansChi" : "𝞦",
+    "\\bisansPsi" : "𝞧",
+    "\\bisansOmega" : "𝞨",
+    "\\bisansalpha" : "𝞪",
+    "\\bisansbeta" : "𝞫",
+    "\\bisansgamma" : "𝞬",
+    "\\bisansdelta" : "𝞭",
+    "\\bisansepsilon" : "𝞮",
+    "\\bisanszeta" : "𝞯",
+    "\\bisanseta" : "𝞰",
+    "\\bisanstheta" : "𝞱",
+    "\\bisansiota" : "𝞲",
+    "\\bisanskappa" : "𝞳",
+    "\\bisanslambda" : "𝞴",
+    "\\bisansmu" : "𝞵",
+    "\\bisansnu" : "𝞶",
+    "\\bisansxi" : "𝞷",
+    "\\bisansomicron" : "𝞸",
+    "\\bisanspi" : "𝞹",
+    "\\bisansrho" : "𝞺",
+    "\\bisansvarsigma" : "𝞻",
+    "\\bisanssigma" : "𝞼",
+    "\\bisanstau" : "𝞽",
+    "\\bisansupsilon" : "𝞾",
+    "\\bisansphi" : "𝞿",
+    "\\bisanschi" : "𝟀",
+    "\\bisanspsi" : "𝟁",
+    "\\bisansomega" : "𝟂",
+    "\\bisansvarepsilon" : "𝟄",
+    "\\bisansvartheta" : "𝟅",
+    "\\bisansvarkappa" : "𝟆",
+    "\\bisansvarphi" : "𝟇",
+    "\\bisansvarrho" : "𝟈",
+    "\\bisansvarpi" : "𝟉",
+    "\\bfzero" : "𝟎",
+    "\\bfone" : "𝟏",
+    "\\bftwo" : "𝟐",
+    "\\bfthree" : "𝟑",
+    "\\bffour" : "𝟒",
+    "\\bffive" : "𝟓",
+    "\\bfsix" : "𝟔",
+    "\\bfseven" : "𝟕",
+    "\\bfeight" : "𝟖",
+    "\\bfnine" : "𝟗",
+    "\\bbzero" : "𝟘",
+    "\\bbone" : "𝟙",
+    "\\bbtwo" : "𝟚",
+    "\\bbthree" : "𝟛",
+    "\\bbfour" : "𝟜",
+    "\\bbfive" : "𝟝",
+    "\\bbsix" : "𝟞",
+    "\\bbseven" : "𝟟",
+    "\\bbeight" : "𝟠",
+    "\\bbnine" : "𝟡",
+    "\\sanszero" : "𝟢",
+    "\\sansone" : "𝟣",
+    "\\sanstwo" : "𝟤",
+    "\\sansthree" : "𝟥",
+    "\\sansfour" : "𝟦",
+    "\\sansfive" : "𝟧",
+    "\\sanssix" : "𝟨",
+    "\\sansseven" : "𝟩",
+    "\\sanseight" : "𝟪",
+    "\\sansnine" : "𝟫",
+    "\\bsanszero" : "𝟬",
+    "\\bsansone" : "𝟭",
+    "\\bsanstwo" : "𝟮",
+    "\\bsansthree" : "𝟯",
+    "\\bsansfour" : "𝟰",
+    "\\bsansfive" : "𝟱",
+    "\\bsanssix" : "𝟲",
+    "\\bsansseven" : "𝟳",
+    "\\bsanseight" : "𝟴",
+    "\\bsansnine" : "𝟵",
+    "\\ttzero" : "𝟶",
+    "\\ttone" : "𝟷",
+    "\\tttwo" : "𝟸",
+    "\\ttthree" : "𝟹",
+    "\\ttfour" : "𝟺",
+    "\\ttfive" : "𝟻",
+    "\\ttsix" : "𝟼",
+    "\\ttseven" : "𝟽",
+    "\\tteight" : "𝟾",
+    "\\ttnine" : "𝟿",
+    "\\underbar" : "̲",
+    "\\underleftrightarrow" : "͍",
+}
+
+
+reverse_latex_symbol = { v:k for k,v in latex_symbols.items()}

openalex_env_map/lib/python3.10/site-packages/IPython/core/logger.py

@@ -0,0 +1,231 @@
+"""Logger class for IPython's logging facilities.
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2001 Janko Hauser <[email protected]> and
+#       Copyright (C) 2001-2006 Fernando Perez <[email protected]>
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#*****************************************************************************
+
+#****************************************************************************
+# Modules and globals
+
+# Python standard modules
+import glob
+import io
+import logging
+import os
+import time
+
+
+# prevent jedi/parso's debug messages pipe into interactiveshell
+logging.getLogger("parso").setLevel(logging.WARNING)
+
+#****************************************************************************
+# FIXME: This class isn't a mixin anymore, but it still needs attributes from
+# ipython and does input cache management.  Finish cleanup later...
+
+class Logger(object):
+    """A Logfile class with different policies for file creation"""
+
+    def __init__(self, home_dir, logfname='Logger.log', loghead=u'',
+                 logmode='over'):
+
+        # this is the full ipython instance, we need some attributes from it
+        # which won't exist until later. What a mess, clean up later...
+        self.home_dir = home_dir
+
+        self.logfname = logfname
+        self.loghead = loghead
+        self.logmode = logmode
+        self.logfile = None
+
+        # Whether to log raw or processed input
+        self.log_raw_input = False
+
+        # whether to also log output
+        self.log_output = False
+
+        # whether to put timestamps before each log entry
+        self.timestamp = False
+
+        # activity control flags
+        self.log_active = False
+
+    # logmode is a validated property
+    def _set_mode(self,mode):
+        if mode not in ['append','backup','global','over','rotate']:
+            raise ValueError('invalid log mode %s given' % mode)
+        self._logmode = mode
+
+    def _get_mode(self):
+        return self._logmode
+
+    logmode = property(_get_mode,_set_mode)
+
+    def logstart(self, logfname=None, loghead=None, logmode=None,
+                 log_output=False, timestamp=False, log_raw_input=False):
+        """Generate a new log-file with a default header.
+
+        Raises RuntimeError if the log has already been started"""
+
+        if self.logfile is not None:
+            raise RuntimeError('Log file is already active: %s' %
+                               self.logfname)
+
+        # The parameters can override constructor defaults
+        if logfname is not None: self.logfname = logfname
+        if loghead is not None: self.loghead = loghead
+        if logmode is not None: self.logmode = logmode
+
+        # Parameters not part of the constructor
+        self.timestamp = timestamp
+        self.log_output = log_output
+        self.log_raw_input = log_raw_input
+
+        # init depending on the log mode requested
+        isfile = os.path.isfile
+        logmode = self.logmode
+
+        if logmode == 'append':
+            self.logfile = io.open(self.logfname, 'a', encoding='utf-8')
+
+        elif logmode == 'backup':
+            if isfile(self.logfname):
+                backup_logname = self.logfname+'~'
+                # Manually remove any old backup, since os.rename may fail
+                # under Windows.
+                if isfile(backup_logname):
+                    os.remove(backup_logname)
+                os.rename(self.logfname,backup_logname)
+            self.logfile = io.open(self.logfname, 'w', encoding='utf-8')
+
+        elif logmode == 'global':
+            self.logfname = os.path.join(self.home_dir,self.logfname)
+            self.logfile = io.open(self.logfname, 'a', encoding='utf-8')
+
+        elif logmode == 'over':
+            if isfile(self.logfname):
+                os.remove(self.logfname)
+            self.logfile = io.open(self.logfname,'w', encoding='utf-8')
+
+        elif logmode == 'rotate':
+            if isfile(self.logfname):
+                if isfile(self.logfname+'.001~'):
+                    old = glob.glob(self.logfname+'.*~')
+                    old.sort()
+                    old.reverse()
+                    for f in old:
+                        root, ext = os.path.splitext(f)
+                        num = int(ext[1:-1])+1
+                        os.rename(f, root+'.'+repr(num).zfill(3)+'~')
+                os.rename(self.logfname, self.logfname+'.001~')
+            self.logfile = io.open(self.logfname, 'w', encoding='utf-8')
+
+        if logmode != 'append':
+            self.logfile.write(self.loghead)
+
+        self.logfile.flush()
+        self.log_active = True
+
+    def switch_log(self,val):
+        """Switch logging on/off. val should be ONLY a boolean."""
+
+        if val not in [False,True,0,1]:
+            raise ValueError('Call switch_log ONLY with a boolean argument, '
+                             'not with: %s' % val)
+
+        label = {0:'OFF',1:'ON',False:'OFF',True:'ON'}
+
+        if self.logfile is None:
+            print("""
+Logging hasn't been started yet (use logstart for that).
+
+%logon/%logoff are for temporarily starting and stopping logging for a logfile
+which already exists. But you must first start the logging process with
+%logstart (optionally giving a logfile name).""")
+
+        else:
+            if self.log_active == val:
+                print('Logging is already',label[val])
+            else:
+                print('Switching logging',label[val])
+                self.log_active = not self.log_active
+                self.log_active_out = self.log_active
+
+    def logstate(self):
+        """Print a status message about the logger."""
+        if self.logfile is None:
+            print('Logging has not been activated.')
+        else:
+            state = self.log_active and 'active' or 'temporarily suspended'
+            print('Filename       :', self.logfname)
+            print('Mode           :', self.logmode)
+            print('Output logging :', self.log_output)
+            print('Raw input log  :', self.log_raw_input)
+            print('Timestamping   :', self.timestamp)
+            print('State          :', state)
+
+    def log(self, line_mod, line_ori):
+        """Write the sources to a log.
+
+        Inputs:
+
+        - line_mod: possibly modified input, such as the transformations made
+          by input prefilters or input handlers of various kinds. This should
+          always be valid Python.
+
+        - line_ori: unmodified input line from the user. This is not
+          necessarily valid Python.
+        """
+
+        # Write the log line, but decide which one according to the
+        # log_raw_input flag, set when the log is started.
+        if self.log_raw_input:
+            self.log_write(line_ori)
+        else:
+            self.log_write(line_mod)
+
+    def log_write(self, data, kind='input'):
+        """Write data to the log file, if active"""
+
+        # print('data: %r' % data)  # dbg
+        if self.log_active and data:
+            write = self.logfile.write
+            if kind=='input':
+                if self.timestamp:
+                    write(time.strftime('# %a, %d %b %Y %H:%M:%S\n', time.localtime()))
+                write(data)
+            elif kind=='output' and self.log_output:
+                odata = u'\n'.join([u'#[Out]# %s' % s
+                                   for s in data.splitlines()])
+                write(u'%s\n' % odata)
+            try:
+                self.logfile.flush()
+            except OSError:
+                print("Failed to flush the log file.")
+                print(
+                    f"Please check that {self.logfname} exists and have the right permissions."
+                )
+                print(
+                    "Also consider turning off the log with `%logstop` to avoid this warning."
+                )
+
+    def logstop(self):
+        """Fully stop logging and close log file.
+
+        In order to start logging again, a new logstart() call needs to be
+        made, possibly (though not necessarily) with a new filename, mode and
+        other options."""
+
+        if self.logfile is not None:
+            self.logfile.close()
+            self.logfile = None
+        else:
+            print("Logging hadn't been started.")
+        self.log_active = False
+
+    # For backwards compatibility, in case anyone was using this.
+    close_log = logstop

openalex_env_map/lib/python3.10/site-packages/IPython/core/macro.py

@@ -0,0 +1,53 @@
+"""Support for interactive macros in IPython"""
+
+#*****************************************************************************
+#       Copyright (C) 2001-2005 Fernando Perez <[email protected]>
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#*****************************************************************************
+
+import re
+
+from IPython.utils.encoding import DEFAULT_ENCODING
+
+coding_declaration = re.compile(r"#\s*coding[:=]\s*([-\w.]+)")
+
+class Macro(object):
+    """Simple class to store the value of macros as strings.
+
+    Macro is just a callable that executes a string of IPython
+    input when called.
+    """
+
+    def __init__(self,code):
+        """store the macro value, as a single string which can be executed"""
+        lines = []
+        enc = None
+        for line in code.splitlines():
+            coding_match = coding_declaration.match(line)
+            if coding_match:
+                enc = coding_match.group(1)
+            else:
+                lines.append(line)
+        code = "\n".join(lines)
+        if isinstance(code, bytes):
+            code = code.decode(enc or DEFAULT_ENCODING)
+        self.value = code + '\n'
+    
+    def __str__(self):
+        return self.value
+
+    def __repr__(self):
+        return 'IPython.macro.Macro(%s)' % repr(self.value)
+    
+    def __getstate__(self):
+        """ needed for safe pickling via %store """
+        return {'value': self.value}
+    
+    def __add__(self, other):
+        if isinstance(other, Macro):
+            return Macro(self.value + other.value)
+        elif isinstance(other, str):
+            return Macro(self.value + other)
+        raise TypeError

openalex_env_map/lib/python3.10/site-packages/IPython/core/magic.py

@@ -0,0 +1,759 @@
+# encoding: utf-8
+"""Magic functions for InteractiveShell.
+"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2001 Janko Hauser <[email protected]> and
+#  Copyright (C) 2001 Fernando Perez <[email protected]>
+#  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
+
+#-----------------------------------------------------------------------------
+# 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):
+        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):
+        """
+        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 = None
+    # Dict for the mapping of magic names to methods, set by class decorator
+    magics = None
+    # Flag to check that the class decorator was properly applied
+    registered = False
+    # Instance of IPython shell
+    shell = 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 = {}  # 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))
+                ) 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)
+        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"""
+
+        if fn not in self.lsmagic():
+            error("%s is not a magic function" % fn)
+        self.options_table[fn] = optstr
+
+
+class MagicAlias(object):
+    """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

openalex_env_map/lib/python3.10/site-packages/IPython/core/magic_arguments.py

@@ -0,0 +1,310 @@
+''' A decorator-based method of constructing IPython magics with `argparse`
+option handling.
+
+New magic functions can be defined like so::
+
+    from IPython.core.magic_arguments import (argument, magic_arguments,
+        parse_argstring)
+
+    @magic_arguments()
+    @argument('-o', '--option', help='An optional argument.')
+    @argument('arg', type=int, help='An integer positional argument.')
+    def magic_cool(self, arg):
+        """ A really cool magic command.
+
+    """
+        args = parse_argstring(magic_cool, arg)
+        ...
+
+The `@magic_arguments` decorator marks the function as having argparse arguments.
+The `@argument` decorator adds an argument using the same syntax as argparse's
+`add_argument()` method. More sophisticated uses may also require the
+`@argument_group` or `@kwds` decorator to customize the formatting and the
+parsing.
+
+Help text for the magic is automatically generated from the docstring and the
+arguments::
+
+    In[1]: %cool?
+        %cool [-o OPTION] arg
+        
+        A really cool magic command.
+        
+        positional arguments:
+          arg                   An integer positional argument.
+        
+        optional arguments:
+          -o OPTION, --option OPTION
+                                An optional argument.
+
+Here is an elaborated example that uses default parameters in `argument` and calls the `args` in the cell magic::
+
+    from IPython.core.magic import register_cell_magic
+    from IPython.core.magic_arguments import (argument, magic_arguments,
+                                            parse_argstring)
+
+
+    @magic_arguments()
+    @argument(
+        "--option",
+        "-o",
+        help=("Add an option here"),
+    )
+    @argument(
+        "--style",
+        "-s",
+        default="foo",
+        help=("Add some style arguments"),
+    )
+    @register_cell_magic
+    def my_cell_magic(line, cell):
+        args = parse_argstring(my_cell_magic, line)
+        print(f"{args.option=}")
+        print(f"{args.style=}")
+        print(f"{cell=}")
+
+In a jupyter notebook, this cell magic can be executed like this::
+
+    %%my_cell_magic -o Hello
+    print("bar")
+    i = 42
+
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.core.magic_arguments
+   :parts: 3
+
+'''
+#-----------------------------------------------------------------------------
+# Copyright (C) 2010-2011, 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.
+#-----------------------------------------------------------------------------
+import argparse
+import re
+
+# Our own imports
+from IPython.core.error import UsageError
+from IPython.utils.decorators import undoc
+from IPython.utils.process import arg_split
+from IPython.utils.text import dedent
+
+NAME_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]*$")
+
+@undoc
+class MagicHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """A HelpFormatter with a couple of changes to meet our needs.
+    """
+    # Modified to dedent text.
+    def _fill_text(self, text, width, indent):
+        return argparse.RawDescriptionHelpFormatter._fill_text(self, dedent(text), width, indent)
+
+    # Modified to wrap argument placeholders in <> where necessary.
+    def _format_action_invocation(self, action):
+        if not action.option_strings:
+            metavar, = self._metavar_formatter(action, action.dest)(1)
+            return metavar
+
+        else:
+            parts = []
+
+            # if the Optional doesn't take a value, format is:
+            #    -s, --long
+            if action.nargs == 0:
+                parts.extend(action.option_strings)
+
+            # if the Optional takes a value, format is:
+            #    -s ARGS, --long ARGS
+            else:
+                default = action.dest.upper()
+                args_string = self._format_args(action, default)
+                # IPYTHON MODIFICATION: If args_string is not a plain name, wrap
+                # it in <> so it's valid RST.
+                if not NAME_RE.match(args_string):
+                    args_string = "<%s>" % args_string
+                for option_string in action.option_strings:
+                    parts.append('%s %s' % (option_string, args_string))
+
+            return ', '.join(parts)
+
+    # Override the default prefix ('usage') to our % magic escape,
+    # in a code block.
+    def add_usage(self, usage, actions, groups, prefix="::\n\n  %"):
+        super(MagicHelpFormatter, self).add_usage(usage, actions, groups, prefix)
+
+class MagicArgumentParser(argparse.ArgumentParser):
+    """ An ArgumentParser tweaked for use by IPython magics.
+    """
+    def __init__(self,
+                 prog=None,
+                 usage=None,
+                 description=None,
+                 epilog=None,
+                 parents=None,
+                 formatter_class=MagicHelpFormatter,
+                 prefix_chars='-',
+                 argument_default=None,
+                 conflict_handler='error',
+                 add_help=False):
+        if parents is None:
+            parents = []
+        super(MagicArgumentParser, self).__init__(prog=prog, usage=usage,
+            description=description, epilog=epilog,
+            parents=parents, formatter_class=formatter_class,
+            prefix_chars=prefix_chars, argument_default=argument_default,
+            conflict_handler=conflict_handler, add_help=add_help)
+
+    def error(self, message):
+        """ Raise a catchable error instead of exiting.
+        """
+        raise UsageError(message)
+
+    def parse_argstring(self, argstring):
+        """ Split a string into an argument list and parse that argument list.
+        """
+        argv = arg_split(argstring)
+        return self.parse_args(argv)
+
+
+def construct_parser(magic_func):
+    """ Construct an argument parser using the function decorations.
+    """
+    kwds = getattr(magic_func, 'argcmd_kwds', {})
+    if 'description' not in kwds:
+        kwds['description'] = getattr(magic_func, '__doc__', None)
+    arg_name = real_name(magic_func)
+    parser = MagicArgumentParser(arg_name, **kwds)
+    # Reverse the list of decorators in order to apply them in the
+    # order in which they appear in the source.
+    group = None
+    for deco in magic_func.decorators[::-1]:
+        result = deco.add_to_parser(parser, group)
+        if result is not None:
+            group = result
+
+    # Replace the magic function's docstring with the full help text.
+    magic_func.__doc__ = parser.format_help()
+
+    return parser
+
+
+def parse_argstring(magic_func, argstring):
+    """ Parse the string of arguments for the given magic function.
+    """
+    return magic_func.parser.parse_argstring(argstring)
+
+
+def real_name(magic_func):
+    """ Find the real name of the magic.
+    """
+    magic_name = magic_func.__name__
+    if magic_name.startswith('magic_'):
+        magic_name = magic_name[len('magic_'):]
+    return getattr(magic_func, 'argcmd_name', magic_name)
+
+
+class ArgDecorator(object):
+    """ Base class for decorators to add ArgumentParser information to a method.
+    """
+
+    def __call__(self, func):
+        if not getattr(func, 'has_arguments', False):
+            func.has_arguments = True
+            func.decorators = []
+        func.decorators.append(self)
+        return func
+
+    def add_to_parser(self, parser, group):
+        """ Add this object's information to the parser, if necessary.
+        """
+        pass
+
+
+class magic_arguments(ArgDecorator):
+    """ Mark the magic as having argparse arguments and possibly adjust the
+    name.
+    """
+
+    def __init__(self, name=None):
+        self.name = name
+
+    def __call__(self, func):
+        if not getattr(func, 'has_arguments', False):
+            func.has_arguments = True
+            func.decorators = []
+        if self.name is not None:
+            func.argcmd_name = self.name
+        # This should be the first decorator in the list of decorators, thus the
+        # last to execute. Build the parser.
+        func.parser = construct_parser(func)
+        return func
+
+
+class ArgMethodWrapper(ArgDecorator):
+
+    """
+    Base class to define a wrapper for ArgumentParser method.
+
+    Child class must define either `_method_name` or `add_to_parser`.
+
+    """
+
+    _method_name: str
+
+    def __init__(self, *args, **kwds):
+        self.args = args
+        self.kwds = kwds
+
+    def add_to_parser(self, parser, group):
+        """ Add this object's information to the parser.
+        """
+        if group is not None:
+            parser = group
+        getattr(parser, self._method_name)(*self.args, **self.kwds)
+        return None
+
+
+class argument(ArgMethodWrapper):
+    """ Store arguments and keywords to pass to add_argument().
+
+    Instances also serve to decorate command methods.
+    """
+    _method_name = 'add_argument'
+
+
+class defaults(ArgMethodWrapper):
+    """ Store arguments and keywords to pass to set_defaults().
+
+    Instances also serve to decorate command methods.
+    """
+    _method_name = 'set_defaults'
+
+
+class argument_group(ArgMethodWrapper):
+    """ Store arguments and keywords to pass to add_argument_group().
+
+    Instances also serve to decorate command methods.
+    """
+
+    def add_to_parser(self, parser, group):
+        """ Add this object's information to the parser.
+        """
+        return parser.add_argument_group(*self.args, **self.kwds)
+
+
+class kwds(ArgDecorator):
+    """ Provide other keywords to the sub-parser constructor.
+    """
+    def __init__(self, **kwds):
+        self.kwds = kwds
+
+    def __call__(self, func):
+        func = super(kwds, self).__call__(func)
+        func.argcmd_kwds = self.kwds
+        return func
+
+
+__all__ = ['magic_arguments', 'argument', 'argument_group', 'kwds',
+    'parse_argstring']

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/__init__.py

@@ -0,0 +1,42 @@
+"""Implementation of all the magic functions built into IPython.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2012 The 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+from ..magic import Magics, magics_class
+from .auto import AutoMagics
+from .basic import BasicMagics, AsyncMagics
+from .code import CodeMagics, MacroToEdit
+from .config import ConfigMagics
+from .display import DisplayMagics
+from .execution import ExecutionMagics
+from .extension import ExtensionMagics
+from .history import HistoryMagics
+from .logging import LoggingMagics
+from .namespace import NamespaceMagics
+from .osm import OSMagics
+from .packaging import PackagingMagics
+from .pylab import PylabMagics
+from .script import ScriptMagics
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+@magics_class
+class UserMagics(Magics):
+    """Placeholder for user-defined magics to be added at runtime.
+
+    All magics are eventually merged into a single namespace at runtime, but we
+    use this class to isolate the magics defined dynamically by the user into
+    their own class.
+    """

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/ast_mod.py

@@ -0,0 +1,330 @@
+"""
+This module contains utility function and classes to inject simple ast
+transformations based on code strings into IPython. While it is already possible
+with ast-transformers it is not easy to directly manipulate ast.
+
+
+IPython has pre-code and post-code hooks, but are ran from within the IPython
+machinery so may be inappropriate, for example for performance measurement.
+
+This module give you tools to simplify this, and expose 2 classes:
+
+- `ReplaceCodeTransformer` which is a simple ast transformer based on code
+  template,
+
+and for advance case:
+
+- `Mangler` which is a simple ast transformer that mangle names in the ast.
+
+
+Example, let's try to make a simple version of the ``timeit`` magic, that run a
+code snippet 10 times and print the average time taken.
+
+Basically we want to run :
+
+.. code-block:: python
+
+    from time import perf_counter
+    now = perf_counter()
+    for i in range(10):
+        __code__ # our code
+    print(f"Time taken: {(perf_counter() - now)/10}")
+    __ret__ # the result of the last statement
+
+Where ``__code__`` is the code snippet we want to run, and ``__ret__`` is the
+result, so that if we for example run `dataframe.head()` IPython still display
+the head of dataframe instead of nothing.
+
+Here is a complete example of a file `timit2.py` that define such a magic:
+
+.. code-block:: python
+
+    from IPython.core.magic import (
+        Magics,
+        magics_class,
+        line_cell_magic,
+    )
+    from IPython.core.magics.ast_mod import ReplaceCodeTransformer
+    from textwrap import dedent
+    import ast
+
+    template = template = dedent('''
+        from time import perf_counter
+        now = perf_counter()
+        for i in range(10):
+            __code__
+        print(f"Time taken: {(perf_counter() - now)/10}")
+        __ret__
+    '''
+    )
+
+
+    @magics_class
+    class AstM(Magics):
+        @line_cell_magic
+        def t2(self, line, cell):
+            transformer = ReplaceCodeTransformer.from_string(template)
+            transformer.debug = True
+            transformer.mangler.debug = True
+            new_code = transformer.visit(ast.parse(cell))
+            return exec(compile(new_code, "<ast>", "exec"))
+
+
+    def load_ipython_extension(ip):
+        ip.register_magics(AstM)
+
+
+
+.. code-block:: python
+
+    In [1]: %load_ext timit2
+
+    In [2]: %%t2
+       ...: import time
+       ...: time.sleep(0.05)
+       ...:
+       ...:
+    Time taken: 0.05435649999999441
+
+
+If you wish to ran all the code enter in IPython in an ast transformer, you can
+do so as well:
+
+.. code-block:: python
+
+    In [1]: from IPython.core.magics.ast_mod import ReplaceCodeTransformer
+       ...:
+       ...: template = '''
+       ...: from time import perf_counter
+       ...: now = perf_counter()
+       ...: __code__
+       ...: print(f"Code ran in {perf_counter()-now}")
+       ...: __ret__'''
+       ...:
+       ...: get_ipython().ast_transformers.append(ReplaceCodeTransformer.from_string(template))
+
+    In [2]: 1+1
+    Code ran in 3.40410006174352e-05
+    Out[2]: 2
+
+
+
+Hygiene and Mangling
+--------------------
+
+The ast transformer above is not hygienic, it may not work if the user code use
+the same variable names as the ones used in the template. For example.
+
+To help with this by default the `ReplaceCodeTransformer` will mangle all names
+staring with 3 underscores. This is a simple heuristic that should work in most
+case, but can be cumbersome in some case. We provide a `Mangler` class that can
+be overridden to change the mangling heuristic, or simply use the `mangle_all`
+utility function. It will _try_ to mangle all names (except `__ret__` and
+`__code__`), but this include builtins (``print``, ``range``, ``type``) and
+replace those by invalid identifiers py prepending ``mangle-``:
+``mangle-print``, ``mangle-range``, ``mangle-type`` etc. This is not a problem
+as currently Python AST support invalid identifiers, but it may not be the case
+in the future.
+
+You can set `ReplaceCodeTransformer.debug=True` and
+`ReplaceCodeTransformer.mangler.debug=True` to see the code after mangling and
+transforming:
+
+.. code-block:: python
+
+
+    In [1]: from IPython.core.magics.ast_mod import ReplaceCodeTransformer, mangle_all
+       ...:
+       ...: template = '''
+       ...: from builtins import type, print
+       ...: from time import perf_counter
+       ...: now = perf_counter()
+       ...: __code__
+       ...: print(f"Code ran in {perf_counter()-now}")
+       ...: __ret__'''
+       ...:
+       ...: transformer = ReplaceCodeTransformer.from_string(template, mangling_predicate=mangle_all)
+
+
+    In [2]: transformer.debug = True
+       ...: transformer.mangler.debug = True
+       ...: get_ipython().ast_transformers.append(transformer)
+
+    In [3]: 1+1
+    Mangling Alias mangle-type
+    Mangling Alias mangle-print
+    Mangling Alias mangle-perf_counter
+    Mangling now
+    Mangling perf_counter
+    Not mangling __code__
+    Mangling print
+    Mangling perf_counter
+    Mangling now
+    Not mangling __ret__
+    ---- Transformed code ----
+    from builtins import type as mangle-type, print as mangle-print
+    from time import perf_counter as mangle-perf_counter
+    mangle-now = mangle-perf_counter()
+    ret-tmp = 1 + 1
+    mangle-print(f'Code ran in {mangle-perf_counter() - mangle-now}')
+    ret-tmp
+    ---- ---------------- ----
+    Code ran in 0.00013654199938173406
+    Out[3]: 2
+
+
+"""
+
+__skip_doctest__ = True
+
+
+from ast import (
+    NodeTransformer,
+    Store,
+    Load,
+    Name,
+    Expr,
+    Assign,
+    Module,
+    Import,
+    ImportFrom,
+)
+import ast
+import copy
+
+from typing import Dict, Optional, Union
+
+
+mangle_all = lambda name: False if name in ("__ret__", "__code__") else True
+
+
+class Mangler(NodeTransformer):
+    """
+    Mangle given names in and ast tree to make sure they do not conflict with
+    user code.
+    """
+
+    enabled: bool = True
+    debug: bool = False
+
+    def log(self, *args, **kwargs):
+        if self.debug:
+            print(*args, **kwargs)
+
+    def __init__(self, predicate=None):
+        if predicate is None:
+            predicate = lambda name: name.startswith("___")
+        self.predicate = predicate
+
+    def visit_Name(self, node):
+        if self.predicate(node.id):
+            self.log("Mangling", node.id)
+            # Once in the ast we do not need
+            # names to be valid identifiers.
+            node.id = "mangle-" + node.id
+        else:
+            self.log("Not mangling", node.id)
+        return node
+
+    def visit_FunctionDef(self, node):
+        if self.predicate(node.name):
+            self.log("Mangling", node.name)
+            node.name = "mangle-" + node.name
+        else:
+            self.log("Not mangling", node.name)
+
+        for arg in node.args.args:
+            if self.predicate(arg.arg):
+                self.log("Mangling function arg", arg.arg)
+                arg.arg = "mangle-" + arg.arg
+            else:
+                self.log("Not mangling function arg", arg.arg)
+        return self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ImportFrom):
+        return self._visit_Import_and_ImportFrom(node)
+
+    def visit_Import(self, node: Import):
+        return self._visit_Import_and_ImportFrom(node)
+
+    def _visit_Import_and_ImportFrom(self, node: Union[Import, ImportFrom]):
+        for alias in node.names:
+            asname = alias.name if alias.asname is None else alias.asname
+            if self.predicate(asname):
+                new_name: str = "mangle-" + asname
+                self.log("Mangling Alias", new_name)
+                alias.asname = new_name
+            else:
+                self.log("Not mangling Alias", alias.asname)
+        return node
+
+
+class ReplaceCodeTransformer(NodeTransformer):
+    enabled: bool = True
+    debug: bool = False
+    mangler: Mangler
+
+    def __init__(
+        self, template: Module, mapping: Optional[Dict] = None, mangling_predicate=None
+    ):
+        assert isinstance(mapping, (dict, type(None)))
+        assert isinstance(mangling_predicate, (type(None), type(lambda: None)))
+        assert isinstance(template, ast.Module)
+        self.template = template
+        self.mangler = Mangler(predicate=mangling_predicate)
+        if mapping is None:
+            mapping = {}
+        self.mapping = mapping
+
+    @classmethod
+    def from_string(
+        cls, template: str, mapping: Optional[Dict] = None, mangling_predicate=None
+    ):
+        return cls(
+            ast.parse(template), mapping=mapping, mangling_predicate=mangling_predicate
+        )
+
+    def visit_Module(self, code):
+        if not self.enabled:
+            return code
+        # if not isinstance(code, ast.Module):
+        # recursively called...
+        #    return generic_visit(self, code)
+        last = code.body[-1]
+        if isinstance(last, Expr):
+            code.body.pop()
+            code.body.append(Assign([Name("ret-tmp", ctx=Store())], value=last.value))
+            ast.fix_missing_locations(code)
+            ret = Expr(value=Name("ret-tmp", ctx=Load()))
+            ret = ast.fix_missing_locations(ret)
+            self.mapping["__ret__"] = ret
+        else:
+            self.mapping["__ret__"] = ast.parse("None").body[0]
+        self.mapping["__code__"] = code.body
+        tpl = ast.fix_missing_locations(self.template)
+
+        tx = copy.deepcopy(tpl)
+        tx = self.mangler.visit(tx)
+        node = self.generic_visit(tx)
+        node_2 = ast.fix_missing_locations(node)
+        if self.debug:
+            print("---- Transformed code ----")
+            print(ast.unparse(node_2))
+            print("---- ---------------- ----")
+        return node_2
+
+    # this does not work as the name might be in a list and one might want to extend the list.
+    # def visit_Name(self, name):
+    #     if name.id in self.mapping and name.id == "__ret__":
+    #         print(name, "in mapping")
+    #         if isinstance(name.ctx, ast.Store):
+    #             return Name("tmp", ctx=Store())
+    #         else:
+    #             return copy.deepcopy(self.mapping[name.id])
+    #     return name
+
+    def visit_Expr(self, expr):
+        if isinstance(expr.value, Name) and expr.value.id in self.mapping:
+            if self.mapping[expr.value.id] is not None:
+                return copy.deepcopy(self.mapping[expr.value.id])
+        return self.generic_visit(expr)

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/auto.py

@@ -0,0 +1,144 @@
+"""Implementation of magic functions that control various automatic behaviors.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2012 The 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Our own packages
+from IPython.core.magic import Bunch, Magics, magics_class, line_magic
+from IPython.testing.skipdoctest import skip_doctest
+from logging import error
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+@magics_class
+class AutoMagics(Magics):
+    """Magics that control various autoX behaviors."""
+
+    def __init__(self, shell):
+        super(AutoMagics, self).__init__(shell)
+        # namespace for holding state we may need
+        self._magic_state = Bunch()
+
+    @line_magic
+    def automagic(self, parameter_s=''):
+        """Make magic functions callable without having to type the initial %.
+
+        Without arguments toggles on/off (when off, you must call it as
+        %automagic, of course).  With arguments it sets the value, and you can
+        use any of (case insensitive):
+
+         - on, 1, True: to activate
+
+         - off, 0, False: to deactivate.
+
+        Note that magic functions have lowest priority, so if there's a
+        variable whose name collides with that of a magic fn, automagic won't
+        work for that function (you get the variable instead). However, if you
+        delete the variable (del var), the previously shadowed magic function
+        becomes visible to automagic again."""
+
+        arg = parameter_s.lower()
+        mman = self.shell.magics_manager
+        if arg in ('on', '1', 'true'):
+            val = True
+        elif arg in ('off', '0', 'false'):
+            val = False
+        else:
+            val = not mman.auto_magic
+        mman.auto_magic = val
+        print('\n' + self.shell.magics_manager.auto_status())
+
+    @skip_doctest
+    @line_magic
+    def autocall(self, parameter_s=''):
+        """Make functions callable without having to type parentheses.
+
+        Usage:
+
+           %autocall [mode]
+
+        The mode can be one of: 0->Off, 1->Smart, 2->Full.  If not given, the
+        value is toggled on and off (remembering the previous state).
+
+        In more detail, these values mean:
+
+        0 -> fully disabled
+
+        1 -> active, but do not apply if there are no arguments on the line.
+
+        In this mode, you get::
+
+          In [1]: callable
+          Out[1]: <built-in function callable>
+
+          In [2]: callable 'hello'
+          ------> callable('hello')
+          Out[2]: False
+
+        2 -> Active always.  Even if no arguments are present, the callable
+        object is called::
+
+          In [2]: float
+          ------> float()
+          Out[2]: 0.0
+
+        Note that even with autocall off, you can still use '/' at the start of
+        a line to treat the first argument on the command line as a function
+        and add parentheses to it::
+
+          In [8]: /str 43
+          ------> str(43)
+          Out[8]: '43'
+
+        # all-random (note for auto-testing)
+        """
+
+        valid_modes = {
+            0: "Off",
+            1: "Smart",
+            2: "Full",
+        }
+
+        def errorMessage() -> str:
+            error = "Valid modes: "
+            for k, v in valid_modes.items():
+                error += str(k) + "->" + v + ", "
+            error = error[:-2]  # remove tailing `, ` after last element
+            return error
+
+        if parameter_s:
+            if not parameter_s in map(str, valid_modes.keys()):
+                error(errorMessage())
+                return
+            arg = int(parameter_s)
+        else:
+            arg = 'toggle'
+
+        if not arg in (*list(valid_modes.keys()), "toggle"):
+            error(errorMessage())
+            return
+
+        if arg in (valid_modes.keys()):
+            self.shell.autocall = arg
+        else: # toggle
+            if self.shell.autocall:
+                self._magic_state.autocall_save = self.shell.autocall
+                self.shell.autocall = 0
+            else:
+                try:
+                    self.shell.autocall = self._magic_state.autocall_save
+                except AttributeError:
+                    self.shell.autocall = self._magic_state.autocall_save = 1
+
+        print("Automatic calling is:", list(valid_modes.values())[self.shell.autocall])

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/basic.py

@@ -0,0 +1,666 @@
+"""Implementation of basic magic functions."""
+
+
+from logging import error
+import io
+import os
+from pprint import pformat
+import sys
+from warnings import warn
+
+from traitlets.utils.importstring import import_item
+from IPython.core import magic_arguments, page
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
+from IPython.utils.text import format_screen, dedent, indent
+from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.ipstruct import Struct
+
+
+class MagicsDisplay(object):
+    def __init__(self, magics_manager, ignore=None):
+        self.ignore = ignore if ignore else []
+        self.magics_manager = magics_manager
+    
+    def _lsmagic(self):
+        """The main implementation of the %lsmagic"""
+        mesc = magic_escapes['line']
+        cesc = magic_escapes['cell']
+        mman = self.magics_manager
+        magics = mman.lsmagic()
+        out = ['Available line magics:',
+               mesc + ('  '+mesc).join(sorted([m for m,v in magics['line'].items() if (v not in self.ignore)])),
+               '',
+               'Available cell magics:',
+               cesc + ('  '+cesc).join(sorted([m for m,v in magics['cell'].items() if (v not in self.ignore)])),
+               '',
+               mman.auto_status()]
+        return '\n'.join(out)
+
+    def _repr_pretty_(self, p, cycle):
+        p.text(self._lsmagic())
+    
+    def __repr__(self):
+        return self.__str__()
+
+    def __str__(self):
+        return self._lsmagic()
+    
+    def _jsonable(self):
+        """turn magics dict into jsonable dict of the same structure
+
+        replaces object instances with their class names as strings
+        """
+        magic_dict = {}
+        mman = self.magics_manager
+        magics = mman.lsmagic()
+        for key, subdict in magics.items():
+            d = {}
+            magic_dict[key] = d
+            for name, obj in subdict.items():
+                try:
+                    classname = obj.__self__.__class__.__name__
+                except AttributeError:
+                    classname = 'Other'
+                
+                d[name] = classname
+        return magic_dict
+        
+    def _repr_json_(self):
+        return self._jsonable()
+
+
+@magics_class
+class BasicMagics(Magics):
+    """Magics that provide central IPython functionality.
+
+    These are various magics that don't fit into specific categories but that
+    are all part of the base 'IPython experience'."""
+
+    @skip_doctest
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument(
+        '-l', '--line', action='store_true',
+        help="""Create a line magic alias."""
+    )
+    @magic_arguments.argument(
+        '-c', '--cell', action='store_true',
+        help="""Create a cell magic alias."""
+    )
+    @magic_arguments.argument(
+        'name',
+        help="""Name of the magic to be created."""
+    )
+    @magic_arguments.argument(
+        'target',
+        help="""Name of the existing line or cell magic."""
+    )
+    @magic_arguments.argument(
+        '-p', '--params', default=None,
+        help="""Parameters passed to the magic function."""
+    )
+    @line_magic
+    def alias_magic(self, line=''):
+        """Create an alias for an existing line or cell magic.
+
+        Examples
+        --------
+        ::
+
+          In [1]: %alias_magic t timeit
+          Created `%t` as an alias for `%timeit`.
+          Created `%%t` as an alias for `%%timeit`.
+
+          In [2]: %t -n1 pass
+          107 ns ± 43.6 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+          In [3]: %%t -n1
+             ...: pass
+             ...:
+          107 ns ± 58.3 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)
+
+          In [4]: %alias_magic --cell whereami pwd
+          UsageError: Cell magic function `%%pwd` not found.
+          In [5]: %alias_magic --line whereami pwd
+          Created `%whereami` as an alias for `%pwd`.
+
+          In [6]: %whereami
+          Out[6]: '/home/testuser'
+
+          In [7]: %alias_magic h history -p "-l 30" --line
+          Created `%h` as an alias for `%history -l 30`.
+        """
+
+        args = magic_arguments.parse_argstring(self.alias_magic, line)
+        shell = self.shell
+        mman = self.shell.magics_manager
+        escs = ''.join(magic_escapes.values())
+
+        target = args.target.lstrip(escs)
+        name = args.name.lstrip(escs)
+
+        params = args.params
+        if (params and
+                ((params.startswith('"') and params.endswith('"'))
+                or (params.startswith("'") and params.endswith("'")))):
+            params = params[1:-1]
+
+        # Find the requested magics.
+        m_line = shell.find_magic(target, 'line')
+        m_cell = shell.find_magic(target, 'cell')
+        if args.line and m_line is None:
+            raise UsageError('Line magic function `%s%s` not found.' %
+                             (magic_escapes['line'], target))
+        if args.cell and m_cell is None:
+            raise UsageError('Cell magic function `%s%s` not found.' %
+                             (magic_escapes['cell'], target))
+
+        # If --line and --cell are not specified, default to the ones
+        # that are available.
+        if not args.line and not args.cell:
+            if not m_line and not m_cell:
+                raise UsageError(
+                    'No line or cell magic with name `%s` found.' % target
+                )
+            args.line = bool(m_line)
+            args.cell = bool(m_cell)
+
+        params_str = "" if params is None else " " + params
+
+        if args.line:
+            mman.register_alias(name, target, 'line', params)
+            print('Created `%s%s` as an alias for `%s%s%s`.' % (
+                magic_escapes['line'], name,
+                magic_escapes['line'], target, params_str))
+
+        if args.cell:
+            mman.register_alias(name, target, 'cell', params)
+            print('Created `%s%s` as an alias for `%s%s%s`.' % (
+                magic_escapes['cell'], name,
+                magic_escapes['cell'], target, params_str))
+
+    @line_magic
+    def lsmagic(self, parameter_s=''):
+        """List currently available magic functions."""
+        return MagicsDisplay(self.shell.magics_manager, ignore=[])
+
+    def _magic_docs(self, brief=False, rest=False):
+        """Return docstrings from magic functions."""
+        mman = self.shell.magics_manager
+        docs = mman.lsmagic_docs(brief, missing='No documentation')
+
+        if rest:
+            format_string = '**%s%s**::\n\n%s\n\n'
+        else:
+            format_string = '%s%s:\n%s\n'
+
+        return ''.join(
+            [format_string % (magic_escapes['line'], fname,
+                              indent(dedent(fndoc)))
+             for fname, fndoc in sorted(docs['line'].items())]
+            +
+            [format_string % (magic_escapes['cell'], fname,
+                              indent(dedent(fndoc)))
+             for fname, fndoc in sorted(docs['cell'].items())]
+        )
+
+    @line_magic
+    def magic(self, parameter_s=''):
+        """Print information about the magic function system.
+
+        Supported formats: -latex, -brief, -rest
+        """
+
+        mode = ''
+        try:
+            mode = parameter_s.split()[0][1:]
+        except IndexError:
+            pass
+
+        brief = (mode == 'brief')
+        rest = (mode == 'rest')
+        magic_docs = self._magic_docs(brief, rest)
+
+        if mode == 'latex':
+            print(self.format_latex(magic_docs))
+            return
+        else:
+            magic_docs = format_screen(magic_docs)
+
+        out = ["""
+IPython's 'magic' functions
+===========================
+
+The magic function system provides a series of functions which allow you to
+control the behavior of IPython itself, plus a lot of system-type
+features. There are two kinds of magics, line-oriented and cell-oriented.
+
+Line magics are prefixed with the % character and work much like OS
+command-line calls: they get as an argument the rest of the line, where
+arguments are passed without parentheses or quotes.  For example, this will
+time the given statement::
+
+        %timeit range(1000)
+
+Cell magics are prefixed with a double %%, and they are functions that get as
+an argument not only the rest of the line, but also the lines below it in a
+separate argument.  These magics are called with two arguments: the rest of the
+call line and the body of the cell, consisting of the lines below the first.
+For example::
+
+        %%timeit x = numpy.random.randn((100, 100))
+        numpy.linalg.svd(x)
+
+will time the execution of the numpy svd routine, running the assignment of x
+as part of the setup phase, which is not timed.
+
+In a line-oriented client (the terminal or Qt console IPython), starting a new
+input with %% will automatically enter cell mode, and IPython will continue
+reading input until a blank line is given.  In the notebook, simply type the
+whole cell as one entity, but keep in mind that the %% escape can only be at
+the very start of the cell.
+
+NOTE: If you have 'automagic' enabled (via the command line option or with the
+%automagic function), you don't need to type in the % explicitly for line
+magics; cell magics always require an explicit '%%' escape.  By default,
+IPython ships with automagic on, so you should only rarely need the % escape.
+
+Example: typing '%cd mydir' (without the quotes) changes your working directory
+to 'mydir', if it exists.
+
+For a list of the available magic functions, use %lsmagic. For a description
+of any of them, type %magic_name?, e.g. '%cd?'.
+
+Currently the magic system has the following functions:""",
+       magic_docs,
+       "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
+       str(self.lsmagic()),
+       ]
+        page.page('\n'.join(out))
+
+
+    @line_magic
+    def page(self, parameter_s=''):
+        """Pretty print the object and display it through a pager.
+
+        %page [options] OBJECT
+
+        If no object is given, use _ (last output).
+
+        Options:
+
+          -r: page str(object), don't pretty-print it."""
+
+        # After a function contributed by Olivier Aubert, slightly modified.
+
+        # Process options/args
+        opts, args = self.parse_options(parameter_s, 'r')
+        raw = 'r' in opts
+
+        oname = args and args or '_'
+        info = self.shell._ofind(oname)
+        if info.found:
+            if raw:
+                txt = str(info.obj)
+            else:
+                txt = pformat(info.obj)
+            page.page(txt)
+        else:
+            print('Object `%s` not found' % oname)
+
+    @line_magic
+    def pprint(self, parameter_s=''):
+        """Toggle pretty printing on/off."""
+        ptformatter = self.shell.display_formatter.formatters['text/plain']
+        ptformatter.pprint = bool(1 - ptformatter.pprint)
+        print('Pretty printing has been turned',
+              ['OFF','ON'][ptformatter.pprint])
+
+    @line_magic
+    def colors(self, parameter_s=''):
+        """Switch color scheme for prompts, info system and exception handlers.
+
+        Currently implemented schemes: NoColor, Linux, LightBG.
+
+        Color scheme names are not case-sensitive.
+
+        Examples
+        --------
+        To get a plain black and white terminal::
+
+          %colors nocolor
+        """
+        def color_switch_err(name):
+            warn('Error changing %s color schemes.\n%s' %
+                 (name, sys.exc_info()[1]), stacklevel=2)
+
+
+        new_scheme = parameter_s.strip()
+        if not new_scheme:
+            raise UsageError(
+                "%colors: you must specify a color scheme. See '%colors?'")
+        # local shortcut
+        shell = self.shell
+
+        # Set shell colour scheme
+        try:
+            shell.colors = new_scheme
+            shell.refresh_style()
+        except:
+            color_switch_err('shell')
+
+        # Set exception colors
+        try:
+            shell.InteractiveTB.set_colors(scheme = new_scheme)
+            shell.SyntaxTB.set_colors(scheme = new_scheme)
+        except:
+            color_switch_err('exception')
+
+        # Set info (for 'object?') colors
+        if shell.color_info:
+            try:
+                shell.inspector.set_active_scheme(new_scheme)
+            except:
+                color_switch_err('object inspector')
+        else:
+            shell.inspector.set_active_scheme('NoColor')
+
+    @line_magic
+    def xmode(self, parameter_s=''):
+        """Switch modes for the exception handlers.
+
+        Valid modes: Plain, Context, Verbose, and Minimal.
+
+        If called without arguments, acts as a toggle.
+
+        When in verbose mode the value `--show` (and `--hide`)
+        will respectively show (or hide) frames with ``__tracebackhide__ =
+        True`` value set.
+        """
+
+        def xmode_switch_err(name):
+            warn('Error changing %s exception modes.\n%s' %
+                 (name,sys.exc_info()[1]))
+
+        shell = self.shell
+        if parameter_s.strip() == "--show":
+            shell.InteractiveTB.skip_hidden = False
+            return
+        if parameter_s.strip() == "--hide":
+            shell.InteractiveTB.skip_hidden = True
+            return
+
+        new_mode = parameter_s.strip().capitalize()
+        try:
+            shell.InteractiveTB.set_mode(mode=new_mode)
+            print('Exception reporting mode:',shell.InteractiveTB.mode)
+        except:
+            xmode_switch_err('user')
+
+    @line_magic
+    def quickref(self, arg):
+        """ Show a quick reference sheet """
+        from IPython.core.usage import quick_reference
+        qr = quick_reference + self._magic_docs(brief=True)
+        page.page(qr)
+
+    @line_magic
+    def doctest_mode(self, parameter_s=''):
+        """Toggle doctest mode on and off.
+
+        This mode is intended to make IPython behave as much as possible like a
+        plain Python shell, from the perspective of how its prompts, exceptions
+        and output look.  This makes it easy to copy and paste parts of a
+        session into doctests.  It does so by:
+
+        - Changing the prompts to the classic ``>>>`` ones.
+        - Changing the exception reporting mode to 'Plain'.
+        - Disabling pretty-printing of output.
+
+        Note that IPython also supports the pasting of code snippets that have
+        leading '>>>' and '...' prompts in them.  This means that you can paste
+        doctests from files or docstrings (even if they have leading
+        whitespace), and the code will execute correctly.  You can then use
+        '%history -t' to see the translated history; this will give you the
+        input after removal of all the leading prompts and whitespace, which
+        can be pasted back into an editor.
+
+        With these features, you can switch into this mode easily whenever you
+        need to do testing and changes to doctests, without having to leave
+        your existing IPython session.
+        """
+
+        # Shorthands
+        shell = self.shell
+        meta = shell.meta
+        disp_formatter = self.shell.display_formatter
+        ptformatter = disp_formatter.formatters['text/plain']
+        # dstore is a data store kept in the instance metadata bag to track any
+        # changes we make, so we can undo them later.
+        dstore = meta.setdefault('doctest_mode',Struct())
+        save_dstore = dstore.setdefault
+
+        # save a few values we'll need to recover later
+        mode = save_dstore('mode',False)
+        save_dstore('rc_pprint',ptformatter.pprint)
+        save_dstore('xmode',shell.InteractiveTB.mode)
+        save_dstore('rc_separate_out',shell.separate_out)
+        save_dstore('rc_separate_out2',shell.separate_out2)
+        save_dstore('rc_separate_in',shell.separate_in)
+        save_dstore('rc_active_types',disp_formatter.active_types)
+
+        if not mode:
+            # turn on
+
+            # Prompt separators like plain python
+            shell.separate_in = ''
+            shell.separate_out = ''
+            shell.separate_out2 = ''
+
+
+            ptformatter.pprint = False
+            disp_formatter.active_types = ['text/plain']
+
+            shell.run_line_magic("xmode", "Plain")
+        else:
+            # turn off
+            shell.separate_in = dstore.rc_separate_in
+
+            shell.separate_out = dstore.rc_separate_out
+            shell.separate_out2 = dstore.rc_separate_out2
+
+            ptformatter.pprint = dstore.rc_pprint
+            disp_formatter.active_types = dstore.rc_active_types
+
+            shell.run_line_magic("xmode", dstore.xmode)
+
+        # mode here is the state before we switch; switch_doctest_mode takes
+        # the mode we're switching to.
+        shell.switch_doctest_mode(not mode)
+
+        # Store new mode and inform
+        dstore.mode = bool(not mode)
+        mode_label = ['OFF','ON'][dstore.mode]
+        print('Doctest mode is:', mode_label)
+
+    @line_magic
+    def gui(self, parameter_s=''):
+        """Enable or disable IPython GUI event loop integration.
+
+        %gui [GUINAME]
+
+        This magic replaces IPython's threaded shells that were activated
+        using the (pylab/wthread/etc.) command line flags.  GUI toolkits
+        can now be enabled at runtime and keyboard
+        interrupts should work without any problems.  The following toolkits
+        are supported:  wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
+
+            %gui wx      # enable wxPython event loop integration
+            %gui qt      # enable PyQt/PySide event loop integration
+                         # with the latest version available.
+            %gui qt6     # enable PyQt6/PySide6 event loop integration
+            %gui qt5     # enable PyQt5/PySide2 event loop integration
+            %gui gtk     # enable PyGTK event loop integration
+            %gui gtk3    # enable Gtk3 event loop integration
+            %gui gtk4    # enable Gtk4 event loop integration
+            %gui tk      # enable Tk event loop integration
+            %gui osx     # enable Cocoa event loop integration
+                         # (requires %matplotlib 1.1)
+            %gui         # disable all event loop integration
+
+        WARNING:  after any of these has been called you can simply create
+        an application object, but DO NOT start the event loop yourself, as
+        we have already handled that.
+        """
+        opts, arg = self.parse_options(parameter_s, '')
+        if arg=='': arg = None
+        try:
+            return self.shell.enable_gui(arg)
+        except Exception as e:
+            # print simple error message, rather than traceback if we can't
+            # hook up the GUI
+            error(str(e))
+
+    @skip_doctest
+    @line_magic
+    def precision(self, s=''):
+        """Set floating point precision for pretty printing.
+
+        Can set either integer precision or a format string.
+
+        If numpy has been imported and precision is an int,
+        numpy display precision will also be set, via ``numpy.set_printoptions``.
+
+        If no argument is given, defaults will be restored.
+
+        Examples
+        --------
+        ::
+
+            In [1]: from math import pi
+
+            In [2]: %precision 3
+            Out[2]: '%.3f'
+
+            In [3]: pi
+            Out[3]: 3.142
+
+            In [4]: %precision %i
+            Out[4]: '%i'
+
+            In [5]: pi
+            Out[5]: 3
+
+            In [6]: %precision %e
+            Out[6]: '%e'
+
+            In [7]: pi**10
+            Out[7]: 9.364805e+04
+
+            In [8]: %precision
+            Out[8]: '%r'
+
+            In [9]: pi**10
+            Out[9]: 93648.047476082982
+        """
+        ptformatter = self.shell.display_formatter.formatters['text/plain']
+        ptformatter.float_precision = s
+        return ptformatter.float_format
+
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument(
+        'filename', type=str,
+        help='Notebook name or filename'
+    )
+    @line_magic
+    def notebook(self, s):
+        """Export and convert IPython notebooks.
+
+        This function can export the current IPython history to a notebook file.
+        For example, to export the history to "foo.ipynb" do "%notebook foo.ipynb".
+        """
+        args = magic_arguments.parse_argstring(self.notebook, s)
+        outfname = os.path.expanduser(args.filename)
+
+        from nbformat import write, v4
+
+        cells = []
+        hist = list(self.shell.history_manager.get_range())
+        if(len(hist)<=1):
+            raise ValueError('History is empty, cannot export')
+        for session, execution_count, source in hist[:-1]:
+            cells.append(v4.new_code_cell(
+                execution_count=execution_count,
+                source=source
+            ))
+        nb = v4.new_notebook(cells=cells)
+        with io.open(outfname, "w", encoding="utf-8") as f:
+            write(nb, f, version=4)
+
+@magics_class
+class AsyncMagics(BasicMagics):
+
+    @line_magic
+    def autoawait(self, parameter_s):
+        """
+        Allow to change the status of the autoawait option.
+
+        This allow you to set a specific asynchronous code runner.
+
+        If no value is passed, print the currently used asynchronous integration
+        and whether it is activated.
+
+        It can take a number of value evaluated in the following order:
+
+        - False/false/off deactivate autoawait integration
+        - True/true/on activate autoawait integration using configured default
+          loop
+        - asyncio/curio/trio activate autoawait integration and use integration
+          with said library.
+
+        - `sync` turn on the pseudo-sync integration (mostly used for
+          `IPython.embed()` which does not run IPython with a real eventloop and
+          deactivate running asynchronous code. Turning on Asynchronous code with
+          the pseudo sync loop is undefined behavior and may lead IPython to crash.
+
+        If the passed parameter does not match any of the above and is a python
+        identifier, get said object from user namespace and set it as the
+        runner, and activate autoawait.
+
+        If the object is a fully qualified object name, attempt to import it and
+        set it as the runner, and activate autoawait.
+
+        The exact behavior of autoawait is experimental and subject to change
+        across version of IPython and Python.
+        """
+
+        param = parameter_s.strip()
+        d = {True: "on", False: "off"}
+
+        if not param:
+            print("IPython autoawait is `{}`, and set to use `{}`".format(
+                d[self.shell.autoawait],
+                self.shell.loop_runner
+            ))
+            return None
+
+        if param.lower() in ('false', 'off'):
+            self.shell.autoawait = False
+            return None
+        if param.lower() in ('true', 'on'):
+            self.shell.autoawait = True
+            return None
+
+        if param in self.shell.loop_runner_map:
+            self.shell.loop_runner, self.shell.autoawait = self.shell.loop_runner_map[param]
+            return None
+
+        if param in self.shell.user_ns :
+            self.shell.loop_runner = self.shell.user_ns[param]
+            self.shell.autoawait = True
+            return None
+
+        runner = import_item(param)
+
+        self.shell.loop_runner = runner
+        self.shell.autoawait = True

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/code.py

@@ -0,0 +1,757 @@
+"""Implementation of code management magic functions.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2012 The 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib
+import inspect
+import io
+import os
+import re
+import sys
+import ast
+from itertools import chain
+from urllib.request import Request, urlopen
+from urllib.parse import urlencode
+from pathlib import Path
+
+# Our own packages
+from IPython.core.error import TryNext, StdinNotImplementedError, UsageError
+from IPython.core.macro import Macro
+from IPython.core.magic import Magics, magics_class, line_magic
+from IPython.core.oinspect import find_file, find_source_lines
+from IPython.core.release import version
+from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.contexts import preserve_keys
+from IPython.utils.path import get_py_filename
+from warnings import warn
+from logging import error
+from IPython.utils.text import get_text_list
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+# Used for exception handling in magic_edit
+class MacroToEdit(ValueError): pass
+
+ipython_input_pat = re.compile(r"<ipython\-input\-(\d+)-[a-z\d]+>$")
+
+# To match, e.g. 8-10 1:5 :10 3-
+range_re = re.compile(r"""
+(?P<start>\d+)?
+((?P<sep>[\-:])
+ (?P<end>\d+)?)?
+$""", re.VERBOSE)
+
+
+def extract_code_ranges(ranges_str):
+    """Turn a string of range for %%load into 2-tuples of (start, stop)
+    ready to use as a slice of the content split by lines.
+
+    Examples
+    --------
+    list(extract_input_ranges("5-10 2"))
+    [(4, 10), (1, 2)]
+    """
+    for range_str in ranges_str.split():
+        rmatch = range_re.match(range_str)
+        if not rmatch:
+            continue
+        sep = rmatch.group("sep")
+        start = rmatch.group("start")
+        end = rmatch.group("end")
+
+        if sep == '-':
+            start = int(start) - 1 if start else None
+            end = int(end) if end else None
+        elif sep == ':':
+            start = int(start) - 1 if start else None
+            end = int(end) - 1 if end else None
+        else:
+            end = int(start)
+            start = int(start) - 1
+        yield (start, end)
+
+
+def extract_symbols(code, symbols):
+    """
+    Return a tuple  (blocks, not_found)
+    where ``blocks`` is a list of code fragments
+    for each symbol parsed from code, and ``not_found`` are
+    symbols not found in the code.
+
+    For example::
+
+        In [1]: code = '''a = 10
+           ...: def b(): return 42
+           ...: class A: pass'''
+
+        In [2]: extract_symbols(code, 'A,b,z')
+        Out[2]: (['class A: pass\\n', 'def b(): return 42\\n'], ['z'])
+    """
+    symbols = symbols.split(',')
+
+    # this will raise SyntaxError if code isn't valid Python
+    py_code = ast.parse(code)
+
+    marks = [(getattr(s, 'name', None), s.lineno) for s in py_code.body]
+    code = code.split('\n')
+
+    symbols_lines = {}
+    
+    # we already know the start_lineno of each symbol (marks). 
+    # To find each end_lineno, we traverse in reverse order until each 
+    # non-blank line
+    end = len(code)  
+    for name, start in reversed(marks):
+        while not code[end - 1].strip():
+            end -= 1
+        if name:
+            symbols_lines[name] = (start - 1, end)
+        end = start - 1
+
+    # Now symbols_lines is a map
+    # {'symbol_name': (start_lineno, end_lineno), ...}
+    
+    # fill a list with chunks of codes for each requested symbol
+    blocks = []
+    not_found = []
+    for symbol in symbols:
+        if symbol in symbols_lines:
+            start, end = symbols_lines[symbol]
+            blocks.append('\n'.join(code[start:end]) + '\n')
+        else:
+            not_found.append(symbol)
+
+    return blocks, not_found
+
+def strip_initial_indent(lines):
+    """For %load, strip indent from lines until finding an unindented line.
+
+    https://github.com/ipython/ipython/issues/9775
+    """
+    indent_re = re.compile(r'\s+')
+
+    it = iter(lines)
+    first_line = next(it)
+    indent_match = indent_re.match(first_line)
+
+    if indent_match:
+        # First line was indented
+        indent = indent_match.group()
+        yield first_line[len(indent):]
+
+        for line in it:
+            if line.startswith(indent):
+                yield line[len(indent) :]
+            elif line in ("\n", "\r\n") or len(line) == 0:
+                yield line
+            else:
+                # Less indented than the first line - stop dedenting
+                yield line
+                break
+    else:
+        yield first_line
+
+    # Pass the remaining lines through without dedenting
+    for line in it:
+        yield line
+
+
+class InteractivelyDefined(Exception):
+    """Exception for interactively defined variable in magic_edit"""
+    def __init__(self, index):
+        self.index = index
+
+
+@magics_class
+class CodeMagics(Magics):
+    """Magics related to code management (loading, saving, editing, ...)."""
+
+    def __init__(self, *args, **kwargs):
+        self._knowntemps = set()
+        super(CodeMagics, self).__init__(*args, **kwargs)
+
+    @line_magic
+    def save(self, parameter_s=''):
+        """Save a set of lines or a macro to a given filename.
+
+        Usage:\\
+          %save [options] filename [history]
+
+        Options:
+
+          -r: use 'raw' input.  By default, the 'processed' history is used,
+          so that magics are loaded in their transformed version to valid
+          Python.  If this option is given, the raw input as typed as the
+          command line is used instead.
+          
+          -f: force overwrite.  If file exists, %save will prompt for overwrite
+          unless -f is given.
+
+          -a: append to the file instead of overwriting it.
+
+        The history argument uses the same syntax as %history for input ranges,
+        then saves the lines to the filename you specify.
+
+        If no ranges are specified, saves history of the current session up to
+        this point.
+
+        It adds a '.py' extension to the file if you don't do so yourself, and
+        it asks for confirmation before overwriting existing files.
+
+        If `-r` option is used, the default extension is `.ipy`.
+        """
+
+        opts,args = self.parse_options(parameter_s,'fra',mode='list')
+        if not args:
+            raise UsageError('Missing filename.')
+        raw = 'r' in opts
+        force = 'f' in opts
+        append = 'a' in opts
+        mode = 'a' if append else 'w'
+        ext = '.ipy' if raw else '.py'
+        fname, codefrom = args[0], " ".join(args[1:])
+        if not fname.endswith(('.py','.ipy')):
+            fname += ext
+        fname = os.path.expanduser(fname)
+        file_exists = os.path.isfile(fname)
+        if file_exists and not force and not append:
+            try:
+                overwrite = self.shell.ask_yes_no('File `%s` exists. Overwrite (y/[N])? ' % fname, default='n')
+            except StdinNotImplementedError:
+                print("File `%s` exists. Use `%%save -f %s` to force overwrite" % (fname, parameter_s))
+                return
+            if not overwrite :
+                print('Operation cancelled.')
+                return
+        try:
+            cmds = self.shell.find_user_code(codefrom,raw)
+        except (TypeError, ValueError) as e:
+            print(e.args[0])
+            return
+        with io.open(fname, mode, encoding="utf-8") as f:
+            if not file_exists or not append:
+                f.write("# coding: utf-8\n")
+            f.write(cmds)
+            # make sure we end on a newline
+            if not cmds.endswith('\n'):
+                f.write('\n')
+        print('The following commands were written to file `%s`:' % fname)
+        print(cmds)
+
+    @line_magic
+    def pastebin(self, parameter_s=''):
+        """Upload code to dpaste.com, returning the URL.
+
+        Usage:\\
+          %pastebin [-d "Custom description"][-e 24] 1-7
+
+        The argument can be an input history range, a filename, or the name of a
+        string or macro.
+
+        If no arguments are given, uploads the history of this session up to
+        this point.
+
+        Options:
+
+          -d: Pass a custom description. The default will say
+              "Pasted from IPython".
+          -e: Pass number of days for the link to be expired.
+              The default will be 7 days.
+        """
+        opts, args = self.parse_options(parameter_s, "d:e:")
+
+        try:
+            code = self.shell.find_user_code(args)
+        except (ValueError, TypeError) as e:
+            print(e.args[0])
+            return
+
+        expiry_days = 7
+        try:
+            expiry_days = int(opts.get("e", 7))
+        except ValueError as e:
+            print(e.args[0].capitalize())
+            return
+        if expiry_days < 1 or expiry_days > 365:
+            print("Expiry days should be in range of 1 to 365")
+            return
+
+        post_data = urlencode(
+            {
+                "title": opts.get("d", "Pasted from IPython"),
+                "syntax": "python",
+                "content": code,
+                "expiry_days": expiry_days,
+            }
+        ).encode("utf-8")
+
+        request = Request(
+            "https://dpaste.com/api/v2/",
+            headers={"User-Agent": "IPython v{}".format(version)},
+        )
+        response = urlopen(request, post_data)
+        return response.headers.get('Location')
+
+    @line_magic
+    def loadpy(self, arg_s):
+        """Alias of `%load`
+
+        `%loadpy` has gained some flexibility and dropped the requirement of a `.py`
+        extension. So it has been renamed simply into %load. You can look at
+        `%load`'s docstring for more info.
+        """
+        self.load(arg_s)
+
+    @line_magic
+    def load(self, arg_s):
+        """Load code into the current frontend.
+
+        Usage:\\
+          %load [options] source
+
+          where source can be a filename, URL, input history range, macro, or
+          element in the user namespace
+
+        If no arguments are given, loads the history of this session up to this
+        point.
+
+        Options:
+
+          -r <lines>: Specify lines or ranges of lines to load from the source.
+          Ranges could be specified as x-y (x..y) or in python-style x:y 
+          (x..(y-1)). Both limits x and y can be left blank (meaning the 
+          beginning and end of the file, respectively).
+
+          -s <symbols>: Specify function or classes to load from python source. 
+
+          -y : Don't ask confirmation for loading source above 200 000 characters.
+
+          -n : Include the user's namespace when searching for source code.
+
+        This magic command can either take a local filename, a URL, an history
+        range (see %history) or a macro as argument, it will prompt for
+        confirmation before loading source with more than 200 000 characters, unless
+        -y flag is passed or if the frontend does not support raw_input::
+
+        %load
+        %load myscript.py
+        %load 7-27
+        %load myMacro
+        %load http://www.example.com/myscript.py
+        %load -r 5-10 myscript.py
+        %load -r 10-20,30,40: foo.py
+        %load -s MyClass,wonder_function myscript.py
+        %load -n MyClass
+        %load -n my_module.wonder_function
+        """
+        opts,args = self.parse_options(arg_s,'yns:r:')
+        search_ns = 'n' in opts
+        contents = self.shell.find_user_code(args, search_ns=search_ns)
+
+        if 's' in opts:
+            try:
+                blocks, not_found = extract_symbols(contents, opts['s'])
+            except SyntaxError:
+                # non python code
+                error("Unable to parse the input as valid Python code")
+                return
+
+            if len(not_found) == 1:
+                warn('The symbol `%s` was not found' % not_found[0])
+            elif len(not_found) > 1:
+                warn('The symbols %s were not found' % get_text_list(not_found,
+                                                                     wrap_item_with='`')
+                )
+
+            contents = '\n'.join(blocks)
+
+        if 'r' in opts:
+            ranges = opts['r'].replace(',', ' ')
+            lines = contents.split('\n')
+            slices = extract_code_ranges(ranges)
+            contents = [lines[slice(*slc)] for slc in slices]
+            contents = '\n'.join(strip_initial_indent(chain.from_iterable(contents)))
+
+        l = len(contents)
+
+        # 200 000 is ~ 2500 full 80 character lines
+        # so in average, more than 5000 lines
+        if l > 200000 and 'y' not in opts:
+            try:
+                ans = self.shell.ask_yes_no(("The text you're trying to load seems pretty big"\
+                " (%d characters). Continue (y/[N]) ?" % l), default='n' )
+            except StdinNotImplementedError:
+                #assume yes if raw input not implemented
+                ans = True
+
+            if ans is False :
+                print('Operation cancelled.')
+                return
+
+        contents = "# %load {}\n".format(arg_s) + contents
+
+        self.shell.set_next_input(contents, replace=True)
+
+    @staticmethod
+    def _find_edit_target(shell, args, opts, last_call):
+        """Utility method used by magic_edit to find what to edit."""
+
+        def make_filename(arg):
+            "Make a filename from the given args"
+            try:
+                filename = get_py_filename(arg)
+            except IOError:
+                # If it ends with .py but doesn't already exist, assume we want
+                # a new file.
+                if arg.endswith('.py'):
+                    filename = arg
+                else:
+                    filename = None
+            return filename
+
+        # Set a few locals from the options for convenience:
+        opts_prev = 'p' in opts
+        opts_raw = 'r' in opts
+
+        # custom exceptions
+        class DataIsObject(Exception): pass
+
+        # Default line number value
+        lineno = opts.get('n',None)
+
+        if opts_prev:
+            args = '_%s' % last_call[0]
+            if args not in shell.user_ns:
+                args = last_call[1]
+
+        # by default this is done with temp files, except when the given
+        # arg is a filename
+        use_temp = True
+
+        data = ''
+
+        # First, see if the arguments should be a filename.
+        filename = make_filename(args)
+        if filename:
+            use_temp = False
+        elif args:
+            # Mode where user specifies ranges of lines, like in %macro.
+            data = shell.extract_input_lines(args, opts_raw)
+            if not data:
+                try:
+                    # Load the parameter given as a variable. If not a string,
+                    # process it as an object instead (below)
+
+                    # print('*** args',args,'type',type(args))  # dbg
+                    data = eval(args, shell.user_ns)
+                    if not isinstance(data, str):
+                        raise DataIsObject
+
+                except (NameError,SyntaxError):
+                    # given argument is not a variable, try as a filename
+                    filename = make_filename(args)
+                    if filename is None:
+                        warn("Argument given (%s) can't be found as a variable "
+                             "or as a filename." % args)
+                        return (None, None, None)
+                    use_temp = False
+
+                except DataIsObject as e:
+                    # macros have a special edit function
+                    if isinstance(data, Macro):
+                        raise MacroToEdit(data) from e
+
+                    # For objects, try to edit the file where they are defined
+                    filename = find_file(data)
+                    if filename:
+                        if 'fakemodule' in filename.lower() and \
+                            inspect.isclass(data):
+                            # class created by %edit? Try to find source
+                            # by looking for method definitions instead, the
+                            # __module__ in those classes is FakeModule.
+                            attrs = [getattr(data, aname) for aname in dir(data)]
+                            for attr in attrs:
+                                if not inspect.ismethod(attr):
+                                    continue
+                                filename = find_file(attr)
+                                if filename and \
+                                  'fakemodule' not in filename.lower():
+                                    # change the attribute to be the edit
+                                    # target instead
+                                    data = attr
+                                    break
+                        
+                        m = ipython_input_pat.match(os.path.basename(filename))
+                        if m:
+                            raise InteractivelyDefined(int(m.groups()[0])) from e
+
+                        datafile = 1
+                    if filename is None:
+                        filename = make_filename(args)
+                        datafile = 1
+                        if filename is not None:
+                            # only warn about this if we get a real name
+                            warn('Could not find file where `%s` is defined.\n'
+                             'Opening a file named `%s`' % (args, filename))
+                    # Now, make sure we can actually read the source (if it was
+                    # in a temp file it's gone by now).
+                    if datafile:
+                        if lineno is None:
+                            lineno = find_source_lines(data)
+                        if lineno is None:
+                            filename = make_filename(args)
+                            if filename is None:
+                                warn('The file where `%s` was defined '
+                                     'cannot be read or found.' % data)
+                                return (None, None, None)
+                    use_temp = False
+
+        if use_temp:
+            filename = shell.mktempfile(data)
+            print('IPython will make a temporary file named:',filename)
+
+        # use last_call to remember the state of the previous call, but don't
+        # let it be clobbered by successive '-p' calls.
+        try:
+            last_call[0] = shell.displayhook.prompt_count
+            if not opts_prev:
+                last_call[1] = args
+        except:
+            pass
+
+
+        return filename, lineno, use_temp
+
+    def _edit_macro(self,mname,macro):
+        """open an editor with the macro data in a file"""
+        filename = self.shell.mktempfile(macro.value)
+        self.shell.hooks.editor(filename)
+
+        # and make a new macro object, to replace the old one
+        mvalue = Path(filename).read_text(encoding="utf-8")
+        self.shell.user_ns[mname] = Macro(mvalue)
+
+    @skip_doctest
+    @line_magic
+    def edit(self, parameter_s='',last_call=['','']):
+        """Bring up an editor and execute the resulting code.
+
+        Usage:
+          %edit [options] [args]
+
+        %edit runs IPython's editor hook. The default version of this hook is
+        set to call the editor specified by your $EDITOR environment variable.
+        If this isn't found, it will default to vi under Linux/Unix and to
+        notepad under Windows. See the end of this docstring for how to change
+        the editor hook.
+
+        You can also set the value of this editor via the
+        ``TerminalInteractiveShell.editor`` option in your configuration file.
+        This is useful if you wish to use a different editor from your typical
+        default with IPython (and for Windows users who typically don't set
+        environment variables).
+
+        This command allows you to conveniently edit multi-line code right in
+        your IPython session.
+
+        If called without arguments, %edit opens up an empty editor with a
+        temporary file and will execute the contents of this file when you
+        close it (don't forget to save it!).
+
+
+        Options:
+
+        -n <number>: open the editor at a specified line number.  By default,
+        the IPython editor hook uses the unix syntax 'editor +N filename', but
+        you can configure this by providing your own modified hook if your
+        favorite editor supports line-number specifications with a different
+        syntax.
+
+        -p: this will call the editor with the same data as the previous time
+        it was used, regardless of how long ago (in your current session) it
+        was.
+
+        -r: use 'raw' input.  This option only applies to input taken from the
+        user's history.  By default, the 'processed' history is used, so that
+        magics are loaded in their transformed version to valid Python.  If
+        this option is given, the raw input as typed as the command line is
+        used instead.  When you exit the editor, it will be executed by
+        IPython's own processor.
+
+        -x: do not execute the edited code immediately upon exit. This is
+        mainly useful if you are editing programs which need to be called with
+        command line arguments, which you can then do using %run.
+
+
+        Arguments:
+
+        If arguments are given, the following possibilities exist:
+
+        - If the argument is a filename, IPython will load that into the
+          editor. It will execute its contents with execfile() when you exit,
+          loading any code in the file into your interactive namespace.
+
+        - The arguments are ranges of input history,  e.g. "7 ~1/4-6".
+          The syntax is the same as in the %history magic.
+
+        - If the argument is a string variable, its contents are loaded
+          into the editor. You can thus edit any string which contains
+          python code (including the result of previous edits).
+
+        - If the argument is the name of an object (other than a string),
+          IPython will try to locate the file where it was defined and open the
+          editor at the point where it is defined. You can use `%edit function`
+          to load an editor exactly at the point where 'function' is defined,
+          edit it and have the file be executed automatically.
+
+        - If the object is a macro (see %macro for details), this opens up your
+          specified editor with a temporary file containing the macro's data.
+          Upon exit, the macro is reloaded with the contents of the file.
+
+        Note: opening at an exact line is only supported under Unix, and some
+        editors (like kedit and gedit up to Gnome 2.8) do not understand the
+        '+NUMBER' parameter necessary for this feature. Good editors like
+        (X)Emacs, vi, jed, pico and joe all do.
+
+        After executing your code, %edit will return as output the code you
+        typed in the editor (except when it was an existing file). This way
+        you can reload the code in further invocations of %edit as a variable,
+        via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
+        the output.
+
+        Note that %edit is also available through the alias %ed.
+
+        This is an example of creating a simple function inside the editor and
+        then modifying it. First, start up the editor::
+
+          In [1]: edit
+          Editing... done. Executing edited code...
+          Out[1]: 'def foo():\\n    print("foo() was defined in an editing
+          session")\\n'
+
+        We can then call the function foo()::
+
+          In [2]: foo()
+          foo() was defined in an editing session
+
+        Now we edit foo.  IPython automatically loads the editor with the
+        (temporary) file where foo() was previously defined::
+
+          In [3]: edit foo
+          Editing... done. Executing edited code...
+
+        And if we call foo() again we get the modified version::
+
+          In [4]: foo()
+          foo() has now been changed!
+
+        Here is an example of how to edit a code snippet successive
+        times. First we call the editor::
+
+          In [5]: edit
+          Editing... done. Executing edited code...
+          hello
+          Out[5]: "print('hello')\\n"
+
+        Now we call it again with the previous output (stored in _)::
+
+          In [6]: edit _
+          Editing... done. Executing edited code...
+          hello world
+          Out[6]: "print('hello world')\\n"
+
+        Now we call it with the output #8 (stored in _8, also as Out[8])::
+
+          In [7]: edit _8
+          Editing... done. Executing edited code...
+          hello again
+          Out[7]: "print('hello again')\\n"
+
+
+        Changing the default editor hook:
+
+        If you wish to write your own editor hook, you can put it in a
+        configuration file which you load at startup time.  The default hook
+        is defined in the IPython.core.hooks module, and you can use that as a
+        starting example for further modifications.  That file also has
+        general instructions on how to set a new hook for use once you've
+        defined it."""
+        opts,args = self.parse_options(parameter_s,'prxn:')
+
+        try:
+            filename, lineno, is_temp = self._find_edit_target(self.shell, 
+                                                       args, opts, last_call)
+        except MacroToEdit as e:
+            self._edit_macro(args, e.args[0])
+            return
+        except InteractivelyDefined as e:
+            print("Editing In[%i]" % e.index)
+            args = str(e.index)
+            filename, lineno, is_temp = self._find_edit_target(self.shell, 
+                                                       args, opts, last_call)
+        if filename is None:
+            # nothing was found, warnings have already been issued,
+            # just give up.
+            return
+
+        if is_temp:
+            self._knowntemps.add(filename)
+        elif (filename in self._knowntemps):
+            is_temp = True
+
+
+        # do actual editing here
+        print('Editing...', end=' ')
+        sys.stdout.flush()
+        filepath = Path(filename)
+        try:
+            # Quote filenames that may have spaces in them when opening
+            # the editor
+            quoted = filename = str(filepath.absolute())
+            if " " in quoted:
+                quoted = "'%s'" % quoted
+            self.shell.hooks.editor(quoted, lineno)
+        except TryNext:
+            warn('Could not open editor')
+            return
+
+        # XXX TODO: should this be generalized for all string vars?
+        # For now, this is special-cased to blocks created by cpaste
+        if args.strip() == "pasted_block":
+            self.shell.user_ns["pasted_block"] = filepath.read_text(encoding="utf-8")
+
+        if 'x' in opts:  # -x prevents actual execution
+            print()
+        else:
+            print('done. Executing edited code...')
+            with preserve_keys(self.shell.user_ns, '__file__'):
+                if not is_temp:
+                    self.shell.user_ns["__file__"] = filename
+                if "r" in opts:  # Untranslated IPython code
+                    source = filepath.read_text(encoding="utf-8")
+                    self.shell.run_cell(source, store_history=False)
+                else:
+                    self.shell.safe_execfile(filename, self.shell.user_ns,
+                                             self.shell.user_ns)
+
+        if is_temp:
+            try:
+                return filepath.read_text(encoding="utf-8")
+            except IOError as msg:
+                if Path(msg.filename) == filepath:
+                    warn('File not found. Did you forget to save?')
+                    return
+                else:
+                    self.shell.showtraceback()

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/config.py

@@ -0,0 +1,140 @@
+"""Implementation of configuration-related magic functions.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2012 The 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Stdlib
+import re
+
+# Our own packages
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, magics_class, line_magic
+from logging import error
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+reg = re.compile(r'^\w+\.\w+$')
+@magics_class
+class ConfigMagics(Magics):
+
+    def __init__(self, shell):
+        super(ConfigMagics, self).__init__(shell)
+        self.configurables = []
+
+    @line_magic
+    def config(self, s):
+        """configure IPython
+
+            %config Class[.trait=value]
+
+        This magic exposes most of the IPython config system. Any
+        Configurable class should be able to be configured with the simple
+        line::
+
+            %config Class.trait=value
+
+        Where `value` will be resolved in the user's namespace, if it is an
+        expression or variable name.
+
+        Examples
+        --------
+
+        To see what classes are available for config, pass no arguments::
+
+            In [1]: %config
+            Available objects for config:
+                AliasManager
+                DisplayFormatter
+                HistoryManager
+                IPCompleter
+                LoggingMagics
+                MagicsManager
+                OSMagics
+                PrefilterManager
+                ScriptMagics
+                TerminalInteractiveShell
+
+        To view what is configurable on a given class, just pass the class
+        name::
+
+            In [2]: %config LoggingMagics
+            LoggingMagics(Magics) options
+            ---------------------------
+            LoggingMagics.quiet=<Bool>
+                Suppress output of log state when logging is enabled
+                Current: False
+
+        but the real use is in setting values::
+
+            In [3]: %config LoggingMagics.quiet = True
+
+        and these values are read from the user_ns if they are variables::
+
+            In [4]: feeling_quiet=False
+
+            In [5]: %config LoggingMagics.quiet = feeling_quiet
+
+        """
+        from traitlets.config.loader import Config
+        # some IPython objects are Configurable, but do not yet have
+        # any configurable traits.  Exclude them from the effects of
+        # this magic, as their presence is just noise:
+        configurables = sorted(set([ c for c in self.shell.configurables
+                                     if c.__class__.class_traits(config=True)
+                                     ]), key=lambda x: x.__class__.__name__)
+        classnames = [ c.__class__.__name__ for c in configurables ]
+
+        line = s.strip()
+        if not line:
+            # print available configurable names
+            print("Available objects for config:")
+            for name in classnames:
+                print("   ", name)
+            return
+        elif line in classnames:
+            # `%config TerminalInteractiveShell` will print trait info for
+            # TerminalInteractiveShell
+            c = configurables[classnames.index(line)]
+            cls = c.__class__
+            help = cls.class_get_help(c)
+            # strip leading '--' from cl-args:
+            help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
+            print(help)
+            return
+        elif reg.match(line):
+            cls, attr = line.split('.')
+            return getattr(configurables[classnames.index(cls)],attr)
+        elif '=' not in line:
+            msg = "Invalid config statement: %r, "\
+                  "should be `Class.trait = value`."
+            
+            ll = line.lower()
+            for classname in classnames:
+                if ll == classname.lower():
+                    msg = msg + '\nDid you mean %s (note the case)?' % classname
+                    break
+
+            raise UsageError( msg % line)
+
+        # otherwise, assume we are setting configurables.
+        # leave quotes on args when splitting, because we want
+        # unquoted args to eval in user_ns
+        cfg = Config()
+        exec("cfg."+line, self.shell.user_ns, locals())
+
+        for configurable in configurables:
+            try:
+                configurable.update_config(cfg)
+            except Exception as e:
+                error(e)

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/display.py

@@ -0,0 +1,93 @@
+"""Simple magics for display formats"""
+#-----------------------------------------------------------------------------
+#  Copyright (c) 2012 The 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.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Our own packages
+from IPython.display import display, Javascript, Latex, SVG, HTML, Markdown
+from IPython.core.magic import  (
+    Magics, magics_class, cell_magic
+)
+from IPython.core import magic_arguments
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+
+@magics_class
+class DisplayMagics(Magics):
+    """Magics for displaying various output types with literals
+
+    Defines javascript/latex/svg/html cell magics for writing
+    blocks in those languages, to be rendered in the frontend.
+    """
+
+    @cell_magic
+    def js(self, line, cell):
+        """Run the cell block of Javascript code
+
+        Alias of `%%javascript`
+
+        Starting with IPython 8.0 %%javascript is pending deprecation to be replaced
+        by a more flexible system
+
+        Please See https://github.com/ipython/ipython/issues/13376
+        """
+        self.javascript(line, cell)
+
+    @cell_magic
+    def javascript(self, line, cell):
+        """Run the cell block of Javascript code
+
+        Starting with IPython 8.0 %%javascript is pending deprecation to be replaced
+        by a more flexible system
+
+        Please See https://github.com/ipython/ipython/issues/13376
+        """
+        display(Javascript(cell))
+
+
+    @cell_magic
+    def latex(self, line, cell):
+        """Render the cell as a block of LaTeX
+
+        The subset of LaTeX which is supported depends on the implementation in
+        the client.  In the Jupyter Notebook, this magic only renders the subset
+        of LaTeX defined by MathJax
+        [here](https://docs.mathjax.org/en/v2.5-latest/tex.html)."""
+        display(Latex(cell))
+
+    @cell_magic
+    def svg(self, line, cell):
+        """Render the cell as an SVG literal"""
+        display(SVG(cell))
+
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument(
+        '--isolated', action='store_true', default=False,
+        help="""Annotate the cell as 'isolated'.
+Isolated cells are rendered inside their own <iframe> tag"""
+    )
+    @cell_magic
+    def html(self, line, cell):
+        """Render the cell as a block of HTML"""
+        args = magic_arguments.parse_argstring(self.html, line)
+        html = HTML(cell)
+        if args.isolated:
+            display(html, metadata={'text/html':{'isolated':True}})
+        else:
+            display(html)
+
+    @cell_magic
+    def markdown(self, line, cell):
+        """Render the cell as Markdown text block"""
+        display(Markdown(cell))

openalex_env_map/lib/python3.10/site-packages/IPython/core/magics/execution.py

@@ -0,0 +1,1624 @@
+# -*- coding: utf-8 -*-
+"""Implementation of execution-related magic functions."""
+
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+
+import ast
+import bdb
+import builtins as builtin_mod
+import copy
+import cProfile as profile
+import gc
+import itertools
+import math
+import os
+import pstats
+import re
+import shlex
+import sys
+import time
+import timeit
+from typing import Dict, Any
+from ast import (
+    Assign,
+    Call,
+    Expr,
+    Load,
+    Module,
+    Name,
+    NodeTransformer,
+    Store,
+    parse,
+    unparse,
+)
+from io import StringIO
+from logging import error
+from pathlib import Path
+from pdb import Restart
+from textwrap import dedent, indent
+from warnings import warn
+
+from IPython.core import magic_arguments, oinspect, page
+from IPython.core.displayhook import DisplayHook
+from IPython.core.error import UsageError
+from IPython.core.macro import Macro
+from IPython.core.magic import (
+    Magics,
+    cell_magic,
+    line_cell_magic,
+    line_magic,
+    magics_class,
+    needs_local_scope,
+    no_var_expand,
+    on_off,
+    output_can_be_silenced,
+)
+from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.capture import capture_output
+from IPython.utils.contexts import preserve_keys
+from IPython.utils.ipstruct import Struct
+from IPython.utils.module_paths import find_mod
+from IPython.utils.path import get_py_filename, shellglob
+from IPython.utils.timing import clock, clock2
+from IPython.core.magics.ast_mod import ReplaceCodeTransformer
+
+#-----------------------------------------------------------------------------
+# Magic implementation classes
+#-----------------------------------------------------------------------------
+
+
+class TimeitResult(object):
+    """
+    Object returned by the timeit magic with info about the run.
+
+    Contains the following attributes :
+
+    loops: (int) number of loops done per measurement
+    repeat: (int) number of times the measurement has been repeated
+    best: (float) best execution time / number
+    all_runs: (list of float) execution time of each run (in s)
+    compile_time: (float) time of statement compilation (s)
+
+    """
+    def __init__(self, loops, repeat, best, worst, all_runs, compile_time, precision):
+        self.loops = loops
+        self.repeat = repeat
+        self.best = best
+        self.worst = worst
+        self.all_runs = all_runs
+        self.compile_time = compile_time
+        self._precision = precision
+        self.timings = [ dt / self.loops for dt in all_runs]
+
+    @property
+    def average(self):
+        return math.fsum(self.timings) / len(self.timings)
+
+    @property
+    def stdev(self):
+        mean = self.average
+        return (math.fsum([(x - mean) ** 2 for x in self.timings]) / len(self.timings)) ** 0.5
+
+    def __str__(self):
+        pm = '+-'
+        if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
+            try:
+                u'\xb1'.encode(sys.stdout.encoding)
+                pm = u'\xb1'
+            except:
+                pass
+        return "{mean} {pm} {std} per loop (mean {pm} std. dev. of {runs} run{run_plural}, {loops:,} loop{loop_plural} each)".format(
+            pm=pm,
+            runs=self.repeat,
+            loops=self.loops,
+            loop_plural="" if self.loops == 1 else "s",
+            run_plural="" if self.repeat == 1 else "s",
+            mean=_format_time(self.average, self._precision),
+            std=_format_time(self.stdev, self._precision),
+        )
+
+    def _repr_pretty_(self, p , cycle):
+        unic = self.__str__()
+        p.text(u'<TimeitResult : '+unic+u'>')
+
+
+class TimeitTemplateFiller(ast.NodeTransformer):
+    """Fill in the AST template for timing execution.
+
+    This is quite closely tied to the template definition, which is in
+    :meth:`ExecutionMagics.timeit`.
+    """
+    def __init__(self, ast_setup, ast_stmt):
+        self.ast_setup = ast_setup
+        self.ast_stmt = ast_stmt
+
+    def visit_FunctionDef(self, node):
+        "Fill in the setup statement"
+        self.generic_visit(node)
+        if node.name == "inner":
+            node.body[:1] = self.ast_setup.body
+
+        return node
+
+    def visit_For(self, node):
+        "Fill in the statement to be timed"
+        if getattr(getattr(node.body[0], 'value', None), 'id', None) == 'stmt':
+            node.body = self.ast_stmt.body
+        return node
+
+
+class Timer(timeit.Timer):
+    """Timer class that explicitly uses self.inner
+    
+    which is an undocumented implementation detail of CPython,
+    not shared by PyPy.
+    """
+    # Timer.timeit copied from CPython 3.4.2
+    def timeit(self, number=timeit.default_number):
+        """Time 'number' executions of the main statement.
+
+        To be precise, this executes the setup statement once, and
+        then returns the time it takes to execute the main statement
+        a number of times, as a float measured in seconds.  The
+        argument is the number of times through the loop, defaulting
+        to one million.  The main statement, the setup statement and
+        the timer function to be used are passed to the constructor.
+        """
+        it = itertools.repeat(None, number)
+        gcold = gc.isenabled()
+        gc.disable()
+        try:
+            timing = self.inner(it, self.timer)
+        finally:
+            if gcold:
+                gc.enable()
+        return timing
+
+
+@magics_class
+class ExecutionMagics(Magics):
+    """Magics related to code execution, debugging, profiling, etc."""
+
+    _transformers: Dict[str, Any] = {}
+
+    def __init__(self, shell):
+        super(ExecutionMagics, self).__init__(shell)
+        # Default execution function used to actually run user code.
+        self.default_runner = None
+
+    @skip_doctest
+    @no_var_expand
+    @line_cell_magic
+    def prun(self, parameter_s='', cell=None):
+
+        """Run a statement through the python code profiler.
+
+        **Usage, in line mode:**
+
+          %prun [options] statement
+
+        **Usage, in cell mode:**
+
+          %%prun [options] [statement]
+
+          code...
+
+          code...
+
+        In cell mode, the additional code lines are appended to the (possibly
+        empty) statement in the first line.  Cell mode allows you to easily
+        profile multiline blocks without having to put them in a separate
+        function.
+
+        The given statement (which doesn't require quote marks) is run via the
+        python profiler in a manner similar to the profile.run() function.
+        Namespaces are internally managed to work correctly; profile.run
+        cannot be used in IPython because it makes certain assumptions about
+        namespaces which do not hold under IPython.
+
+        Options:
+
+        -l <limit>
+          you can place restrictions on what or how much of the
+          profile gets printed. The limit value can be:
+
+             * A string: only information for function names containing this string
+               is printed.
+
+             * An integer: only these many lines are printed.
+
+             * A float (between 0 and 1): this fraction of the report is printed
+               (for example, use a limit of 0.4 to see the topmost 40% only).
+
+          You can combine several limits with repeated use of the option. For
+          example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
+          information about class constructors.
+
+        -r
+          return the pstats.Stats object generated by the profiling. This
+          object has all the information about the profile in it, and you can
+          later use it for further analysis or in other functions.
+
+        -s <key>
+          sort profile by given key. You can provide more than one key
+          by using the option several times: '-s key1 -s key2 -s key3...'. The
+          default sorting key is 'time'.
+
+          The following is copied verbatim from the profile documentation
+          referenced below:
+
+          When more than one key is provided, additional keys are used as
+          secondary criteria when the there is equality in all keys selected
+          before them.
+
+          Abbreviations can be used for any key names, as long as the
+          abbreviation is unambiguous.  The following are the keys currently
+          defined:
+
+          ============  =====================
+          Valid Arg     Meaning
+          ============  =====================
+          "calls"       call count
+          "cumulative"  cumulative time
+          "file"        file name
+          "module"      file name
+          "pcalls"      primitive call count
+          "line"        line number
+          "name"        function name
+          "nfl"         name/file/line
+          "stdname"     standard name
+          "time"        internal time
+          ============  =====================
+
+          Note that all sorts on statistics are in descending order (placing
+          most time consuming items first), where as name, file, and line number
+          searches are in ascending order (i.e., alphabetical). The subtle
+          distinction between "nfl" and "stdname" is that the standard name is a
+          sort of the name as printed, which means that the embedded line
+          numbers get compared in an odd way.  For example, lines 3, 20, and 40
+          would (if the file names were the same) appear in the string order
+          "20" "3" and "40".  In contrast, "nfl" does a numeric compare of the
+          line numbers.  In fact, sort_stats("nfl") is the same as
+          sort_stats("name", "file", "line").
+
+        -T <filename>
+          save profile results as shown on screen to a text
+          file. The profile is still shown on screen.
+
+        -D <filename>
+          save (via dump_stats) profile statistics to given
+          filename. This data is in a format understood by the pstats module, and
+          is generated by a call to the dump_stats() method of profile
+          objects. The profile is still shown on screen.
+
+        -q
+          suppress output to the pager.  Best used with -T and/or -D above.
+
+        If you want to run complete programs under the profiler's control, use
+        ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
+        contains profiler specific options as described here.
+
+        You can read the complete documentation for the profile module with::
+
+          In [1]: import profile; profile.help()
+
+        .. versionchanged:: 7.3
+            User variables are no longer expanded,
+            the magic line is always left unmodified.
+
+        """
+        opts, arg_str = self.parse_options(parameter_s, 'D:l:rs:T:q',
+                                           list_all=True, posix=False)
+        if cell is not None:
+            arg_str += '\n' + cell
+        arg_str = self.shell.transform_cell(arg_str)
+        return self._run_with_profiler(arg_str, opts, self.shell.user_ns)
+
+    def _run_with_profiler(self, code, opts, namespace):
+        """
+        Run `code` with profiler.  Used by ``%prun`` and ``%run -p``.
+
+        Parameters
+        ----------
+        code : str
+            Code to be executed.
+        opts : Struct
+            Options parsed by `self.parse_options`.
+        namespace : dict
+            A dictionary for Python namespace (e.g., `self.shell.user_ns`).
+
+        """
+
+        # Fill default values for unspecified options:
+        opts.merge(Struct(D=[''], l=[], s=['time'], T=['']))
+
+        prof = profile.Profile()
+        try:
+            prof = prof.runctx(code, namespace, namespace)
+            sys_exit = ''
+        except SystemExit:
+            sys_exit = """*** SystemExit exception caught in code being profiled."""
+
+        stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
+
+        lims = opts.l
+        if lims:
+            lims = []  # rebuild lims with ints/floats/strings
+            for lim in opts.l:
+                try:
+                    lims.append(int(lim))
+                except ValueError:
+                    try:
+                        lims.append(float(lim))
+                    except ValueError:
+                        lims.append(lim)
+
+        # Trap output.
+        stdout_trap = StringIO()
+        stats_stream = stats.stream
+        try:
+            stats.stream = stdout_trap
+            stats.print_stats(*lims)
+        finally:
+            stats.stream = stats_stream
+
+        output = stdout_trap.getvalue()
+        output = output.rstrip()
+
+        if 'q' not in opts:
+            page.page(output)
+        print(sys_exit, end=' ')
+
+        dump_file = opts.D[0]
+        text_file = opts.T[0]
+        if dump_file:
+            prof.dump_stats(dump_file)
+            print(
+                f"\n*** Profile stats marshalled to file {repr(dump_file)}.{sys_exit}"
+            )
+        if text_file:
+            pfile = Path(text_file)
+            pfile.touch(exist_ok=True)
+            pfile.write_text(output, encoding="utf-8")
+
+            print(
+                f"\n*** Profile printout saved to text file {repr(text_file)}.{sys_exit}"
+            )
+
+        if 'r' in opts:
+            return stats
+
+        return None
+
+    @line_magic
+    def pdb(self, parameter_s=''):
+        """Control the automatic calling of the pdb interactive debugger.
+
+        Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
+        argument it works as a toggle.
+
+        When an exception is triggered, IPython can optionally call the
+        interactive pdb debugger after the traceback printout. %pdb toggles
+        this feature on and off.
+
+        The initial state of this feature is set in your configuration
+        file (the option is ``InteractiveShell.pdb``).
+
+        If you want to just activate the debugger AFTER an exception has fired,
+        without having to type '%pdb on' and rerunning your code, you can use
+        the %debug magic."""
+
+        par = parameter_s.strip().lower()
+
+        if par:
+            try:
+                new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
+            except KeyError:
+                print ('Incorrect argument. Use on/1, off/0, '
+                       'or nothing for a toggle.')
+                return
+        else:
+            # toggle
+            new_pdb = not self.shell.call_pdb
+
+        # set on the shell
+        self.shell.call_pdb = new_pdb
+        print('Automatic pdb calling has been turned',on_off(new_pdb))
+
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument('--breakpoint', '-b', metavar='FILE:LINE',
+        help="""
+        Set break point at LINE in FILE.
+        """
+    )
+    @magic_arguments.argument('statement', nargs='*',
+        help="""
+        Code to run in debugger.
+        You can omit this in cell magic mode.
+        """
+    )
+    @no_var_expand
+    @line_cell_magic
+    @needs_local_scope
+    def debug(self, line="", cell=None, local_ns=None):
+        """Activate the interactive debugger.
+
+        This magic command support two ways of activating debugger.
+        One is to activate debugger before executing code.  This way, you
+        can set a break point, to step through the code from the point.
+        You can use this mode by giving statements to execute and optionally
+        a breakpoint.
+
+        The other one is to activate debugger in post-mortem mode.  You can
+        activate this mode simply running %debug without any argument.
+        If an exception has just occurred, this lets you inspect its stack
+        frames interactively.  Note that this will always work only on the last
+        traceback that occurred, so you must call this quickly after an
+        exception that you wish to inspect has fired, because if another one
+        occurs, it clobbers the previous one.
+
+        If you want IPython to automatically do this on every exception, see
+        the %pdb magic for more details.
+
+        .. versionchanged:: 7.3
+            When running code, user variables are no longer expanded,
+            the magic line is always left unmodified.
+
+        """
+        args = magic_arguments.parse_argstring(self.debug, line)
+
+        if not (args.breakpoint or args.statement or cell):
+            self._debug_post_mortem()
+        elif not (args.breakpoint or cell):
+            # If there is no breakpoints, the line is just code to execute
+            self._debug_exec(line, None, local_ns)
+        else:
+            # Here we try to reconstruct the code from the output of
+            # parse_argstring. This might not work if the code has spaces
+            # For example this fails for `print("a b")`
+            code = "\n".join(args.statement)
+            if cell:
+                code += "\n" + cell
+            self._debug_exec(code, args.breakpoint, local_ns)
+
+    def _debug_post_mortem(self):
+        self.shell.debugger(force=True)
+
+    def _debug_exec(self, code, breakpoint, local_ns=None):
+        if breakpoint:
+            (filename, bp_line) = breakpoint.rsplit(':', 1)
+            bp_line = int(bp_line)
+        else:
+            (filename, bp_line) = (None, None)
+        self._run_with_debugger(
+            code, self.shell.user_ns, filename, bp_line, local_ns=local_ns
+        )
+
+    @line_magic
+    def tb(self, s):
+        """Print the last traceback.
+
+        Optionally, specify an exception reporting mode, tuning the
+        verbosity of the traceback. By default the currently-active exception
+        mode is used. See %xmode for changing exception reporting modes.
+
+        Valid modes: Plain, Context, Verbose, and Minimal.
+        """
+        interactive_tb = self.shell.InteractiveTB
+        if s:
+            # Switch exception reporting mode for this one call.
+            # Ensure it is switched back.
+            def xmode_switch_err(name):
+                warn('Error changing %s exception modes.\n%s' %
+                    (name,sys.exc_info()[1]))
+
+            new_mode = s.strip().capitalize()
+            original_mode = interactive_tb.mode
+            try:
+                try:
+                    interactive_tb.set_mode(mode=new_mode)
+                except Exception:
+                    xmode_switch_err('user')
+                else:
+                    self.shell.showtraceback()
+            finally:
+                interactive_tb.set_mode(mode=original_mode)
+        else:
+            self.shell.showtraceback()
+
+    @skip_doctest
+    @line_magic
+    def run(self, parameter_s='', runner=None,
+                  file_finder=get_py_filename):
+        """Run the named file inside IPython as a program.
+
+        Usage::
+
+          %run [-n -i -e -G]
+               [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
+               ( -m mod | filename ) [args]
+
+        The filename argument should be either a pure Python script (with
+        extension ``.py``), or a file with custom IPython syntax (such as
+        magics). If the latter, the file can be either a script with ``.ipy``
+        extension, or a Jupyter notebook with ``.ipynb`` extension. When running
+        a Jupyter notebook, the output from print statements and other
+        displayed objects will appear in the terminal (even matplotlib figures
+        will open, if a terminal-compliant backend is being used). Note that,
+        at the system command line, the ``jupyter run`` command offers similar
+        functionality for executing notebooks (albeit currently with some
+        differences in supported options).
+
+        Parameters after the filename are passed as command-line arguments to
+        the program (put in sys.argv). Then, control returns to IPython's
+        prompt.
+
+        This is similar to running at a system prompt ``python file args``,
+        but with the advantage of giving you IPython's tracebacks, and of
+        loading all variables into your interactive namespace for further use
+        (unless -p is used, see below).
+
+        The file is executed in a namespace initially consisting only of
+        ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
+        sees its environment as if it were being run as a stand-alone program
+        (except for sharing global objects such as previously imported
+        modules). But after execution, the IPython interactive namespace gets
+        updated with all variables defined in the program (except for __name__
+        and sys.argv). This allows for very convenient loading of code for
+        interactive work, while giving each program a 'clean sheet' to run in.
+
+        Arguments are expanded using shell-like glob match.  Patterns
+        '*', '?', '[seq]' and '[!seq]' can be used.  Additionally,
+        tilde '~' will be expanded into user's home directory.  Unlike
+        real shells, quotation does not suppress expansions.  Use
+        *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
+        To completely disable these expansions, you can use -G flag.
+
+        On Windows systems, the use of single quotes `'` when specifying
+        a file is not supported. Use double quotes `"`.
+
+        Options:
+
+        -n
+          __name__ is NOT set to '__main__', but to the running file's name
+          without extension (as python does under import).  This allows running
+          scripts and reloading the definitions in them without calling code
+          protected by an ``if __name__ == "__main__"`` clause.
+
+        -i
+          run the file in IPython's namespace instead of an empty one. This
+          is useful if you are experimenting with code written in a text editor
+          which depends on variables defined interactively.
+
+        -e
+          ignore sys.exit() calls or SystemExit exceptions in the script
+          being run.  This is particularly useful if IPython is being used to
+          run unittests, which always exit with a sys.exit() call.  In such
+          cases you are interested in the output of the test results, not in
+          seeing a traceback of the unittest module.
+
+        -t
+          print timing information at the end of the run.  IPython will give
+          you an estimated CPU time consumption for your script, which under
+          Unix uses the resource module to avoid the wraparound problems of
+          time.clock().  Under Unix, an estimate of time spent on system tasks
+          is also given (for Windows platforms this is reported as 0.0).
+
+        If -t is given, an additional ``-N<N>`` option can be given, where <N>
+        must be an integer indicating how many times you want the script to
+        run.  The final timing report will include total and per run results.
+
+        For example (testing the script uniq_stable.py)::
+
+            In [1]: run -t uniq_stable
+
+            IPython CPU timings (estimated):
+              User  :    0.19597 s.
+              System:        0.0 s.
+
+            In [2]: run -t -N5 uniq_stable
+
+            IPython CPU timings (estimated):
+            Total runs performed: 5
+              Times :      Total       Per run
+              User  :   0.910862 s,  0.1821724 s.
+              System:        0.0 s,        0.0 s.
+
+        -d
+          run your program under the control of pdb, the Python debugger.
+          This allows you to execute your program step by step, watch variables,
+          etc.  Internally, what IPython does is similar to calling::
+
+              pdb.run('execfile("YOURFILENAME")')
+
+          with a breakpoint set on line 1 of your file.  You can change the line
+          number for this automatic breakpoint to be <N> by using the -bN option
+          (where N must be an integer). For example::
+
+              %run -d -b40 myscript
+
+          will set the first breakpoint at line 40 in myscript.py.  Note that
+          the first breakpoint must be set on a line which actually does
+          something (not a comment or docstring) for it to stop execution.
+
+          Or you can specify a breakpoint in a different file::
+
+              %run -d -b myotherfile.py:20 myscript
+
+          When the pdb debugger starts, you will see a (Pdb) prompt.  You must
+          first enter 'c' (without quotes) to start execution up to the first
+          breakpoint.
+
+          Entering 'help' gives information about the use of the debugger.  You
+          can easily see pdb's full documentation with "import pdb;pdb.help()"
+          at a prompt.
+
+        -p
+          run program under the control of the Python profiler module (which
+          prints a detailed report of execution times, function calls, etc).
+
+          You can pass other options after -p which affect the behavior of the
+          profiler itself. See the docs for %prun for details.
+
+          In this mode, the program's variables do NOT propagate back to the
+          IPython interactive namespace (because they remain in the namespace
+          where the profiler executes them).
+
+          Internally this triggers a call to %prun, see its documentation for
+          details on the options available specifically for profiling.
+
+        There is one special usage for which the text above doesn't apply:
+        if the filename ends with .ipy[nb], the file is run as ipython script,
+        just as if the commands were written on IPython prompt.
+
+        -m
+          specify module name to load instead of script path. Similar to
+          the -m option for the python interpreter. Use this option last if you
+          want to combine with other %run options. Unlike the python interpreter
+          only source modules are allowed no .pyc or .pyo files.
+          For example::
+
+              %run -m example
+
+          will run the example module.
+
+        -G
+          disable shell-like glob expansion of arguments.
+
+        """
+
+        # Logic to handle issue #3664
+        # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
+        if '-m' in parameter_s and '--' not in parameter_s:
+            argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
+            for idx, arg in enumerate(argv):
+                if arg and arg.startswith('-') and arg != '-':
+                    if arg == '-m':
+                        argv.insert(idx + 2, '--')
+                        break
+                else:
+                    # Positional arg, break
+                    break
+            parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
+
+        # get arguments and set sys.argv for program to be run.
+        opts, arg_lst = self.parse_options(parameter_s,
+                                           'nidtN:b:pD:l:rs:T:em:G',
+                                           mode='list', list_all=1)
+        if "m" in opts:
+            modulename = opts["m"][0]
+            modpath = find_mod(modulename)
+            if modpath is None:
+                msg = '%r is not a valid modulename on sys.path'%modulename
+                raise Exception(msg)
+            arg_lst = [modpath] + arg_lst
+        try:
+            fpath = None # initialize to make sure fpath is in scope later
+            fpath = arg_lst[0]
+            filename = file_finder(fpath)
+        except IndexError as e:
+            msg = 'you must provide at least a filename.'
+            raise Exception(msg) from e
+        except IOError as e:
+            try:
+                msg = str(e)
+            except UnicodeError:
+                msg = e.message
+            if os.name == 'nt' and re.match(r"^'.*'$",fpath):
+                warn('For Windows, use double quotes to wrap a filename: %run "mypath\\myfile.py"')
+            raise Exception(msg) from e
+        except TypeError:
+            if fpath in sys.meta_path:
+                filename = ""
+            else:
+                raise
+
+        if filename.lower().endswith(('.ipy', '.ipynb')):
+            with preserve_keys(self.shell.user_ns, '__file__'):
+                self.shell.user_ns['__file__'] = filename
+                self.shell.safe_execfile_ipy(filename, raise_exceptions=True)
+            return
+
+        # Control the response to exit() calls made by the script being run
+        exit_ignore = 'e' in opts
+
+        # Make sure that the running script gets a proper sys.argv as if it
+        # were run from a system shell.
+        save_argv = sys.argv # save it for later restoring
+
+        if 'G' in opts:
+            args = arg_lst[1:]
+        else:
+            # tilde and glob expansion
+            args = shellglob(map(os.path.expanduser,  arg_lst[1:]))
+
+        sys.argv = [filename] + args  # put in the proper filename
+
+        if 'n' in opts:
+            name = Path(filename).stem
+        else:
+            name = '__main__'
+
+        if 'i' in opts:
+            # Run in user's interactive namespace
+            prog_ns = self.shell.user_ns
+            __name__save = self.shell.user_ns['__name__']
+            prog_ns['__name__'] = name
+            main_mod = self.shell.user_module
+
+            # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
+            # set the __file__ global in the script's namespace
+            # TK: Is this necessary in interactive mode?
+            prog_ns['__file__'] = filename
+        else:
+            # Run in a fresh, empty namespace
+
+            # The shell MUST hold a reference to prog_ns so after %run
+            # exits, the python deletion mechanism doesn't zero it out
+            # (leaving dangling references). See interactiveshell for details
+            main_mod = self.shell.new_main_mod(filename, name)
+            prog_ns = main_mod.__dict__
+
+        # pickle fix.  See interactiveshell for an explanation.  But we need to
+        # make sure that, if we overwrite __main__, we replace it at the end
+        main_mod_name = prog_ns['__name__']
+
+        if main_mod_name == '__main__':
+            restore_main = sys.modules['__main__']
+        else:
+            restore_main = False
+
+        # This needs to be undone at the end to prevent holding references to
+        # every single object ever created.
+        sys.modules[main_mod_name] = main_mod
+
+        if 'p' in opts or 'd' in opts:
+            if 'm' in opts:
+                code = 'run_module(modulename, prog_ns)'
+                code_ns = {
+                    'run_module': self.shell.safe_run_module,
+                    'prog_ns': prog_ns,
+                    'modulename': modulename,
+                }
+            else:
+                if 'd' in opts:
+                    # allow exceptions to raise in debug mode
+                    code = 'execfile(filename, prog_ns, raise_exceptions=True)'
+                else:
+                    code = 'execfile(filename, prog_ns)'
+                code_ns = {
+                    'execfile': self.shell.safe_execfile,
+                    'prog_ns': prog_ns,
+                    'filename': get_py_filename(filename),
+                }
+
+        try:
+            stats = None
+            if 'p' in opts:
+                stats = self._run_with_profiler(code, opts, code_ns)
+            else:
+                if 'd' in opts:
+                    bp_file, bp_line = parse_breakpoint(
+                        opts.get('b', ['1'])[0], filename)
+                    self._run_with_debugger(
+                        code, code_ns, filename, bp_line, bp_file)
+                else:
+                    if 'm' in opts:
+                        def run():
+                            self.shell.safe_run_module(modulename, prog_ns)
+                    else:
+                        if runner is None:
+                            runner = self.default_runner
+                        if runner is None:
+                            runner = self.shell.safe_execfile
+
+                        def run():
+                            runner(filename, prog_ns, prog_ns,
+                                    exit_ignore=exit_ignore)
+
+                    if 't' in opts:
+                        # timed execution
+                        try:
+                            nruns = int(opts['N'][0])
+                            if nruns < 1:
+                                error('Number of runs must be >=1')
+                                return
+                        except (KeyError):
+                            nruns = 1
+                        self._run_with_timing(run, nruns)
+                    else:
+                        # regular execution
+                        run()
+
+            if 'i' in opts:
+                self.shell.user_ns['__name__'] = __name__save
+            else:
+                # update IPython interactive namespace
+
+                # Some forms of read errors on the file may mean the
+                # __name__ key was never set; using pop we don't have to
+                # worry about a possible KeyError.
+                prog_ns.pop('__name__', None)
+
+                with preserve_keys(self.shell.user_ns, '__file__'):
+                    self.shell.user_ns.update(prog_ns)
+        finally:
+            # It's a bit of a mystery why, but __builtins__ can change from
+            # being a module to becoming a dict missing some key data after
+            # %run.  As best I can see, this is NOT something IPython is doing
+            # at all, and similar problems have been reported before:
+            # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
+            # Since this seems to be done by the interpreter itself, the best
+            # we can do is to at least restore __builtins__ for the user on
+            # exit.
+            self.shell.user_ns['__builtins__'] = builtin_mod
+
+            # Ensure key global structures are restored
+            sys.argv = save_argv
+            if restore_main:
+                sys.modules['__main__'] = restore_main
+                if '__mp_main__' in sys.modules:
+                    sys.modules['__mp_main__'] = restore_main
+            else:
+                # Remove from sys.modules the reference to main_mod we'd
+                # added.  Otherwise it will trap references to objects
+                # contained therein.
+                del sys.modules[main_mod_name]
+
+        return stats
+
+    def _run_with_debugger(
+        self, code, code_ns, filename=None, bp_line=None, bp_file=None, local_ns=None
+    ):
+        """
+        Run `code` in debugger with a break point.
+
+        Parameters
+        ----------
+        code : str
+            Code to execute.
+        code_ns : dict
+            A namespace in which `code` is executed.
+        filename : str
+            `code` is ran as if it is in `filename`.
+        bp_line : int, optional
+            Line number of the break point.
+        bp_file : str, optional
+            Path to the file in which break point is specified.
+            `filename` is used if not given.
+        local_ns : dict, optional
+            A local namespace in which `code` is executed.
+
+        Raises
+        ------
+        UsageError
+            If the break point given by `bp_line` is not valid.
+
+        """
+        deb = self.shell.InteractiveTB.pdb
+        if not deb:
+            self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
+            deb = self.shell.InteractiveTB.pdb
+
+        # deb.checkline() fails if deb.curframe exists but is None; it can
+        # handle it not existing. https://github.com/ipython/ipython/issues/10028
+        if hasattr(deb, 'curframe'):
+            del deb.curframe
+
+        # reset Breakpoint state, which is moronically kept
+        # in a class
+        bdb.Breakpoint.next = 1
+        bdb.Breakpoint.bplist = {}
+        bdb.Breakpoint.bpbynumber = [None]
+        deb.clear_all_breaks()
+        if bp_line is not None:
+            # Set an initial breakpoint to stop execution
+            maxtries = 10
+            bp_file = bp_file or filename
+            checkline = deb.checkline(bp_file, bp_line)
+            if not checkline:
+                for bp in range(bp_line + 1, bp_line + maxtries + 1):
+                    if deb.checkline(bp_file, bp):
+                        break
+                else:
+                    msg = ("\nI failed to find a valid line to set "
+                           "a breakpoint\n"
+                           "after trying up to line: %s.\n"
+                           "Please set a valid breakpoint manually "
+                           "with the -b option." % bp)
+                    raise UsageError(msg)
+            # if we find a good linenumber, set the breakpoint
+            deb.do_break('%s:%s' % (bp_file, bp_line))
+
+        if filename:
+            # Mimic Pdb._runscript(...)
+            deb._wait_for_mainpyfile = True
+            deb.mainpyfile = deb.canonic(filename)
+
+        # Start file run
+        print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
+        try:
+            if filename:
+                # save filename so it can be used by methods on the deb object
+                deb._exec_filename = filename
+            while True:
+                try:
+                    trace = sys.gettrace()
+                    deb.run(code, code_ns, local_ns)
+                except Restart:
+                    print("Restarting")
+                    if filename:
+                        deb._wait_for_mainpyfile = True
+                        deb.mainpyfile = deb.canonic(filename)
+                    continue
+                else:
+                    break
+                finally:
+                    sys.settrace(trace)
+            
+
+        except:
+            etype, value, tb = sys.exc_info()
+            # Skip three frames in the traceback: the %run one,
+            # one inside bdb.py, and the command-line typed by the
+            # user (run by exec in pdb itself).
+            self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
+
+    @staticmethod
+    def _run_with_timing(run, nruns):
+        """
+        Run function `run` and print timing information.
+
+        Parameters
+        ----------
+        run : callable
+            Any callable object which takes no argument.
+        nruns : int
+            Number of times to execute `run`.
+
+        """
+        twall0 = time.perf_counter()
+        if nruns == 1:
+            t0 = clock2()
+            run()
+            t1 = clock2()
+            t_usr = t1[0] - t0[0]
+            t_sys = t1[1] - t0[1]
+            print("\nIPython CPU timings (estimated):")
+            print("  User   : %10.2f s." % t_usr)
+            print("  System : %10.2f s." % t_sys)
+        else:
+            runs = range(nruns)
+            t0 = clock2()
+            for nr in runs:
+                run()
+            t1 = clock2()
+            t_usr = t1[0] - t0[0]
+            t_sys = t1[1] - t0[1]
+            print("\nIPython CPU timings (estimated):")
+            print("Total runs performed:", nruns)
+            print("  Times  : %10s   %10s" % ('Total', 'Per run'))
+            print("  User   : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
+            print("  System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
+        twall1 = time.perf_counter()
+        print("Wall time: %10.2f s." % (twall1 - twall0))
+
+    @skip_doctest
+    @no_var_expand
+    @line_cell_magic
+    @needs_local_scope
+    def timeit(self, line='', cell=None, local_ns=None):
+        """Time execution of a Python statement or expression
+
+        **Usage, in line mode:**
+
+          %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
+
+        **or in cell mode:**
+
+          %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
+
+          code
+
+          code...
+
+        Time execution of a Python statement or expression using the timeit
+        module.  This function can be used both as a line and cell magic:
+
+        - In line mode you can time a single-line statement (though multiple
+          ones can be chained with using semicolons).
+
+        - In cell mode, the statement in the first line is used as setup code
+          (executed but not timed) and the body of the cell is timed.  The cell
+          body has access to any variables created in the setup code.
+
+        Options:
+
+        -n<N>: execute the given statement <N> times in a loop. If <N> is not
+        provided, <N> is determined so as to get sufficient accuracy.
+
+        -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
+        average result.
+        Default: 7
+
+        -t: use time.time to measure the time, which is the default on Unix.
+        This function measures wall time.
+
+        -c: use time.clock to measure the time, which is the default on
+        Windows and measures wall time. On Unix, resource.getrusage is used
+        instead and returns the CPU user time.
+
+        -p<P>: use a precision of <P> digits to display the timing result.
+        Default: 3
+
+        -q: Quiet, do not print result.
+
+        -o: return a TimeitResult that can be stored in a variable to inspect
+        the result in more details.
+
+        .. versionchanged:: 7.3
+            User variables are no longer expanded,
+            the magic line is always left unmodified.
+
+        Examples
+        --------
+        ::
+
+          In [1]: %timeit pass
+          8.26 ns ± 0.12 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
+
+          In [2]: u = None
+
+          In [3]: %timeit u is None
+          29.9 ns ± 0.643 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
+
+          In [4]: %timeit -r 4 u == None
+
+          In [5]: import time
+
+          In [6]: %timeit -n1 time.sleep(2)
+
+        The times reported by %timeit will be slightly higher than those
+        reported by the timeit.py script when variables are accessed. This is
+        due to the fact that %timeit executes the statement in the namespace
+        of the shell, compared with timeit.py, which uses a single setup
+        statement to import function or create variables. Generally, the bias
+        does not matter as long as results from timeit.py are not mixed with
+        those from %timeit."""
+
+        opts, stmt = self.parse_options(
+            line, "n:r:tcp:qo", posix=False, strict=False, preserve_non_opts=True
+        )
+        if stmt == "" and cell is None:
+            return
+        
+        timefunc = timeit.default_timer
+        number = int(getattr(opts, "n", 0))
+        default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
+        repeat = int(getattr(opts, "r", default_repeat))
+        precision = int(getattr(opts, "p", 3))
+        quiet = 'q' in opts
+        return_result = 'o' in opts
+        if hasattr(opts, "t"):
+            timefunc = time.time
+        if hasattr(opts, "c"):
+            timefunc = clock
+
+        timer = Timer(timer=timefunc)
+        # this code has tight coupling to the inner workings of timeit.Timer,
+        # but is there a better way to achieve that the code stmt has access
+        # to the shell namespace?
+        transform  = self.shell.transform_cell
+
+        if cell is None:
+            # called as line magic
+            ast_setup = self.shell.compile.ast_parse("pass")
+            ast_stmt = self.shell.compile.ast_parse(transform(stmt))
+        else:
+            ast_setup = self.shell.compile.ast_parse(transform(stmt))
+            ast_stmt = self.shell.compile.ast_parse(transform(cell))
+
+        ast_setup = self.shell.transform_ast(ast_setup)
+        ast_stmt = self.shell.transform_ast(ast_stmt)
+
+        # Check that these compile to valid Python code *outside* the timer func
+        # Invalid code may become valid when put inside the function & loop,
+        # which messes up error messages.
+        # https://github.com/ipython/ipython/issues/10636
+        self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
+        self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
+
+        # This codestring is taken from timeit.template - we fill it in as an
+        # AST, so that we can apply our AST transformations to the user code
+        # without affecting the timing code.
+        timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
+                                        '    setup\n'
+                                        '    _t0 = _timer()\n'
+                                        '    for _i in _it:\n'
+                                        '        stmt\n'
+                                        '    _t1 = _timer()\n'
+                                        '    return _t1 - _t0\n')
+
+        timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
+        timeit_ast = ast.fix_missing_locations(timeit_ast)
+
+        # Track compilation time so it can be reported if too long
+        # Minimum time above which compilation time will be reported
+        tc_min = 0.1
+
+        t0 = clock()
+        code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
+        tc = clock()-t0
+
+        ns = {}
+        glob = self.shell.user_ns
+        # handles global vars with same name as local vars. We store them in conflict_globs.
+        conflict_globs = {}
+        if local_ns and cell is None:
+            for var_name, var_val in glob.items():
+                if var_name in local_ns:
+                    conflict_globs[var_name] = var_val
+            glob.update(local_ns)
+            
+        exec(code, glob, ns)
+        timer.inner = ns["inner"]
+
+        # This is used to check if there is a huge difference between the
+        # best and worst timings.
+        # Issue: https://github.com/ipython/ipython/issues/6471
+        if number == 0:
+            # determine number so that 0.2 <= total time < 2.0
+            for index in range(0, 10):
+                number = 10 ** index
+                time_number = timer.timeit(number)
+                if time_number >= 0.2:
+                    break
+
+        all_runs = timer.repeat(repeat, number)
+        best = min(all_runs) / number
+        worst = max(all_runs) / number
+        timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
+
+        # Restore global vars from conflict_globs
+        if conflict_globs:
+           glob.update(conflict_globs)
+                
+        if not quiet :
+            # Check best timing is greater than zero to avoid a
+            # ZeroDivisionError.
+            # In cases where the slowest timing is lesser than a microsecond
+            # we assume that it does not really matter if the fastest
+            # timing is 4 times faster than the slowest timing or not.
+            if worst > 4 * best and best > 0 and worst > 1e-6:
+                print("The slowest run took %0.2f times longer than the "
+                      "fastest. This could mean that an intermediate result "
+                      "is being cached." % (worst / best))
+           
+            print( timeit_result )
+
+            if tc > tc_min:
+                print("Compiler time: %.2f s" % tc)
+        if return_result:
+            return timeit_result
+
+    @skip_doctest
+    @no_var_expand
+    @needs_local_scope
+    @line_cell_magic
+    @output_can_be_silenced
+    def time(self,line='', cell=None, local_ns=None):
+        """Time execution of a Python statement or expression.
+
+        The CPU and wall clock times are printed, and the value of the
+        expression (if any) is returned.  Note that under Win32, system time
+        is always reported as 0, since it can not be measured.
+
+        This function can be used both as a line and cell magic:
+
+        - In line mode you can time a single-line statement (though multiple
+          ones can be chained with using semicolons).
+
+        - In cell mode, you can time the cell body (a directly
+          following statement raises an error).
+
+        This function provides very basic timing functionality.  Use the timeit
+        magic for more control over the measurement.
+
+        .. versionchanged:: 7.3
+            User variables are no longer expanded,
+            the magic line is always left unmodified.
+
+        Examples
+        --------
+        ::
+
+          In [1]: %time 2**128
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00
+          Out[1]: 340282366920938463463374607431768211456L
+
+          In [2]: n = 1000000
+
+          In [3]: %time sum(range(n))
+          CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
+          Wall time: 1.37
+          Out[3]: 499999500000L
+
+          In [4]: %time print('hello world')
+          hello world
+          CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+          Wall time: 0.00
+
+        .. note::
+            The time needed by Python to compile the given expression will be
+            reported if it is more than 0.1s.
+
+            In the example below, the actual exponentiation is done by Python
+            at compilation time, so while the expression can take a noticeable
+            amount of time to compute, that time is purely due to the
+            compilation::
+
+                In [5]: %time 3**9999;
+                CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+                Wall time: 0.00 s
+
+                In [6]: %time 3**999999;
+                CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+                Wall time: 0.00 s
+                Compiler : 0.78 s
+        """
+        # fail immediately if the given expression can't be compiled
+        
+        if line and cell:
+            raise UsageError("Can't use statement directly after '%%time'!")
+        
+        if cell:
+            expr = self.shell.transform_cell(cell)
+        else:
+            expr = self.shell.transform_cell(line)
+
+        # Minimum time above which parse time will be reported
+        tp_min = 0.1
+
+        t0 = clock()
+        expr_ast = self.shell.compile.ast_parse(expr)
+        tp = clock()-t0
+
+        # Apply AST transformations
+        expr_ast = self.shell.transform_ast(expr_ast)
+
+        # Minimum time above which compilation time will be reported
+        tc_min = 0.1
+
+        expr_val=None
+        if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
+            mode = 'eval'
+            source = '<timed eval>'
+            expr_ast = ast.Expression(expr_ast.body[0].value)
+        else:
+            mode = 'exec'
+            source = '<timed exec>'
+            # multi-line %%time case
+            if len(expr_ast.body) > 1 and isinstance(expr_ast.body[-1], ast.Expr):
+                expr_val= expr_ast.body[-1]
+                expr_ast = expr_ast.body[:-1]
+                expr_ast = Module(expr_ast, [])
+                expr_val = ast.Expression(expr_val.value)
+
+        t0 = clock()
+        code = self.shell.compile(expr_ast, source, mode)
+        tc = clock()-t0
+
+        # skew measurement as little as possible
+        glob = self.shell.user_ns
+        wtime = time.time
+        # time execution
+        wall_st = wtime()
+        if mode=='eval':
+            st = clock2()
+            try:
+                out = eval(code, glob, local_ns)
+            except:
+                self.shell.showtraceback()
+                return
+            end = clock2()
+        else:
+            st = clock2()
+            try:
+                exec(code, glob, local_ns)
+                out=None
+                # multi-line %%time case
+                if expr_val is not None:
+                    code_2 = self.shell.compile(expr_val, source, 'eval')
+                    out = eval(code_2, glob, local_ns)
+            except:
+                self.shell.showtraceback()
+                return
+            end = clock2()
+
+        wall_end = wtime()
+        # Compute actual times and report
+        wall_time = wall_end - wall_st
+        cpu_user = end[0] - st[0]
+        cpu_sys = end[1] - st[1]
+        cpu_tot = cpu_user + cpu_sys
+        # On windows cpu_sys is always zero, so only total is displayed
+        if sys.platform != "win32":
+            print(
+                f"CPU times: user {_format_time(cpu_user)}, sys: {_format_time(cpu_sys)}, total: {_format_time(cpu_tot)}"
+            )
+        else:
+            print(f"CPU times: total: {_format_time(cpu_tot)}")
+        print(f"Wall time: {_format_time(wall_time)}")
+        if tc > tc_min:
+            print(f"Compiler : {_format_time(tc)}")
+        if tp > tp_min:
+            print(f"Parser   : {_format_time(tp)}")
+        return out
+
+    @skip_doctest
+    @line_magic
+    def macro(self, parameter_s=''):
+        """Define a macro for future re-execution. It accepts ranges of history,
+        filenames or string objects.
+
+        Usage:\\
+          %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
+
+        Options:
+
+          -r: use 'raw' input.  By default, the 'processed' history is used,
+          so that magics are loaded in their transformed version to valid
+          Python.  If this option is given, the raw input as typed at the
+          command line is used instead.
+          
+          -q: quiet macro definition.  By default, a tag line is printed 
+          to indicate the macro has been created, and then the contents of 
+          the macro are printed.  If this option is given, then no printout
+          is produced once the macro is created.
+
+        This will define a global variable called `name` which is a string
+        made of joining the slices and lines you specify (n1,n2,... numbers
+        above) from your input history into a single string. This variable
+        acts like an automatic function which re-executes those lines as if
+        you had typed them. You just type 'name' at the prompt and the code
+        executes.
+
+        The syntax for indicating input ranges is described in %history.
+
+        Note: as a 'hidden' feature, you can also use traditional python slice
+        notation, where N:M means numbers N through M-1.
+
+        For example, if your history contains (print using %hist -n )::
+
+          44: x=1
+          45: y=3
+          46: z=x+y
+          47: print(x)
+          48: a=5
+          49: print('x',x,'y',y)
+
+        you can create a macro with lines 44 through 47 (included) and line 49
+        called my_macro with::
+
+          In [55]: %macro my_macro 44-47 49
+
+        Now, typing `my_macro` (without quotes) will re-execute all this code
+        in one pass.
+
+        You don't need to give the line-numbers in order, and any given line
+        number can appear multiple times. You can assemble macros with any
+        lines from your input history in any order.
+
+        The macro is a simple object which holds its value in an attribute,
+        but IPython's display system checks for macros and executes them as
+        code instead of printing them when you type their name.
+
+        You can view a macro's contents by explicitly printing it with::
+
+          print(macro_name)
+
+        """
+        opts,args = self.parse_options(parameter_s,'rq',mode='list')
+        if not args:   # List existing macros
+            return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
+        if len(args) == 1:
+            raise UsageError(
+                "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
+        name, codefrom = args[0], " ".join(args[1:])
+
+        # print('rng',ranges)  # dbg
+        try:
+            lines = self.shell.find_user_code(codefrom, 'r' in opts)
+        except (ValueError, TypeError) as e:
+            print(e.args[0])
+            return
+        macro = Macro(lines)
+        self.shell.define_macro(name, macro)
+        if not ( 'q' in opts) : 
+            print('Macro `%s` created. To execute, type its name (without quotes).' % name)
+            print('=== Macro contents: ===')
+            print(macro, end=' ')
+
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument('output', type=str, default='', nargs='?',
+        help="""The name of the variable in which to store output.
+        This is a utils.io.CapturedIO object with stdout/err attributes
+        for the text of the captured output.
+
+        CapturedOutput also has a show() method for displaying the output,
+        and __call__ as well, so you can use that to quickly display the
+        output.
+
+        If unspecified, captured output is discarded.
+        """
+    )
+    @magic_arguments.argument('--no-stderr', action="store_true",
+        help="""Don't capture stderr."""
+    )
+    @magic_arguments.argument('--no-stdout', action="store_true",
+        help="""Don't capture stdout."""
+    )
+    @magic_arguments.argument('--no-display', action="store_true",
+        help="""Don't capture IPython's rich display."""
+    )
+    @cell_magic
+    def capture(self, line, cell):
+        """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
+        args = magic_arguments.parse_argstring(self.capture, line)
+        out = not args.no_stdout
+        err = not args.no_stderr
+        disp = not args.no_display
+        with capture_output(out, err, disp) as io:
+            self.shell.run_cell(cell)
+        if DisplayHook.semicolon_at_end_of_expression(cell):
+            if args.output in self.shell.user_ns:
+                del self.shell.user_ns[args.output]
+        elif args.output:
+            self.shell.user_ns[args.output] = io
+
+    @skip_doctest
+    @magic_arguments.magic_arguments()
+    @magic_arguments.argument("name", type=str, default="default", nargs="?")
+    @magic_arguments.argument(
+        "--remove", action="store_true", help="remove the current transformer"
+    )
+    @magic_arguments.argument(
+        "--list", action="store_true", help="list existing transformers name"
+    )
+    @magic_arguments.argument(
+        "--list-all",
+        action="store_true",
+        help="list existing transformers name and code template",
+    )
+    @line_cell_magic
+    def code_wrap(self, line, cell=None):
+        """
+        Simple magic to quickly define a code transformer for all IPython's future input.
+
+        ``__code__`` and ``__ret__`` are special variable that represent the code to run
+        and the value of the last expression of ``__code__`` respectively.
+
+        Examples
+        --------
+
+        .. ipython::
+
+            In [1]: %%code_wrap before_after
+               ...: print('before')
+               ...: __code__
+               ...: print('after')
+               ...: __ret__
+
+
+            In [2]: 1
+            before
+            after
+            Out[2]: 1
+
+            In [3]: %code_wrap --list
+            before_after
+
+            In [4]: %code_wrap --list-all
+            before_after :
+                print('before')
+                __code__
+                print('after')
+                __ret__
+
+            In [5]: %code_wrap --remove before_after
+
+        """
+        args = magic_arguments.parse_argstring(self.code_wrap, line)
+
+        if args.list:
+            for name in self._transformers.keys():
+                print(name)
+            return
+        if args.list_all:
+            for name, _t in self._transformers.items():
+                print(name, ":")
+                print(indent(ast.unparse(_t.template), "    "))
+            print()
+            return
+
+        to_remove = self._transformers.pop(args.name, None)
+        if to_remove in self.shell.ast_transformers:
+            self.shell.ast_transformers.remove(to_remove)
+        if cell is None or args.remove:
+            return
+
+        _trs = ReplaceCodeTransformer(ast.parse(cell))
+
+        self._transformers[args.name] = _trs
+        self.shell.ast_transformers.append(_trs)
+
+
+def parse_breakpoint(text, current_file):
+    '''Returns (file, line) for file:line and (current_file, line) for line'''
+    colon = text.find(':')
+    if colon == -1:
+        return current_file, int(text)
+    else:
+        return text[:colon], int(text[colon+1:])
+    
+def _format_time(timespan, precision=3):
+    """Formats the timespan in a human readable form"""
+
+    if timespan >= 60.0:
+        # we have more than a minute, format that in a human readable form
+        # Idea from http://snipplr.com/view/5713/
+        parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
+        time = []
+        leftover = timespan
+        for suffix, length in parts:
+            value = int(leftover / length)
+            if value > 0:
+                leftover = leftover % length
+                time.append(u'%s%s' % (str(value), suffix))
+            if leftover < 1:
+                break
+        return " ".join(time)
+
+
+    # Unfortunately characters outside of range(128) can cause problems in
+    # certain terminals.
+    # See bug: https://bugs.launchpad.net/ipython/+bug/348466
+    # Try to prevent crashes by being more secure than it needs to
+    # E.g. eclipse is able to print a µ, but has no sys.stdout.encoding set.
+    units = ["s", "ms", "us", "ns"]  # the safe value
+    if hasattr(sys.stdout, "encoding") and sys.stdout.encoding:
+        try:
+            "μ".encode(sys.stdout.encoding)
+            units = ["s", "ms", "μs", "ns"]
+        except:
+            pass
+    scaling = [1, 1e3, 1e6, 1e9]
+        
+    if timespan > 0.0:
+        order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
+    else:
+        order = 3
+    return "%.*g %s" % (precision, timespan * scaling[order], units[order])