python-code-style

Follow Python code organization conventions including method ordering, datetime handling, circular import avoidance, and type annotations. Use when organizing service classes, handling dates, or structuring modules.

Ir para a instalação

Repositório: gestrich/python-architecture
Última atividade na origem: 25 de janeiro de 2026 às 16:26
Idioma detectado do SKILL.md: inglês
Estrelas: 0
Forks: 0

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.

npx skills add https://github.com/gestrich/python-architecture --skill python-code-style

O comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.

Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

SKILL.md

Instruções da origem · Visualização somente leitura

Voltar à pesquisa Voltar à instalação

cli-architecture

Structure CLI applications using command dispatcher pattern. Covers entry points, command routing, argument parsing, and explicit parameter flow. Use when building CLI tools or refactoring command structure.

2026-01-25

creating-services

Creates new Python service classes following Martin Fowler's Service Layer pattern with constructor-based dependency injection, proper layering (Core vs Composite), and static vs instance method conventions. Use when adding new services or refactoring business logic into service classes.

2026-01-25

identifying-layer-placement

Determines the correct architectural layer (Entry Point/Service/Domain/Infrastructure) for code placement in Python applications using Service Layer pattern. Prevents layer violations and maintains separation of concerns. Use when adding new functionality, refactoring code, or unclear where code should live.

2026-01-25

Ver todas deste repositório

from datetime import datetime, timezone

# ✅ Always timezone-aware
now = datetime.now(timezone.utc)
timestamp = datetime(2025, 1, 15, 10, 30, 0, tzinfo=timezone.utc)

# ❌ Never naive
now = datetime.now()  # Missing timezone

class UserService:
    def __init__(self):
        pass

    # ❌ Private method before public methods
    def _validate_email(self, email: str):
        pass

    # ❌ Public methods scattered after private ones
    def create_user(self, email: str, name: str):
        return self._validate_email(email)

    def _hash_password(self, password: str):
        pass

    def authenticate(self, email: str, password: str):
        pass

class UserService:
    def __init__(self, db: Database):
        self.db = db

    # Public API methods first (high-level to low-level)
    def create_user(self, email: str, name: str) -> User:
        """Create a new user account."""
        self._validate_email(email)
        return User(email=email, name=name)

    def authenticate(self, email: str, password: str) -> bool:
        """Authenticate user credentials."""
        user = self.db.find_user(email)
        return self._verify_password(user, password)

    # Private helper methods last
    def _validate_email(self, email: str):
        """Validate email format."""
        if "@" not in email:
            raise ValueError("Invalid email")

    def _verify_password(self, user: User, password: str) -> bool:
        """Verify password hash."""
        return self._hash_password(password) == user.password_hash

    def _hash_password(self, password: str) -> str:
        """Hash password for storage."""
        return hashlib.sha256(password.encode()).hexdigest()

class ReportService:
    def __init__(self, repo: str):
        self.repo = repo

    def __str__(self):
        return f"ReportService({self.repo})"

    # Class methods
    @classmethod
    def from_config(cls, config: dict):
        return cls(config["repo"])

    # Static methods
    @staticmethod
    def validate_format(fmt: str):
        return fmt in ["json", "csv", "html"]

    # Public instance methods (high-level first)
    def generate_report(self, data: list) -> str:
        validated = self._validate_data(data)
        return self._format_output(validated)

    def export_report(self, report: str, path: str):
        self._write_file(path, report)

    # Private helpers
    def _validate_data(self, data: list):
        return [item for item in data if item]

    def _format_output(self, data: list) -> str:
        return "\n".join(str(item) for item in data)

    def _write_file(self, path: str, content: str):
        with open(path, "w") as f:
            f.write(content)

class SimpleService:
    def __init__(self):
        pass

    # Public API methods
    def operation_one(self):
        pass

    def operation_two(self):
        pass

    # Static utility methods
    @staticmethod
    def utility_function():
        pass

    # Private helper methods
    def _internal_helper(self):
        pass

