Python API Reference

ska_ser_skuid — public symbols

The top-level package re-exports the most commonly used symbols:

class EntityType(value)[source]

Bases: StrEnum

Enumerates all accepted prefixes for SKUID entity types.

Each member value is the short string prefix used in SKUID strings, e.g. EntityType.SBD has value 'sbd' and produces IDs like sbd-6txs9jhxnk7.

DP = 'dp'
EB = 'eb'
OB = 'ob'
OBSQ = 'obsq'
OBSQI = 'obsqi'
PB = 'pb'
PNL = 'pnl'
PNLD = 'pnld'
PRJ = 'prj'
PRP = 'prp'
RVW = 'rvw'
SBD = 'sbd'
SBI = 'sbi'
SFT = 'sft'
SFTA = 'sfta'
SFTC = 'sftc'
SFTCR = 'sftcr'
TXN = 'txn'
classmethod validate(value)[source]
Return type:

Self

exception EntityTypeError[source]

Bases: InvalidSkuidError

Raised when a SKUID is passed with an unexepcted entity type prefix.

Form

alias of SkuidForm

class IntSkuid(prefix, uid)[source]

Bases: NamedTuple

prefix

Alias for field number 0

uid

Alias for field number 1

exception InvalidSkuidError[source]

Bases: ValueError

Raised when trying to process a SKUID that does not conform to ADR-129.

class LongSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to long form (type-<generator_id>-<YYYYMMDD>-<base32>).

Accepts a short or long SKUID string and coerces it to long form. When parameterised with a specific EntityType via LongSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

LongSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import LongSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = LongSkuid("sbd-3v")  # -> "sbd-0-20260107-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnLong = LongSkuid[Literal[EntityType.TXN]]
val = TxnLong(123)  # -> e.g. "txn-0-20260309-3v"
class ShortSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to short form (type-<base32>).

Accepts a short or long SKUID string and coerces it to short form. When parameterised with a specific EntityType via ShortSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

ShortSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import ShortSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = ShortSkuid("sbd-0-20260107-3v")  # -> "sbd-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnShort = ShortSkuid[Literal[EntityType.TXN]]
val = TxnShort(123)  # -> e.g. "txn-3v"
get_scan_id(telescope_bit, generator=<ska_ser_skuid.snowflake.ScanIDGenerator object>)[source]

Generate a Scan ID using the module-level default generator.

Thin convenience wrapper around ScanIDGenerator.generate().

Parameters:

  • telescope_bit (TelescopeBit) – Single bit to avoid collisions between telescopes.

  • generator (ScanIDGenerator) – The ScanIDGenerator instance to use.

Return type:

int

Returns:

A 48-bit Scan ID integer.

Example:

from ska_ser_skuid import LOW_SCAN, MID_SCAN, get_scan_id
scan_id = get_scan_id(LOW_SCAN)
get_snowflake(generator_id=130, generator=<ska_ser_skuid.snowflake.SnowflakeGenerator object>)[source]

Generate a Snowflake ID using the module-level default generator.

Thin convenience wrapper around SnowflakeGenerator.generate().

Parameters:

  • generator_id (int) – A 10-bit integer (0–1023) identifying this generator.

  • generator (SnowflakeGenerator) – The SnowflakeGenerator instance to use.

Return type:

int

Returns:

A 63-bit Snowflake ID.

int_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Convert a SKUID string (short or long) to an (entity_type, integer) named tuple.

Useful for storing SKUIDs as int64 values in a database.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – Either a full SKUID string or just the entity-type prefix (when snowflake is also supplied).

  • snowflake (Optional[int]) – Pre-computed Snowflake integer. When provided, skuid_or_etype is treated as the entity-type prefix rather than a full SKUID string.

  • enforce_validation (bool) – If False, skip full SKUID validation (default True).

Return type:

IntSkuid

Returns:

A IntSkuid named tuple (prefix, uid).

Raises:

InvalidSkuidError – If the SKUID string cannot be parsed and validation is enabled.

is_valid_skuid(skuid)[source]

Return True if skuid is a valid Snowflake-based SKUID string.

Parameters:

