"""DTOs for post use cases.

This module defines Data Transfer Objects used for communication between
application layer use cases and presentation layer. DTOs are immutable
dataclasses that carry data across process boundaries.
"""

from dataclasses import dataclass
from datetime import datetime
from uuid import UUID


@dataclass(frozen=True)
class CreatePostDTO:
    """DTO for creating a post.

    Carries post creation data from API to use case.
    Contains all required fields for post creation.

    Attributes:
        title: Post title string.
        content: Post content string.
        author_id: Identifier of the post author.
        tags: Optional list of tags for categorization.

    Example:
        >>> dto = CreatePostDTO(
        ...     title="My Post",
        ...     content="Content here...",
        ...     author_id="user-123",
        ...     tags=["python"]
        ... )
    """

    title: str
    content: str
    author_id: str
    tags: list[str] | None = None


@dataclass(frozen=True)
class UpdatePostDTO:
    """DTO for updating a post.

    Carries optional post update data. All fields are optional
    allowing partial updates.

    Attributes:
        title: Optional new title.
        content: Optional new content.
        tags: Optional new tags list.

    Example:
        >>> dto = UpdatePostDTO(title="Updated Title")
    """

    title: str | None = None
    content: str | None = None
    tags: list[str] | None = None


@dataclass(frozen=True)
class PostResponseDTO:
    """DTO for post response.

    Carries complete post data for API responses.
    Includes all post attributes and metadata.

    Attributes:
        id: Unique post identifier.
        title: Post title.
        content: Post content.
        slug: URL-friendly slug.
        author_id: Author identifier.
        published: Publication status.
        tags: List of tags.
        created_at: Creation timestamp.
        updated_at: Last update timestamp.

    Example:
        >>> dto = PostResponseDTO(
        ...     id=uuid,
        ...     title="Post",
        ...     content="...",
        ...     slug="post",
        ...     author_id="user-123",
        ...     published=True,
        ...     tags=[],
        ...     created_at=datetime.now(),
        ...     updated_at=datetime.now()
        ... )
    """

    id: UUID
    title: str
    content: str
    slug: str
    author_id: str
    published: bool
    tags: list[str]
    created_at: datetime
    updated_at: datetime