"""list_dir — return the immediate children of a directory."""

from __future__ import annotations

import errno
from pathlib import Path

from .exceptions import (
    FilesystemOSError,
    NotADirectory,
    PermissionDenied,
    SourceNotFound,
)


def list_dir(path: Path) -> list[Path]:
    """Return the immediate children of ``path``, sorted by name.

    Returns absolute :class:`~pathlib.Path` objects for both files and
    directories. Does not recurse.

    Raises:
        SourceNotFound: ``path`` does not exist.
        NotADirectory: ``path`` exists but is not a directory.
        PermissionDenied: the directory is not readable.
        FilesystemOSError: any other ``OSError`` from ``iterdir``.
    """
    if not path.exists():
        raise SourceNotFound(path)
    if not path.is_dir():
        raise NotADirectory(path)

    try:
        return sorted(path.iterdir())
    except PermissionError as e:
        raise PermissionDenied(path, action="list_dir") from e
    except OSError as e:
        if e.errno == errno.EACCES:
            raise PermissionDenied(path, action="list_dir") from e
        raise FilesystemOSError("list_dir", path, e) from e