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 firstSemVer 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#
| Type | Definition | Description |
|---|---|---|
Identifier | type Identifier = str | int | |
ReleaseType | type ReleaseType = Literal['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'] | |
Input | type Input = SemVer | str | Components |
Classes#
Functions#
invalid#
invalid(message) -> NeverRaise a SemVerError with message.
| Parameter | Type | Description |
|---|---|---|
message | str |
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>": .
| Parameter | Type | Description |
|---|---|---|
label | str | |
input | str | |
parse | Callable[[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) -> intA version component: digits without leading zeros, at most 2**53 - 1.
| Parameter | Type | Description |
|---|---|---|
value | str | |
label | str |
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) -> IdentifierA pre-release identifier, digits read as an int.
| Parameter | Type | Description |
|---|---|---|
identifier | Identifier |
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 identifiersame_core#
same_core(a, b) -> boolWhether MAJOR.MINOR.PATCH are equal.
| Parameter | Type | Description |
|---|---|---|
a | Core | |
b | Core |
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).
| Parameter | Type | Description |
|---|---|---|
a | Core | |
b | Core |
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) -> SemVerA version from its components; raises SemVerError when invalid.
| Parameter | Type | Description |
|---|---|---|
components | Components |
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.
| Parameter | Type | Description |
|---|---|---|
text | str |
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) -> SemVerparse; raises its SemVerError.
| Parameter | Type | Description |
|---|---|---|
text | str |
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.
| Parameter | Type | Description |
|---|---|---|
value | Input |
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| Parameter | Type | Description |
|---|---|---|
value | Input |
Returns SemVer
def from_input_unsafe(value: Input) -> SemVer:
return _or_raise(from_input(value))