python-docs-mcp-server 0.1.2__py3-none-any.whl

mcp_server_python_docs/data/synonyms.yaml

@@ -0,0 +1,194 @@
+# Python stdlib concept synonym/expansion table
+# Format: concept: [expansion terms]
+# Used for query expansion before FTS5 search
+# ~150 curated entries covering major Python stdlib concepts
+
+# Concurrency & Parallelism
+parallel: [concurrent, multiprocessing, threading, asyncio, concurrent.futures, parallel execution]
+async: [asyncio, await, coroutine, async for, async with, event loop, asynchronous]
+threading: [thread, threading, Thread, Lock, RLock, Semaphore, Barrier, Event, Condition]
+multiprocessing: [multiprocessing, Process, Pool, Queue, Pipe, shared memory]
+concurrent: [concurrent.futures, ThreadPoolExecutor, ProcessPoolExecutor, Future, Executor]
+subprocess: [subprocess, subprocess.run, subprocess.Popen, shlex, shell command]
+event loop: [asyncio, asyncio.run, asyncio.get_event_loop, AbstractEventLoop]
+coroutine: [asyncio, async def, await, coroutine, Task, gather]
+task group: [asyncio.TaskGroup, asyncio.gather, asyncio.wait, task management]
+synchronization: [Lock, RLock, Semaphore, Event, Condition, Barrier, threading]
+future: [concurrent.futures, Future, asyncio.Future, result, exception]
+
+# Data Serialization
+json: [json, json.loads, json.dumps, json.load, json.dump, JSON parsing]
+parse json: [json, json.loads, json.load, JSON decoding]
+serialize json: [json, json.dumps, json.dump, JSON encoding]
+csv: [csv, csv.reader, csv.writer, csv.DictReader, csv.DictWriter, delimiter]
+xml: [xml, xml.etree.ElementTree, xml.dom, xml.sax, XML parsing]
+html parsing: [html.parser, HTMLParser, html, html.entities]
+serialization: [json, marshal, object serialization, data format]
+struct: [struct, struct.pack, struct.unpack, binary data, byte packing]
+base64: [base64, base64.b64encode, base64.b64decode, encoding]
+configparser: [configparser, ConfigParser, ini file, configuration]
+toml: [tomllib, tomllib.load, TOML parsing]
+
+# File System & I/O
+file io: [open, pathlib, os.path, io, shutil, fileinput, file reading, file writing]
+path: [pathlib, pathlib.Path, os.path, path manipulation, file path]
+pathlib: [pathlib, Path, PurePath, PosixPath, WindowsPath]
+temp files: [tempfile, TemporaryFile, NamedTemporaryFile, mkdtemp, temporary]
+glob: [glob, glob.glob, fnmatch, pattern matching, file search]
+shutil: [shutil, shutil.copy, shutil.move, shutil.rmtree, file operations]
+directory: [os, os.listdir, os.scandir, os.walk, pathlib, directory listing]
+file copy: [shutil.copy, shutil.copy2, shutil.copytree, file duplication]
+file delete: [os.remove, os.unlink, shutil.rmtree, pathlib.Path.unlink]
+read file: [open, read, readline, readlines, pathlib.Path.read_text]
+write file: [open, write, writelines, pathlib.Path.write_text]
+binary io: [io, io.BytesIO, io.BufferedReader, io.BufferedWriter, binary]
+text io: [io, io.StringIO, io.TextIOWrapper, text stream]
+
+# Networking & Web
+http: [http, http.client, http.server, urllib, urllib.request, HTTP]
+http requests: [urllib, http.client, urllib.request, urllib.parse, URL fetch]
+socket: [socket, socket.socket, TCP, UDP, network programming]
+ssl: [ssl, ssl.create_default_context, TLS, certificate, HTTPS]
+email: [email, email.message, smtplib, imaplib, email parsing]
+url: [urllib, urllib.parse, urlparse, urlencode, URL manipulation]
+ftp: [ftplib, FTP, file transfer]
+http server: [http.server, HTTPServer, SimpleHTTPRequestHandler]
+url parsing: [urllib.parse, urlparse, urljoin, quote, unquote]
+ip address: [ipaddress, IPv4Address, IPv6Address, ip_network]
+
+# Text Processing
+string: [str, string, string formatting, string methods, text]
+string formatting: [str.format, f-string, format, printf, string interpolation]
+regex: [re, regular expression, pattern, re.match, re.search, re.findall, re.sub]
+text processing: [string, textwrap, difflib, unicodedata, text manipulation]
+unicode: [unicodedata, codecs, encoding, utf-8, character, codepoint]
+encoding: [codecs, encode, decode, utf-8, ascii, latin-1, chardet]
+template: [string.Template, string formatting, placeholder]
+textwrap: [textwrap, textwrap.wrap, textwrap.dedent, text wrapping]
+difflib: [difflib, SequenceMatcher, unified_diff, context_diff]
+translate: [str.translate, str.maketrans, character mapping]
+
+# Data Structures
+list: [list, append, extend, insert, sort, sorted, sequence]
+dict: [dict, dictionary, mapping, keys, values, items, defaultdict]
+set: [set, frozenset, intersection, union, difference, symmetric_difference]
+tuple: [tuple, namedtuple, immutable sequence]
+collections: [collections, deque, defaultdict, OrderedDict, Counter, ChainMap, namedtuple]
+deque: [collections.deque, double-ended queue, appendleft, popleft]
+counter: [collections.Counter, counting, most_common, frequency]
+defaultdict: [collections.defaultdict, default factory, missing key]
+ordered dict: [collections.OrderedDict, ordered dictionary, insertion order]
+named tuple: [collections.namedtuple, typing.NamedTuple, named fields]
+array: [array, array.array, typed array, numeric array]
+queue: [queue, Queue, LifoQueue, PriorityQueue, SimpleQueue]
+heap: [heapq, heappush, heappop, priority queue, heap]
+bisect: [bisect, bisect_left, bisect_right, insort, sorted insertion]
+chain map: [collections.ChainMap, nested scopes, mapping chain]
+
+# Date & Time
+date time: [datetime, time, calendar, zoneinfo, timedelta, timezone]
+datetime: [datetime, datetime.datetime, datetime.date, datetime.time, datetime.timedelta]
+time: [time, time.time, time.sleep, time.monotonic, time.perf_counter]
+calendar: [calendar, calendar.month, weekday, leap year]
+timezone: [zoneinfo, ZoneInfo, timezone, datetime.timezone, UTC]
+timedelta: [datetime.timedelta, time difference, duration]
+
+# Type System
+type hint: [typing, annotation, generic, TypeVar, Protocol, Union, Optional]
+typing: [typing, List, Dict, Set, Tuple, Optional, Union, Any, Generic]
+protocol: [typing.Protocol, structural subtyping, duck typing, ABC]
+generic: [typing.Generic, TypeVar, ParamSpec, type variable]
+dataclass: [dataclasses, dataclass, field, asdict, astuple]
+enum: [enum, Enum, IntEnum, Flag, auto, enumeration]
+abstract: [abc, ABC, abstractmethod, abstract base class]
+type checking: [typing, TYPE_CHECKING, runtime type, mypy, pyright]
+annotated: [typing.Annotated, type annotation, metadata]
+type alias: [typing.TypeAlias, type, NewType]
+
+# Testing
+testing: [unittest, pytest, mock, doctest, unittest.mock, test]
+unittest: [unittest, TestCase, setUp, tearDown, assert, test runner]
+mock: [unittest.mock, Mock, MagicMock, patch, side_effect]
+doctest: [doctest, doctest.testmod, interactive example, docstring test]
+assert: [assert, assertEqual, assertTrue, assertRaises, assertion]
+
+# Math & Numbers
+math: [math, math.sqrt, math.ceil, math.floor, math.log, mathematics]
+decimal: [decimal, Decimal, precision, rounding, financial]
+fractions: [fractions, Fraction, rational number, numerator, denominator]
+random: [random, random.choice, random.randint, random.shuffle, random.sample]
+statistics: [statistics, mean, median, stdev, variance, statistical]
+complex: [complex, cmath, complex number, imaginary]
+number: [int, float, complex, decimal, fractions, numeric]
+infinity: [math.inf, float inf, math.isinf, infinite]
+
+# Functional Programming
+itertools: [itertools, chain, product, permutations, combinations, cycle, repeat]
+functools: [functools, lru_cache, partial, reduce, wraps, total_ordering]
+operator: [operator, itemgetter, attrgetter, methodcaller, operator overloading]
+contextlib: [contextlib, contextmanager, suppress, redirect_stdout, ExitStack]
+context manager: [contextlib, with statement, __enter__, __exit__, contextmanager]
+decorator: [functools.wraps, decorator pattern, wrapper function]
+lambda: [lambda, anonymous function, inline function]
+map filter: [map, filter, reduce, list comprehension, generator expression]
+partial: [functools.partial, partial application, currying]
+cache: [functools.lru_cache, functools.cache, memoization, caching]
+
+# OS & System
+os: [os, os.path, os.environ, os.getcwd, operating system]
+platform: [platform, sys.platform, os.name, system information]
+signal: [signal, signal.signal, SIGINT, SIGTERM, signal handler]
+environment: [os.environ, os.getenv, environment variable, env]
+process: [os, os.getpid, os.fork, multiprocessing, process management]
+permissions: [os.chmod, os.chown, stat, file permissions, access]
+system info: [platform, sys, os.uname, machine, processor]
+working directory: [os.getcwd, os.chdir, pathlib.Path.cwd]
+symlink: [os.symlink, os.readlink, symbolic link, pathlib.Path.symlink_to]
+
+# Debugging & Inspection
+logging: [logging, logger, getLogger, basicConfig, log level, handler]
+warnings: [warnings, warn, DeprecationWarning, filter, simplefilter]
+traceback: [traceback, traceback.format_exc, traceback.print_exc, stack trace]
+pdb: [pdb, breakpoint, debugger, pdb.set_trace, step, continue]
+inspect: [inspect, inspect.signature, inspect.getmembers, introspection]
+ast: [ast, abstract syntax tree, ast.parse, ast.dump, code analysis]
+dis: [dis, disassemble, bytecode, opcode, instruction]
+gc: [gc, garbage collector, gc.collect, gc.get_objects, memory]
+tracemalloc: [tracemalloc, memory tracking, memory leak, allocation]
+profiling: [cProfile, profile, pstats, timeit, performance measurement]
+weakref: [weakref, WeakRef, weak reference, reference counting]
+
+# Security & Cryptography
+hashlib: [hashlib, md5, sha256, sha512, hash, digest, checksum]
+secrets: [secrets, token_hex, token_urlsafe, secure random, password]
+hmac: [hmac, message authentication, HMAC, digest, signature]
+password: [hashlib, secrets, password hashing, salt]
+
+# CLI & Arguments
+argparse: [argparse, ArgumentParser, add_argument, parse_args, command line]
+command line: [argparse, sys.argv, click, CLI, command line interface]
+getopt: [getopt, option parsing, command line options]
+shlex: [shlex, shlex.split, shell parsing, command splitting]
+
+# Compression & Archives
+zip: [zipfile, ZipFile, compression, archive, extract]
+tar: [tarfile, TarFile, tar archive, gzip, bzip2]
+gzip: [gzip, GzipFile, compression, decompress]
+compression: [zlib, gzip, bz2, lzma, compress, decompress]
+
+# Copy & Comparison
+copy: [copy, copy.copy, copy.deepcopy, shallow copy, deep copy]
+comparison: [operator, functools.total_ordering, __eq__, __lt__, rich comparison]
+pprint: [pprint, pprint.pprint, pretty print, formatted output]
+repr: [repr, __repr__, __str__, string representation]
+
+# Internationalization
+locale: [locale, localization, number format, currency format]
+gettext: [gettext, translation, internationalization, i18n]
+
+# Networking Protocols
+xmlrpc: [xmlrpc, xmlrpc.client, xmlrpc.server, RPC, remote procedure call]
+
+# Database
+sqlite: [sqlite3, sqlite3.connect, SQL, database, cursor, execute]
+dbm: [dbm, dbm.open, key-value store, persistent dictionary]

