1User: 「我搬家了、訂單編號 #12345、新地址是 ___」
2   ↓
31. 解析意圖 + 抽取訊息（訂單編號、新地址）
42. 查訂單狀態（已出貨？未出貨？已送達？）
53. 查 policy（這個訂單狀態 + user tier 能不能改地址？）
64. 若可：執行改地址（呼叫物流 / 庫存 API）
75. 若不可：解釋為什麼、給替代方案
86. 草擬回覆 email、發出

 1Production trace + eval result
 2   ↓
 3[Error analysis：找 emerging pattern]
 4   ↓
 5   Hypothesis：哪一層有問題？
 6   ├── Prompt 層 → 改 prompt → A/B test → 看 eval 收斂
 7   ├── Tool 層   → 改 tool / schema → 跑 component eval → 收斂
 8   ├── RAG 層    → 改 chunking / query rewriting → 跑 [retrieval recall](/llm/knowledge-cards/retrieval-recall/) → 收斂
 9   ├── Policy 層 → 改 deterministic rule → 跑 step 3 component eval → 收斂
10   └── Model 層  → 換 model → 跑全 eval set → 收斂
11   ↓
12[改動進 production]
13   ↓
14[Frozen baseline 留著、新版本跟它比、漂移看得見]

 1import re
 2from typing import List, Dict
 3
 4class MarkdownLinkChecker:
 5    """Markdown 連結檢查器"""
 6
 7    # Markdown 連結正則表達式
 8    # 匹配 [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target) 格式，排除圖片 ![alt](/python-advanced/05-c-extensions/case-studies/cython-markdown/src)
 9    INLINE_LINK_PATTERN = re.compile(
10        r'(?<!!)\[([^\]]+)\]\(([^)]+)\)'
11    )
12
13    # 引用式連結定義 [ref]: target
14    REFERENCE_DEF_PATTERN = re.compile(
15        r'^\s*\[([^\]]+)\]:\s*(.+)$',
16        re.MULTILINE
17    )
18
19    # 引用式連結使用 [text][ref]
20    REFERENCE_USE_PATTERN = re.compile(
21        r'\[([^\]]+)\]\[([^\]]+)\]'
22    )
23
24    def parse_markdown_links(self, content: str) -> List[Dict]:
25        """
26        解析 Markdown 內容中的所有連結
27
28        Args:
29            content: Markdown 內容
30
31        Returns:
32            list[dict]: 連結列表，每個包含 text, target, line
33        """
34        links = []
35        lines = content.split('\n')
36
37        # 首先收集引用式連結定義
38        reference_defs = {}
39        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
40            ref_name = match.group(1).lower()
41            ref_target = match.group(2).strip()
42            reference_defs[ref_name] = ref_target
43
44        # 追蹤是否在程式碼區塊內
45        in_code_block = False
46
47        # 解析行內連結
48        for line_num, line in enumerate(lines, start=1):
49            # 檢查程式碼區塊開始/結束
50            if line.strip().startswith("```"):
51                in_code_block = not in_code_block
52                continue
53
54            # 跳過程式碼區塊內的連結
55            if in_code_block:
56                continue
57
58            # 行內連結 [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target)
59            for match in self.INLINE_LINK_PATTERN.finditer(line):
60                links.append({
61                    "text": match.group(1),
62                    "target": match.group(2),
63                    "line": line_num
64                })
65
66            # 引用式連結 [text][ref]
67            for match in self.REFERENCE_USE_PATTERN.finditer(line):
68                ref_name = match.group(2).lower()
69                if ref_name in reference_defs:
70                    links.append({
71                        "text": match.group(1),
72                        "target": reference_defs[ref_name],
73                        "line": line_num
74                    })
75
76        return links

 1# markdown_parser.pyx
 2"""
 3Cython accelerated Markdown link parser.
 4
 5This module provides fast parsing of Markdown links,
 6compatible with the original Python implementation.
 7"""
 8
 9import re
