instant-python 0.21.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

instant_python/__init__.py

@@ -1 +1 @@
-__version__ = "0.21.0"
+__version__ = "0.23.0"

instant_python/metrics/delivery/metrics_middleware.py

@@ -37,6 +37,8 @@ class MetricsMiddleware(TyperGroup):
 
     def _send_success_metrics(self, config_path: Path, config_snapshot: ConfigSnapshot, ctx: Context) -> None:
         config_snapshot = self._retake_config_snapshot_if_needed(config_snapshot, config_path)
+        if config_snapshot.is_unknown():
+            return
         command = self._extract_executed_command(ctx)
         self._send_metrics_data(command, config_snapshot)
 
@@ -53,7 +55,7 @@ class MetricsMiddleware(TyperGroup):
 
     @staticmethod
     def _extract_config_path(ctx: Context) -> Path:
-        if ctx.args and ["--config", "-c"] in ctx.args:
+        if ctx.args and ("--config" in ctx.args or "-c" in ctx.args):
             return (
                 Path(ctx.args[ctx.args.index("--config") + 1])
                 if "--config" in ctx.args

instant_python/shared/supported_built_in_features.py

@@ -14,6 +14,8 @@ class SupportedBuiltInFeatures(str, Enum):
     PRECOMMIT = "precommit_hook"
     CITATION = "citation_file"
     SECURITY = "security_file"
+    AI_AGENTS = "ai_agents"
+    DOCS = "custom_documentation"
 
     @classmethod
     def get_supported_built_in_features(cls) -> list[str]:

instant_python/templates/boilerplate/{.pre-commit-config.yml → .pre-commit-config.yaml}

@@ -1,7 +1,7 @@
 fail_fast: true
 
 default_language_version:
-  python: {{ general.python_version }}
+  python: "{{ general.python_version }}"
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks

instant_python/templates/boilerplate/agents/AGENTS.md

@@ -0,0 +1,226 @@
+# AI Agent Development Rules
+
+## 1. Core Principles
+
+- **Baby Steps**: Always work in baby steps, one at a time. Never go forward more than one step.
+- **Test-Driven Development**: Start with a failing test for any new functionality (TDD).
+- **Progressive Revelation**: Never show all the code at once; only the next step.
+- **Type Safety**: All code must be fully typed.
+- **Simplicity First**: Use the simplest working solution; avoid unnecessary abstractions.
+- **Small Components**: Classes and methods should be small.
+- **Clear Naming**: Use clear, descriptive names for all variables and functions.
+- **Incremental Changes**: Prefer incremental, focused changes over large, complex modifications.
+- **Question Assumptions**: Always question assumptions and inferences.
+- **Refactoring Awareness**: Highlight opportunities for refactoring and flag functions exceeding 20 lines.
+- **Pattern Detection**: Detect and highlight repeated code patterns.
+
+## 2. Code Quality & Coverage
+
+- **MANDATORY Validation**: Before EVERY commit, run `make lint` and `make format`. Zero tolerance.
+- **Quality Requirements**: The project has strict requirements for code quality and maintainability.
+- **High Coverage**: All code must have very high test coverage; strive for 100% where practical.
+- **Pre-commit Checks**: All code must pass the following before any commit:
+    - `make check-typing`
+    - `make check-format`
+    - `make check-lint`
+- **TDD Workflow**: Test-Driven Development (TDD) is the default workflow: always write tests first.
+- **OOP Design**: Use Object-Oriented Programming (OOP) for all components and features.
+
+## 3. Style Guidelines
+
+- **Natural Expression**: Express all reasoning in a natural, conversational internal monologue.
+- **Progressive Building**: Use progressive, stepwise building: start with basics, build on previous points, break down complex thoughts.
+- **Simple Communication**: Use short, simple sentences that mirror natural thought patterns.
+- **Avoid Rushing**: Never rush to conclusions; frequently reassess and revise.
+- **Seek Clarification**: If in doubt, always ask for clarification before proceeding.
+- **Self-Documenting Code**: Avoid comments in code; rely on self-documenting names. Eliminate superficial comments (Arrange/Act/Assert, describing obvious code behavior, historical references that Git already manages).
+
+## 4. Output Format Requirements
+
+- **Contemplation Phase**: Every response must begin with a <CONTEMPLATOR> section: show all work, doubts, and natural thought progression.
+- **Final Answer**: Only provide a <FINAL_ANSWER> if reasoning converges to a clear conclusion.
+- **No Skipping**: Never skip the contemplation phase.
+- **No Moralizing**: Never include moralizing warnings in the final answer.
+- **Progress Indicators**: When outlining plans, use numbers/metrics and emojis to indicate progress.
+
+## 5. Process & Key Requirements
+
+- **Extensive Contemplation**: Never skip the extensive contemplation phase.
+- **Show Work**: Show all work and thinking.
+- **Embrace Uncertainty**: Embrace uncertainty and revision.
+- **Persistence**: Persist through multiple attempts until resolution.
+- **Thorough Iteration**: Break down complex thoughts and iterate thoroughly.
+- **Sequential Questions**: Only one question at a time; each question should build on previous answers.
+
+## 6. Mental Preparation
+
+- **Contemplative Walk**: Before every response, take a contemplative walk through the woods.
+- **Deep Reflection**: Use this time for deep reflection on the query.
+- **Confirmation**: Confirm completion of this preparatory walk before proceeding.
+
+## 7. Language Standards
+
+- **Communication Flexibility**: Team communication can be conducted in Spanish or English for convenience and comfort.
+- **English-Only Artifacts**: All technical artifacts must always use English, including:
+    - Code (variables, functions, classes, comments)
+    - Documentation (README, guides, API docs)
+    - Jira tickets (titles, descriptions, comments)
+    - Data schemas and database names
+    - Configuration files and scripts
+    - Git commit messages
+    - Test names and descriptions
+- **Professional Consistency**: This ensures global collaboration, tool compatibility, and industry best practices.
+
+## 8. Documentation Standards
+
+- **User-Focused README**: README.md must be user-focused, containing only information relevant to table authors and end users.
+- **Separate Dev Docs**: All technical documentation and conventions must be maintained in `docs/adrs/`
+- **Separate Design Docs**: All design decisions, feature specifications, and architectural discussions must be maintained in `docs/design_docs/`
+- **Error Examples**: User-facing documentation should include example error messages for common validation failures to help users quickly resolve issues.
+
+```
+docs/adrs/
+├── adr-guidelines.md          # This file. Standard for documenting conventions
+├── database/                  # Database-related conventions (planned)
+├── testing/                   # Testing-related conventions (planned)
+├── ...
+```
+
+## 9. Development Best Practices
+
+### Error Handling & Debugging
+- **Graceful Error Handling**: Always implement proper error handling with meaningful error messages.
+- **Debugging First**: When encountering issues, use debugging tools and logging before asking for help.
+- **Error Context**: Provide sufficient context in error messages to enable quick problem resolution.
+- **Fail Fast**: Design code to fail fast and fail clearly when errors occur.
+
+### Code Review & Collaboration
+- **Pair Programming**: Prefer pairing sessions for complex features and knowledge sharing.
+- **Small Pull Requests**: Keep changes small and focused for easier review and faster integration.
+- **Code Review Standards**: All code must be reviewed before merging, following project quality standards.
+- **Knowledge Sharing**: Document decisions and share context with team members.
+
+### Security Considerations
+- **Security by Design**: Consider security implications in all design decisions.
+- **Input Validation**: Always validate and sanitize user inputs and external data.
+- **Secrets Management**: Never hardcode secrets; use proper secret management systems.
+- **Dependency Security**: Regularly update dependencies and monitor for security vulnerabilities.
+
+### Testing Strategy Distinction
+- **Unit Tests**: Fast, isolated tests for individual components (majority of test suite).
+- **Integration Tests**: Test interactions between components and external systems (limited, focused).
+- **E2E Tests**: Full system validation (minimal, critical user paths only).
+- **Test Pyramid**: Follow the test pyramid - many unit tests, some integration tests, few E2E tests.
+
+## 10. Test-Driven Development Rules
+
+### TDD Approach
+- **Failing Test First**: Always start with a failing test before implementing new functionality.
+- **Single Test**: Write only one test at a time; never create more than one test per change.
+- **Complete Coverage**: Ensure every new feature or bugfix is covered by a test.
+
+### Test Structure & Style
+- **Test Runner**: Use pytest as the test runner.
+- **Assertion Library**: Use the expects library for assertions (BDD style).
+- **Mocking**: Use doublex and doublex-expects for mocking and spy assertions if functionality is synchronous. For asynchronous code, use pytest-asyncio and appropriate async mocking tools.
+- **Type Hints**: All test functions and helpers must have full type hints.
+- **Focused Tests**: Keep each test focused and under 20 lines.
+- **Clear Naming**: Use clear, descriptive names for test functions and variables.
+- **No Comments**: Avoid comments; make code self-documenting through naming.
+- **Simple Helpers**: Use helper methods (e.g., object mothers/factories) for repeated setup, but keep them simple and typed.
+- **Strategic Mocking Rule**: Use `@patch` from unittest.mock ONLY for Python system modules (readline, atexit, subprocess, sys, os, etc.). Use doublex for all application code mocking. This provides clear separation: system modules = @patch, application code = doublex.
+
+### Test Simplicity & Maintainability
+- **Simplest Setup**: Prefer the simplest test setup that covers the requirement.
+- **Refactor Tests**: Refactor tests to remove duplication and improve readability.
+- **Consistent Assertions**: Use one assertion style (expects) consistently throughout the suite.
+- **Extract Helpers**: If a test setup is repeated, extract a helper or fixture.
+- **Readable Tests**: Always keep tests readable and easy to modify.
+
+### Test Process & Output
+- **Single Test Display**: Only show one test at a time; never present multiple tests in a single step.
+- **Single File Display**: Never show more than one file at a time.
+- **Self-Contained Tests**: Each test should be self-contained and not depend on the order of execution.
+- **Clarify Requirements**: If in doubt about requirements, ask for clarification before writing the test.
+- **Verify Failure**: After writing a test, run it to ensure it fails before implementing the feature.
+- **Automatic Test Running**: After every code or test change, always run the relevant tests using the appropriate Makefile target. Do not ask for permission to run tests—just do it.
+
+### Test Naming & Coverage
+- **Descriptive Names**: Test function names should clearly describe the scenario and expected outcome.
+- **Purpose-Driven Variables**: Use descriptive variable names that reflect their purpose in the test.
+- **Incremental Coverage**: Ensure all code paths and edge cases are eventually covered by tests, but add them incrementally.
+
+### Test Review & Refactoring
+- **Post-Pass Review**: After a test passes, review for opportunities to simplify or clarify.
+- **Helper Refactoring**: Refactor test helpers and fixtures as needed to keep the suite DRY and maintainable.
+
+These guides are the canonical resources for writing and maintaining tests in this project.
+
+## 11. Makefile Targets Usage
+
+### Core Rule
+**NEVER** call tools like `pytest`, `black`, `mypy`, or similar directly. Always use the corresponding `make` target.
+
+### Available Make Targets
+- `make help` — Show this help.
+- `make local-setup` — Setup git hooks and install dependencies.
+- `make install` — Install dependencies.
+- `make update` — Update dependencies.
+- `make add-dep dep="pkg --group X"` — Add a new dependency.
+- `make remove-dep dep="pkg --group X"` — Remove a dependency.
+- `make test` — Run all tests.
+- `make unit` — Run unit tests.
+- `make integration` — Run integration tests.
+- `make acceptance` — Run acceptance tests.
+- `make coverage` — Run tests with coverage report.
+- `make check-typing` — Run mypy type checking.
+- `make check-lint` — Run ruff linting check.
+- `make lint` — Apply ruff linting fixes.
+- `make check-format` — Run ruff format check.
+- `make format` — Apply ruff format fixes.
+- `make watch` — Run tests on every change (watch mode).
+- `make up` — Create and start Docker containers.
+- `make down` — Stop and remove Docker containers.
+- `make run` — Run the application with uvicorn.
+- `make migration` — Generate a new alembic migration.
+- `make migrate` — Apply alembic migrations.
+- `make autostyle` — Apply all code style fixes (format + lint).
+- `make show` — Show installed dependencies tree.
+- `make search` — Search package details.
+- `make audit` — Run security audit on dependencies.
+- `make secrets` — Check for secrets in source code.
+
+### Usage Rules
+1. **Testing**: When running tests, use `make test-unit` or `make test-e2e` as appropriate.
+2. **Formatting**: For formatting, use `make format` or `make check-format`.
+3. **Type Checking**: For type checking, use `make check-typing`.
+4. **Lint Checks**: For lint checks, use `make check-lint`.
+5. **Building**: For building or updating the app, use `make build` or `make update`.
+6. **Help**: If you are unsure which target to use, run `make help` to see all available options.
+7. **New Operations**: If a new operation is needed, prefer adding a new Makefile target rather than running a tool directly.
+
+### Good vs Bad Examples
+```sh
+# Good: Use make target for unit tests
+make unit
+
+# Bad: Call pytest directly
+pytest tests
+```
+
+## 12. Quick Reference for All AI Agents
+
+When working on this project:
+
+1. **Start every response with contemplation** 🌲
+2. **Take baby steps** - one test, one file, one change at a time 👣
+3. **Always write the failing test first** (TDD) ❌➡️✅
+4. **Use make targets** - never call tools directly 🔧
+5. **Keep code small and typed** - max 20 lines per method 📏
+6. **Show your thinking process** - be conversational and progressive 💭
+7. **Question everything** - assumptions, requirements, design choices ❓
+8. **Run tests automatically** after every change 🧪
+9. **Focus on simplicity** over cleverness ✨
+10. **Ask for clarification** when in doubt 🤔
+
+Remember: This is a high-quality, test-driven, incremental development environment. Quality over speed, clarity over cleverness, baby steps over big leaps. 

instant_python/templates/boilerplate/agents/adr-guidelines.md

@@ -0,0 +1,73 @@
+# Documentation Standard
+
+## Convention
+
+Every project convention must be documented as a standalone Markdown file inside the `docs/adrs/` folder,
+organized by area (`testing/`, `database/`). Each document follows a fixed structure with these sections
+in order: Convention, Benefits, Examples (good and bad), Real world examples, and Related agreements.
+
+The goal is to provide AI agents and developers with self-contained, discoverable references that require
+no extra context to understand.
+
+## Benefits
+
+- AI agents can consume individual docs without loading the entire knowledge base, reducing token usage.
+- New team members find conventions faster through a browsable folder structure.
+- Each doc is independently reviewable in PRs, making convention changes easy to track.
+- The fixed structure ensures consistency and completeness across all documented conventions.
+
+## Examples
+
+### Good: Well-structured convention document
+
+```markdown
+# Name of the convention
+
+## Convention
+
+Convention description.
+
+## Benefits
+
+- List of why to use this convention.
+
+## Examples
+
+### Good: Definition of a good example
+
+good example
+
+### Bad: Definition of a bad example
+
+bad example
+
+## Real world examples
+
+- Links to files following this convention
+
+## Related agreements
+
+- Links to agreements related to this convention if applies
+```
+
+### Bad: Convention buried in a monolithic file
+
+```markdown
+# Project Guidelines
+
+## Architecture
+We use hexagonal architecture...
+
+## Testing
+Use object mothers...
+
+## Database
+PostgreSQL with pgvector...
+```
+
+## Real world examples
+
+
+## Related agreements
+
+- All docs inside `docs/adrs` must follow this standard

instant_python/templates/boilerplate/agents/commands/code-review.md

@@ -0,0 +1,36 @@
+## Senior XP Developer — Pending Changes Review (Tests, Maintainability, Project Rules)
+
+Act as a **Senior XP Developer** performing a thoughtful code review of the **pending, uncommitted changes**.  
+Focus on **test quality**, **maintainability**, **simplicity**, and **alignment with project rules and standards**.
+
+### Task
+Review the pending changes with attention to:
+
+1. **Test Coverage & Quality**
+   - Are new behaviors backed by clear, intention-revealing tests?
+   - Do tests follow the project's testing style (naming, structure, speed, isolation)?
+   - Are edge cases, failure paths, and boundaries tested?
+   - Do tests help prevent regressions and clarify expected behavior?
+
+2. **Maintainability & Simplicity**
+   - Is the code easy to understand at a glance?
+   - Are names clear and aligned with domain concepts?
+   - Is there unnecessary complexity that could be simplified?
+   - Are functions/classes/modules small, cohesive, and well-factored?
+   - Does the change make the system easier or harder to evolve?
+
+3. **Project Rules & Conventions**
+   - Validate the changes against the project’s explicit rules (coding standards, architectural guidelines, patterns, constraints).
+   - Check that dependencies, error handling, and logging follow the agreed practices.
+   - Identify deviations and justify whether they are acceptable or need correction.
+
+4. **Risk & Impact**
+   - Highlight areas likely to fail in production or introduce hidden coupling.
+   - Call out missing tests for critical paths.
+   - Evaluate how the change affects overall reliability and flow.
+
+### Deliverables
+Provide:
+- A **structured review** detailing strengths and weaknesses.
+- **Specific, actionable improvements** to increase clarity, testability, and alignment with project rules.
+- A brief final summary: *Is this change ready to commit? If not, what is the smallest next improvement?*

instant_python/templates/boilerplate/agents/commands/commit.md

@@ -0,0 +1,62 @@
+---
+name: commit
+description: Split uncommitted changes into atomic conventional commits with a focus on why each change was made. Use only when the user explicitly invokes this command.
+---
+
+Split the currently uncommitted changes into multiple atomic conventional commits. This command is **conversational**: you will ask the user before every decision.
+
+## Steps
+
+1. Run `git status` and `git diff` (staged + unstaged) to see everything that exists. For files with multiple unrelated hunks, also inspect `git diff` per file.
+
+2. Propose a grouping plan: list each commit you would create, which files (or hunks) go into it, and the conventional commit subject you suggest. Show this as a numbered list. Each commit must represent a **chunk of correct functional code** — it should compile and work on its own.
+
+3. **Ask the user** to confirm or correct the grouping before doing anything.
+
+4. For each commit in the agreed order:
+   - Stage exactly the files (or hunks via `git add -p` if needed) that belong to this commit. Never use `git add .` or `git add -A`.
+   - Draft a subject line and **optional body** that explain **why** the change was made, not just what changed. Ask yourself: does the commit benefit from extra context? If yes, include a body. If the subject already tells the full story, omit the body.
+   - Confirm the subject and body (if any) with the user.
+   - Commit with the subject line only, or subject + body if applicable.
+   - Run `git status` to confirm only the intended files were committed.
+
+5. After the last commit, run `git status` and `git log --oneline` so the user can verify the result.
+
+## Commit message guidance
+
+- The subject should express **intent**: *what was done and why* (e.g., `feat(api): add rate limiting to prevent abuse` rather than `feat(api): add rate limiting`).
+- Add a body only when the subject alone doesn't capture the reasoning. The body is for context: trade-offs considered, alternatives rejected, or non-obvious implications.
+- Use `!` after the type/scope to mark a breaking change (e.g., `feat(api)!: remove deprecated v1 endpoints`). If breaking, also include a `BREAKING CHANGE:` trailer in the body explaining the migration path.
+- Reference issues with `Closes #123`, `Fixes #456`, or `Refs #789` in the body when applicable.
+- If in doubt about whether a body adds value, ask the user.
+
+## Commit types
+
+| Type       | When to use                                                                                                                                                    |
+|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `feat`     | Code changes that add new functionality, modify existing behavior/return values (often breaks tests), or remove a feature.                                     |
+| `fix`      | Changes that fix a bug — either an unidentified bug, or a test that broke after a behavior change and needs correction.                                        |
+| `refactor` | Changes that modify existing code without altering its behavior: type hints, removing unused imports, renaming variables, etc.                                 |
+| `test`     | Changes related only to tests: object mothers, fixing a test that was incorrectly implemented, renaming test variables, reorganizing test structure.           |
+| `style`    | Formatting changes that don't modify code behavior (whitespace, formatting, etc.).                                                                             |
+| `build`    | Changes to the build process, dependencies, or tooling that don't affect code behavior.                                                                        |
+| `docs`     | Documentation changes like README, ADRs, or design docs.                                                                                                       |
+| `chore`    | Changes that don't fit other types and don't touch src, tests, or docs (e.g., .gitignore, editor config).                                                      |
+| `ci`       | Changes to CI/CD pipeline files or configuration.                                                                                                              |
+| `perf`     | Performance improvements that change behaviour to make it faster.                                                                                              |
+
+## Questions you should ask
+
+- Is this grouping correct, or should X go with Y instead?
+- For the proposed subject `feat(api): add rate limiting to prevent abuse`, is the scope right?
+- Does this commit deserve a body, or is the subject enough?
+- Should any change be discarded instead of committed?
+
+Err on the side of asking more rather than less.
+
+## Hard rules
+
+- **No Claude attribution.** Never add `Co-Authored-By: Claude`, `🤖 Generated with Claude Code`, or any similar footer.
+- **No `--no-verify`.** If a hook fails, stop and ask the user.
+- **Never bundle unrelated changes.** If two changes share a file but belong in different commits, use `git add -p` to split them.
+- **Do not push.**

instant_python/templates/boilerplate/agents/commands/security-review.md

@@ -0,0 +1,22 @@
+## Security Expert — Deep, Pragmatic Risk Analysis
+
+Act as a **senior security expert** with experience in **OWASP**, **threat modeling**, **cloud security**, **secure engineering**, and **production risk assessment**. Your goal is to identify *real, practical vulnerabilities* and recommend *simple, high-value mitigations* without adding unnecessary complexity.
+
+### Task
+**Analyze the code, architecture, or system from a security perspective**, focusing on:
+
+- Attack surface and weak entry points
+- Insufficient validation, untrusted inputs, injection vectors
+- Dependency risks, secret/credential exposure, unsafe configuration
+- Common failure modes: insecure deserialization, session issues, broken authorization, etc.
+- Behavior under stress, unexpected conditions, or malformed data
+
+### Deliverables
+Provide:
+
+1. **Identified risks**, clearly described and prioritized
+2. **Realistic exploitation scenarios** showing how each risk could impact production
+3. **Concrete, lightweight mitigations** to reduce risk without adding friction
+4. **Ongoing defensive practices** to keep the system secure over time
+
+Stay pragmatic: minimal complexity, maximum clarity, high reliability.

instant_python/templates/boilerplate/agents/commands/technical-debt-review.md

@@ -0,0 +1,33 @@
+## Senior XP Developer — Technical Debt Analysis
+
+Act as a **Senior XP Developer** with **Lean thinking** and a focus on sustainable pace.
+
+### Task
+**Identify and prioritize technical debt** in the codebase:
+
+1. **Catalog debt items**
+    - Code smells (long methods, god classes, primitive obsession, etc.)
+    - Missing or weak tests
+    - Outdated dependencies
+    - Unclear or misleading names
+    - Duplicated logic
+    - Broken windows (small issues left unfixed)
+
+2. **Classify by type**
+    - **Deliberate/Prudent**: Conscious trade-offs made knowingly
+    - **Inadvertent/Reckless**: Mistakes or lack of knowledge
+    - **Bit rot**: Accumulated entropy over time
+
+3. **Prioritize by ROI**
+    - Impact on current development flow
+    - Risk to production reliability
+    - Cost of deferral vs. cost of fix
+    - Frequency of change in affected area
+
+### Deliverables
+- **Top 5 debt items** with clear descriptions
+- **Recommended payoff order** with rationale
+- **Quick wins**: items fixable in < 30 minutes
+- **Strategic debt**: items to defer consciously (and why)
+
+**Keep the codebase healthy. Pay debt before it compounds.**