cocoindex-io/cocoindex · warning · DeprecationWarning

CodeAst is deprecated and now aliases CodeSource; use CodeSo

Error message

CodeAst is deprecated and now aliases CodeSource; use CodeSource with CodePattern.match_source / match_code, RecursiveSplitter.split, and index_terms

What it means

The module-level name CodeAst has been removed/renamed to CodeSource; a module __getattr__ still resolves CodeAst to CodeSource but emits a DeprecationWarning. Its old eager constructor semantics and .matches/.split/.index_terms methods are gone — those operations now live on consumers (CodePattern.match_source/match_code, RecursiveSplitter.split, index_terms).

Source

Thrown at python/cocoindex/ops/code.py:330

            summary=seg.summary,
            rendered_start=seg.rendered_start,
            rendered_end=seg.rendered_end,
        )
        for seg in raw.segments
    ]
    return _view.SourceView(text=raw.text, segments=segments)


def __getattr__(name: str) -> _typing.Any:
    # Deprecated alias for the removed ``CodeAst`` class, so annotations and
    # ``isinstance`` checks in older callers keep working. ``CodeSource`` is
    # the single handle now; note its constructor is lazy and tolerant where
    # ``CodeAst``'s was eager and raising, and the old ``.matches`` / ``.split``
    # / ``.index_terms`` methods live on the consumers instead
    # (``CodePattern.match_source`` / ``match_code``, ``RecursiveSplitter.split``,
    # ``index_terms``).
    if name == "CodeAst":
        _warnings.warn(
            "CodeAst is deprecated and now aliases CodeSource; use CodeSource "
            "with CodePattern.match_source / match_code, RecursiveSplitter.split, "
            "and index_terms",
            DeprecationWarning,
            stacklevel=2,
        )
        return CodeSource
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

View on GitHub (pinned to e84aa99b32)

Solutions

Replace CodeAst with CodeSource in imports and annotations.
Move parse-and-match calls to CodePattern.match_source / match_code.
Replace old handle.split calls with RecursiveSplitter.split and indexing-term usage with index_terms.
Note CodeSource's constructor is lazy and tolerant where CodeAst's was eager and raising; remove try/except around construction that relied on eager validation.

Example fix

// before
from cocoindex.ops.code import CodeAst
ast = CodeAst(text)
matches = ast.matches(pattern)
// after
from cocoindex.ops.code import CodePattern, CodeSource
src = CodeSource(text)
matches = pattern.match_source(src)

Defensive patterns

Strategy: type-guard

Validate before calling

import cocoindex.ops.code as code_ops
if hasattr(code_ops, "CodeAst"):
    import warnings
    warnings.warn("CodeAst still referenced; migrate to CodeSource", DeprecationWarning)

Type guard

def uses_removed_codeast(module: object) -> bool:
    return getattr(module, "CodeAst", None) is not None

Try / catch

import warnings
with warnings.catch_warnings():
    warnings.filterwarnings("ignore", message="CodeAst is deprecated", category=DeprecationWarning)
    CodeSource = code_ops.CodeAst  # transitional shim only

Prevention

Import CodeSource, never CodeAst, in new code.
Use CodePattern.match_source / match_code instead of instance .matches.
Use RecursiveSplitter.split and index_terms for splitting/indexing instead of handle methods.
Enable -W error::DeprecationWarning in test runs to catch removed-name usage immediately.

When it happens

Trigger: Importing or referencing ops.code.CodeAst (e.g. `from cocoindex.ops.code import CodeAst` or attribute access), which hits the module __getattr__ path.

Common situations: Legacy code and examples written before the CodeAst→CodeSource refactor; upgrades surface the DeprecationWarning and may then fail where old methods (.matches, .split on the handle) are called.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/cdf4d49fc4ad03d7. Report an issue: GitHub.