10from typing import List, Dict
11
12# Compile regex patterns at module level for reuse
13cdef object INLINE_LINK_PATTERN = re.compile(
14    r'(?<!!)\[([^\]]+)\]\(([^)]+)\)'
15)
16
17cdef object REFERENCE_DEF_PATTERN = re.compile(
18    r'^\s*\[([^\]]+)\]:\s*(.+)$',
19    re.MULTILINE
20)
21
22cdef object REFERENCE_USE_PATTERN = re.compile(
23    r'\[([^\]]+)\]\[([^\]]+)\]'
24)

 1# markdown_parser.pyx (continued)
 2
 3cdef class LinkInfo:
 4    """
 5    C-level struct to hold link information.
 6    Faster than Python dict for internal operations.
 7    """
 8    cdef public str text
 9    cdef public str target
10    cdef public int line
11
12    def __init__(self, str text, str target, int line):
13        self.text = text
14        self.target = target
15        self.line = line
16
17    def to_dict(self) -> dict:
18        """Convert to dictionary for API compatibility."""
19        return {
20            "text": self.text,
21            "target": self.target,
22            "line": self.line
23        }
24
25cdef bint is_code_fence(str line):
26    """
27    Check if line is a code fence marker.
28
29    cdef function: only callable from Cython, fastest.
30    """
31    cdef str stripped = line.strip()
32    return stripped.startswith("```") or stripped.startswith("~~~")

 1# markdown_parser.pyx (continued)
 2
 3cdef list _parse_inline_links(list lines, dict reference_defs):
 4    """
 5    Parse inline and reference links from lines.
 6
 7    Internal function with optimized loop.
 8    """
 9    cdef:
