rugged-gemini: Skill for Claude Code

Python Idioms and Patterns

Python rewards explicitness and readability. Follow Zen of Python. If it reads like plain English, it's idiomatic.

Scope: Python coding idioms. Layout: @.gemini/skills/project-structure-python/SKILL.md. Tests: GEMINI.md § Testing Strategy. Logging: @.gemini/skills/logging-and-observability-principles/SKILL.md.

Type Hints — Non-Negotiable

Always annotate function signatures and public APIs. Use from __future__ import annotations.

from __future__ import annotations
from collections.abc import Sequence

def calculate_discount(items: Sequence[Item], coupon: Coupon) -> float: ...

1. X | None over Optional[X] (3.10+):

   def find_user(user_id: str) -> User | None: ...
   

2. TypeAlias and TypeVar:

   from typing import TypeVar, TypeAlias
   T = TypeVar("T")
   UserId: TypeAlias = str
   

3. Protocol for structural interfaces (duck-typing):

   from typing import Protocol
   
   class TaskStorage(Protocol):
       def get_by_id(self, task_id: str) -> Task: ...
       def save(self, task: Task) -> None: ...
   

4. TypedDict for structured boundary dicts:

   from typing import TypedDict
   
   class CreateTaskRequest(TypedDict):
       title: str
       priority: Literal["low", "medium", "high"]
   

Error Handling

General: GEMINI.md § Error Handling Principles. Python-specific below.

1. Specific exceptions over except Exception:

   try:
       task = storage.get_by_id(task_id)
   except TaskNotFoundError:
       raise HTTPException(status_code=404, detail="Task not found")
   

2. Domain exception hierarchies:

   class FathError(Exception):
       """Base exception for all domain errors."""
   
   class NotFoundError(FathError):
       def __init__(self, resource: str, resource_id: str) -> None:
           self.resource = resource
           self.resource_id = resource_id
           super().__init__(f"{resource} '{resource_id}' not found")
   
   class ValidationError(FathError):
       def __init__(self, field: str, message: str) -> None:
           self.field = field
           self.message = message
           super().__init__(f"Validation failed on '{field}': {message}")