Skip to content

Conversation

@xpcmdshell
Copy link
Owner

Summary

Improves the developer experience for Session initialization based on API ergonomics review.

  • Make storage parameter honestly required (type hint was lying - said Optional but raised at runtime)
  • Add Session.from_base(path) convenience constructor for local dev
  • Add Session.subprocess(), Session.in_process(), Session.container() preset constructors
  • Re-export executor types at py_code_mode top level (reduces import scatter)

New API

from py_code_mode import Session

# Simplest - just a path (in-process, auto-discovers tools/skills/artifacts/requirements.txt)
async with Session.from_base("./.code-mode") as session:
    await session.run("tools.list()")

# With options
async with Session.from_base(
    "./.code-mode",
    timeout=60.0,
    extra_deps=("pandas",),
    allow_runtime_deps=False,
) as session:
    ...

# Explicit constructors for full control
Session.subprocess(storage_path="./data", tools_path="./tools")
Session.in_process(storage_path="./data")
Session.container(storage_path="./data", image="my-image:latest")

Breaking Changes

  • storage parameter type changed from StorageBackend | None to StorageBackend
    • Was already required at runtime (raised ValueError if None)
    • Now the type signature is honest

Testing

All 56 session tests pass.

- Make storage parameter required (fix type hint lie)
- Add Session.from_base() for simple local dev setup
- Add Session.subprocess(), in_process(), container() preset constructors
- Re-export executor types at py_code_mode top level
- from_base() auto-discovers tools/, skills/, artifacts/, requirements.txt

Breaking change: storage parameter is now required (was already required at runtime)
- Update Quick Start to use Session.from_base()
- Add class method documentation to session-api.md
- Update getting-started.md with new patterns
…method

- subprocess() and inprocess() now take base_path with auto-discovery
- Removed container() - too complex for convenience method, use direct constructor
- Consistent parameter naming (base_path everywhere)
- Updated docs to match
- Convenience methods now create tools/ dir alongside storage dirs
- README now shows explicit constructor usage for full control
- Makes clear convenience methods are shortcuts, not the only API
@xpcmdshell xpcmdshell merged commit 55fd82d into main Jan 2, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants