Python Learning - Agentic Development Workspace

A fully configured VS Code workspace for agentic Python development with best practices built-in.

🚀 Quick Start

1. Setup Virtual Environment

python -m venv venv
source venv/bin/activate  # macOS/Linux
# or for Windows:
# venv\Scripts\activate

2. Install Dependencies

pip install -r requirements.txt

3. Configure Pre-commit Hooks (Optional but Recommended)

pre-commit install

4. Create .env File

cp .env.example .env
# Edit .env with your configuration

📁 Project Structure

.
├── src/                          # Your Python modules
│   └── __init__.py
├── tests/                        # Test files
│   └── __init__.py
├── .github/
│   ├── instructions/
│   │   └── python.instructions.md
│   └── workflows/                # GitHub Actions
├── .vscode/
│   └── settings.json             # VS Code configuration
├── pyproject.toml                # Project metadata & tool config
├── requirements.txt              # Python dependencies
├── pytest.ini                    # Pytest configuration
├── .pre-commit-config.yaml       # Pre-commit hooks
├── .env.example                  # Environment variables template
└── README.md

🛠️ Development Workflow

Formatting & Linting

# Format all Python files
ruff format .

# Lint and check for issues
ruff check . --fix

# Type checking
mypy src/

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_example.py::test_function_name

# Run tests with markers
pytest -m unit          # Only unit tests
pytest -m integration   # Only integration tests

Debugging

• Set breakpoints in VS Code (F9 on line)
• Press F5 to start debugger
• Use Run → Run Without Debugging (Ctrl+F5) to run directly

API Testing

Open Thunder Client (⚡ icon in sidebar) to test HTTP requests without leaving VS Code.

🔧 VS Code Extensions

Installed & configured:

• Python - Language support & debugging
• Pylance - Type checking & IntelliSense
• Ruff - Linter & formatter (auto on save)
• Thunder Client - HTTP client for API testing

📝 Agent Development Tips

Writing Tool Functions

from typing import Annotated
from dataclasses import dataclass

@dataclass
class ToolResult:
    """Structured result from an agent tool."""
    status: str
    data: dict
    error: str | None = None

def agent_tool(
    input_value: Annotated[str, "Input description"],
    timeout: Annotated[int, "Timeout in seconds"] = 30,
) -> ToolResult:
    """Tool function for agent execution.
    
    Args:
        input_value: Description of the input
        timeout: How long to wait
        
    Returns:
        ToolResult with status, data, and optional error
    """
    try:
        # Your logic here
        return ToolResult(status="success", data={})
    except Exception as e:
        return ToolResult(status="error", data={}, error=str(e))

Testing Agent Tools

import pytest
from src.agent_tools import agent_tool

@pytest.mark.unit
def test_agent_tool():
    """Test agent tool with mocked dependencies."""
    result = agent_tool("test input")
    assert result.status == "success"
    assert isinstance(result.data, dict)

🚦 GitHub Actions (CI/CD)

Place workflow files in .github/workflows/ to enable:

• Automated testing on push
• Code quality checks
• Coverage reports
• Type checking

📦 Adding Dependencies

New Production Dependency

pip install <package>
pip freeze > requirements.txt

New Dev Dependency

Edit pyproject.toml under [project.optional-dependencies] → dev

⚙️ Configuration

• Python version: 3.10+ (configured in pyproject.toml)
• Line length: 100 characters
• Type checking: Pylance standard mode
• Test discovery: tests/test_*.py
• Coverage target: Shown in pyproject.toml

🐛 Troubleshooting

Ruff not formatting on save?

• Ensure .vscode/settings.json has editor.formatOnSave: true
• Restart VS Code
• Check Ruff extension is installed: ruff in Extensions

Tests not discovered?

• Ensure tests/ directory exists
• Test files must start with test_
• Test functions must start with test_
• Run pytest --collect-only to debug

Type hints not working?

• Pylance should be installed
• Check python.analysis.typeCheckingMode: "standard" in settings
• Restart Python extension: Cmd+Shift+P → "Developer: Reload Window"

📚 Resources

• Python Best Practices
• Pytest Documentation
• Type Hints
• Ruff Documentation

📄 License

MIT - See LICENSE file for details

---

Next Steps:

1. ✅ Virtual environment created
2. ✅ Dependencies installed
3. ✅ Pre-commit hooks configured
4. Create your first module in src/
5. Add tests in tests/
6. Start building!