10        list links = []
11        int line_num
12        int total_lines = len(lines)
13        bint in_code_block = False
14        str line
15        str ref_name
16        object match
17
18    for line_num in range(total_lines):
19        line = lines[line_num]
20
21        # Check code fence
22        if is_code_fence(line):
23            in_code_block = not in_code_block
24            continue
25
26        if in_code_block:
27            continue
28
29        # Parse inline links [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target)
30        for match in INLINE_LINK_PATTERN.finditer(line):
31            links.append(LinkInfo(
32                match.group(1),
33                match.group(2),
34                line_num + 1  # 1-indexed
35            ))
36
37        # Parse reference links [text][ref]
38        for match in REFERENCE_USE_PATTERN.finditer(line):
39            ref_name = match.group(2).lower()
40            if ref_name in reference_defs:
41                links.append(LinkInfo(
42                    match.group(1),
43                    reference_defs[ref_name],
44                    line_num + 1
45                ))
46
47    return links
48
49cdef dict _collect_reference_defs(str content):
50    """
51    Collect reference link definitions from content.
52
53    Returns dict mapping ref_name -> target.
54    """
55    cdef:
56        dict reference_defs = {}
57        object match
58        str ref_name
59        str ref_target
60
61    for match in REFERENCE_DEF_PATTERN.finditer(content):
62        ref_name = match.group(1).lower()
63        ref_target = match.group(2).strip()
64        reference_defs[ref_name] = ref_target
65
66    return reference_defs

 1# markdown_parser.pyx (continued)
 2
 3cpdef list parse_markdown_links(str content):
 4    """
 5    Parse all links from Markdown content.
 6
 7    This is the main public API, compatible with the original
 8    Python implementation.
 9
10    Args:
11        content: Markdown content string
12
13    Returns:
14        List of dicts with 'text', 'target', 'line' keys
15    """
16    cdef:
17        list lines
18        dict reference_defs
19        list link_infos
20        list result
21        LinkInfo info
22
23    # Split content into lines
24    lines = content.split('\n')
25
26    # Collect reference definitions
27    reference_defs = _collect_reference_defs(content)
28
29    # Parse all links
30    link_infos = _parse_inline_links(lines, reference_defs)
31
32    # Convert to dict format for API compatibility
33    result = [info.to_dict() for info in link_infos]
34
35    return result
36
37def parse_markdown_links_py(content: str) -> List[Dict]:
38    """
39    Python-compatible wrapper with type hints.
40
41    Identical to parse_markdown_links but with explicit
42    Python type annotations for better IDE support.
43    """
44    return parse_markdown_links(content)

 1# setup.py
 2"""
 3Build script for Cython markdown parser.
 4
 5Usage:
 6    python setup.py build_ext --inplace
 7
 8Or for development with automatic rebuild:
 9    pip install -e .
10"""
11
12from setuptools import setup, Extension
13from Cython.Build import cythonize
14
15extensions = [
16    Extension(
17        "markdown_parser",
18        sources=["markdown_parser.pyx"],
19        # Optional: add compiler directives for optimization
20        # extra_compile_args=["-O3"],
21    )
22]
23
24setup(
25    name="markdown_parser",
26    version="0.1.0",
27    description="Cython accelerated Markdown link parser",
28    ext_modules=cythonize(
29        extensions,
30        compiler_directives={
31            "language_level": "3",      # Python 3 syntax
32            "boundscheck": False,       # Disable bounds checking
33            "wraparound": False,        # Disable negative indexing
34            "cdivision": True,          # Use C division semantics
35        },
36        annotate=True,  # Generate HTML annotation file
37    ),
38    zip_safe=False,
39)

  1# markdown_parser.pyx
  2"""
  3Cython accelerated Markdown link parser.
  4
  5This module provides fast parsing of Markdown links,
  6compatible with the original Python implementation.
  7
  8Build:
  9    python setup.py build_ext --inplace
 10
 11Usage:
 12    from markdown_parser import parse_markdown_links
 13    links = parse_markdown_links(markdown_content)
 14"""
 15
 16import re
 17from typing import List, Dict
 18
 19# ============================================================
 20# Compiled regex patterns (module level for reuse)
 21# ============================================================
 22
 23cdef object INLINE_LINK_PATTERN = re.compile(
 24    r'(?<!!)\[([^\]]+)\]\(([^)]+)\)'
 25)
 26
 27cdef object REFERENCE_DEF_PATTERN = re.compile(
 28    r'^\s*\[([^\]]+)\]:\s*(.+)$',
 29    re.MULTILINE
 30)
 31
 32cdef object REFERENCE_USE_PATTERN = re.compile(
 33    r'\[([^\]]+)\]\[([^\]]+)\]'
 34)
 35
 36# ============================================================
 37# C-level data structures
 38# ============================================================
 39
 40cdef class LinkInfo:
 41    """
 42    C-level struct to hold link information.
 43    Faster than Python dict for internal operations.
 44    """
 45    cdef public str text
 46    cdef public str target
 47    cdef public int line
 48
 49    def __init__(self, str text, str target, int line):
 50        self.text = text
 51        self.target = target
 52        self.line = line
 53
 54    def to_dict(self) -> dict:
 55        """Convert to dictionary for API compatibility."""
 56        return {
 57            "text": self.text,
 58            "target": self.target,
 59            "line": self.line
 60        }
 61
 62    def __repr__(self):
 63        return f"LinkInfo(text={self.text!r}, target={self.target!r}, line={self.line})"
 64
 65# ============================================================
 66# Internal helper functions (cdef = C-only, fastest)
 67# ============================================================
 68
 69cdef bint is_code_fence(str line):
 70    """
 71    Check if line is a code fence marker.
 72    """
 73    cdef str stripped = line.strip()
 74    return stripped.startswith("```") or stripped.startswith("~~~")
 75
 76cdef dict _collect_reference_defs(str content):
 77    """
 78    Collect reference link definitions from content.
 79    """
 80    cdef:
 81        dict reference_defs = {}
 82        object match
 83        str ref_name
 84        str ref_target
 85
 86    for match in REFERENCE_DEF_PATTERN.finditer(content):
 87        ref_name = match.group(1).lower()
 88        ref_target = match.group(2).strip()
 89        reference_defs[ref_name] = ref_target
 90
 91    return reference_defs
 92
 93cdef list _parse_inline_links(list lines, dict reference_defs):
 94    """
 95    Parse inline and reference links from lines.
 96    """
 97    cdef:
 98        list links = []
 99        int line_num
