GitHub

API reference for semver.

Semantic versions, SemVer 2.0.0 (Effect's SemVer)::

v = semver.parse_unsafe("1.2.3-rc.1+build")
v.prerelease          # ("rc", 1)
v.bump("minor")       # SemVer 1.3.0
v < semver.parse_unsafe("1.2.3")  # True: a pre-release comes first

SemVer is a frozen dataclass that validates itself: components are integers from 0 to 2**53 - 1, identifiers match [0-9A-Za-z-]+, a numeric pre-release identifier is an int ("2" becomes 2) without leading zeros. < / > follow the spec's precedence, which ignores build metadata; == and hash include it (Effect's Order and Equivalence). Bumps follow npm's semver.inc.

Types

TypeDefinitionDescription
Identifiertype Identifier = str | int
ReleaseTypetype ReleaseType = Literal['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease']
Inputtype Input = SemVer | str | Components

Classes

Functions

invalid

invalid(message) -> Never

Raise a SemVerError with message.

ParameterTypeDescription
messagestr

Returns Never

def invalid(message: str) -> Never:
    """Raise a ``SemVerError`` with ``message``."""
    raise SemVerError(message)

try_parse

try_parse[A](label, input, parse) -> Result[A, SemVerError]

parse(input), its SemVerError prefixed with Invalid <label> "<input>": .

ParameterTypeDescription
labelstr
inputstr
parseCallable[[str], A]

Returns Result[A, SemVerError]

def try_parse[A](label: str, input: str, parse: Callable[[str], A]) -> Result[A, SemVerError]:
    """``parse(input)``, its ``SemVerError`` prefixed with ``Invalid
    <label> "<input>": ``."""
    try:
        return Ok(parse(input))
    except SemVerError as error:
        return Err(SemVerError(f"Invalid {label} {quote(input)}: {error.message}", input))

parse_component

parse_component(value, label) -> int

A version component: digits without leading zeros, at most 2**53 - 1.

ParameterTypeDescription
valuestr
labelstr

Returns int

def parse_component(value: str, label: str) -> int:
    """A version component: digits without leading zeros, at most ``2**53 - 1``."""
    if not is_digits(value) or (value[0] == "0" and value != "0"):
        invalid(
            f"{label} must be a non-negative integer without leading zeros, received {quote(value)}"
        )
    if len(value) > _SAFE_DIGITS or int(value) > _MAX_SAFE:
        # JavaScript's ``Number(value)``: 20 digits round, 400 are Infinity.
        invalid(f"{label} must be a non-negative safe integer, received {js_number(float(value))}")
    return int(value)

prerelease_identifier

prerelease_identifier(identifier) -> Identifier

A pre-release identifier, digits read as an int.

ParameterTypeDescription
identifierIdentifier

Returns Identifier

def prerelease_identifier(identifier: Identifier) -> Identifier:
    """A pre-release identifier, digits read as an ``int``."""
    if isinstance(identifier, int):
        return _check_component(identifier, "numeric pre-release identifier")
    if not _IDENTIFIER.fullmatch(identifier):
        invalid(
            f"pre-release identifier must be non-empty [0-9A-Za-z-], received {quote(identifier)}"
        )
    if is_digits(identifier):
        return parse_component(identifier, "numeric pre-release identifier")
    return identifier

same_core

same_core(a, b) -> bool

Whether MAJOR.MINOR.PATCH are equal.

ParameterTypeDescription
aCore
bCore

Returns bool

def same_core(a: Core, b: Core) -> bool:
    """Whether MAJOR.MINOR.PATCH are equal."""
    return (a.major, a.minor, a.patch) == (b.major, b.minor, b.patch)

compare_core

compare_core(a, b) -> Literal[-1, 0, 1]

Precedence of MAJOR.MINOR.PATCH and the pre-release (build ignored).

ParameterTypeDescription
aCore
bCore

Returns Literal[-1, 0, 1]

def compare_core(a: Core, b: Core) -> Literal[-1, 0, 1]:
    """Precedence of MAJOR.MINOR.PATCH and the pre-release (build ignored)."""
    return (
        _sign(a.major, b.major)
        or _sign(a.minor, b.minor)
        or _sign(a.patch, b.patch)
        or _compare_prerelease(a.prerelease, b.prerelease)
    )

make

make(components) -> SemVer

A version from its components; raises SemVerError when invalid.

ParameterTypeDescription
componentsComponents

Returns SemVer

def make(components: Components) -> SemVer:
    """A version from its components; raises ``SemVerError`` when invalid."""
    return SemVer(
        components["major"],
        components["minor"],
        components["patch"],
        tuple(components.get("prerelease", ())),
        tuple(components.get("build", ())),
    )

parse

parse(text) -> Result[SemVer, SemVerError]

A SemVer 2.0.0 string, or the reason it is not one.

ParameterTypeDescription
textstr

Returns Result[SemVer, SemVerError]

def parse(text: str) -> Result[SemVer, SemVerError]:
    """A SemVer 2.0.0 string, or the reason it is not one."""
    return try_parse("SemVer", text, _parse_or_raise)

parse_unsafe

parse_unsafe(text) -> SemVer

parse; raises its SemVerError.

ParameterTypeDescription
textstr

Returns SemVer

def parse_unsafe(text: str) -> SemVer:
    """``parse``; raises its ``SemVerError``."""
    return _or_raise(parse(text))

from_input

from_input(value) -> Result[SemVer, SemVerError]

A version as is, a string parsed, or components checked.

ParameterTypeDescription
valueInput

Returns Result[SemVer, SemVerError]

def from_input(value: Input) -> Result[SemVer, SemVerError]:
    """A version as is, a string parsed, or components checked."""
    if isinstance(value, SemVer):
        return Ok(value)
    if isinstance(value, str):
        return parse(value)
    try:
        return Ok(make(value))
    except SemVerError as error:
        return Err(error)

from_input_unsafe

from_input_unsafe(value) -> SemVer
ParameterTypeDescription
valueInput

Returns SemVer

def from_input_unsafe(value: Input) -> SemVer:
    return _or_raise(from_input(value))