skuid (str) – The string to validate.

Return type:

bool

Returns:

True if the string is a valid short or long SKUID, False otherwise.

long_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Return the long-form (type-<gen>-<YYYYMMDD>-<base32>) representation of a SKUID.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – A short or long SKUID string, or just the entity-type prefix when snowflake is also provided.

  • snowflake (Optional[int]) – Pre-computed Snowflake integer (optional).

  • enforce_validation (bool) – If False, already-long strings are returned without re-parsing (default True).

Return type:

Union[LongSkuid[TypeVar(E, bound= EntityType)], str]

Returns:

The SKUID in long form.

Raises:

InvalidSkuidError – If the input cannot be parsed and validation is enabled.

make_generator_id(value)[source]

Deterministically produce a 10-bit generator ID by hashing the input bytes.

Uses BLAKE2b (2-byte digest) truncated to 10 bits. The default generator ID is derived from the system hostname via this function.

Parameters:

value (bytes) – Bytes to hash, e.g. socket.getfqdn().encode().

Return type:

int

Returns:

An integer in the range [0, 1024) (10 bits).

Example:

from ska_ser_skuid import make_generator_id, mint_skuid, EntityType
GENERATOR_ID = make_generator_id(b'my-service-instance')  # e.g. 620
skuid = mint_skuid(EntityType.SBD, generator_id=GENERATOR_ID)
mint_skuid(entity_type, *, generator_id=130, generator_instance=<ska_ser_skuid.snowflake.SnowflakeGenerator object>, form=SkuidForm.SHORT)[source]

Generate a new SKUID.

Parameters:

  • entity_type (TypeVar(E, bound= EntityType)) – The entity type prefix, e.g. 'sbd', 'eb', or EntityType.SBD.

  • generator_id (int) – A 10-bit integer (0-1023) that identifies the system minting this SKUID. Derive one deterministically using make_generator_id(). Defaults to a hash of the system hostname.

  • generator_instance (SnowflakeGenerator) – The SnowflakeGenerator instance to use. Uses the module-level default when omitted.

  • form (SkuidForm | str) – Whether to return the short (default) or long form. Accepts SkuidForm enum values or the strings 'short' / 'long'.

Return type:

Union[ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)]]

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)
short_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Return the short-form (type-<base32>) representation of a SKUID.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – A short or long SKUID string, or just the entity-type prefix when snowflake is also provided.

  • snowflake (Optional[int]) – Pre-computed Snowflake integer (optional).

  • enforce_validation (bool) – If False, the base32 suffix is extracted directly without full validation (default True).

Return type:

Union[ShortSkuid[TypeVar(E, bound= EntityType)], str]

Returns:

The SKUID in short form.

Raises:

InvalidSkuidError – If the input cannot be parsed and validation is enabled.

Core — ska_ser_skuid.skuid

class IntSkuid(prefix, uid)[source]

Bases: NamedTuple

prefix

Alias for field number 0

uid

Alias for field number 1

class LongSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to long form (type-<generator_id>-<YYYYMMDD>-<base32>).

Accepts a short or long SKUID string and coerces it to long form. When parameterised with a specific EntityType via LongSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

LongSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import LongSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = LongSkuid("sbd-3v")  # -> "sbd-0-20260107-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnLong = LongSkuid[Literal[EntityType.TXN]]
val = TxnLong(123)  # -> e.g. "txn-0-20260309-3v"
class ShortSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to short form (type-<base32>).

Accepts a short or long SKUID string and coerces it to short form. When parameterised with a specific EntityType via ShortSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

ShortSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import ShortSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = ShortSkuid("sbd-0-20260107-3v")  # -> "sbd-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnShort = ShortSkuid[Literal[EntityType.TXN]]
val = TxnShort(123)  # -> e.g. "txn-3v"
class SkuidForm(value)[source]

Bases: StrEnum

Supported formats for SKUIDs.

LONG = 'long'
SHORT = 'short'
class SnowflakeSkuid(entity_type, snowflake_id)[source]

Bases: Generic[E]

Representation of a Snowflake-based SKUID.

__init__(entity_type, snowflake_id)[source]

