Initial commit

2025-11-30 09:00:19 +08:00
commit abf7b25716
6 changed files with 1377 additions and 0 deletions
--- a/skills/python-project-setup/SKILL.md
+++ b/skills/python-project-setup/SKILL.md
@@ -0,0 +1,486 @@
+---
+name: python-project-setup
+description: Sets up modern Python projects with uv tooling, src layout, and PEP8 standards. Handles both new and existing projects, presents interactive library selection for CLI/TUI apps, generates pyproject.toml, and provides complete scaffolding with type hints and proper structure.
+---
+
+# Python Project Setup Skill
+
+A specialized skill for setting up modern Python projects using uv tooling, best practices, and standardized project structures.
+
+## Overview
+
+This skill enables Claude to autonomously set up Python projects following modern best practices. It promotes the use of `uv` (the fast Python package manager), enforces PEP8 standards, type hints, and proper project structure with `src` layout.
+
+## Capabilities
+
+When activated, this skill provides:
+
+1. **Modern Tooling with uv**
+   - Use `uv` instead of pip/python directly
+   - Initialize virtual environments: `uv venv`
+   - Manage dependencies: `uv add`, `uv remove`
+   - Sync dependencies: `uv sync`
+   - Run scripts: `uv run`
+
+2. **Project Structure Detection & Setup**
+   - Detect if project is new or existing
+   - Analyze current structure and adapt recommendations
+   - Promote `src/package_name` layout
+   - Create proper `__init__.py` files
+   - Setup `__main__.py` entry points
+
+3. **pyproject.toml Management**
+   - Generate modern pyproject.toml
+   - Configure project metadata
+   - Setup dependencies and dev dependencies
+   - Include tool configurations (ruff, mypy, pytest)
+   - Define entry points for CLI applications
+
+4. **Library Selection**
+   - Present interactive menu for library choices
+   - **CLI applications**: click (commands), rich (output), inquirer (interactive prompts)
+   - **TUI applications**: textual (framework), rich (rendering)
+   - **Pure libraries**: minimal dependencies
+   - Smart recommendations based on project type
+
+5. **Standards Enforcement**
+   - PEP8 compliance via ruff
+   - Type hints for all functions/methods
+   - Proper docstring formats (Google/NumPy style)
+   - Follow PEP8 and modern Python standards
+
+## Usage
+
+This skill activates automatically when:
+- User requests: "Create a new Python project"
+- User asks: "Setup Python project structure"
+- User mentions: "Initialize Python package"
+- User wants to: "Migrate to uv"
+- Claude detects Python project initialization
+- pyproject.toml creation or modification is discussed
+
+**Automatic Defaults**:
+- Uses current directory as project root
+- Derives package name from directory name
+- Detects and uses current Python version
+- No tests (user can add later)
+- Minimal dependencies by default
+
+**Only ONE Question**:
+- Project type + libraries combined (default: minimal)
+
+## Project Setup Approach
+
+### For New Projects
+
+**IMPORTANT**: Always work in the current directory as the project root.
+
+1. **Gather Requirements**
+   - Package name (derive from current directory name by default)
+   - **Ask ONE merged question**: Project type + libraries combined:
+     ```
+     What type of project? (press Enter for CLI with click+rich)
+     [1] CLI with click+rich (default)
+     [2] CLI with argparse
+     [3] CLI with typer
+     [4] TUI with textual
+     [5] Generic Python Project
+     ```
+   - **Don't ask about tests** - skip by default
+
+2. **Assume Current Directory & Python Version**
+   - **Use current folder as project root** (don't create new directory)
+   - Derive package name from current folder name (convert to valid Python identifier)
+   - Example: `my-awesome-app/` → package name: `my_awesome_app`
+   - **Detect current Python version** and use as project requirement
+   - Example: `python --version` → `Python 3.11.5` → `requires-python = ">=3.11"`
+
+3. **Check Environment**
+   ```bash
+   # Detect current Python version
+   python --version  # Use this as the project's Python requirement
+
+   # Verify uv is installed
+   uv --version
+
+   # If not installed, provide instructions:
+   # macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
+   # Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   ```
+
+4. **Create Minimal Project Structure in Current Directory**
+   ```
+   ./                           # Current directory (project root)
+   ├── src/
+   │   └── package_name/
+   │       ├── __init__.py
+   │       └── __main__.py      # Entry point
+   ├── pyproject.toml           # Minimal config
+   ├── README.md
+   └── .gitignore
+   ```
+
+   **Note**: No tests/, no .python-version - keep it minimal!
+
+5. **Skip Tests by Default**
+   - Do NOT ask about tests
+   - Do NOT create tests/ directory
+   - Do NOT include pytest in dev dependencies
+   - User can add tests later if needed
+
+6. **Generate Minimal pyproject.toml**
+   ```toml
+   [project]
+   name = "package-name"
+   version = "0.1.0"
+   description = "Project description"
+   authors = [
+       {name = "Author Name", email = "author@example.com"}
+   ]
+   readme = "README.md"
+   requires-python = ">=3.11"  # Use detected Python version (e.g., 3.11, 3.12, etc.)
+   dependencies = [
+       # Based on library selection
+   ]
+
+   [project.optional-dependencies]
+   dev = [
+       "ruff>=0.1.0",
+       "mypy>=1.8.0",
+   ]
+   # Note: No pytest by default - add when needed
+
+   [project.scripts]
+   package-name = "package_name.__main__:main"
+
+   [build-system]
+   requires = ["hatchling"]
+   build-backend = "hatchling.build"
+
+   [tool.ruff]
+   line-length = 88
+   target-version = "py311"
+   select = ["E", "F", "I", "N", "W", "UP"]
+
+   [tool.mypy]
+   python_version = "3.11"
+   strict = true
+   warn_return_any = true
+   warn_unused_configs = true
+
+   [tool.pytest.ini_options]
+   testpaths = ["tests"]
+   python_files = ["test_*.py"]
+   ```
+
+8. **Initialize with uv in Current Directory**
+   ```bash
+   # Already in project directory (current folder)
+
+   # Create virtual environment
+   uv venv
+
+   # Sync dependencies from pyproject.toml
+   uv sync
+
+   # Add project in editable mode
+   uv pip install -e .
+
+   # Add development dependencies (includes pytest if tests opted in)
+   uv sync --group dev
+   ```
+
+9. **Create Entry Point Examples**
+
+   For `src/package_name/__main__.py`:
+   ```python
+   """Main entry point for package_name."""
+
+   def main() -> None:
+       """Execute the main program."""
+       print("Hello from package_name!")
+
+   if __name__ == "__main__":
+       main()
+   ```
+
+   For CLI apps with click:
+   ```python
+   """Main entry point for package_name CLI."""
+
+   import click
+   from rich.console import Console
+
+   console = Console()
+
+   @click.group()
+   @click.version_option()
+   def main() -> None:
+       """Package name CLI application."""
+       pass
+
+   @main.command()
+   @click.option("--name", default="World", help="Name to greet")
+   def hello(name: str) -> None:
+       """Greet someone."""
+       console.print(f"[bold green]Hello, {name}![/bold green]")
+
+   if __name__ == "__main__":
+       main()
+   ```
+
+### For Existing Projects
+
+**IMPORTANT**: Always work in the current directory, don't create subdirectories.
+
+1. **Analyze Current Directory Structure**
+   - Check for setup.py, requirements.txt, or pyproject.toml
+   - Identify current package structure
+   - Assess if src layout is used
+   - **Detect existing tests/** directory
+
+2. **Detect Context**
+   - Is uv already being used?
+   - What's the current dependency management approach?
+   - Are there existing entry points?
+   - **Are tests already present?** (skip test skeleton question if yes)
+
+3. **Skip Tests Question**
+   - Do NOT ask about tests for existing projects
+   - User can add tests manually if needed
+
+4. **Provide Migration Path**
+   ```bash
+   # Already in project directory (current folder)
+
+   # Convert requirements.txt to pyproject.toml
+   # Create pyproject.toml with [project.dependencies]
+
+   # Initialize uv for existing project
+   uv venv
+
+   # Import existing requirements
+   uv pip install -r requirements.txt
+
+   # Generate lock file
+   uv sync
+   ```
+
+5. **Recommend Structure Improvements**
+   - Suggest moving to src layout if not present
+   - Identify missing __init__.py files
+   - Recommend adding __main__.py if needed
+   - Suggest adding type hints if missing
+
+6. **Adapt, Don't Force**
+   - Respect existing conventions if reasonable
+   - Provide gradual migration suggestions
+   - Explain benefits of each recommendation
+
+## Output Format
+
+Provide setup results in this format:
+
+```markdown
+## Python Project Setup Complete
+
+### Project Directory
+**Working in**: `./` (current directory)
+**Package name**: `package_name`
+
+### Project Structure
+[Show created directory tree relative to current directory]
+
+### Configuration
+- **Python version**: [Detected from current environment, e.g., 3.11+]
+- **Package manager**: uv
+- **Layout**: src layout
+- **Entry point**: src/package_name/__main__.py
+- **Tests**: Not included (add later if needed)
+
+### Dependencies Installed
+**Main dependencies:**
+- [list dependencies]
+
+**Development dependencies:**
+- ruff (linting)
+- mypy (type checking)
+
+### Next Steps
+1. Activate virtual environment:
+   \`\`\`bash
+   source .venv/bin/activate  # Linux/macOS
+   .venv\\Scripts\\activate     # Windows
+   \`\`\`
+
+2. Run your application:
+   \`\`\`bash
+   uv run python -m package_name
+   # or
+   uv run package-name
+   \`\`\`
+
+3. Add new dependencies:
+   \`\`\`bash
+   uv add package-name
+   \`\`\`
+
+4. Lint code:
+   \`\`\`bash
+   uv run ruff check .
+   uv run mypy src
+   \`\`\`
+
+### Development Commands
+- Add dependency: `uv add package-name`
+- Add dev dependency: `uv add --dev package-name`
+- Remove dependency: `uv remove package-name`
+- Update dependencies: `uv sync`
+- Run script: `uv run python script.py`
+```
+
+## Standards Enforced
+
+### Always Use uv Commands
+- ❌ `pip install package`
+- ✅ `uv add package`
+
+- ❌ `pip install -r requirements.txt`
+- ✅ `uv sync`
+
+- ❌ `python script.py`
+- ✅ `uv run python script.py`
+
+- ❌ `python -m venv .venv`
+- ✅ `uv venv`
+
+### Project Structure Standards
+```
+src/package_name/          # Use src layout
+├── __init__.py           # Package marker (can be empty or contain version)
+├── __main__.py           # Entry point with main() function
+├── module1.py            # Application modules
+└── module2.py
+```
+
+### Code Standards
+- All functions must have type hints
+- Use `"""Docstrings"""` for all public functions/classes
+- Follow PEP8 (enforced by ruff)
+- Line length: 88 characters (Black standard)
+- Use absolute imports from package root
+
+### Example Type-Hinted Code
+```python
+from typing import Optional
+
+def process_data(
+    input_data: list[str],
+    max_items: int = 10,
+    filter_empty: bool = True
+) -> dict[str, int]:
+    """Process input data and return statistics.
+
+    Args:
+        input_data: List of strings to process
+        max_items: Maximum number of items to process
+        filter_empty: Whether to filter out empty strings
+
+    Returns:
+        Dictionary with processing statistics
+    """
+    result: dict[str, int] = {}
+    # Implementation
+    return result
+```
+
+## Library Recommendations
+
+### For CLI Applications
+```toml
+dependencies = [
+    "click>=8.1.0",      # Command-line interface framework
+    "rich>=13.7.0",      # Beautiful terminal output
+    "inquirer>=3.2.0",   # Interactive prompts
+]
+```
+
+### For TUI Applications
+```toml
+dependencies = [
+    "textual>=0.47.0",   # Modern TUI framework
+    "rich>=13.7.0",      # Rendering engine
+]
+```
+
+### For Libraries
+```toml
+dependencies = [
+    # Only essential dependencies
+    # Keep it minimal
+]
+```
+
+## Best Practices
+
+1. **Work in current directory** - Don't create nested project folders
+2. **Use current Python version** - Detect from environment, don't ask
+3. **Ask one merged question** - Project type + libraries combined
+4. **Start with minimal dependencies** - Add more as needed
+5. **Always include type hints** - Helps with IDE support and catches bugs
+6. **Use src layout** - Prevents import issues and packaging problems
+7. **Pin major versions only** - e.g., `>=8.1.0` not `==8.1.0`
+8. **Separate dev dependencies** - Use `[project.optional-dependencies]`
+9. **Document with docstrings** - Every public function and class
+10. **Don't ask about tests** - Skip by default, users add when ready
+11. **Use ruff for linting** - Fast, comprehensive, replaces flake8/isort/black
+
+## Common Patterns
+
+### CLI Application with Click + Rich
+```python
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+@click.command()
+@click.argument("name")
+@click.option("--count", default=1, help="Number of greetings")
+def greet(name: str, count: int) -> None:
+    """Greet NAME COUNT times."""
+    for _ in range(count):
+        console.print(f"[bold blue]Hello, {name}![/bold blue]")
+```
+
+### TUI Application with Textual
+```python
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Button
+
+class MyApp(App):
+    """A simple Textual application."""
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Button("Click me!", id="btn")
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button press."""
+        self.notify("Button clicked!")
+
+if __name__ == "__main__":
+    app = MyApp()
+    app.run()
+```
+
+## Integration
+
+This skill works seamlessly with:
+- New Python project creation
+- Existing project modernization
+- Migration from pip to uv
+- Package structure refactoring
+- Dependency management tasks