Skip to content

v0.22.3

Latest
Latest

Choose a tag to compare

View all tags
@igorbenav igorbenav released this 21 Jun 03:53
· 2 commits to main since this release
v0.22.3
60d3d5c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

FastCRUD 0.22.3 Release Notes

FastCRUD 0.22.3 introduces a bundled Agent Skill inside the published wheel. After installing FastCRUD, run uvx library-skills (or uvx library-skills --claude for Claude Code) from your project root once, and any compatible coding assistant picks up FastCRUD-specific guidance grounded in the real public API.

Added

Bundled Library Skill for AI Coding Agents

LLM coding assistants previously had two options when working with FastCRUD: read the docs site at build time, or guess from the imported symbols. Both produced confidently-wrong code — agents iterated crud.get() per ID instead of using id__in=[...], called crud.get_multi(limit=None) on unbounded tables, and forgot that return_as_model=True requires schema_to_select.

This release fixes that by bundling an Agent Skill inside the wheel at fastcrud/.agents/skills/fastcrud/, following the Library Skills convention. The skill installs as a symbolic link in your project, so upgrading FastCRUD automatically updates the guidance.

Install:

# Run from your project root after `uv add fastcrud` / `pip install fastcrud`
uvx library-skills              # for Codex, Cursor, Copilot, OpenCode, etc.
uvx library-skills --claude     # for Claude Code (uses .claude/skills/)

What the skill teaches:

  • Canonical setup — the minimal model + schemas + crud_router pattern
  • Choosing the right method — get vs get_joined vs get_multi_joined, and which one avoids N+1
  • Avoiding N+1 — auto-detection via include_relationships=True, manual JoinConfig, and nested_limit for one-to-many collections (with the SQL ROW_NUMBER() OVER (PARTITION BY ...) mechanics)
  • The limit=None footgun — when it's safe (domain-bounded WHERE clause), when it isn't, and the three-tier pagination default
  • When NOT to use FastCRUD — aggregate roll-ups, CTEs, GROUP BY projections, bulk writes, and dialect-specific features that belong to raw SQLAlchemy
  • Return-value semantics — create() returns None by default, return_as_model=True requires schema_to_select, type narrowing via subclass overrides
  • Filter syntax — every __op suffix, joined filters with ., Depends(...) filters, custom operators
  • Gotchas — async-session-only, soft delete behavior, joined-table inheritance, SQLModel polymorphism caveat, Python 3.14 PEP 649 compatibility

Layout:

fastcrud/.agents/skills/fastcrud/
├── SKILL.md              # entry point — loaded when the agent activates the skill
└── references/
    ├── methods.md        # every FastCRUD method, return semantics, type narrowing
    ├── filters.md        # every operator, FilterConfig, dependency filters, custom operators
    ├── joins.md          # JoinConfig, auto-detection, nested_limit, polymorphism
    ├── pagination.md     # offset vs cursor, sanity-checking limit=None
    └── endpoints.md      # crud_router params, EndpointCreator subclassing, soft delete

The skill uses progressive disclosure — the agent loads only the name and short description at startup; the full body loads when a task matches; reference files load on demand. Many libraries can ship skills this way without bloating the agent's context.

Documentation: Library Skill page with full install instructions, layout, and verification tips.

What's Changed

  • Add bundled Library Skill for AI coding agents by @igorbenav in #334

Full Changelog: v0.22.2...v0.22.3

Assets 2
Loading