from uuid import UUID from sqlalchemy import select from sqlalchemy.exc import IntegrityError from sqlalchemy.orm import Session from .exceptions import EmailAlreadyExistsError from .models import User from .schema import UserCreate, UserUpdate def retrieve_user_by_id(session: Session, user_id: UUID) -> User | None: """Retrieve a user by their unique identifier. Args: session (Session): The active database session. user_id (UUID): The unique identifier of the user to retrieve. Returns: User | None: The matching user, or ``None`` if no user exists with the given ID. """ return session.get(User, user_id) def list_users(session: Session) -> list[User]: """Retrieve a list of users. Args: session (Session): The active database session. Returns: list[User]: The users, ordered by creation time. """ stmt = select(User).order_by(User.created_at) return list(session.scalars(stmt).all()) def insert_user(session: Session, new_user: UserCreate) -> User: """Create and persist a new user. Args: session (Session): The active database session. new_user (UserCreate): The data for the user to create. Returns: User: The persisted user, including database-generated fields such as ``id`` and ``created_at``. Raises: EmailAlreadyExistsError: If a user with the given email already exists. """ user = User(**new_user.model_dump()) session.add(user) try: session.commit() except IntegrityError as exc: session.rollback() raise EmailAlreadyExistsError(new_user.email) from exc session.refresh(user) return user def update_user(session: Session, user: User, user_update: UserUpdate) -> User: """Apply a partial update to an existing user. Only fields explicitly set on ``user_update`` are modified; all other fields retain their current values. Args: session (Session): The active database session. user (User): The user to update. user_update (UserUpdate): The fields to change and their new values. Returns: User: The updated user, refreshed from the database. Raises: EmailAlreadyExistsError: If the update changes the email to one already registered to another user. """ update_values = user_update.model_dump(exclude_unset=True) for field, value in update_values.items(): setattr(user, field, value) try: session.commit() except IntegrityError as exc: session.rollback() raise EmailAlreadyExistsError(update_values.get("email")) from exc session.refresh(user) return user def delete_user(session: Session, user: User) -> None: """Permanently delete a user. The user's associated ``UserAuth`` record is deleted along with it via the relationship's cascade. Args: session (Session): The active database session. user (User): The user to delete. """ session.delete(user) session.commit()