Configuration Management

class MdParserConfig:
    """
    Main configuration dataclass for MyST parser settings.
    
    Attributes:
        commonmark_only (bool): Use strict CommonMark parser only
        gfm_only (bool): Use strict GitHub Flavored Markdown parser only
        enable_extensions (set[str]): Enable syntax extensions
        disable_syntax (Iterable[str]): Disable CommonMark syntax elements
        all_links_external (bool): Parse all links as simple hyperlinks
        links_external_new_tab (bool): Open external links in new tab
        url_schemes (dict): URI schemes converted to external links
        ref_domains (Iterable[str] | None): Sphinx domain names for link references
        fence_as_directive (set[str]): Interpret code fences as directives
        number_code_blocks (Sequence[str]): Add line numbers to code blocks
        title_to_header (bool): Convert title field to H1 header
        heading_anchors (int): Heading level depth for HTML anchors
        heading_slug_func (Callable[[str], str] | None): Function for creating heading anchors
        html_meta (dict[str, str]): HTML meta tags
        footnote_sort (bool): Move footnotes to document end
        footnote_transition (bool): Place transition before footnotes
        words_per_minute (int): Reading speed calculations
    """
    commonmark_only: bool = False
    gfm_only: bool = False
    enable_extensions: set[str] = field(default_factory=set)
    disable_syntax: Iterable[str] = field(default_factory=list)
    all_links_external: bool = False
    links_external_new_tab: bool = False
    url_schemes: dict = field(default_factory=dict)
    ref_domains: Iterable[str] | None = None
    fence_as_directive: set[str] = field(default_factory=set)
    number_code_blocks: Sequence[str] = field(default_factory=list)
    title_to_header: bool = False
    heading_anchors: int = 0
    heading_slug_func: Callable[[str], str] | None = None
    html_meta: dict[str, str] = field(default_factory=dict)
    footnote_sort: bool = False
    footnote_transition: bool = False
    words_per_minute: int = 200

from myst_parser.config.main import MdParserConfig

# Create configuration with common settings
config = MdParserConfig(
    enable_extensions={"tasklist", "deflist", "substitution", "colon_fence"},
    heading_anchors=3,
    footnote_sort=True,
    footnote_transition=True,
    html_meta={"author": "Documentation Team"},
    words_per_minute=250
)

# Configuration for strict CommonMark parsing
strict_config = MdParserConfig(
    commonmark_only=True,
    enable_extensions=set()  # No extensions in strict mode
)

# Configuration for external link handling
external_config = MdParserConfig(
    all_links_external=True,
    links_external_new_tab=True,
    url_schemes={"http": ["external"], "https": ["external"]}
)

def merge_file_level(
    config: MdParserConfig, 
    topmatter: dict, 
    warning: Callable
) -> MdParserConfig:
    """
    Merge file-level configuration with global config.
    
    Args:
        config: Global MdParserConfig instance
        topmatter: YAML frontmatter dictionary from document
        warning: Warning callback function
        
    Returns:
        New MdParserConfig with merged settings
        
    Raises:
        TopmatterReadError: When frontmatter contains invalid configuration
    """

from myst_parser.config.main import MdParserConfig, merge_file_level, read_topmatter

# Global configuration
global_config = MdParserConfig(
    enable_extensions={"tasklist", "deflist"},
    heading_anchors=2
)

# Document with YAML frontmatter
document_content = """---
myst:
  enable_extensions: ["substitution", "colon_fence"]
  heading_anchors: 4
  footnote_sort: true
---
# Document Content
"""

# Read and merge configuration
topmatter = read_topmatter(document_content)
merged_config = merge_file_level(
    global_config, 
    topmatter.get('myst', {}),
    lambda msg: print(f"Warning: {msg}")
)

print(merged_config.enable_extensions)  # {"substitution", "colon_fence"}
print(merged_config.heading_anchors)     # 4
print(merged_config.footnote_sort)       # True

def read_topmatter(text: str) -> dict:
    """
    Read YAML frontmatter from source string.
    
    Args:
        text: Source text potentially containing YAML frontmatter
        
    Returns:
        Dictionary containing parsed YAML data
        
    Raises:
        TopmatterReadError: When YAML parsing fails
    """

from myst_parser.config.main import read_topmatter

# Document with frontmatter
source = """---
title: "MyST Document"
author: "John Doe"
myst:
  enable_extensions: ["tasklist"]
  heading_anchors: 3
---
# Document Title

Content here...
"""

# Parse frontmatter
metadata = read_topmatter(source)
print(metadata['title'])    # "MyST Document"
print(metadata['author'])   # "John Doe"
print(metadata['myst']['enable_extensions'])  # ["tasklist"]

def validate_field(inst, field, value) -> None:
    """
    Validate single dataclass field.
    
    Args:
        inst: Dataclass instance
        field: Field being validated
        value: Value to validate
        
    Raises:
        ValueError: When validation fails
    """

def validate_fields(inst) -> None:
    """
    Validate all dataclass fields.
    
    Args:
        inst: Dataclass instance to validate
        
    Raises:
        ValueError: When any field validation fails
    """

def instance_of(type_: type) -> ValidatorType:
    """
    Create type validator.
    
    Args:
        type_: Expected type
        
    Returns:
        Validator function
    """

def optional(validator: ValidatorType) -> ValidatorType:
    """
    Make attribute optional.
    
    Args:
        validator: Base validator
        
    Returns:
        Optional validator function
    """

def in_(options: Iterable) -> ValidatorType:
    """
    Create value-in-options validator.
    
    Args:
        options: Allowed values
        
    Returns:
        Validator function
    """

def deep_iterable(
    member_validator: ValidatorType, 
    iterable_validator: ValidatorType
) -> ValidatorType:
    """
    Create deep iterable validator.
    
    Args:
        member_validator: Validator for iterable members
        iterable_validator: Validator for iterable itself
        
    Returns:
        Deep iterable validator function
    """

from myst_parser.config.dc_validators import validate_fields, instance_of, in_
from myst_parser.config.main import MdParserConfig

# Create configuration
config = MdParserConfig(
    enable_extensions={"tasklist", "deflist"},
    heading_anchors=3,
    footnote_sort=True
)

# Validate all fields
try:
    validate_fields(config)
    print("Configuration is valid")
except ValueError as e:
    print(f"Validation error: {e}")

# Custom validation example
from dataclasses import dataclass, field

@dataclass
class CustomConfig:
    mode: str = field(validator=in_(["strict", "loose"]))
    count: int = field(validator=instance_of(int))

class TopmatterReadError(Exception):
    """Exception raised when reading YAML frontmatter fails."""

class UrlSchemeType(TypedDict):
    """Configuration for external URL schemes."""
    allowed_schemes: tuple[str, ...]
    classes: list[str]

ValidatorType = Callable[[object, object, object], None]