uv-scripts.mdc

---
description: Standards for creating and managing utility scripts with UV
globs: scripts/.*
---
# UV Scripts Standards

<rule>
name: uv_scripts
description: Standards for creating and managing utility scripts with UV

filters:
  - type: file_extension
    pattern: "\\.py$"
  - type: path
    pattern: "^scripts/.*"
  - type: exclude_path
    pattern: "^(stackone_ai|examples)/.*"  # Exclude package and examples

actions:
  - type: suggest
    message: |
      When creating utility scripts with UV:

      1. Location:
         - Place all utility scripts in the `scripts/` directory
         - NOT for examples (use examples/ directory instead)
      
      2. Include UV script dependencies header:
         ```python
         # /// script
         # requires-python = ">=3.8"
         # dependencies = [
         #   "package1",
         #   "package2>=1.0.0"
         # ]
         # ///
         ```

      3. Script Structure:
         - Type hints are required
         - Use async/await when doing I/O operations
         - Include main guard: `if __name__ == "__main__":`
         - Add return types to functions

      4. Running Scripts:
         ```bash
         uv run scripts/your_script.py
         ```

      5. Error Handling:
         - Use try/except blocks for external calls
         - Print meaningful error messages
         - Exit with appropriate status codes

examples:
  - input: |
      # Utility script
      # /// script
      # requires-python = ">=3.8"
      # dependencies = ["httpx"]
      # ///

      from typing import Dict
      import asyncio
      import httpx

      async def fetch_data() -> Dict:
          async with httpx.AsyncClient() as client:
              response = await client.get("https://api.example.com")
              return response.json()

      if __name__ == "__main__":
          asyncio.run(fetch_data())
    output: "Correctly structured utility script"

metadata:
  priority: high
  version: 1.1
  tags:
    - scripts
    - uv
    - python
</rule>