Construct a SnowflakeSkuid.

Parameters:

  • entity_type (TypeVar(E, bound= EntityType)) – The SKA entity type prefix, e.g. EntityType.SBD.

  • snowflake_id (int) – A 63-bit Snowflake integer.

Raises:

InvalidSkuidError – If snowflake_id is outside [0, 2**63).

property datetime

The UTC datetime representation of the snowflake timestamp.

entity_type
property generator_id

The generator ID component of the snowflake.

long()[source]

Return the long string representation of the SKUID.

Return type:

LongSkuid[TypeVar(E, bound= EntityType)]

classmethod parse(skuid)[source]

Parse a SKUID string into a SnowflakeSkuid instance.

Accepts both the short form (type-<base32>) and the long form (type-<gen>-<YYYYMMDD>-<base32>).

Use sparingly. As a general rule, SKUIDs should be treated as opaque, atomic identifiers similar to a UUID.

Parameters:

skuid (Union[ShortSkuid[TypeVar(_F, bound= EntityType)], LongSkuid[TypeVar(_F, bound= EntityType)]]) – The SKUID string to parse.

Return type:

SnowflakeSkuid[TypeVar(_F, bound= EntityType)]

Returns:

The parsed SKUID.

Raises:

InvalidSkuidError – If skuid is not a valid SKUID string.

property random_suffix

The random suffix component of the snowflake.

short()[source]

Return the short string representation of the SKUID.

Return type:

ShortSkuid[TypeVar(E, bound= EntityType)]

snowflake
property timestamp_ms

The timestamp component of the snowflake in milliseconds.

int_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Convert a SKUID string (short or long) to an (entity_type, integer) named tuple.

Useful for storing SKUIDs as int64 values in a database.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – Either a full SKUID string or just the entity-type prefix (when snowflake is also supplied).

  • snowflake (Optional[int]) – Pre-computed Snowflake integer. When provided, skuid_or_etype is treated as the entity-type prefix rather than a full SKUID string.

  • enforce_validation (bool) – If False, skip full SKUID validation (default True).

Return type:

IntSkuid

Returns:

A IntSkuid named tuple (prefix, uid).

Raises:

InvalidSkuidError – If the SKUID string cannot be parsed and validation is enabled.

is_valid_skuid(skuid)[source]

Return True if skuid is a valid Snowflake-based SKUID string.

Parameters:

skuid (str) – The string to validate.

Return type:

bool

Returns:

True if the string is a valid short or long SKUID, False otherwise.

long_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Return the long-form (type-<gen>-<YYYYMMDD>-<base32>) representation of a SKUID.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – A short or long SKUID string, or just the entity-type prefix when snowflake is also provided.

  • snowflake (Optional[int]) – Pre-computed Snowflake integer (optional).

  • enforce_validation (bool) – If False, already-long strings are returned without re-parsing (default True).

Return type:

Union[LongSkuid[TypeVar(E, bound= EntityType)], str]

Returns:

The SKUID in long form.

Raises:

InvalidSkuidError – If the input cannot be parsed and validation is enabled.

mint_skuid(entity_type, *, generator_id=130, generator_instance=<ska_ser_skuid.snowflake.SnowflakeGenerator object>, form=SkuidForm.SHORT)[source]

Generate a new SKUID.

Parameters:

  • entity_type (TypeVar(E, bound= EntityType)) – The entity type prefix, e.g. 'sbd', 'eb', or EntityType.SBD.

  • generator_id (int) – A 10-bit integer (0-1023) that identifies the system minting this SKUID. Derive one deterministically using make_generator_id(). Defaults to a hash of the system hostname.

  • generator_instance (SnowflakeGenerator) – The SnowflakeGenerator instance to use. Uses the module-level default when omitted.

  • form (SkuidForm | str) – Whether to return the short (default) or long form. Accepts SkuidForm enum values or the strings 'short' / 'long'.

Return type:

Union[ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)]]

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)
short_skuid(skuid_or_etype, snowflake=None, *, enforce_validation=True)[source]

Return the short-form (type-<base32>) representation of a SKUID.