class ComplexService:
    def __init__(self):
        pass

    # ============================================================
    # Core CRUD Operations
    # ============================================================

    def create_resource(self, data: dict):
        pass

    def get_resource(self, id: str):
        pass

    def update_resource(self, id: str, data: dict):
        pass

    def delete_resource(self, id: str):
        pass

    # ============================================================
    # Query Operations
    # ============================================================

    def find_resources(self, filter: dict):
        pass

    def count_resources(self, filter: dict):
        pass

    # ============================================================
    # Utility Operations
    # ============================================================

    @staticmethod
    def parse_identifier(text: str):
        pass

    @staticmethod
    def validate_data(data: dict):
        pass

# artifact_operations.py

from dataclasses import dataclass
from typing import List

# ============================================================
# Public Models
# ============================================================

@dataclass
class ProjectArtifact:
    """Public dataclass for artifact data."""
    name: str
    size: int
    created_at: str

@dataclass
class ArtifactMetadata:
    """Metadata for artifact collections."""
    total_count: int
    total_size: int

# ============================================================
# Public API Functions
# ============================================================

def find_artifacts(project: str) -> List[ProjectArtifact]:
    """Highest-level public function - main entry point."""
    raw_data = _fetch_from_api(project)
    return [_parse_artifact(item) for item in raw_data]

def get_artifact_details(artifact: ProjectArtifact) -> dict:
    """Mid-level public function - supporting operation."""
    return {
        "name": artifact.name,
        "size_mb": artifact.size / 1024 / 1024,
        "age_days": calculate_age(artifact.created_at)
    }

# ============================================================
# Module Utilities
# ============================================================

def parse_artifact_name(name: str) -> tuple[str, str]:
    """Utility function used by multiple operations."""
    parts = name.split("-")
    return parts[0], "-".join(parts[1:])

def calculate_age(timestamp: str) -> int:
    """Calculate age in days from timestamp."""
    # Implementation
    pass

# ============================================================
# Private Helper Functions
# ============================================================

def _fetch_from_api(project: str) -> list:
    """Private implementation detail - API interaction."""
    # Implementation
    pass

def _parse_artifact(data: dict) -> ProjectArtifact:
    """Private implementation detail - data parsing."""
    return ProjectArtifact(
        name=data["name"],
        size=data["size"],
        created_at=data["created_at"]
    )

from datetime import datetime

# ❌ Naive datetime - no timezone information
now = datetime.now()
timestamp = datetime(2025, 1, 15, 10, 30, 0)
utc_now = datetime.utcnow()  # ❌ Deprecated and naive

# Problems with naive datetimes:
# - Ambiguous: Which timezone does this represent?
# - Cannot compare naive and timezone-aware datetimes
# - Serialized without timezone, leading to misinterpretation

from datetime import datetime, timezone

# ✅ Always use timezone-aware datetimes
now = datetime.now(timezone.utc)
timestamp = datetime(2025, 1, 15, 10, 30, 0, tzinfo=timezone.utc)

# ✅ Use UTC for all internal operations
created_at = datetime.now(timezone.utc)
last_updated = datetime.now(timezone.utc)

# ✅ Serialize to ISO 8601 with timezone
timestamp_str = now.isoformat()  # "2025-01-15T10:30:00+00:00"

from datetime import datetime, timezone

def parse_iso_timestamp(timestamp_str: str) -> datetime:
    """Parse ISO 8601 timestamp to timezone-aware datetime.

    Handles both "Z" and "+00:00" timezone formats.
    """
    if timestamp_str.endswith("Z"):
        timestamp_str = timestamp_str[:-1] + "+00:00"

    dt = datetime.fromisoformat(timestamp_str)

    # Ensure timezone-aware
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)

    return dt

# Usage
parsed_dt = parse_iso_timestamp("2025-01-15T10:30:00Z")
parsed_dt2 = parse_iso_timestamp("2025-01-15T10:30:00+00:00")

from dataclasses import dataclass
from datetime import datetime, timezone

@dataclass
class Event:
    name: str
    created_at: datetime

    def __post_init__(self):
        """Validate that datetime fields are timezone-aware."""
        if self.created_at.tzinfo is None:
            raise ValueError(
                f"created_at must be timezone-aware. "
                f"Use datetime.now(timezone.utc) or parse_iso_timestamp()"
            )

# ✅ Valid - timezone-aware
event = Event("deployment", datetime.now(timezone.utc))

# ❌ Raises ValueError - naive datetime
event = Event("deployment", datetime.now())