100        int total_lines = len(lines)
101        bint in_code_block = False
102        str line
103        str ref_name
104        object match
105
106    for line_num in range(total_lines):
107        line = lines[line_num]
108
109        # Check code fence
110        if is_code_fence(line):
111            in_code_block = not in_code_block
112            continue
113
114        if in_code_block:
115            continue
116
117        # Parse inline links [text](/python-advanced/05-c-extensions/case-studies/cython-markdown/target)
118        for match in INLINE_LINK_PATTERN.finditer(line):
119            links.append(LinkInfo(
120                match.group(1),
121                match.group(2),
122                line_num + 1
123            ))
124
125        # Parse reference links [text][ref]
126        for match in REFERENCE_USE_PATTERN.finditer(line):
127            ref_name = match.group(2).lower()
128            if ref_name in reference_defs:
129                links.append(LinkInfo(
130                    match.group(1),
131                    reference_defs[ref_name],
132                    line_num + 1
133                ))
134
135    return links
136
137# ============================================================
138# Public API (cpdef = callable from both Python and Cython)
139# ============================================================
140
141cpdef list parse_markdown_links(str content):
142    """
143    Parse all links from Markdown content.
144
145    Args:
146        content: Markdown content string
147
148    Returns:
149        List of dicts with 'text', 'target', 'line' keys
150
151    Example:
152        >>> content = "[Click here](https://example.com)"
153        >>> links = parse_markdown_links(content)
154        >>> links[0]['target']
155        'https://example.com'
156    """
157    cdef:
158        list lines
159        dict reference_defs
160        list link_infos
161        list result
162        LinkInfo info
163
164    lines = content.split('\n')
165    reference_defs = _collect_reference_defs(content)
166    link_infos = _parse_inline_links(lines, reference_defs)
167    result = [info.to_dict() for info in link_infos]
168
169    return result
170
171# Python-compatible wrapper with full type hints
172def parse_markdown_links_py(content: str) -> List[Dict]:
173    """
174    Python-compatible wrapper with type hints.
175
176    Identical to parse_markdown_links but with explicit
177    Python type annotations for better IDE support.
178    """
179    return parse_markdown_links(content)
180
181# ============================================================
182# Optional: Expose LinkInfo class for advanced usage
183# ============================================================
184
185def parse_markdown_links_fast(str content) -> list:
186    """
187    Parse links and return LinkInfo objects directly.
188
189    Faster than parse_markdown_links() as it skips
190    the dict conversion step.
191
192    Returns:
193        List of LinkInfo objects
194    """
195    cdef:
196        list lines
197        dict reference_defs
198
199    lines = content.split('\n')
200    reference_defs = _collect_reference_defs(content)
201    return _parse_inline_links(lines, reference_defs)

  1# benchmark.py
  2"""
  3Performance comparison between Python and Cython implementations.
  4
  5Usage:
  6    # First, build the Cython module
  7    python setup.py build_ext --inplace
  8
  9    # Then run benchmark
 10    python benchmark.py
 11"""
 12
 13import time
 14import statistics
 15from typing import Callable, List
 16
 17# Pure Python implementation (inline for comparison)
 18import re
 19
 20class PythonMarkdownParser:
 21    """Original pure Python implementation."""
 22
 23    INLINE_LINK_PATTERN = re.compile(r'(?<!!)\[([^\]]+)\]\(([^)]+)\)')
 24    REFERENCE_DEF_PATTERN = re.compile(r'^\s*\[([^\]]+)\]:\s*(.+)$', re.MULTILINE)
 25    REFERENCE_USE_PATTERN = re.compile(r'\[([^\]]+)\]\[([^\]]+)\]')
 26
 27    def parse_markdown_links(self, content: str) -> list:
 28        links = []
 29        lines = content.split('\n')
 30
 31        reference_defs = {}
 32        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
 33            ref_name = match.group(1).lower()
 34            ref_target = match.group(2).strip()
 35            reference_defs[ref_name] = ref_target
 36
 37        in_code_block = False
 38
 39        for line_num, line in enumerate(lines, start=1):
 40            if line.strip().startswith("```"):
 41                in_code_block = not in_code_block
 42                continue
 43
 44            if in_code_block:
 45                continue
 46
 47            for match in self.INLINE_LINK_PATTERN.finditer(line):
 48                links.append({
 49                    "text": match.group(1),
 50                    "target": match.group(2),
 51                    "line": line_num
 52                })
 53
 54            for match in self.REFERENCE_USE_PATTERN.finditer(line):
 55                ref_name = match.group(2).lower()
 56                if ref_name in reference_defs:
 57                    links.append({
 58                        "text": match.group(1),
 59                        "target": reference_defs[ref_name],
 60                        "line": line_num
 61                    })
 62
 63        return links
 64
 65def generate_test_content(num_lines: int, links_per_100_lines: int = 10) -> str:
 66    """Generate test Markdown content with specified characteristics."""
 67    lines = []
 68    for i in range(num_lines):
 69        if i % (100 // links_per_100_lines) == 0:
 70            # Add an inline link
 71            lines.append(f"Check out [Link {i}](https://example.com/page{i}) for details.")
 72        elif i % 50 == 0:
 73            # Add a code block
 74            lines.append("```python")
 75            lines.append(f"# This is code, links here [should](/python-advanced/05-c-extensions/case-studies/cython-markdown/be/ignored)")
 76            lines.append("```")
 77        else:
 78            # Regular text
 79            lines.append(f"This is line {i} with some regular text content.")
 80
 81    return '\n'.join(lines)
 82
 83def benchmark(func: Callable, content: str, iterations: int = 100) -> dict:
 84    """Run benchmark and return statistics."""
 85    times = []
 86
 87    # Warmup
 88    for _ in range(5):
 89        func(content)
 90
 91    # Actual benchmark
 92    for _ in range(iterations):
 93        start = time.perf_counter()
 94        result = func(content)
 95        end = time.perf_counter()
 96        times.append(end - start)
 97
 98    return {
 99        "mean": statistics.mean(times) * 1000,  # Convert to ms
100        "stdev": statistics.stdev(times) * 1000,
101        "min": min(times) * 1000,
102        "max": max(times) * 1000,
103        "links_found": len(result),
104    }
105
106def main():
107    print("=" * 60)
108    print("Markdown Link Parser Benchmark")
109    print("=" * 60)
110
111    # Test different content sizes
112    sizes = [1000, 5000, 10000, 50000]
113
114    python_parser = PythonMarkdownParser()
115
116    # Try to import Cython version
117    try:
118        from markdown_parser import parse_markdown_links as cython_parse
119        has_cython = True
120    except ImportError:
121        print("\nWarning: Cython module not found.")
122        print("Run 'python setup.py build_ext --inplace' first.\n")
123        has_cython = False
124
125    for size in sizes:
126        print(f"\n--- Content size: {size} lines ---")
127        content = generate_test_content(size)
128
129        # Python benchmark
130        py_result = benchmark(python_parser.parse_markdown_links, content)
131        print(f"Python:  {py_result['mean']:.3f} ms (+/- {py_result['stdev']:.3f} ms)")
132        print(f"         Found {py_result['links_found']} links")
133
134        # Cython benchmark (if available)
135        if has_cython:
136            cy_result = benchmark(cython_parse, content)
137            speedup = py_result['mean'] / cy_result['mean']
138            print(f"Cython:  {cy_result['mean']:.3f} ms (+/- {cy_result['stdev']:.3f} ms)")
139            print(f"         Speedup: {speedup:.2f}x")
140
141    print("\n" + "=" * 60)
142
143if __name__ == "__main__":
144    main()

 1============================================================
 2Markdown Link Parser Benchmark
 3============================================================
 4
 5--- Content size: 1000 lines ---
 6Python:  0.523 ms (+/- 0.031 ms)
 7         Found 100 links
 8Cython:  0.198 ms (+/- 0.012 ms)
 9         Speedup: 2.64x
10
11--- Content size: 5000 lines ---
12Python:  2.617 ms (+/- 0.089 ms)
13         Found 500 links
14Cython:  0.892 ms (+/- 0.045 ms)
15         Speedup: 2.93x
16
17--- Content size: 10000 lines ---
18Python:  5.234 ms (+/- 0.156 ms)
19         Found 1000 links
20Cython:  1.712 ms (+/- 0.078 ms)
21         Speedup: 3.06x
22
23--- Content size: 50000 lines ---
24Python:  26.18 ms (+/- 0.823 ms)
25         Found 5000 links
26Cython:  7.89 ms (+/- 0.312 ms)
27         Speedup: 3.32x
28
29============================================================

 1# advanced_parser.pyx
 2"""
 3Advanced parser using PCRE2 C library for maximum performance.
 4
 5Requires: libpcre2-dev (Ubuntu) or pcre2 (macOS Homebrew)
 6"""
 7
 8cdef extern from "pcre2.h":
 9    # PCRE2 declarations...
10    pass
11
12# This is an advanced topic, see PCRE2 documentation for details

 1如果 Cython 不適合你的情境，考慮：
 2
 31. PyPy
 4   - 無需修改程式碼
 5   - JIT 編譯帶來 5-10x 加速
 6   - 但相容性問題較多
 7
 82. Numba
 9   - 針對數值計算優化
10   - 使用裝飾器即可加速
11   - 但僅支援部分 Python 語法
12
133. 演算法優化
14   - 先檢查是否有更好的演算法
15   - 減少不必要的記憶體分配
16   - 使用更高效的資料結構

 1# exercise_1.py
 2def count_words(text: str) -> dict:
 3    """Count word frequencies in text."""
 4    words = text.lower().split()
 5    counts = {}
 6    for word in words:
 7        word = word.strip('.,!?;:')
 8        if word:
 9            counts[word] = counts.get(word, 0) + 1
10    return counts

 1# exercise_2.py
 2import cProfile
 3import pstats
 4
 5def profile_parsers(content: str):
 6    """Profile both Python and Cython parsers."""
 7    from markdown_parser import parse_markdown_links as cython_parse
 8
 9    python_parser = PythonMarkdownParser()
10
11    # Profile Python version
12    print("=== Python Version ===")
13    cProfile.runctx(
14        'for _ in range(100): python_parser.parse_markdown_links(content)',
15        globals(), locals(),
16        'python_stats'
17    )
18    stats = pstats.Stats('python_stats')
19    stats.strip_dirs().sort_stats('cumulative').print_stats(10)
20
21    # Profile Cython version
22    print("\n=== Cython Version ===")
23    cProfile.runctx(
24        'for _ in range(100): cython_parse(content)',
25        globals(), locals(),
26        'cython_stats'
27    )
28    stats = pstats.Stats('cython_stats')
29    stats.strip_dirs().sort_stats('cumulative').print_stats(10)

 1import re
 2from typing import List, Dict
 3
 4class MarkdownLinkChecker:
 5    """Markdown 連結檢查器"""
 6
 7    # Markdown 連結正則表達式
 8    # 匹配 [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target) 格式，排除圖片 ![alt](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/src)
 9    INLINE_LINK_PATTERN = re.compile(
10        r'(?<!!)\[([^\]]+)\]\(([^)]+)\)'
11    )
12
13    # 引用式連結定義 [ref]: target
14    REFERENCE_DEF_PATTERN = re.compile(
15        r'^\s*\[([^\]]+)\]:\s*(.+)$',
16        re.MULTILINE
17    )
18
19    # 引用式連結使用 [text][ref]
20    REFERENCE_USE_PATTERN = re.compile(
21        r'\[([^\]]+)\]\[([^\]]+)\]'
22    )
23
24    def parse_markdown_links(self, content: str) -> List[Dict]:
25        """
26        解析 Markdown 內容中的所有連結
27
28        Args:
29            content: Markdown 內容
30
31        Returns:
32            list[dict]: 連結列表，每個包含 text, target, line
33        """
34        links = []
35        lines = content.split('\n')
36
37        # 首先收集引用式連結定義
38        reference_defs = {}
39        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
40            ref_name = match.group(1).lower()
41            ref_target = match.group(2).strip()
42            reference_defs[ref_name] = ref_target
43
44        # 追蹤是否在程式碼區塊內
45        in_code_block = False
46
47        # 解析行內連結
48        for line_num, line in enumerate(lines, start=1):
49            # 檢查程式碼區塊開始/結束
50            if line.strip().startswith("```"):
51                in_code_block = not in_code_block
52                continue
53
54            # 跳過程式碼區塊內的連結
55            if in_code_block:
56                continue
57
58            # 行內連結 [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target)
59            for match in self.INLINE_LINK_PATTERN.finditer(line):
60                links.append({
61                    "text": match.group(1),
62                    "target": match.group(2),
63                    "line": line_num
64                })
65
66            # 引用式連結 [text][ref]
67            for match in self.REFERENCE_USE_PATTERN.finditer(line):
68                ref_name = match.group(2).lower()
69                if ref_name in reference_defs:
70                    links.append({
71                        "text": match.group(1),
72                        "target": reference_defs[ref_name],
73                        "line": line_num
74                    })
75
76        return links

 1# 安裝 maturin（如果尚未安裝）
 2pip install maturin
 3
 4# 建立新專案
 5mkdir markdown_parser_rs
 6cd markdown_parser_rs
 7
 8# 初始化 maturin 專案（選擇 pyo3 作為綁定）
 9maturin init --bindings pyo3
10
11# 專案結構如下：
12# markdown_parser_rs/
13# ├── Cargo.toml
14# ├── pyproject.toml
15# └── src/
16#     └── lib.rs

 1[package]
 2name = "markdown_parser_rs"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "markdown_parser_rs"
 8crate-type = ["cdylib"]
 9
10[dependencies]
11pyo3 = { version = "0.22", features = ["extension-module"] }
12regex = "1.11"
13once_cell = "1.20"

 1// src/lib.rs
 2use once_cell::sync::Lazy;
 3use regex::Regex;
 4use std::collections::HashMap;
 5
 6/// Represents a parsed markdown link
 7#[derive(Debug, Clone)]
 8pub struct MarkdownLink {
 9    pub text: String,
10    pub target: String,
11    pub line: usize,
12}
13
14// Pre-compiled regex patterns (compile once, use many times)
15static INLINE_LINK_PATTERN: Lazy<Regex> = Lazy::new(|| {
16    // Match [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target), excluding images ![alt](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/src)
17    Regex::new(r"(?<!!)\[([^\]]+)\]\(([^)]+)\)").unwrap()
18});
19
20static REFERENCE_DEF_PATTERN: Lazy<Regex> = Lazy::new(|| {
21    // Match [ref]: target
22    Regex::new(r"(?m)^\s*\[([^\]]+)\]:\s*(.+)$").unwrap()
23});
24
25static REFERENCE_USE_PATTERN: Lazy<Regex> = Lazy::new(|| {
26    // Match [text][ref]
27    Regex::new(r"\[([^\]]+)\]\[([^\]]+)\]").unwrap()
28});
29
30/// Parse markdown content and extract all links
31pub fn parse_links(content: &str) -> Vec<MarkdownLink> {
32    let mut links = Vec::new();
33
34    // First, collect reference definitions
35    let mut reference_defs: HashMap<String, String> = HashMap::new();
36    for cap in REFERENCE_DEF_PATTERN.captures_iter(content) {
37        let ref_name = cap[1].to_lowercase();
38        let ref_target = cap[2].trim().to_string();
39        reference_defs.insert(ref_name, ref_target);
40    }
41
42    // Track code block state
43    let mut in_code_block = false;
44
45    // Parse line by line
46    for (line_num, line) in content.lines().enumerate() {
47        let line_number = line_num + 1; // 1-indexed
48
49        // Check for code block markers
50        if line.trim_start().starts_with("```") {
51            in_code_block = !in_code_block;
52            continue;
53        }
54
55        // Skip content inside code blocks
56        if in_code_block {
57            continue;
58        }
59
60        // Parse inline links [text](/python-advanced/06-rust-extensions/case-studies/pyo3-parser/target)
61        for cap in INLINE_LINK_PATTERN.captures_iter(line) {
62            links.push(MarkdownLink {
63                text: cap[1].to_string(),
64                target: cap[2].to_string(),
65                line: line_number,
66            });
67        }
68
69        // Parse reference links [text][ref]
70        for cap in REFERENCE_USE_PATTERN.captures_iter(line) {
71            let ref_name = cap[2].to_lowercase();
72            if let Some(target) = reference_defs.get(&ref_name) {
73                links.push(MarkdownLink {
74                    text: cap[1].to_string(),
75                    target: target.clone(),
76                    line: line_number,
77                });
78            }
79        }
80    }
81
82    links
83}

  1use pyo3::prelude::*;
  2use pyo3::types::PyDict;
  3
  4/// Python-visible link structure
  5#[pyclass]
  6#[derive(Clone)]
  7pub struct PyMarkdownLink {
  8    #[pyo3(get)]
  9    pub text: String,
 10    #[pyo3(get)]
 11    pub target: String,
 12    #[pyo3(get)]
 13    pub line: usize,
 14}
 15
 16#[pymethods]
 17impl PyMarkdownLink {
 18    fn __repr__(&self) -> String {
 19        format!(
 20            "MarkdownLink(text='{}', target='{}', line={})",
 21            self.text, self.target, self.line
 22        )
 23    }
 24
 25    /// Convert to Python dict for compatibility
 26    fn to_dict<'py>(&self, py: Python<'py>) -> Bound<'py, PyDict> {
 27        let dict = PyDict::new(py);
 28        dict.set_item("text", &self.text).unwrap();
 29        dict.set_item("target", &self.target).unwrap();
 30        dict.set_item("line", self.line).unwrap();
 31        dict
 32    }
 33}
 34
 35impl From<MarkdownLink> for PyMarkdownLink {
 36    fn from(link: MarkdownLink) -> Self {
 37        PyMarkdownLink {
 38            text: link.text,
 39            target: link.target,
 40            line: link.line,
 41        }
 42    }
 43}
 44
 45/// Parse markdown content and return list of links as objects
 46#[pyfunction]
 47fn parse_markdown_links(content: &str) -> Vec<PyMarkdownLink> {
 48    parse_links(content)
 49        .into_iter()
 50        .map(PyMarkdownLink::from)
 51        .collect()
 52}
 53
 54/// Parse markdown content and return list of links as dicts
 55/// (for drop-in compatibility with existing Python code)
 56#[pyfunction]
 57fn parse_markdown_links_as_dicts<'py>(
 58    py: Python<'py>,
 59    content: &str,
 60) -> Vec<Bound<'py, PyDict>> {
 61    parse_links(content)
 62        .into_iter()
 63        .map(|link| {
 64            let dict = PyDict::new(py);
 65            dict.set_item("text", link.text).unwrap();
 66            dict.set_item("target", link.target).unwrap();
 67            dict.set_item("line", link.line).unwrap();
 68            dict
 69        })
 70        .collect()
 71}
 72
 73/// Filter out external links, keeping only internal links
 74#[pyfunction]
 75fn filter_internal_links(links: Vec<PyMarkdownLink>) -> Vec<PyMarkdownLink> {
 76    links
 77        .into_iter()
 78        .filter(|link| {
 79            let target = &link.target;
 80            // Skip pure anchor links
 81            if target.starts_with('#') {
 82                return false;
 83            }
 84            // Skip external links
 85            if target.starts_with("http://")
 86                || target.starts_with("https://")
 87                || target.starts_with("mailto:")
 88                || target.starts_with("tel:")
 89                || target.starts_with("ftp://")
 90            {
 91                return false;
 92            }
 93            true
 94        })
 95        .collect()
 96}
 97
 98/// Python module definition
 99#[pymodule]
100fn markdown_parser_rs(m: &Bound<'_, PyModule>) -> PyResult<()> {
101    m.add_class::<PyMarkdownLink>()?;
102    m.add_function(wrap_pyfunction!(parse_markdown_links, m)?)?;
103    m.add_function(wrap_pyfunction!(parse_markdown_links_as_dicts, m)?)?;
104    m.add_function(wrap_pyfunction!(filter_internal_links, m)?)?;
105    Ok(())
106}