Parameters:

  • skuid_or_etype (Union[TypeVar(E, bound= EntityType), ShortSkuid[TypeVar(E, bound= EntityType)], LongSkuid[TypeVar(E, bound= EntityType)], str]) – A short or long SKUID string, or just the entity-type prefix when snowflake is also provided.

  • snowflake (Optional[int]) – Pre-computed Snowflake integer (optional).

  • enforce_validation (bool) – If False, the base32 suffix is extracted directly without full validation (default True).

Return type:

Union[ShortSkuid[TypeVar(E, bound= EntityType)], str]

Returns:

The SKUID in short form.

Raises:

InvalidSkuidError – If the input cannot be parsed and validation is enabled.

Snowflake generator — ska_ser_skuid.snowflake

Snowflake ID generator.

Heavily adapted from https://github.com/10xHub/snowflakekit https://en.wikipedia.org/wiki/Snowflake_ID

class ScanIDGenerator[source]

Bases: _TimestampGeneratorBase

Generates unique 48-bit Scan IDs as opaque integers.

Layout: [42 bits timestamp][5 bits sequence][1 bit generator]

__init__()[source]
generate(telescope_bit=TelescopeBit.LOW)[source]

Generate a collision-resistent 48-bit Scan ID.

Thread-safe. If all 32 sequence values are exhausted within the current millisecond, waits until the clock advances.

Parameters:

telescope_bit (TelescopeBit) – Single bit to avoid collisions between telescopes.

Return type:

int

Returns:

A 48-bit Scan ID integer.

Raises:

  • ValueError – If telescope_bit is not 1 or 0.

  • RuntimeError – If the system clock moves backwards.

class SnowflakeGenerator[source]

Bases: _TimestampGeneratorBase

Generates unique 63-bit IDs using the Snowflake algorithm.

__init__()[source]
generate(*, generator_id=130)[source]

Generate a collision-safe 63-bit Snowflake ID.

Thread-safe. If all 2048 random suffixes are exhausted within the current millisecond, waits until the clock advances.

Parameters:

generator_id (int) – A 10-bit integer (0–1023) identifying this generator. Defaults to a hash of the system hostname.

Return type:

int

Returns:

A 63-bit Snowflake ID.

Raises:

  • OverflowError – If generator_id is outside [0, 1024).

  • RuntimeError – If the system clock moves backwards.

class TelescopeBit(value)[source]

Bases: IntEnum

An enumeration.

LOW = 0
MID = 1
extract_generator_id(snowflake)[source]

Extract the 10-bit generator ID from a Snowflake integer.

Parameters:

snowflake (int) – A 63-bit Snowflake ID.

Return type:

int

Returns:

The generator ID component (0–1023).

extract_random_suffix(snowflake)[source]

Extract the 11-bit random suffix from a Snowflake integer.

Parameters:

snowflake (int) – A 63-bit Snowflake ID.

Return type:

int

Returns:

The random suffix component (0–2047).

extract_timestamp_ms(snowflake)[source]

Extract the Unix timestamp (milliseconds) from a Snowflake integer.

The returned value is a standard Unix epoch timestamp in milliseconds (SKUID timestamp offset is added internally).

Parameters:

snowflake (int) – A 63-bit Snowflake ID.

Return type:

int

Returns:

Unix timestamp in milliseconds.

get_scan_id(telescope_bit, generator=<ska_ser_skuid.snowflake.ScanIDGenerator object>)[source]

Generate a Scan ID using the module-level default generator.

Thin convenience wrapper around ScanIDGenerator.generate().

Parameters:
Return type:

int

Returns:

A 48-bit Scan ID integer.

Example:

from ska_ser_skuid import LOW_SCAN, MID_SCAN, get_scan_id
scan_id = get_scan_id(LOW_SCAN)
get_snowflake(generator_id=130, generator=<ska_ser_skuid.snowflake.SnowflakeGenerator object>)[source]

Generate a Snowflake ID using the module-level default generator.

Thin convenience wrapper around SnowflakeGenerator.generate().

Parameters:
Return type:

int

Returns:

A 63-bit Snowflake ID.

make_generator_id(value)[source]

Deterministically produce a 10-bit generator ID by hashing the input bytes.

