python-api
Look up the public API of a Python package against the *installed version* and cache what's worth keeping. Four shapes by question type: (0) cache hit under `scratch/api/<lib>/<version>/`; (1) `inspect.signature` + `pydoc.render_doc` for a symbol; (2) `dir` / `pkgutil.iter_modules` for a module surface; (3) WebSearch + WebFetch of versioned docs for narrative ("how", "which", "what does X return when Y"). Never write a symbol from training-data memory — recognition is not a lookup. TRIGGER — any of: - About to name a symbol (function / class / method / arg) in code. - User asks "what's the signature of X?", "what's in module Y?", "how do I call X?", "which of A/B should I use?". - User asks "what does X return when <condition>?" (Shape 3 — see decision table). - Another workflow skill (`build-ml-pipeline`, `evaluate-ml-pipeline`, `iterate-from-skore`, `smoke-test-ml-pipeline`) says "consult the API skill". - About to reach for a library's "obvious" pattern from memory. SKIP when: the s
probabl-ai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add probabl-ai/skills --skill python-api技能说明
name: python-api
description: >
Look up the public API of a Python package against the installed
version and cache what's worth keeping. Four shapes by question
type: (0) cache hit under scratch/api/<lib>/<version>/;
(1) inspect.signature + pydoc.render_doc for a symbol;
(2) dir / pkgutil.iter_modules for a module surface;
(3) WebSearch + WebFetch of versioned docs for narrative
("how", "which", "what does X return when Y"). Never write a
symbol from training-data memory — recognition is not a lookup.
TRIGGER — any of:
- About to name a symbol (function / class / method / arg) in code.
- User asks "what's the signature of X?", "what's in module Y?", "how do I call X?", "which of A/B should I use?".
- User asks "what does X return when ?" (Shape 3 — see decision table).
- Another workflow skill (
build-ml-pipeline,evaluate-ml-pipeline,iterate-from-skore,smoke-test-ml-pipeline) says "consult the API skill". - About to reach for a library's "obvious" pattern from memory.
SKIP when: the signature is obvious from a call site you just
read in this turn; the work is filesystem / shell only (no
Python symbols); a scratch/api/<lib>/<version>/<topic>.md
cache file already answers the question (still a Shape 0
consultation — you just don't fetch).
HOW TO USE: resolve the package version first via a scratch
file (scratch/<ts>_version_<pkg>.py with import <pkg>; print(<pkg>.__version__) — run with pixi run python scratch/<ts>_version_<pkg>.py). Then list
scratch/api/<lib>/<version>/. Then pick the shape from the
"What kind of question?" table. Narrative findings get cached
back. All Python execution goes through scratch/<ts>_*.py
files — inline python -c is forbidden regardless of length.
Stack-specific orientation lives in
references/stack_orientation.md — load on demand.
python-api
Discover the public API of any installed Python package, cache what matters, never trust training-data memory.
Three durable rules:
- Lookup against the installed version, never memory. Recognition is not a lookup. The version may have renamed / re-signatured / deprecated the symbol you remember.
- Cache to
scratch/api/<lib>/<version>/<topic>.mdso the next agent doesn't repeat the probe. - Bundled
references/≠ workspace cache. Bundled refs are durable workflow patterns; cache files are per-version extracts.
Next-step pointers
| Came here for… | After lookup, next is… |
|---|---|
| Symbol signature for code about to be written | → continue caller's flow (e.g. build-ml-pipeline § next step) |
| "Which library / which entry?" | → continue with the picked symbol; cache lands |
| Bootstrap turn (first workspace) | → required minimum cache lands; see references/bootstrap_cache.md |
| Failure debugging (KeyError / AttributeError) | → see Stop condition "Lookup failure ≠ artifact missing" |
What kind of question? → Shape
Pick the shape by question type before picking a tool. Wrong shape produces a wrong-looking cache file and burns a turn.
| The user's question is shaped like… | Shape |
|---|---|
"What's in scratch/api/<lib>/<version>/?" (always check first) | 0 cache hit |
| "Which entry point for <task>?" | Stack orientation below, then Shape 1 / 1b to confirm |
| "What's the signature of X?" / "What args does X take?" / "What's the return type?" | 1b LSP hover (fast) → fall through to 1 if hover is sparse |
| "What does X do?" / "Full docstring of X?" (need Parameters / Examples / See Also) | 1 symbol card (pydoc) |
| "What's in module Y?" (open-ended discovery) | 2 module surface |
"Search for symbols matching foo* across the env" | 2b LSP workspace symbol |
| "How does X work?" / "Which of A or B should I use?" | 3 narrative |
"What does X return when <arg> is <value>?" | 3 narrative |
| "What's the recommended pattern for …?" | 3 narrative |
Shape 3 is the right answer when the question depends on a
condition over an argument. help() carries a Returns
section but typically does not enumerate dispatch behaviour under
each argument value — that lives in narrative docs.
Shape 1b vs Shape 1. Pyright hover gives the type signature
(richer inferred return types than inspect.signature) + the first
paragraph of the docstring — fast, no Python execution. Pydoc gives
the full docstring with all sections — slower but authoritative.
Default escalation: 1b first for "what's the signature"; fall
through to 1 if hover is empty / one-liner.
Prerequisites for Shape 1b / 2b (LSP shapes). Pyright available
via opencode LSP AND pyrightconfig.json pointing at the lsp env.
If either is missing, LSP shapes are unavailable — use Shape 1 / 2
directly. The agent feature: installed row in JOURNAL.md
Status Workspace decisions is the precondition; see
python-env-manager § Agent feature.
Stop conditions — read before any lookup
- No symbols from memory. Every function / class / method / arg
must come from a lookup this turn —
inspect.signature, ascratch/api/<lib>/<version>/file, or a fresh WebFetch. Recognition does not count. Sticky named cases — full list inreferences/named_traps.md:- skrub:
tabular_learner→tabular_pipelinein 0.7+. - skrub:
mark_as_y(target_column)→ signature dropped the positional arg in 0.9+; use.skb.select("...")before mark. - skore:
Project.get(...)is by id, not user-facingkey; enumerate viaproject.summarize()first.
- skrub:
- Never fabricate a probe result. If the probe hasn't executed,
the
Signature/help()sections must remain blank or marked<pending probe execution>. Same rule for Shape 3: do not paraphrase docs from memory; cache file holds verbatim extracts. - Version-correct first. Resolve
<pkg>.__version__before any lookup. The version subf