Python-module extension surface for safe-function namespace

[amc-corey-cox]

Provide a path for downstream trans-spec authors to register custom functions in the safe-function namespace without writing a Python harness around linkml-map.

Design

Decorator-based discovery. Users write a plain Python module and tag functions:

from linkml_map.utils.extensions import safe_function

@safe_function
def slugify(s, separator="_"):
    ...

@safe_function(override=True)  # explicit shadowing of a built-in
def lower(s):
    ...

@safe_function(distributes=False)  # list-style function, opts out of scalar distribution
def my_aggregator(items):
    ...

The decorator is the membership marker. @safe_function is a declaration by the author that the function is bounded-time, pure, and free of I/O — linkml-map does not verify this. Same posture as typing.final.

Loader. load_extensions(paths) reads file paths, imports each via importlib.util.spec_from_file_location, walks the module for tagged functions, applies the _distributing wrapper to scalar ones, and returns the merged dict.

CLI. -F/--functions PATH repeatable on map-data. File paths only — same shape as --schema. Module-name discovery (e.g. pkg.mod) deferred until demand emerges.

Semantics.

• Collision between two extensions: error.
• Collision with a built-in: error unless the extension declared override=True.
• override=True declared but no matching built-in exists: warn (typo catcher; doesn't block).
• Missing function (typo or extension not loaded): error differentiates the two cases.
  • No -F flags + unknown name → Unknown function 'foo'. Did you forget --functions?
  • With -F flags + unknown name → Unknown function 'foo'. Not in built-ins or loaded extensions [a.py, b.py]. Did you mean: 'bar', 'baz'?
• Extension function raises at runtime: wrap with attribution (file + function name).
• Extension referenced in spec but not loaded at runtime: fail with clear exception (same wrapping pattern). Convention: trans-specs note required extensions in a header comment. A declarative `required_extensions:` YAML key is a likely follow-up but out of scope here.

Scope. CLI flag + Python kwarg on `ObjectTransformer`. Python users replicate the CLI's loader call.

Where it lives. New module `src/linkml_map/utils/extensions.py`. Keeps `eval_utils.py` from accreting.

Docs (ship with the PR)

• Extension contract — pure, bounded-time, deterministic, no I/O, author-declared safe.
• When NOT to use extensions — explicit anti-pattern: don't escape the declarative model. Extensions are for named atomic operations that read cleaner as a name than as an expression chain. Not for putting transformation logic in Python.
• Convention — specs requiring extensions document it in a top-level header comment.

Out of scope (deferred)

• `required_extensions:` YAML key for declarative dependency on extensions. Want this eventually; not yet.
• Module-name path syntax (`pkg.module`) in addition to file paths.
• `--allow-override` CLI flag — the decorator's `override=True` is sufficient declaration.

Origin: discussion during #242. Python API already accepts `functions=` at `src/linkml_map/utils/eval_utils.py:558`; this exposes that cleanly to non-Python trans-spec authors while preserving the safety boundary.

[github-actions]

Summary

What this issue proposes: A clean, ergonomic path for downstream trans-spec authors to inject custom functions into linkml-map's safe-function namespace — without writing a Python harness. The hook already exists in the Python API (functions= kwarg at eval_utils.py:552/587); this issue exposes it via a decorator + file-based loader + CLI flag.

---

Origin and context

This issue grew directly from the discussion on #242 (add slugify builtin): while slugify deserves a first-class builtin, the meta-question — "what do downstream authors do when they need a custom function that isn't worth upstreaming?" — needed its own answer. This issue is that answer.

Prior art: #116 (uuid5) (closed Feb 2026) established the pattern of adding bounded-time, pure functions to the safe builtin registry in eval_utils.py. This issue extends that pattern to user-authored functions outside the core library.

The concrete downstream consumer motivating the cluster is the schema-automator EML importer (schema-automator#208), which needs to turn human-readable EML <entityName> / <attributeName> fields into valid LinkML identifiers.

---

Design summary

Three-layer addition:

Layer	What	Where
Decorator	@safe_function / @safe_function(override=True, distributes=False) — author-declared safety contract	new src/linkml_map/utils/extensions.py
Loader	load_extensions(paths) — imports files via importlib.util.spec_from_file_location, walks for tagged functions, applies _distributing wrapper	same module
CLI	-F / --functions PATH (repeatable) on map-data	cli/cli.py

Safety posture: Author-declared, not verified — same philosophy as typing.final. The decorator is a declaration that the function is bounded-time, pure, and I/O-free; linkml-map trusts the author.

Collision semantics (well-specified):

Situation	Outcome
Two extensions with same name	Error
Extension collides with a builtin, no override=True	Error
override=True but no matching builtin	Warn (typo catcher)
Unknown function, no -F flags loaded	Unknown function 'foo'. Did you forget --functions?
Unknown function, -F flags present	Unknown function 'foo'. Not in built-ins or loaded extensions [a.py, b.py]. Did you mean: 'bar', 'baz'?

distributes=False lets aggregate / list-style functions opt out of the automatic scalar-distribution wrapper that _SCALAR_FUNCTIONS normally gets.

---

Related open issues

Issue	Title	Relationship
#242	Add slugify safe builtin	Direct trigger; slugify goes in as a first-class builtin; this issue handles the "what about next time" question
#241	Transform-time validation against target schema constraints	Sibling: slugify returns None on unusable input; #241 is where "must-not-be-None" for required slots is enforced with source-row provenance
#116 ✅	uuid5() safe builtin	Closed precedent; established the bounded-time-function-in-safe-namespace pattern

---

Explicitly deferred (out of scope here)

• required_extensions: YAML key for declarative dependency declaration in trans-specs (noted as a likely follow-up)
• Module-name syntax (pkg.module) in addition to file paths
• --allow-override CLI flag (the override=True decorator attribute is sufficient)

---

Implementation notes

• New module src/linkml_map/utils/extensions.py keeps eval_utils.py from accreting more surface area.
• Python API users replicate the same load_extensions(paths) call the CLI makes, then pass the result to ObjectTransformer.
• Docs to ship with the PR: extension contract ("pure, bounded-time, deterministic, no I/O"), explicit anti-pattern ("don't put transformation logic in extensions"), and the convention that trans-specs requiring extensions document it in a top-level header comment.

---

Status

Open, no implementation yet. Well-specified and ready for a PR. The @dragon-ai-agent trigger in #242's summary suggests the team is using automated agents for implementation — this issue is similarly implementation-ready.