Uses BLAKE2b (2-byte digest) truncated to 10 bits. The default generator ID is derived from the system hostname via this function.

Parameters:

value (bytes) – Bytes to hash, e.g. socket.getfqdn().encode().

Return type:

int

Returns:

An integer in the range [0, 1024) (10 bits).

Example:

from ska_ser_skuid import make_generator_id, mint_skuid, EntityType
GENERATOR_ID = make_generator_id(b'my-service-instance')  # e.g. 620
skuid = mint_skuid(EntityType.SBD, generator_id=GENERATOR_ID)
unix_epoch()[source]

Return the Unix epoch timestamp in milliseconds.

Return type:

int

Returns:

unix epoch in milliseconds.

Entity types — ska_ser_skuid.entity_types

class EntityType(value)[source]

Bases: StrEnum

Enumerates all accepted prefixes for SKUID entity types.

Each member value is the short string prefix used in SKUID strings, e.g. EntityType.SBD has value 'sbd' and produces IDs like sbd-6txs9jhxnk7.

DP = 'dp'
EB = 'eb'
OB = 'ob'
OBSQ = 'obsq'
OBSQI = 'obsqi'
PB = 'pb'
PNL = 'pnl'
PNLD = 'pnld'
PRJ = 'prj'
PRP = 'prp'
RVW = 'rvw'
SBD = 'sbd'
SBI = 'sbi'
SFT = 'sft'
SFTA = 'sfta'
SFTC = 'sftc'
SFTCR = 'sftcr'
TXN = 'txn'
classmethod validate(value)[source]
Return type:

Self

class StrEnum(value)[source]

Bases: str, Enum

An enumeration.

Errors — ska_ser_skuid.errors

exception EntityTypeError[source]

Bases: InvalidSkuidError

Raised when a SKUID is passed with an unexepcted entity type prefix.

exception InvalidSkuidError[source]

Bases: ValueError

Raised when trying to process a SKUID that does not conform to ADR-129.

SKUID string types — ska_ser_skuid.skuid.classes

class ShortSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to short form (type-<base32>).

Accepts a short or long SKUID string and coerces it to short form. When parameterised with a specific EntityType via ShortSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

ShortSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import ShortSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = ShortSkuid("sbd-0-20260107-3v")  # -> "sbd-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnShort = ShortSkuid[Literal[EntityType.TXN]]
val = TxnShort(123)  # -> e.g. "txn-3v"
class LongSkuid(value)[source]

Bases: SkuidStrBase[E]

A SKUID string normalised to long form (type-<generator_id>-<YYYYMMDD>-<base32>).

Accepts a short or long SKUID string and coerces it to long form. When parameterised with a specific EntityType via LongSkuid[Literal[EntityType.SBD]], it additionally:

  • rejects strings whose prefix does not match, and

  • accepts bare snowflake integers and applies the known prefix.

LongSkuid is a plain str subclass, so it can be used anywhere a string is expected. It also integrates with Pydantic v2 as a field type.

Examples:

from ska_ser_skuid import LongSkuid, EntityType
from typing import Literal

# Unparameterised — accepts any entity type, string input only
val = LongSkuid("sbd-3v")  # -> "sbd-0-20260107-3v"

# Parameterised — enforces prefix, accepts integer snowflake input
TxnLong = LongSkuid[Literal[EntityType.TXN]]
val = TxnLong(123)  # -> e.g. "txn-0-20260309-3v"

Base32 encoding — ska_ser_skuid.base32

b32decode(encoded_id)[source]

Decode a Crockford Base32 string back to an integer.

Parameters:

encoded_id (str) – A non-empty string using the Crockford Base32 alphabet.

Return type:

int

Returns:

The decoded non-negative integer.

Raises:

ValueError – If encoded_id is empty or contains an invalid character.

b32encode(n)[source]

Encode a non-negative integer using Crockford Base32.

Uses the alphabet 0-9 a-z (excluding i, l, o, u).

Parameters:

n (int) – Non-negative integer to encode.

Return type:

str

Returns:

Crockford Base32 string representation.

Raises:

ValueError – If n is negative.