marktripy 1.0.3__py3-none-any.whl

marktripy/__init__.py

@@ -0,0 +1,10 @@
+# this_file: marktripy/__init__.py
+"""marktripy: A Python package for converting Markdown to AST and back to Markdown."""
+
+__version__ = "0.1.0"
+__author__ = "Adam"
+
+from loguru import logger
+
+# Configure default logger
+logger.disable("marktripy")  # Disabled by default, users can enable

marktripy/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.0.3'
+__version_tuple__ = version_tuple = (1, 0, 3)

marktripy/core/__init__.py

@@ -0,0 +1,7 @@
+# this_file: marktripy/core/__init__.py
+"""Core abstractions and interfaces for marktripy."""
+
+from marktripy.core.ast import ASTNode
+from marktripy.core.parser import Parser
+
+__all__ = ["ASTNode", "Parser"]

marktripy/core/ast.py

@@ -0,0 +1,274 @@
+# this_file: marktripy/core/ast.py
+"""Abstract Syntax Tree node definitions for marktripy."""
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Any
+
+from loguru import logger
+
+
+@dataclass
+class ASTNode(ABC):
+    """Base class for all AST nodes.
+
+    This represents a node in the Markdown abstract syntax tree. Each node
+    has a type, optional children, attributes, content, and metadata.
+
+    Attributes:
+        type: The type of node (e.g., 'heading', 'paragraph', 'list')
+        children: List of child nodes
+        attrs: Dictionary of attributes (e.g., 'id', 'class')
+        content: Optional text content for leaf nodes
+        meta: Parser-specific metadata (e.g., source position)
+    """
+
+    type: str
+    children: list[ASTNode] = field(default_factory=list)
+    attrs: dict[str, Any] = field(default_factory=dict)
+    content: str | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate node after initialization."""
+        if not self.type:
+            raise ValueError("Node type cannot be empty")
+        logger.debug(f"Created ASTNode: type={self.type}, children={len(self.children)}")
+
+    def add_child(self, child: ASTNode) -> None:
+        """Add a child node."""
+        self.children.append(child)
+        logger.debug(f"Added child {child.type} to {self.type}")
+
+    def remove_child(self, child: ASTNode) -> None:
+        """Remove a child node."""
+        self.children.remove(child)
+        logger.debug(f"Removed child {child.type} from {self.type}")
+
+    def get_attr(self, name: str, default: Any = None) -> Any:
+        """Get an attribute value."""
+        return self.attrs.get(name, default)
+
+    def set_attr(self, name: str, value: Any) -> None:
+        """Set an attribute value."""
+        self.attrs[name] = value
+        logger.debug(f"Set attribute {name}={value} on {self.type}")
+
+    def walk(self) -> list[ASTNode]:
+        """Walk the tree and return all nodes in depth-first order."""
+        nodes = [self]
+        for child in self.children:
+            nodes.extend(child.walk())
+        return nodes
+
+    def find_all(self, node_type: str) -> list[ASTNode]:
+        """Find all nodes of a specific type in the subtree."""
+        return [node for node in self.walk() if node.type == node_type]
+
+    def replace_child(self, old_child: ASTNode, new_child: ASTNode) -> None:
+        """Replace a child node with another."""
+        try:
+            index = self.children.index(old_child)
+            self.children[index] = new_child
+            logger.debug(f"Replaced child {old_child.type} with {new_child.type}")
+        except ValueError as e:
+            raise ValueError(f"Child {old_child.type} not found in {self.type}") from e
+
+    def clone(self) -> ASTNode:
+        """Create a deep copy of this node and its subtree."""
+        import copy
+
+        # Create a shallow copy of the node
+        cloned = copy.copy(self)
+        # Deep copy the mutable attributes
+        cloned.children = [child.clone() for child in self.children]
+        cloned.attrs = self.attrs.copy()
+        cloned.meta = self.meta.copy()
+        return cloned
+
+
+# Concrete node types
+@dataclass
+class Document(ASTNode):
+    """Root document node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="document", **kwargs)
+
+
+@dataclass
+class Heading(ASTNode):
+    """Heading node with level."""
+
+    level: int = 1
+
+    def __init__(self, level: int = 1, **kwargs):
+        super().__init__(type="heading", **kwargs)
+        self.level = level
+        if not 1 <= level <= 6:
+            raise ValueError(f"Heading level must be 1-6, got {level}")
+
+
+@dataclass
+class Paragraph(ASTNode):
+    """Paragraph node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="paragraph", **kwargs)
+
+
+@dataclass
+class Text(ASTNode):
+    """Text leaf node."""
+
+    def __init__(self, content: str, **kwargs):
+        super().__init__(type="text", content=content, **kwargs)
+
+
+@dataclass
+class Emphasis(ASTNode):
+    """Emphasis (italic) node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="emphasis", **kwargs)
+
+
+@dataclass
+class Strong(ASTNode):
+    """Strong (bold) node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="strong", **kwargs)
+
+
+@dataclass
+class Link(ASTNode):
+    """Link node with href and title."""
+
+    href: str = ""
+    title: str | None = None
+
+    def __init__(self, href: str = "", title: str | None = None, **kwargs):
+        super().__init__(type="link", **kwargs)
+        self.href = href
+        self.title = title
+        self.set_attr("href", href)
+        if title:
+            self.set_attr("title", title)
+
+
+@dataclass
+class Image(ASTNode):
+    """Image node with src, alt, and title."""
+
+    src: str = ""
+    alt: str = ""
+    title: str | None = None
+
+    def __init__(self, src: str = "", alt: str = "", title: str | None = None, **kwargs):
+        super().__init__(type="image", **kwargs)
+        self.src = src
+        self.alt = alt
+        self.title = title
+        self.set_attr("src", src)
+        self.set_attr("alt", alt)
+        if title:
+            self.set_attr("title", title)
+
+
+@dataclass
+class CodeBlock(ASTNode):
+    """Code block with optional language."""
+
+    language: str | None = None
+
+    def __init__(self, content: str, language: str | None = None, **kwargs):
+        super().__init__(type="code_block", content=content, **kwargs)
+        self.language = language
+        if language:
+            self.set_attr("language", language)
+
+
+@dataclass
+class InlineCode(ASTNode):
+    """Inline code node."""
+
+    def __init__(self, content: str, **kwargs):
+        super().__init__(type="inline_code", content=content, **kwargs)
+
+
+@dataclass
+class List(ASTNode):
+    """List node (ordered or unordered)."""
+
+    ordered: bool = False
+    start: int | None = None
+    tight: bool = True
+
+    def __init__(
+        self, ordered: bool = False, start: int | None = None, tight: bool = True, **kwargs
+    ):
+        super().__init__(type="list", **kwargs)
+        self.ordered = ordered
+        self.start = start
+        self.tight = tight
+        # Don't set ordered as an HTML attribute - it's determined by tag type
+        if start is not None and start != 1:
+            self.set_attr("start", start)
+
+
+@dataclass
+class ListItem(ASTNode):
+    """List item node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="list_item", **kwargs)
+
+
+@dataclass
+class BlockQuote(ASTNode):
+    """Block quote node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="blockquote", **kwargs)
+
+
+@dataclass
+class HorizontalRule(ASTNode):
+    """Horizontal rule node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="horizontal_rule", **kwargs)
+
+
+@dataclass
+class Table(ASTNode):
+    """Table node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="table", **kwargs)
+
+
+@dataclass
+class TableRow(ASTNode):
+    """Table row node."""
+
+    def __init__(self, **kwargs):
+        super().__init__(type="table_row", **kwargs)
+
+
+@dataclass
+class TableCell(ASTNode):
+    """Table cell node."""
+
+    header: bool = False
+    align: str | None = None
+
+    def __init__(self, header: bool = False, align: str | None = None, **kwargs):
+        super().__init__(type="table_cell", **kwargs)
+        self.header = header
+        self.align = align
+        if align:
+            self.set_attr("align", align)

marktripy/core/parser.py

@@ -0,0 +1,199 @@
+# this_file: marktripy/core/parser.py
+"""Abstract parser interface for marktripy."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from loguru import logger
+
+from marktripy.core.ast import Document
+
+
+class Parser(ABC):
+    """Abstract base class for Markdown parsers.
+
+    This interface defines the contract that all parser implementations
+    must follow. Parsers convert Markdown text into an AST representation.
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        """Initialize parser with optional configuration.
+
+        Args:
+            config: Parser-specific configuration options
+        """
+        self.config = config or {}
+        logger.debug(f"Initialized {self.__class__.__name__} with config: {self.config}")
+
+    @abstractmethod
+    def parse(self, text: str) -> Document:
+        """Parse Markdown text into an AST.
+
+        Args:
+            text: The Markdown text to parse
+
+        Returns:
+            The root Document node of the AST
+        """
+
+    @abstractmethod
+    def get_capabilities(self) -> dict[str, bool]:
+        """Get parser capabilities.
+
+        Returns a dictionary indicating which features this parser supports.
+
+        Returns:
+            Dictionary with capability flags like:
+            - 'tables': Table support
+            - 'strikethrough': Strikethrough syntax
+            - 'task_lists': Task list checkboxes
+            - 'footnotes': Footnote references
+            - 'definition_lists': Definition list syntax
+            - 'math': Math expressions
+            - 'smart_quotes': Smart typography
+            - 'custom_extensions': Custom extension support
+        """
+
+    def validate_markdown(self, text: str) -> list[str]:
+        """Validate Markdown syntax and return any errors.
+
+        Default implementation just tries to parse and catches exceptions.
+        Subclasses can override for more detailed validation.
+
+        Args:
+            text: The Markdown text to validate
+
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors = []
+        try:
+            self.parse(text)
+        except Exception as e:
+            errors.append(str(e))
+        return errors
+
+    def preprocess(self, text: str) -> str:
+        """Preprocess Markdown text before parsing.
+
+        Can be overridden by subclasses to normalize text, handle
+        special cases, or apply transformations.
+
+        Args:
+            text: Raw Markdown text
+
+        Returns:
+            Preprocessed text ready for parsing
+        """
+        # Normalize line endings
+        text = text.replace("\r\n", "\n").replace("\r", "\n")
+
+        # Ensure text ends with newline
+        if text and not text.endswith("\n"):
+            text += "\n"
+
+        logger.debug(f"Preprocessed text: {len(text)} characters")
+        return text
+
+    def postprocess(self, ast: Document) -> Document:
+        """Postprocess AST after parsing.
+
+        Can be overridden by subclasses to apply transformations,
+        validate the AST structure, or enrich nodes with metadata.
+
+        Args:
+            ast: The parsed AST
+
+        Returns:
+            The postprocessed AST
+        """
+        logger.debug(f"Postprocessed AST with {len(ast.children)} top-level nodes")
+        return ast
+
+
+class ParserError(Exception):
+    """Base exception for parser errors."""
+
+    def __init__(self, message: str, line: int | None = None, column: int | None = None):
+        """Initialize parser error.
+
+        Args:
+            message: Error description
+            line: Line number where error occurred (1-based)
+            column: Column number where error occurred (1-based)
+        """
+        self.line = line
+        self.column = column
+
+        if line is not None and column is not None:
+            full_message = f"{message} at line {line}, column {column}"
+        elif line is not None:
+            full_message = f"{message} at line {line}"
+        else:
+            full_message = message
+
+        super().__init__(full_message)
+
+
+class ParserRegistry:
+    """Registry for available parser implementations."""
+
+    _parsers: dict[str, type[Parser]] = {}
+
+    @classmethod
+    def register(cls, name: str, parser_class: type[Parser]) -> None:
+        """Register a parser implementation.
+
+        Args:
+            name: Name to register the parser under
+            parser_class: Parser class to register
+        """
+        if not issubclass(parser_class, Parser):
+            raise TypeError(f"{parser_class} must be a subclass of Parser")
+
+        cls._parsers[name] = parser_class
+        logger.info(f"Registered parser: {name} -> {parser_class.__name__}")
+
+    @classmethod
+    def get(cls, name: str) -> type[Parser]:
+        """Get a registered parser class.
+
+        Args:
+            name: Name of the parser to retrieve
+
+        Returns:
+            The parser class
+
+        Raises:
+            KeyError: If parser name is not registered
+        """
+        if name not in cls._parsers:
+            raise KeyError(
+                f"Parser '{name}' not registered. Available: {list(cls._parsers.keys())}"
+            )
+        return cls._parsers[name]
+
+    @classmethod
+    def create(cls, name: str, config: dict[str, Any] | None = None) -> Parser:
+        """Create a parser instance.
+
+        Args:
+            name: Name of the parser to create
+            config: Parser configuration
+
+        Returns:
+            Parser instance
+        """
+        parser_class = cls.get(name)
+        return parser_class(config)
+
+    @classmethod
+    def list_parsers(cls) -> list[str]:
+        """List all registered parser names.
+
+        Returns:
+            List of parser names
+        """
+        return list(cls._parsers.keys())