mcp_server_python_docs/detection.py

@@ -0,0 +1,82 @@
+"""Python version detection from the user's environment.
+
+Probes multiple sources to determine which Python version the user
+is working with, so the server can default to the right documentation.
+
+Detection order:
+1. .python-version file in cwd (pyenv, mise, rtx convention)
+2. ``python3 --version`` in PATH (user's active interpreter)
+3. ``sys.version_info`` (server's own runtime — last resort)
+"""
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_VERSION_RE = re.compile(r"(\d+\.\d+)")
+
+
+def _parse_major_minor(raw: str) -> str | None:
+    """Extract 'X.Y' from a version string like '3.13.2', 'Python 3.13.2', 'cpython-3.13'."""
+    m = _VERSION_RE.search(raw)
+    return m.group(1) if m else None
+
+
+def detect_python_version() -> tuple[str, str]:
+    """Detect the user's Python version.
+
+    Returns:
+        Tuple of (major_minor, source) where major_minor is like '3.13'
+        and source describes how it was detected.
+    """
+    # 1. .python-version file (pyenv / mise / rtx)
+    pv_file = Path.cwd() / ".python-version"
+    if pv_file.is_file():
+        try:
+            first_line = pv_file.read_text().strip().splitlines()[0].strip()
+            version = _parse_major_minor(first_line)
+            if version:
+                logger.info("Detected Python %s from .python-version", version)
+                return version, ".python-version file"
+        except Exception:
+            pass
+
+    # 2. python3 --version in PATH
+    try:
+        result = subprocess.run(
+            ["python3", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            version = _parse_major_minor(result.stdout.strip())
+            if version:
+                logger.info("Detected Python %s from python3 in PATH", version)
+                return version, "python3 in PATH"
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        pass
+
+    # 3. Server's own runtime
+    version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    logger.info("Using server runtime Python %s as fallback", version)
+    return version, "server runtime"
+
+
+def match_to_indexed(
+    detected: str, indexed_versions: list[str]
+) -> str | None:
+    """Match a detected version to the closest indexed version.
+
+    Returns the detected version if it's in the index, otherwise None.
+    We don't guess -- if a detected version is not indexed, return None and
+    let the normal default resolution handle it.
+    """
+    if detected in indexed_versions:
+        return detected
+    return None

mcp_server_python_docs/diagnostics.py

@@ -0,0 +1,74 @@
+"""Environment diagnostics shared by CLI health checks."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DiagnosticResult:
+    """Result for a single environment diagnostic probe."""
+
+    passed: bool
+    detail: str
+
+
+def _combined_output_excerpt(stdout: str, stderr: str, limit: int = 500) -> str:
+    combined = "\n".join(part.strip() for part in (stderr, stdout) if part.strip())
+    if len(combined) <= limit:
+        return combined
+    return combined[-limit:]
+
+
+def check_build_venv_support(
+    python_executable: str | None = None,
+    timeout: float = 10.0,
+) -> DiagnosticResult:
+    """Check that build-index can create pip-enabled Sphinx environments.
+
+    ``build-index`` creates a disposable Sphinx virtual environment with pip.
+    Debian/Ubuntu hosts without the matching ``pythonX.Y-venv`` package can run
+    the server but fail when that environment needs ``ensurepip``.
+    """
+    executable = python_executable or sys.executable
+    package_name = f"python{sys.version_info.major}.{sys.version_info.minor}-venv"
+    command = [executable, "-c", "import ensurepip; import venv"]
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        return DiagnosticResult(
+            passed=False,
+            detail=f"{executable} not found; build-index cannot create Sphinx venvs",
+        )
+    except subprocess.TimeoutExpired:
+        return DiagnosticResult(
+            passed=False,
+            detail=(
+                f"{executable} timed out while checking venv/ensurepip support "
+                "for build-index"
+            ),
+        )
+
+    if result.returncode == 0:
+        return DiagnosticResult(
+            passed=True,
+            detail=f"{executable} has venv and ensurepip available for build-index",
+        )
+
+    detail = (
+        f"{executable} cannot import venv/ensurepip; build-index needs them to "
+        "create Sphinx venvs. On Debian/Ubuntu, install "
+        f"{package_name} for this interpreter."
+    )
+    output = _combined_output_excerpt(result.stdout, result.stderr)
+    if output:
+        detail = f"{detail} Output: {output}"
+
+    return DiagnosticResult(passed=False, detail=detail)

mcp_server_python_docs/errors.py

@@ -0,0 +1,33 @@
+"""Error taxonomy for python-docs-mcp-server.
+
+Named exceptions for predictable failure modes, mapped to MCP error responses.
+See build guide section 10.
+"""
+
+
+class DocsServerError(Exception):
+    """Base error for all docs server errors."""
+
+
+class VersionNotFoundError(DocsServerError):
+    """Requested Python version not found in index."""
+
+
+class SymbolNotFoundError(DocsServerError):
+    """Requested symbol not found in index."""
+
+
+class PageNotFoundError(DocsServerError):
+    """Requested page/slug not found in index."""
+
+
+class IndexNotBuiltError(DocsServerError):
+    """No index.db found at expected cache path."""
+
+
+class IngestionError(DocsServerError):
+    """Error during index building/ingestion."""
+
+
+class FTS5UnavailableError(DocsServerError):
+    """SQLite FTS5 extension not available in this build."""

mcp_server_python_docs/ingestion/__init__.py

@@ -0,0 +1 @@
+"""Ingestion layer: objects.inv parsing and content ingestion."""

mcp_server_python_docs/ingestion/cpython_versions.py

@@ -0,0 +1,32 @@
+"""Pinned CPython documentation build targets."""
+from __future__ import annotations
+
+from typing import Final, TypedDict
+
+
+class CPythonDocsBuildConfig(TypedDict):
+    """Build settings for one CPython documentation release."""
+
+    tag: str
+    sphinx_pin: str
+
+
+SUPPORTED_DOC_VERSIONS: Final[tuple[str, ...]] = (
+    "3.10",
+    "3.11",
+    "3.12",
+    "3.13",
+    "3.14",
+)
+
+SUPPORTED_DOC_VERSIONS_CSV: Final[str] = ",".join(SUPPORTED_DOC_VERSIONS)
+
+# CPython git tags are pinned so content builds are reproducible and do not
+# drift when a maintenance branch receives new commits.
+CPYTHON_DOCS_BUILD_CONFIG: Final[dict[str, CPythonDocsBuildConfig]] = {
+    "3.10": {"tag": "v3.10.20", "sphinx_pin": "sphinx==3.4.3"},
+    "3.11": {"tag": "v3.11.15", "sphinx_pin": "sphinx~=7.2.0"},
+    "3.12": {"tag": "v3.12.13", "sphinx_pin": "sphinx~=8.2.0"},
+    "3.13": {"tag": "v3.13.13", "sphinx_pin": "sphinx<9.0.0"},
+    "3.14": {"tag": "v3.14.4", "sphinx_pin": "sphinx<9.0.0"},
+}

mcp_server_python_docs/ingestion/inventory.py

@@ -0,0 +1,178 @@
+"""Ingest symbols from Python docs objects.inv via sphobjinv."""
+from __future__ import annotations
+
+import logging
+import sqlite3
+
+import sphobjinv as soi
+
+from mcp_server_python_docs.storage.db import bootstrap_schema
+
+logger = logging.getLogger(__name__)
+
+# Priority ordering for duplicate symbol resolution (INGR-I-05)
+# Lower number = higher priority
+ROLE_PRIORITY: dict[str, int] = {
+    "class": 0,
+    "exception": 1,
+    "function": 2,
+    "method": 3,
+    "attribute": 4,
+    "data": 5,
+    "module": 6,
+}
+
+
+def _expand_uri(obj: soi.DataObjStr) -> str:
+    """Expand $ shorthand in URI to full qualified name (INGR-I-03).
+
+    objects.inv uses $ as shorthand for the object name.
+    E.g., uri="library/asyncio-task.html#$" with name="asyncio.TaskGroup"
+    becomes "library/asyncio-task.html#asyncio.TaskGroup"
+    """
+    uri: str = obj.uri  # type: ignore[assignment]  # sphobjinv lacks type stubs
+    if "$" in uri:
+        uri = uri.replace("$", obj.name)  # type: ignore[arg-type]
+    return uri
+
+
+def _get_display_name(obj: soi.DataObjStr) -> str:
+    """Get display name, falling back to obj.name when dispname is '-' (INGR-I-04)."""
+    if obj.dispname == "-":  # type: ignore[comparison-overlap]  # sphobjinv lacks stubs
+        return obj.name  # type: ignore[return-value]
+    return obj.dispname  # type: ignore[return-value]
+
+
+def _extract_module(qualified_name: str) -> str | None:
+    """Extract module from qualified name.
+
+    'asyncio.TaskGroup' -> 'asyncio'
+    'json.dumps' -> 'json'
+    'os.path.join' -> 'os.path'
+    """
+    parts = qualified_name.rsplit(".", 1)
+    if len(parts) > 1:
+        return parts[0]
+    return None
+
+
+def _normalize_name(name: str) -> str:
+    """Normalize a symbol name for search.
+
+    Lowercases and strips leading/trailing whitespace.
+    Preserves dots and underscores for identifier matching.
+    """
+    return name.strip().lower()
+
+
+def ingest_inventory(
+    conn: sqlite3.Connection, version: str, *, is_default: bool = False
+) -> int:
+    """Download objects.inv for a Python version and populate symbols.
+
+    Args:
+        conn: Read-write SQLite connection
+        version: Python version string (e.g., "3.13")
+        is_default: Whether this version is the default for queries (MVER-02)
+
+    Returns:
+        Number of symbols inserted
+
+    Steps:
+    1. Bootstrap schema (idempotent)
+    2. Insert/update doc_set for this version
+    3. Download objects.inv via sphobjinv
+    4. Parse each DataObjStr into a symbol row
+    5. Handle duplicates via priority ordering (INGR-I-05)
+    6. Populate symbols_fts in same transaction (INGR-I-06)
+    """
+    # Validate version format first, before any DB writes (WR-02)
+    import re
+
+    if not re.match(r"^\d+\.\d+$", version):
+        from mcp_server_python_docs.errors import IngestionError
+
+        raise IngestionError(f"Invalid version format: {version!r}")
+
+    bootstrap_schema(conn)
+
+    # Upsert doc_set for this version
+    conn.execute(
+        "INSERT OR REPLACE INTO doc_sets "
+        "(source, version, language, label, is_default, base_url) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (
+            "python-docs",
+            version,
+            "en",
+            f"Python {version}",
+            1 if is_default else 0,
+            f"https://docs.python.org/{version}/",
+        ),
+    )
+    doc_set_id = conn.execute(
+        "SELECT id FROM doc_sets "
+        "WHERE source = 'python-docs' AND version = ? AND language = 'en'",
+        (version,),
+    ).fetchone()[0]
+
+    # Clear existing symbols for this doc_set (re-ingestion support)
+    conn.execute("DELETE FROM symbols WHERE doc_set_id = ?", (doc_set_id,))
+
+    # Download and parse objects.inv (INGR-I-01)
+    url = f"https://docs.python.org/{version}/objects.inv"
+    logger.info("Downloading %s...", url)
+    inv = soi.Inventory(url=url)  # type: ignore[call-arg]  # sphobjinv lacks type stubs
+    logger.info("Downloaded %d inventory objects", len(inv.objects))
+
+    # Filter to Python domain objects and collect by qualified_name
+    # for duplicate resolution (INGR-I-05)
+    best_symbols: dict[str, tuple[soi.DataObjStr, int]] = {}
+
+    for obj in inv.objects:
+        if obj.domain != "py":
+            continue
+
+        name = obj.name
+        role = obj.role
+        priority = ROLE_PRIORITY.get(role, 99)
+
+        key = name  # Group by qualified_name for dedup
+        if key not in best_symbols or priority < best_symbols[key][1]:
+            best_symbols[key] = (obj, priority)
+
+    # Insert symbols (INGR-I-02)
+    count = 0
+    for name, (obj, _priority) in best_symbols.items():
+        uri = _expand_uri(obj)
+        module = _extract_module(name)
+        anchor_part = uri.split("#", 1)[1] if "#" in uri else None
+
+        conn.execute(
+            "INSERT OR IGNORE INTO symbols "
+            "(doc_set_id, qualified_name, normalized_name, module, "
+            "symbol_type, uri, anchor) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                doc_set_id,
+                name,
+                _normalize_name(name),
+                module,
+                obj.role,
+                uri,
+                anchor_part,
+            ),
+        )
+        count += 1
+
+    conn.commit()
+
+    # Rebuild symbols_fts from symbols table (INGR-I-06)
+    # For external-content FTS5 tables, use the 'rebuild' command instead of
+    # DELETE + INSERT. The rebuild command re-reads all content from the
+    # content table and repopulates the FTS index atomically.
+    conn.execute("INSERT INTO symbols_fts(symbols_fts) VALUES('rebuild')")
+    conn.commit()
+
+    logger.info("Ingested %d symbols for Python %s", count, version)
+    return count