❌ Avoid	✅ Use Instead
`datetime.now()`	`datetime.now(timezone.utc)`
`datetime.utcnow()` (deprecated)	`datetime.now(timezone.utc)`
`datetime(2025, 1, 15, 10, 30)`	`datetime(2025, 1, 15, 10, 30, tzinfo=timezone.utc)`
`datetime.fromisoformat(iso_str)`	`parse_iso_timestamp(iso_str)`

# ❌ BAD: TYPE_CHECKING guard
from typing import TYPE_CHECKING, List

if TYPE_CHECKING:
    from module_b import SomeClass  # Only imported during type checking

def process_items(items: List["SomeClass"]):  # String annotation workaround
    pass

# ❌ BAD: Using Any to avoid circular import
from typing import Any, List

def process_items(items: List[Any]):  # Lost type safety
    pass

# lower_level.py - No imports from higher_level.py
from dataclasses import dataclass

@dataclass
class GitHubPullRequest:
    number: int
    title: str
    state: str

# higher_level.py - Can import from lower_level.py
from typing import List
from lower_level import GitHubPullRequest  # ✅ One-way dependency

@dataclass
class ProjectStats:
    project_name: str
    open_prs: List[GitHubPullRequest]  # ✅ Proper typing, no strings

# Before: Circular dependency
# module_a.py imports from module_b.py
# module_b.py imports from module_a.py

# After: Shared module breaks the cycle
# shared.py - Common types both modules need
@dataclass
class SharedType:
    pass

# module_a.py - Imports from shared
from shared import SharedType

# module_b.py - Imports from shared
from shared import SharedType

# ❌ Avoid: Quoted string annotation
class User:
    @classmethod
    def from_string(cls, value: str) -> "User":
        return cls()

# ✅ Use: Self type (Python 3.11+)
from typing import Self

class User:
    @classmethod
    def from_string(cls, value: str) -> Self:
        return cls()

    @classmethod
    def from_dict(cls, data: dict) -> Self:
        return cls()

# ✅ Use: Deferred annotations for self-referential types
from __future__ import annotations

from dataclasses import dataclass
from typing import List, Optional

@dataclass
class Section:
    name: str
    elements: List[Section]  # ✅ No quotes needed - deferred evaluation
    parent: Optional[Section] = None

    def add(self, element: Section) -> Section:  # ✅ Clean type hints
        self.elements.append(element)
        element.parent = self
        return self

# Without __future__ import, you'd need:
# elements: List["Section"]  # ❌ Less readable

name	python-code-style
description	Follow Python code organization conventions including method ordering, datetime handling, circular import avoidance, and type annotations. Use when organizing service classes, handling dates, or structuring modules.
user-invocable	true
argument-hint	[topic]

name	python-code-style
description	Follow Python code organization conventions including method ordering, datetime handling, circular import avoidance, and type annotations. Use when organizing service classes, handling dates, or structuring modules.
user-invocable	true
argument-hint	[topic]

python-code-style

Informações da origem

Opções de instalação

Revise os arquivos de origem

Mais deste repositório

Python Code Style

When to Use This Skill

Quick Reference

Method Organization Hierarchy

Python Code Style

When to Use This Skill

Quick Reference

Method Organization Hierarchy

Datetime Usage

Principle: Method Organization

Public Before Private

Anti-Pattern (❌ Avoid)

Recommended Pattern (✅ Use This)

Standard Method Order

Benefits

Principle: Section Headers for Complex Services

When to Use Section Headers

Simple Section Comments

Descriptive Headers for Complex Services

Benefits

Principle: Module-Level Code Organization

Function-Based Modules

Recommended Pattern (✅ Use This)

Benefits

Principle: Always Use Timezone-Aware Datetimes

Anti-Pattern (❌ Avoid)

Recommended Pattern (✅ Use This)

Parsing ISO 8601 Timestamps

Domain Model Validation

Why UTC?

Common Pitfalls

Benefits

Principle: Avoid Circular Imports

Anti-Pattern (❌ Avoid)

Recommended Pattern (✅ Use This)

When You Have a Genuine Cycle

Benefits

Principle: Modern Type Annotations

Use Self for Factory Methods

Use from __future__ import annotations for Self-Referential Types

Benefits

Related Patterns

Related Skills

Further Reading

Mais deste repositório

Use `Self` for Factory Methods

Use `from future import annotations` for Self-Referential Types