{"record":{"id":"167a2461c18cc3d3","repo":"cocoindex-io/cocoindex","slug":"filematch-ast-is-deprecated-use-filematch-source","errorCode":null,"errorMessage":"FileMatch.ast is deprecated; use FileMatch.source (and .text for the file content)","messagePattern":"FileMatch\\.ast is deprecated; use FileMatch\\.source \\(and \\.text for the file content\\)","errorType":"console","errorClass":"DeprecationWarning","httpStatus":null,"severity":"warning","filePath":"python/cocoindex/ops/code.py","lineNumber":198,"sourceCode":"    \"\"\"The result of :meth:`CodePattern.match_file`: the parsed source and the\n    matches found in one file. The file content is ``file_match.source.text``.\"\"\"\n\n    path: str\n    \"\"\"The path that was matched.\"\"\"\n\n    source: CodeSource\n    \"\"\"The parsed source (its AST is already cached — reuse it to split or match\n    more patterns without re-parsing).\"\"\"\n\n    matches: list[CodeMatch]\n    \"\"\"The matches found (always at least one — ``match_file`` returns ``None``\n    when there are none).\"\"\"\n\n    @property\n    def ast(self) -> CodeSource:\n        \"\"\"Deprecated alias of :attr:`source` (the field's name when it held the\n        removed ``CodeAst`` class); use ``.source``.\"\"\"\n        _warnings.warn(\n            \"FileMatch.ast is deprecated; use FileMatch.source \"\n            \"(and .text for the file content)\",\n            DeprecationWarning,\n            stacklevel=2,\n        )\n        return self.source\n\n\ndef match_code(\n    pattern: str, source: \"str | CodeSource\", language: str | None = None\n) -> list[CodeMatch]:\n    r\"\"\"One-shot: match ``pattern`` against ``source`` and return all matches.\n\n    ``source`` is a ``str`` (with ``language`` required) or a :class:`CodeSource`\n    (whose cached parse is reused; ``language`` must be omitted). Prefer a\n    :class:`CodePattern` when matching the same pattern across many sources —\n    this recompiles the pattern per call.\"\"\"\n    if isinstance(source, CodeSource):","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/ops/code.py#L180-L216","documentation":"FileMatch.ast is a deprecated property alias for FileMatch.source, kept because the field was named .ast when the removed CodeAst class existed. Accessing it warns with DeprecationWarning and returns the CodeSource; the file content is on .source.text.","triggerScenarios":"Accessing the .ast property on a FileMatch returned by CodePattern.match_source / match_code.","commonSituations":"Old code iterating code-pattern matches via match.ast that predates the CodeAst→CodeSource rename, triggering the DeprecationWarning after upgrading.","solutions":["Replace file_match.ast with file_match.source.","Read the file content via file_match.source.text instead of assuming .ast holds parsed AST data.","Grep for '.ast' on match results and migrate all usages."],"exampleFix":"// before\nsrc = m.ast\ntext = m.ast.text\n// after\nsrc = m.source\ntext = m.source.text","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"def match_text(m: FileMatch) -> str:\n    return m.source.text","tryCatchPattern":"import warnings\nwith warnings.catch_warnings():\n    warnings.filterwarnings(\"ignore\", message=\"FileMatch.ast is deprecated\", category=DeprecationWarning)\n    src = legacy_match_field(m)","preventionTips":["Use FileMatch.source (and .source.text) exclusively in new code.","Enable DeprecationWarning-as-error in CI to catch alias usage.","After upgrading, grep for '.ast' on code-match results and migrate."],"tags":["deprecation","python","api-migration","text-processing"],"backgroundTag":"deprecated-api-usage","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}