Configuration

class NbParserConfig:
    """
    Central configuration for MyST-NB notebook parsing and processing.
    
    Contains all configuration options with default values, validation,
    and documentation for each setting.
    """
    
    # File read options
    custom_formats: Dict[str, Tuple[str, dict, bool]] = {}
    read_as_md: bool = False
    
    # Configuration override keys
    metadata_key: str = "mystnb"
    cell_metadata_key: str = "mystnb"
    
    # Notebook execution options
    kernel_rgx_aliases: Dict[str, str] = {}
    eval_name_regex: str = r"^[a-zA-Z_][a-zA-Z0-9_]*$"
    execution_mode: Literal["off", "force", "auto", "cache", "inline"] = "auto"
    execution_cache_path: str = ""
    execution_excludepatterns: Sequence[str] = ()
    execution_timeout: int = 30
    execution_in_temp: bool = False
    execution_allow_errors: bool = False
    execution_raise_on_error: bool = False
    execution_show_tb: bool = False
    
    # Pre-processing options
    merge_streams: bool = False
    
    # Render options
    render_plugin: str = "default"
    remove_code_source: bool = False
    remove_code_outputs: bool = False
    scroll_outputs: bool = False
    code_prompt_show: str = "Show code cell {type}"
    code_prompt_hide: str = "Hide code cell {type}"
    number_source_lines: bool = False
    builder_name: str = "html"
    mime_priority_overrides: Sequence[Tuple[str, str, Optional[int]]] = ()
    output_stderr: Literal["show", "remove", "remove-warn", "warn", "error", "severe"] = "show"
    render_text_lexer: str = "myst-ansi"
    render_error_lexer: str = "ipythontb"
    render_image_options: Dict[str, str] = {}
    render_figure_options: Dict[str, str] = {}
    render_markdown_format: Literal["commonmark", "gfm", "myst"] = "commonmark"
    ipywidgets_js: Dict[str, Dict[str, str]] = ipywidgets_js_factory()
    
    # Write options for docutils
    output_folder: str = "build"
    append_css: bool = True
    metadata_to_fm: bool = False

class Section(Enum):
    """
    Configuration section tags.
    
    Defines the scope and hierarchy of configuration settings:
    - global_lvl: Global level configuration
    - file_lvl: File level configuration (notebook)
    - cell_lvl: Cell level configuration
    - config: Meta configuration
    - read: Configuration for reading files
    - execute: Configuration for executing notebooks
    - render: Configuration for rendering notebook elements
    """
    global_lvl = "global"
    file_lvl = "notebook" 
    cell_lvl = "cell"
    config = "config"
    read = "read"
    execute = "execute"
    render = "render"

# Core execution options
execution_mode: str = "auto"
execution_timeout: int = 30  # Timeout in seconds
execution_show_tb: bool = False  # Show full tracebacks
execution_in_temp: bool = False  # Execute in temporary directory
execution_allow_errors: bool = False  # Continue on cell errors
execution_raise_on_error: bool = False  # Raise exceptions on errors

# Code visibility
remove_code_source: bool = False  # Hide input code
remove_code_outputs: bool = False  # Hide outputs
remove_markdown_source: bool = False  # Hide markdown source

# Output handling
output_stderr: str = "show"  # "show", "remove", "remove-warn", "warn", "error"
merge_streams: bool = False  # Merge stdout/stderr

# Renderer selection
render_plugin: str = "default"  # Renderer plugin name
render_priority: dict = None  # MIME type priority overrides

# Syntax highlighting
render_text_lexer: str = "myst-ansi"  # Lexer for text output
render_error_lexer: str = "ipythontb"  # Lexer for error output

# Image rendering
render_image_options: dict = {
    "width": "100%",
    "align": "center"
}

# Figure rendering
render_figure_options: dict = {
    "caption": True,
    "numbering": True
}

# Custom notebook formats
custom_formats: dict = {
    ".Rmd": "Rmd",
    ".qmd": "qmd"
}

# Kernel name aliases
kernel_rgx_aliases: dict = {
    "python.*": "python",
    "ir": "r"
}

{
    "tags": ["hide-input", "hide-output"],
    "mystnb": {
        "execution_timeout": 60,
        "remove_code_source": true
    }
}

# In conf.py for Sphinx
extensions = ['myst_nb']

# Execution settings
nb_execution_mode = "cache"
nb_execution_timeout = 120
nb_execution_cache_path = ".jupyter_cache"

# Display settings
nb_remove_code_source = False
nb_remove_code_outputs = False
nb_merge_streams = True
nb_output_stderr = "show"

# Rendering settings
nb_render_plugin = "default"
nb_render_image_options = {"width": "75%"}
nb_render_figure_options = {"align": "center"}

from myst_nb.core.config import NbParserConfig

# Create configuration
config = NbParserConfig(
    execution_mode="force",
    execution_timeout=60,
    remove_code_source=True,
    render_text_lexer="python"
)

---
mystnb:
  execution_mode: "force"
  execution_timeout: 120
  remove_code_source: false
---

import os
from myst_nb.core.config import NbParserConfig

# Configure based on environment
config = NbParserConfig(
    execution_mode=os.getenv("NB_EXECUTION_MODE", "auto"),
    execution_timeout=int(os.getenv("NB_TIMEOUT", "30")),
    remove_code_source=os.getenv("NB_HIDE_CODE") == "true"
)

## Warning System

### Warning Types

MyST-NB provides a structured warning system for handling various processing issues.

```python { .api }
class MystNBWarnings(Enum):
    """
    Enumeration of MyST-NB warning types for filtering and error handling.
    
    Warning types:
    - LEXER: Issues with syntax highlighting lexer selection
    - FIG_CAPTION: Problems with figure caption processing
    - MIME_TYPE: MIME type handling issues  
    - OUTPUT_TYPE: Unsupported output type warnings
    - CELL_METADATA_KEY: Cell metadata key conflicts
    - CELL_CONFIG: Cell-level configuration issues
    """
    LEXER = "lexer"
    FIG_CAPTION = "fig_caption"
    MIME_TYPE = "mime_type"
    OUTPUT_TYPE = "output_type"
    CELL_METADATA_KEY = "cell_metadata_key"
    CELL_CONFIG = "cell_config"

# In Sphinx conf.py - filter specific warning types
import warnings
from myst_nb.warnings_ import MystNBWarnings

# Suppress specific warning types
warnings.filterwarnings("ignore", category=UserWarning, 
                       message=f".*{MystNBWarnings.LEXER.value}.*")

class AnsiColorLexer:
    """
    Pygments lexer for ANSI color escape sequences.
    
    Entry point: 'myst-ansi'
    Used for: render_text_lexer configuration
    Purpose: Syntax highlighting of terminal output with color codes
    """

class IPythonTracebackLexer:
    """
    Pygments lexer for IPython/Jupyter error tracebacks.
    
    Entry point: 'ipythontb'  
    Used for: render_error_lexer configuration
    Purpose: Enhanced formatting of Python exception tracebacks
    """

# Widget-related MIME types
WIDGET_STATE_MIMETYPE = "application/vnd.jupyter.widget-state+json"
WIDGET_VIEW_MIMETYPE = "application/vnd.jupyter.widget-view+json"

# Entry point group names
RENDER_ENTRY_GROUP = "myst_nb.renderers"
MIME_RENDER_ENTRY_GROUP = "myst_nb.mime_renderers"

# Glue system
GLUE_PREFIX = "application/papermill.record/"

# Sphinx output folder
OUTPUT_FOLDER = "jupyter_execute"