DEFAULT_SOCKET_CANDIDATES

Return the socket candidates in Herdr's documented precedence order. Supplying a named session returns only that session's socket path; otherwise environment variables and the default path are considered.

Return socket candidates in Herdr's documented precedence order.

Parameters:

Name	Type	Description	Default
session	str | None	Optional named Herdr session. When supplied, only that session's socket path is returned.	None

Returns:

Type	Description
list[Path]	Candidate paths ordered by precedence. Without session, the result uses
list[Path]	HERDR_SOCKET_PATH, then HERDR_SESSION, then the default socket.

Example

from herdr_client import DEFAULT_SOCKET_CANDIDATES

candidates = DEFAULT_SOCKET_CANDIDATES(session="work")
print(candidates[0])

Source code in src/herdr_client/transport.py

def DEFAULT_SOCKET_CANDIDATES(session: str | None = None) -> list[Path]:
    """Return socket candidates in Herdr's documented precedence order.

    Args:
        session: Optional named Herdr session. When supplied, only that session's
            socket path is returned.

    Returns:
        Candidate paths ordered by precedence. Without ``session``, the result uses
        ``HERDR_SOCKET_PATH``, then ``HERDR_SESSION``, then the default socket.

    Example:
        ```python
        from herdr_client import DEFAULT_SOCKET_CANDIDATES

        candidates = DEFAULT_SOCKET_CANDIDATES(session="work")
        print(candidates[0])
        ```
    """
    if session is not None:
        return [session_socket_path(session)]

    explicit = os.environ.get("HERDR_SOCKET_PATH")
    if explicit is not None and explicit != "":
        return [Path(explicit)]

    env_session = os.environ.get("HERDR_SESSION")
    if env_session is not None and env_session != "":
        return [session_socket_path(env_session)]

    return [config_dir() / "herdr.sock"]