Safe-function extension surface + slugify/case-converter built-ins

[amc-corey-cox]

Summary

• @safe_function extension mechanism for downstream-supplied functions in the expression eval namespace, loaded via -F/--functions (repeatable). Decorator-based discovery, file-path loading, explicit override semantics on the function rather than a CLI flag. Implements Python-module extension surface for safe-function namespace #248.
• Slugify family of built-ins — slugify, to_snake, to_camel, to_pascal — backed by python-slugify and inflection. Implements Add slugify safe builtin for identifier-shaped expressions #242.
• Enriched unknown-function errors with Levenshtein did-you-mean suggestions and a pointer to --functions, replacing simpleeval's FunctionNotDefined default message.

The extension mechanism was dogfooded by writing slugify as an extension first (see tests/input/extensions/slugify_ext.py), then lifting it into the built-ins. The example extension stays as a learning artifact and demonstrates override=True.

Design notes (locked in #248)

• Author declares safety via the decorator; linkml-map enforces namespace boundaries, not function purity. Same posture as typing.final.
• Collision between two extensions → ExtensionError. Collision with a built-in → ExtensionError unless declared override=True. override=True without a matching built-in → warning.
• File paths only; module-name discovery deferred.
• No --allow-override CLI flag — the decorator's override=True is sufficient declaration.
• Trans-specs that need an extension document it in a header comment; declarative required_extensions: YAML key is a noted follow-up.

Test plan

• uv run pytest — 864 passed, 4 skipped
• uv run pytest --doctest-modules src/linkml_map/utils/eval_utils.py — all doctests pass
• uv run ruff check . and uv run ruff format . clean
• CLI smoke test exercises --functions end-to-end with the slugify example extension

[Copilot]

Pull request overview

Adds a downstream extension mechanism for “safe” expression functions, introduces slugify/case-conversion built-ins, and improves unknown-function diagnostics to guide users toward typos vs missing extension loading.

Changes:

• Introduces @safe_function + load_extensions() to discover and load tagged functions from --functions/-F Python files into the expression namespace.
• Adds new safe built-ins: slugify, to_snake, to_camel, to_pascal, along with enriched “unknown function” errors with did-you-mean suggestions.
• Wires extension functions into ObjectTransformer (Python API) and map-data CLI, and documents/extensions tests the new surface.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
uv.lock	Locks new deps needed for slugify/case conversion (python-slugify, inflection, text-unidecode).
pyproject.toml	Declares new runtime dependencies for the new built-ins.
src/linkml_map/utils/eval_utils.py	Adds slugify/case-converter built-ins and richer unknown-function errors.
src/linkml_map/utils/extensions.py	New extension loader + decorator for downstream safe-function registration.
src/linkml_map/transformer/object_transformer.py	Accepts extension_functions and injects them into expression evaluation.
src/linkml_map/cli/cli.py	Adds repeatable --functions/-F option and loads extensions into the transformer.
tests/test_utils/test_extensions.py	New unit/integration tests for decorator, loader semantics, CLI, and transformer integration.
tests/test_utils/test_eval_utils.py	Updates unknown-function/import tests and adds coverage for new built-ins.
tests/input/extensions/slugify_ext.py	Example extension module demonstrating override=True behavior.
mkdocs.yml	Adds Extensions page to docs nav.
docs/api/functions.md	Documents new built-ins and points to extension docs.
docs/api/extensions.md	Adds end-user documentation for writing/loading extension functions.

Comments suppressed due to low confidence (3)

src/linkml_map/utils/extensions.py:117

• _load_module_from_path() executes arbitrary user modules but doesn’t catch import-time exceptions; non-ExtensionError failures will bypass the CLI’s ExtensionError handling and can leave a partially-initialized module in sys.modules. Wrap exec_module() in try/except to raise ExtensionError with path context, and ensure sys.modules[spec.name] is cleaned up on failure.

    spec = importlib.util.spec_from_file_location(f"_linkml_ext_{path.stem}", path)
    if spec is None or spec.loader is None:
        msg = f"Could not create import spec for: {path}"
        raise ExtensionError(msg)
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module

src/linkml_map/utils/extensions.py:115

• spec_from_file_location(f"_linkml_ext_{path.stem}", path) can collide when two extension files share the same basename (e.g. foo/ext.py and bar/ext.py), causing sys.modules overwrites and confusing import behavior. Consider deriving a unique module name from the full resolved path (e.g., include a short hash) to avoid collisions.

        msg = f"Extension file not found: {path}"
        raise ExtensionError(msg)
    spec = importlib.util.spec_from_file_location(f"_linkml_ext_{path.stem}", path)
    if spec is None or spec.loader is None:
        msg = f"Could not create import spec for: {path}"
        raise ExtensionError(msg)
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module

src/linkml_map/utils/extensions.py:95

• The decorator sets fn._linkml_safe_function = ... directly instead of using the _SAFE_FUNCTION_ATTR constant. Using setattr(fn, _SAFE_FUNCTION_ATTR, ...) avoids the hard-coded attribute name so future refactors can’t accidentally desync tagging vs discovery.

    def _tag(fn: Callable) -> Callable:
        fn._linkml_safe_function = {"override": override, "distributes": distributes}  # type: ignore[attr-defined]
        return fn

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.