Source code for ska_ser_skuid.skuid.mint

from __future__ import annotations

from enum import Enum
from typing import Literal, overload

from ..snowflake import (
    DEFAULT_GENERATOR_ID,
    DEFAULT_SNOWFLAKE_GENERATOR_INSTANCE,
    SnowflakeGenerator,
    get_snowflake,
)
from .core import E, SnowflakeSkuid
from .strings import LongSkuid, ShortSkuid




class SkuidForm(str, Enum):
    """Supported formats for SKUIDs."""

    SHORT = "short"
    LONG = "long"



@overload
def mint_skuid(
    entity_type: E,
    *,
    generator_id: int = ...,
    generator_instance: SnowflakeGenerator = ...,
    form: Literal[SkuidForm.SHORT, "short"] = ...,
) -> ShortSkuid[E]: ...


@overload
def mint_skuid(
    entity_type: E,
    *,
    generator_id: int = ...,
    generator_instance: SnowflakeGenerator = ...,
    form: Literal[SkuidForm.LONG, "long"],
) -> LongSkuid[E]: ...




def mint_skuid(
    entity_type: E,
    *,
    generator_id: int = DEFAULT_GENERATOR_ID,
    generator_instance: SnowflakeGenerator = DEFAULT_SNOWFLAKE_GENERATOR_INSTANCE,
    form: SkuidForm | str = SkuidForm.SHORT,
) -> ShortSkuid[E] | LongSkuid[E]:
    """Generate a new SKUID.

    :param entity_type: The entity type prefix, e.g. ``'sbd'``, ``'eb'``, or
        :attr:`EntityType.SBD`.
    :param generator_id: A 10-bit integer (0-1023) that identifies the system
        minting this SKUID.  Derive one deterministically using
        :func:`make_generator_id`.  Defaults to a hash of the system hostname.
    :param generator_instance: The :class:`~ska_ser_skuid.snowflake.SnowflakeGenerator`
        instance to use.  Uses the module-level default when omitted.
    :param form: Whether to return the short (default) or long form.
        Accepts :class:`SkuidForm` enum values or the strings ``'short'`` / ``'long'``.
    :returns: A SKUID string. Short form example: ``'sbd-6txs9jhxnk7'``.
        Long form example: ``'sbd-986-20260218-6txs9jhxnk7'``.

    Example::

        from ska_ser_skuid import mint_skuid, EntityType
        skuid = mint_skuid(EntityType.SBD)

    """
    form = SkuidForm(form)
    snowflake_id = get_snowflake(generator_id=generator_id, generator=generator_instance)
    skuid = SnowflakeSkuid[E](entity_type, snowflake_id)
    if form is SkuidForm.LONG:
        return skuid.long()
    else:
        return skuid.short()