Segments

Epoch

Bases: Representation, String

Represents the epoch segment of the version (e!).

Source code in versions/segments/epoch.py

@frozen(repr=False, eq=True, order=True)
class Epoch(Representation, String):
    """Represents the *epoch* segment of the version (`e!`)."""

    value: int = DEFAULT_VALUE

    def __bool__(self) -> bool:
        return bool(self.value)

    @classmethod
    def create(cls, value: int = DEFAULT_VALUE) -> Self:
        """Creates an [`Epoch`][versions.segments.epoch.Epoch] from `value`.

        Arguments:
            value: The value of the epoch.

        Returns:
            The newly created [`Epoch`][versions.segments.epoch.Epoch].
        """
        return cls(value)

    @classmethod
    def from_string(cls, string: str) -> Self:
        """Parses an [`Epoch`][versions.segments.epoch.Epoch] from `string`.

        Arguments:
            string: The string to parse.

        Returns:
            The parsed epoch.
        """
        return cls(int(string))

    def to_string(self) -> str:
        """Converts an [`Epoch`][versions.segments.epoch.Epoch] to its string representation.

        Returns:
            The epoch string.
        """
        return str(self.value)

    def set_value(self, value: int) -> Self:
        """Sets the value of the epoch.

        Arguments:
            value: The value to set.

        Returns:
            The updated epoch.
        """
        return evolve(self, value=value)

    def next_value(self) -> Self:
        """Increments the value of the epoch.

        Returns:
            The next epoch.
        """
        return self.set_value(increment(self.value))

create(value: int = DEFAULT_VALUE) -> Self classmethod

Creates an Epoch from value.

Parameters:

Name	Type	Description	Default
value	int	The value of the epoch.	DEFAULT_VALUE

Returns:

Type	Description
Self	The newly created Epoch.

Source code in versions/segments/epoch.py

@classmethod
def create(cls, value: int = DEFAULT_VALUE) -> Self:
    """Creates an [`Epoch`][versions.segments.epoch.Epoch] from `value`.

    Arguments:
        value: The value of the epoch.

    Returns:
        The newly created [`Epoch`][versions.segments.epoch.Epoch].
    """
    return cls(value)

from_string(string: str) -> Self classmethod

Parses an Epoch from string.

Parameters:

Name	Type	Description	Default
string	str	The string to parse.	required

Returns:

Type	Description
Self	The parsed epoch.

Source code in versions/segments/epoch.py

@classmethod
def from_string(cls, string: str) -> Self:
    """Parses an [`Epoch`][versions.segments.epoch.Epoch] from `string`.

    Arguments:
        string: The string to parse.

    Returns:
        The parsed epoch.
    """
    return cls(int(string))

to_string() -> str

Converts an Epoch to its string representation.

Returns:

Type	Description
str	The epoch string.

Source code in versions/segments/epoch.py

def to_string(self) -> str:
    """Converts an [`Epoch`][versions.segments.epoch.Epoch] to its string representation.

    Returns:
        The epoch string.
    """
    return str(self.value)

set_value(value: int) -> Self

Sets the value of the epoch.

Parameters:

Name	Type	Description	Default
value	int	The value to set.	required

Returns:

Type	Description
Self	The updated epoch.

Source code in versions/segments/epoch.py

def set_value(self, value: int) -> Self:
    """Sets the value of the epoch.

    Arguments:
        value: The value to set.

    Returns:
        The updated epoch.
    """
    return evolve(self, value=value)

next_value() -> Self

Increments the value of the epoch.

Returns:

Type	Description
Self	The next epoch.

Source code in versions/segments/epoch.py

def next_value(self) -> Self:
    """Increments the value of the epoch.

    Returns:
        The next epoch.
    """
    return self.set_value(increment(self.value))

Local

Bases: Representation, String

Represents the local segment of the version (+local.n)

Source code in versions/segments/local.py

@frozen(repr=False, eq=True, order=True)
class Local(Representation, String):
    """Represents the *local* segment of the version (`+local.n`)"""

    parts: LocalParts = field(eq=False, order=False)
    """The local segment parts."""

    compare_parts: CompareLocalParts = field(
        repr=False, init=False, eq=True, order=True, hash=False
    )

    @parts.validator
    def check_parts(self, attribute: Attribute[LocalParts], value: LocalParts) -> None:
        if not value:
            raise ValueError(EMPTY_LOCAL)

    @compare_parts.default
    def default_compare_parts(self) -> CompareLocalParts:
        empty = EMPTY

        return tuple(
            (part, empty) if is_int(part) else (negative_infinity, part)  # type: ignore[misc]
            for part in self.parts
        )

    @classmethod
    def create(cls, parts: LocalParts) -> Local:
        """Creates a [`Local`][versions.segments.local.Local] segment from local `parts`.

        Arguments:
            parts: The local parts.

        Returns:
            The newly created [`Local`][versions.segments.local.Local] segment.
        """
        return cls(parts)

    @classmethod
    def from_iterable(cls, iterable: Iterable[LocalPart]) -> Self:
        """Creates a [`Local`][versions.segments.Local] segment from `iterable`.

        Arguments:
            iterable: The local parts in an iterable.

        Returns:
            The newly created [`Local`][versions.segments.Local] segment.
        """
        return cls(tuple(iterable))

    @classmethod
    def from_parts(cls, *parts: LocalPart) -> Self:
        """Creates a [`Local`][versions.segments.Local] segment from local `parts`.

        Arguments:
            *parts: The local parts.

        Returns:
            The newly created [`Local`][versions.segments.Local] segment.
        """
        return cls(parts)

    def into_parts(self) -> LocalParts:
        """Converts a [`Local`][versions.segments.Local] segment to its parts.

        Returns:
            The parts of the local segment.
        """
        return self.parts

    def set_parts(self, *parts: LocalPart) -> Self:
        """Sets the parts of a [`Local`][versions.segments.Local] segment.

        Arguments:
            *parts: The new parts.

        Returns:
            The updated local segment.
        """
        return evolve(self, parts=parts)

    @classmethod
    def from_string(cls, string: str) -> Self:
        """Parses a [`Local`][versions.segments.Local] segment from `string`.

        Arguments:
            string: The string to parse.

        Returns:
            The parsed local segment.
        """
        return cls.from_iterable(map(local_part, split_separators(string)))

    def to_string(self) -> str:
        """Converts a [`Local`][versions.segments.Local] segment to its string representation.

        Returns:
            The local segment string.
        """
        return concat_dot(map(str, self.parts))

parts: LocalParts = field(eq=False, order=False) class-attribute instance-attribute

The local segment parts.

create(parts: LocalParts) -> Local classmethod

Creates a Local segment from local parts.

Parameters:

Name	Type	Description	Default
parts	LocalParts	The local parts.	required

Returns:

Type	Description
Local	The newly created Local segment.

Source code in versions/segments/local.py

@classmethod
def create(cls, parts: LocalParts) -> Local:
    """Creates a [`Local`][versions.segments.local.Local] segment from local `parts`.

    Arguments:
        parts: The local parts.

    Returns:
        The newly created [`Local`][versions.segments.local.Local] segment.
    """
    return cls(parts)

from_iterable(iterable: Iterable[LocalPart]) -> Self classmethod

Creates a Local segment from iterable.

Parameters:

Name	Type	Description	Default
iterable	Iterable[LocalPart]	The local parts in an iterable.	required

Returns:

Type	Description
Self	The newly created Local segment.

Source code in versions/segments/local.py

@classmethod
def from_iterable(cls, iterable: Iterable[LocalPart]) -> Self:
    """Creates a [`Local`][versions.segments.Local] segment from `iterable`.

    Arguments:
        iterable: The local parts in an iterable.

    Returns:
        The newly created [`Local`][versions.segments.Local] segment.
    """
    return cls(tuple(iterable))

from_parts(*parts: LocalPart) -> Self classmethod

Creates a Local segment from local parts.

Parameters:

Name	Type	Description	Default
*parts	LocalPart	The local parts.	()

Returns:

Type	Description
Self	The newly created Local segment.

Source code in versions/segments/local.py

@classmethod
def from_parts(cls, *parts: LocalPart) -> Self:
    """Creates a [`Local`][versions.segments.Local] segment from local `parts`.

    Arguments:
        *parts: The local parts.

    Returns:
        The newly created [`Local`][versions.segments.Local] segment.
    """
    return cls(parts)

into_parts() -> LocalParts

Converts a Local segment to its parts.

Returns:

Type	Description
LocalParts	The parts of the local segment.

Source code in versions/segments/local.py

def into_parts(self) -> LocalParts:
    """Converts a [`Local`][versions.segments.Local] segment to its parts.

    Returns:
        The parts of the local segment.
    """
    return self.parts

set_parts(*parts: LocalPart) -> Self

Sets the parts of a Local segment.

Parameters:

Name	Type	Description	Default
*parts	LocalPart	The new parts.	()

Returns:

Type	Description
Self	The updated local segment.

Source code in versions/segments/local.py

def set_parts(self, *parts: LocalPart) -> Self:
    """Sets the parts of a [`Local`][versions.segments.Local] segment.

    Arguments:
        *parts: The new parts.

    Returns:
        The updated local segment.
    """
    return evolve(self, parts=parts)

from_string(string: str) -> Self classmethod

Parses a Local segment from string.

Parameters:

Name	Type	Description	Default
string	str	The string to parse.	required

Returns:

Type	Description
Self	The parsed local segment.

Source code in versions/segments/local.py

@classmethod
def from_string(cls, string: str) -> Self:
    """Parses a [`Local`][versions.segments.Local] segment from `string`.

    Arguments:
        string: The string to parse.

    Returns:
        The parsed local segment.
    """
    return cls.from_iterable(map(local_part, split_separators(string)))

to_string() -> str

Converts a Local segment to its string representation.

Returns:

Type	Description
str	The local segment string.

Source code in versions/segments/local.py

def to_string(self) -> str:
    """Converts a [`Local`][versions.segments.Local] segment to its string representation.

    Returns:
        The local segment string.
    """
    return concat_dot(map(str, self.parts))

Release

Bases: Representation, String

Represents the release segment of the version (x.y.z).

Source code in versions/segments/release.py

@frozen(repr=False, eq=True, order=True)
class Release(Representation, String):
    """Represents the *release* segment of the version (`x.y.z`)."""

    parts: Parts = field(default=DEFAULT_PARTS, eq=False, order=False)
    """The parts of the release."""

    compare_parts: Parts = field(repr=False, init=False, eq=True, order=True, hash=False)

    @parts.validator
    def check_parts(self, attribute: Attribute[Parts], value: Parts) -> None:
        if not value:
            raise ValueError(EMPTY_RELEASE)

    @compare_parts.default
    def default_compare_parts(self) -> Parts:
        parts = self.parts

        index = count_leading_zeros(reversed(parts))

        if index == self.precision:
            index -= 1  # preserve single zero if the version fully consists of zeros

        return self.slice_parts(-index) if index else parts

    @classmethod
    def create(cls, parts: Parts = DEFAULT_PARTS) -> Self:
        """Creates a [`Release`][versions.segments.release.Release] from `parts`.

        Arguments:
            parts: The parts of the release.

        Returns:
            The newly created [`Release`][versions.segments.release.Release].
        """
        return cls(parts)

    @classmethod
    def from_iterable(cls, iterable: Iterable[int]) -> Self:
        """Creates a [`Release`][versions.segments.release.Release] from `iterable`.

        Arguments:
            iterable: The parts of the release in an iterable.

        Returns:
            The newly created [`Release`][versions.segments.release.Release].
        """
        return cls(tuple(iterable))

    @classmethod
    def from_parts(cls, *parts: int) -> Self:
        """Creates a [`Release`][versions.segments.release.Release] from `parts`.

        Arguments:
            *parts: The parts of the release.

        Returns:
            The newly created [`Release`][versions.segments.release.Release].
        """
        return cls(parts)

    def into_parts(self) -> Parts:
        """Converts a [`Release`][versions.segments.release.Release] to its parts.

        Returns:
            The parts of the release.
        """
        return self.parts

    def set_parts(self, *parts: int) -> Self:
        """Sets the parts of the release to `parts`.

        Arguments:
            *parts: The parts of the release.

        Returns:
            The updated release.
        """
        return evolve(self, parts=parts)

    @property
    def precision(self) -> int:
        """The count of the release parts."""
        return len(self.parts)

    @property
    def last_index(self) -> int:
        """The index of the last release part."""
        # invariant: this is never negative since empty releases are not allowed
        return decrement(self.precision)

    @property
    def major(self) -> int:
        """The *major* part of the release."""
        return self.get_at(MAJOR)

    @property
    def minor(self) -> int:
        """The *minor* part of the release."""
        return self.get_at(MINOR)

    @property
    def micro(self) -> int:
        """The *micro* part of the release."""
        return self.get_at(MICRO)

    @property
    def patch(self) -> int:
        """The *patch* part of the release.

        This is equivalent to [`micro`][versions.segments.release.Release.micro].
        """
        return self.get_at(PATCH)

    @property
    def extra(self) -> Extra:
        """The *extra* parts of the release."""
        return self.parts[TOTAL:]

    def get_at(self, index: int, default: int = DEFAULT_VALUE) -> int:
        """Gets the release part at the `index`, defaulting to `default`.

        Arguments:
            index: The index of the part to get.
            default: The default value to use.

        Returns:
            The release part at `index` or the `default` value.
        """
        return self.get_at_unchecked(index) if self.has_at(index) else default

    def get_at_unchecked(self, index: int) -> int:
        """Gets the release part at the `index`.

        Arguments:
            index: The index of the part to get.

        Raises:
            IndexError: The index is *out-of-bounds*.

        Returns:
            The release part at `index`.
        """
        return self.parts[index]

    def is_semantic(self) -> bool:
        """Checks if the release matches the *semantic versioning* schema.

        Returns:
            Whether the release matches the [`semver`](https://semver.org/) schema.
        """
        return self.precision == TOTAL

    def to_semantic(self) -> Self:
        """Converts the release to match the [`semver`](https://semver.org/) schema.

        Returns:
            The converted release.
        """
        if self.has_extra():
            return self.next_patch().slice(TOTAL)

        return self if self.is_semantic() else self.pad_to(TOTAL)

    def set_major(self, value: int) -> Self:
        """Sets the *major* part of the release to the `value`.

        Arguments:
            value: The value to set the *major* part to.

        Returns:
            The updated release.
        """
        return self.set_at(MAJOR, value)

    def set_minor(self, value: int) -> Self:
        """Sets the *minor* part of the release to the `value`.

        Arguments:
            value: The value to set the *minor* part to.

        Returns:
            The updated release.
        """
        return self.set_at(MINOR, value)

    def set_micro(self, value: int) -> Self:
        """Sets the *micro* part of the release to the `value`.

        Arguments:
            value: The value to set the *micro* part to.

        Returns:
            The updated release.
        """
        return self.set_at(MICRO, value)

    def set_patch(self, value: int) -> Self:
        """Sets the *patch* part of the release to the `value`.

        This is equivalent to [`set_micro`][versions.segments.release.Release.set_micro].

        Arguments:
            value: The value to set the *patch* part to.

        Returns:
            The updated release.
        """
        return self.set_at(PATCH, value)

    def set_at(self, index: int, value: int) -> Self:
        """Sets the release part at the `index` to the `value`.

        Arguments:
            index: The index to set the `value` at.
            value: The value to set the part to.

        Returns:
            The updated release.
        """
        return self.pad_to_index(index).set_at_unchecked(index, value)

    def set_at_unchecked(self, index: int, value: int) -> Self:
        """Sets the release part at the `index` to the `value`.

        Arguments:
            index: The index to set the `value` at.
            value: The value to set the part to.

        Raises:
            IndexError: The index is *out-of-bounds*.

        Returns:
            The updated release.
        """
        mutable = list(self.parts)
        mutable[index] = value

        return self.from_iterable(mutable)

    def next_major(self) -> Self:
        """Bumps the *major* part of the release.

        Returns:
            The bumped release.
        """
        return self.next_at(MAJOR)

    def next_minor(self) -> Self:
        """Bumps the *minor* part of the release.

        Returns:
            The bumped release.
        """
        return self.next_at(MINOR)

    def next_micro(self) -> Self:
        """Bumps the *micro* part of the release.

        Returns:
            The bumped release.
        """
        return self.next_at(MICRO)

    def next_patch(self) -> Self:
        """Bumps the *patch* part of the release.

        This is equivalent to [`next_micro`][versions.segments.release.Release.next_micro].

        Returns:
            The bumped release.
        """
        return self.next_at(PATCH)

    def next_at(
        self, index: int, default: int = DEFAULT_VALUE, padding: int = DEFAULT_PADDING
    ) -> Self:
        """Bumps the part of the release at the `index`.

        Arguments:
            index: The index to bump the part at.
            default: The default value to use.
            padding: The padding to use.

        Returns:
            The bumped release.
        """
        updated = self.set_at(index, increment(self.get_at(index, default)))

        return updated.slice(increment(index)).pad_to(updated.precision, padding)

    def has_major(self) -> bool:
        """Checks if the release has the *major* part.

        Returns:
            Whether the *major* part is present.
        """
        return self.has_at(MAJOR)

    def has_minor(self) -> bool:
        """Checks if the release has the *minor* part.

        Returns:
            Whether the *minor* part is present.
        """
        return self.has_at(MINOR)

    def has_micro(self) -> bool:
        """Checks if the release has the *micro* part.

        Returns:
            Whether the *micro* part is present.
        """
        return self.has_at(MICRO)

    def has_patch(self) -> bool:
        """Checks if the release has the *patch* part.

        This is equivalent to [`has_micro`][versions.segments.release.Release.has_micro].

        Returns:
            Whether the *patch* part is present.
        """
        return self.has_at(PATCH)

    def has_extra(self) -> bool:
        """Checks if the release has any *extra* parts.

        Returns:
            Whether the *extra* parts are present.
        """
        return self.has_at(TOTAL)

    def has_at(self, index: int) -> bool:
        """Checks if the release has a part at the `index`.

        Returns:
            Whether the part at the `index` is present.
        """
        return self.precision > index

    def pad_to(self, length: int, padding: int = DEFAULT_PADDING) -> Self:
        """Pads a [`Release`][versions.segments.release.Release] to the `length` with `padding`.

        Arguments:
            length: The length to pad the release to.
            padding: The padding to use.

        Returns:
            The padded release.
        """
        if self.precision < length:
            return self.from_iterable(fix_to_length(length, padding, self.parts))

        return self

    def pad_to_index(self, index: int, padding: int = DEFAULT_PADDING) -> Self:
        """Pads a [`Release`][versions.segments.release.Release] to the `index` with `padding`.

        Arguments:
            index: The index to pad the release to.
            padding: The padding to use.

        Returns:
            The padded release.
        """
        return self.pad_to(increment(index), padding)

    def pad_to_next(self, padding: int = DEFAULT_PADDING) -> Self:
        """Pads a [`Release`][versions.segments.release.Release] to the next index.

        Arguments:
            padding: The padding to use.

        Returns:
            The padded release.
        """
        return self.pad_to(increment(self.precision), padding)

    def slice(self, index: int) -> Self:
        return self.create(self.slice_parts(index))

    def slice_parts(self, index: int) -> Parts:
        return self.parts[:index]

    @classmethod
    def from_string(cls, string: str) -> Self:
        """Parses a [`Release`][versions.segments.release.Release] from `string`.

        Arguments:
            string: The string to parse.

        Returns:
            The parsed release.
        """
        return cls.from_iterable(map(int, split_dot(string)))

    def to_string(self) -> str:
        """Converts a [`Release`][versions.segments.release.Release] to its string representation.

        Returns:
            The release string.
        """
        return concat_dot(map(str, self.parts))

parts: Parts = field(default=DEFAULT_PARTS, eq=False, order=False) class-attribute instance-attribute

The parts of the release.

precision: int property

The count of the release parts.

last_index: int property

The index of the last release part.

major: int property

The major part of the release.

minor: int property

The minor part of the release.

micro: int property

The micro part of the release.

patch: int property

The patch part of the release.

This is equivalent to micro.

extra: Extra property

The extra parts of the release.

create(parts: Parts = DEFAULT_PARTS) -> Self classmethod

Creates a Release from parts.

Parameters:

Name	Type	Description	Default
parts	Parts	The parts of the release.	DEFAULT_PARTS

Returns:

Type	Description
Self	The newly created Release.

Source code in versions/segments/release.py

@classmethod
def create(cls, parts: Parts = DEFAULT_PARTS) -> Self:
    """Creates a [`Release`][versions.segments.release.Release] from `parts`.

    Arguments:
        parts: The parts of the release.

    Returns:
        The newly created [`Release`][versions.segments.release.Release].
    """
    return cls(parts)

from_iterable(iterable: Iterable[int]) -> Self classmethod

Creates a Release from iterable.

Parameters:

Name	Type	Description	Default
iterable	Iterable[int]	The parts of the release in an iterable.	required

Returns:

Type	Description
Self	The newly created Release.

Source code in versions/segments/release.py

@classmethod
def from_iterable(cls, iterable: Iterable[int]) -> Self:
    """Creates a [`Release`][versions.segments.release.Release] from `iterable`.

    Arguments:
        iterable: The parts of the release in an iterable.

    Returns:
        The newly created [`Release`][versions.segments.release.Release].
    """
    return cls(tuple(iterable))

from_parts(*parts: int) -> Self classmethod

Creates a Release from parts.

Parameters:

Name	Type	Description	Default
*parts	int	The parts of the release.	()

Returns:

Type	Description
Self	The newly created Release.

Source code in versions/segments/release.py

@classmethod
def from_parts(cls, *parts: int) -> Self:
    """Creates a [`Release`][versions.segments.release.Release] from `parts`.

    Arguments:
        *parts: The parts of the release.

    Returns:
        The newly created [`Release`][versions.segments.release.Release].
    """
    return cls(parts)

into_parts() -> Parts

Converts a Release to its parts.

Returns:

Type	Description
Parts	The parts of the release.

Source code in versions/segments/release.py

def into_parts(self) -> Parts:
    """Converts a [`Release`][versions.segments.release.Release] to its parts.

    Returns:
        The parts of the release.
    """
    return self.parts

set_parts(*parts: int) -> Self

Sets the parts of the release to parts.

Parameters:

Name	Type	Description	Default
*parts	int	The parts of the release.	()

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_parts(self, *parts: int) -> Self:
    """Sets the parts of the release to `parts`.

    Arguments:
        *parts: The parts of the release.

    Returns:
        The updated release.
    """
    return evolve(self, parts=parts)

get_at(index: int, default: int = DEFAULT_VALUE) -> int

Gets the release part at the index, defaulting to default.

Parameters:

Name	Type	Description	Default
index	int	The index of the part to get.	required
default	int	The default value to use.	DEFAULT_VALUE

Returns:

Type	Description
int	The release part at index or the default value.

Source code in versions/segments/release.py

def get_at(self, index: int, default: int = DEFAULT_VALUE) -> int:
    """Gets the release part at the `index`, defaulting to `default`.

    Arguments:
        index: The index of the part to get.
        default: The default value to use.

    Returns:
        The release part at `index` or the `default` value.
    """
    return self.get_at_unchecked(index) if self.has_at(index) else default

get_at_unchecked(index: int) -> int

Gets the release part at the index.

Parameters:

Name	Type	Description	Default
index	int	The index of the part to get.	required

Raises:

Type	Description
IndexError	The index is out-of-bounds.

Returns:

Type	Description
int	The release part at index.

Source code in versions/segments/release.py

def get_at_unchecked(self, index: int) -> int:
    """Gets the release part at the `index`.

    Arguments:
        index: The index of the part to get.

    Raises:
        IndexError: The index is *out-of-bounds*.

    Returns:
        The release part at `index`.
    """
    return self.parts[index]

is_semantic() -> bool

Checks if the release matches the semantic versioning schema.

Returns:

Type	Description
bool	Whether the release matches the semver schema.

Source code in versions/segments/release.py

def is_semantic(self) -> bool:
    """Checks if the release matches the *semantic versioning* schema.

    Returns:
        Whether the release matches the [`semver`](https://semver.org/) schema.
    """
    return self.precision == TOTAL

to_semantic() -> Self

Converts the release to match the semver schema.

Returns:

Type	Description
Self	The converted release.

Source code in versions/segments/release.py

def to_semantic(self) -> Self:
    """Converts the release to match the [`semver`](https://semver.org/) schema.

    Returns:
        The converted release.
    """
    if self.has_extra():
        return self.next_patch().slice(TOTAL)

    return self if self.is_semantic() else self.pad_to(TOTAL)

set_major(value: int) -> Self

Sets the major part of the release to the value.

Parameters:

Name	Type	Description	Default
value	int	The value to set the major part to.	required

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_major(self, value: int) -> Self:
    """Sets the *major* part of the release to the `value`.

    Arguments:
        value: The value to set the *major* part to.

    Returns:
        The updated release.
    """
    return self.set_at(MAJOR, value)

set_minor(value: int) -> Self

Sets the minor part of the release to the value.

Parameters:

Name	Type	Description	Default
value	int	The value to set the minor part to.	required

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_minor(self, value: int) -> Self:
    """Sets the *minor* part of the release to the `value`.

    Arguments:
        value: The value to set the *minor* part to.

    Returns:
        The updated release.
    """
    return self.set_at(MINOR, value)

set_micro(value: int) -> Self

Sets the micro part of the release to the value.

Parameters:

Name	Type	Description	Default
value	int	The value to set the micro part to.	required

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_micro(self, value: int) -> Self:
    """Sets the *micro* part of the release to the `value`.

    Arguments:
        value: The value to set the *micro* part to.

    Returns:
        The updated release.
    """
    return self.set_at(MICRO, value)

set_patch(value: int) -> Self

Sets the patch part of the release to the value.

This is equivalent to set_micro.

Parameters:

Name	Type	Description	Default
value	int	The value to set the patch part to.	required

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_patch(self, value: int) -> Self:
    """Sets the *patch* part of the release to the `value`.

    This is equivalent to [`set_micro`][versions.segments.release.Release.set_micro].

    Arguments:
        value: The value to set the *patch* part to.

    Returns:
        The updated release.
    """
    return self.set_at(PATCH, value)

set_at(index: int, value: int) -> Self

Sets the release part at the index to the value.

Parameters:

Name	Type	Description	Default
index	int	The index to set the value at.	required
value	int	The value to set the part to.	required

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_at(self, index: int, value: int) -> Self:
    """Sets the release part at the `index` to the `value`.

    Arguments:
        index: The index to set the `value` at.
        value: The value to set the part to.

    Returns:
        The updated release.
    """
    return self.pad_to_index(index).set_at_unchecked(index, value)

set_at_unchecked(index: int, value: int) -> Self

Sets the release part at the index to the value.

Parameters:

Name	Type	Description	Default
index	int	The index to set the value at.	required
value	int	The value to set the part to.	required

Raises:

Type	Description
IndexError	The index is out-of-bounds.

Returns:

Type	Description
Self	The updated release.

Source code in versions/segments/release.py

def set_at_unchecked(self, index: int, value: int) -> Self:
    """Sets the release part at the `index` to the `value`.

    Arguments:
        index: The index to set the `value` at.
        value: The value to set the part to.

    Raises:
        IndexError: The index is *out-of-bounds*.

    Returns:
        The updated release.
    """
    mutable = list(self.parts)
    mutable[index] = value

    return self.from_iterable(mutable)

next_major() -> Self

Bumps the major part of the release.

Returns:

Type	Description
Self	The bumped release.

Source code in versions/segments/release.py

def next_major(self) -> Self:
    """Bumps the *major* part of the release.

    Returns:
        The bumped release.
    """
    return self.next_at(MAJOR)

next_minor() -> Self

Bumps the minor part of the release.

Returns:

Type	Description
Self	The bumped release.

Source code in versions/segments/release.py

def next_minor(self) -> Self:
    """Bumps the *minor* part of the release.

    Returns:
        The bumped release.
    """
    return self.next_at(MINOR)

next_micro() -> Self

Bumps the micro part of the release.

Returns:

Type	Description
Self	The bumped release.

Source code in versions/segments/release.py

def next_micro(self) -> Self:
    """Bumps the *micro* part of the release.

    Returns:
        The bumped release.
    """
    return self.next_at(MICRO)

next_patch() -> Self

Bumps the patch part of the release.

This is equivalent to next_micro.

Returns:

Type	Description
Self	The bumped release.

Source code in versions/segments/release.py

def next_patch(self) -> Self:
    """Bumps the *patch* part of the release.

    This is equivalent to [`next_micro`][versions.segments.release.Release.next_micro].

    Returns:
        The bumped release.
    """
    return self.next_at(PATCH)

next_at(index: int, default: int = DEFAULT_VALUE, padding: int = DEFAULT_PADDING) -> Self

Bumps the part of the release at the index.

Parameters:

Name	Type	Description	Default
index	int	The index to bump the part at.	required
default	int	The default value to use.	DEFAULT_VALUE
padding	int	The padding to use.	DEFAULT_PADDING

Returns:

Type	Description
Self	The bumped release.

Source code in versions/segments/release.py

def next_at(
    self, index: int, default: int = DEFAULT_VALUE, padding: int = DEFAULT_PADDING
) -> Self:
    """Bumps the part of the release at the `index`.

    Arguments:
        index: The index to bump the part at.
        default: The default value to use.
        padding: The padding to use.

    Returns:
        The bumped release.
    """
    updated = self.set_at(index, increment(self.get_at(index, default)))

    return updated.slice(increment(index)).pad_to(updated.precision, padding)

has_major() -> bool

Checks if the release has the major part.

Returns:

Type	Description
bool	Whether the major part is present.

Source code in versions/segments/release.py

def has_major(self) -> bool:
    """Checks if the release has the *major* part.

    Returns:
        Whether the *major* part is present.
    """
    return self.has_at(MAJOR)

has_minor() -> bool

Checks if the release has the minor part.

Returns:

Type	Description
bool	Whether the minor part is present.

Source code in versions/segments/release.py

def has_minor(self) -> bool:
    """Checks if the release has the *minor* part.

    Returns:
        Whether the *minor* part is present.
    """
    return self.has_at(MINOR)

has_micro() -> bool

Checks if the release has the micro part.

Returns:

Type	Description
bool	Whether the micro part is present.

Source code in versions/segments/release.py

def has_micro(self) -> bool:
    """Checks if the release has the *micro* part.

    Returns:
        Whether the *micro* part is present.
    """
    return self.has_at(MICRO)

has_patch() -> bool

Checks if the release has the patch part.

This is equivalent to has_micro.

Returns:

Type	Description
bool	Whether the patch part is present.

Source code in versions/segments/release.py

def has_patch(self) -> bool:
    """Checks if the release has the *patch* part.

    This is equivalent to [`has_micro`][versions.segments.release.Release.has_micro].

    Returns:
        Whether the *patch* part is present.
    """
    return self.has_at(PATCH)

has_extra() -> bool

Checks if the release has any extra parts.

Returns:

Type	Description
bool	Whether the extra parts are present.

Source code in versions/segments/release.py

def has_extra(self) -> bool:
    """Checks if the release has any *extra* parts.

    Returns:
        Whether the *extra* parts are present.
    """
    return self.has_at(TOTAL)

has_at(index: int) -> bool

Checks if the release has a part at the index.

Returns:

Type	Description
bool	Whether the part at the index is present.

Source code in versions/segments/release.py

def has_at(self, index: int) -> bool:
    """Checks if the release has a part at the `index`.

    Returns:
        Whether the part at the `index` is present.
    """
    return self.precision > index

pad_to(length: int, padding: int = DEFAULT_PADDING) -> Self

Pads a Release to the length with padding.

Parameters:

Name	Type	Description	Default
length	int	The length to pad the release to.	required
padding	int	The padding to use.	DEFAULT_PADDING

Returns:

Type	Description
Self	The padded release.

Source code in versions/segments/release.py

def pad_to(self, length: int, padding: int = DEFAULT_PADDING) -> Self:
    """Pads a [`Release`][versions.segments.release.Release] to the `length` with `padding`.

    Arguments:
        length: The length to pad the release to.
        padding: The padding to use.

    Returns:
        The padded release.
    """
    if self.precision < length:
        return self.from_iterable(fix_to_length(length, padding, self.parts))

    return self

pad_to_index(index: int, padding: int = DEFAULT_PADDING) -> Self

Pads a Release to the index with padding.

Parameters:

Name	Type	Description	Default
index	int	The index to pad the release to.	required
padding	int	The padding to use.	DEFAULT_PADDING

Returns:

Type	Description
Self	The padded release.

Source code in versions/segments/release.py

def pad_to_index(self, index: int, padding: int = DEFAULT_PADDING) -> Self:
    """Pads a [`Release`][versions.segments.release.Release] to the `index` with `padding`.

    Arguments:
        index: The index to pad the release to.
        padding: The padding to use.

    Returns:
        The padded release.
    """
    return self.pad_to(increment(index), padding)

pad_to_next(padding: int = DEFAULT_PADDING) -> Self

Pads a Release to the next index.

Parameters:

Name	Type	Description	Default
padding	int	The padding to use.	DEFAULT_PADDING

Returns:

Type	Description
Self	The padded release.

Source code in versions/segments/release.py

def pad_to_next(self, padding: int = DEFAULT_PADDING) -> Self:
    """Pads a [`Release`][versions.segments.release.Release] to the next index.

    Arguments:
        padding: The padding to use.

    Returns:
        The padded release.
    """
    return self.pad_to(increment(self.precision), padding)

from_string(string: str) -> Self classmethod

Parses a Release from string.

Parameters:

Name	Type	Description	Default
string	str	The string to parse.	required

Returns:

Type	Description
Self	The parsed release.

Source code in versions/segments/release.py

@classmethod
def from_string(cls, string: str) -> Self:
    """Parses a [`Release`][versions.segments.release.Release] from `string`.

    Arguments:
        string: The string to parse.

    Returns:
        The parsed release.
    """
    return cls.from_iterable(map(int, split_dot(string)))

to_string() -> str

Converts a Release to its string representation.

Returns:

Type	Description
str	The release string.

Source code in versions/segments/release.py

def to_string(self) -> str:
    """Converts a [`Release`][versions.segments.release.Release] to its string representation.

    Returns:
        The release string.
    """
    return concat_dot(map(str, self.parts))

DevTag

Bases: Tag

Represents the dev-release tag of the version (dev.n).

Source code in versions/segments/tags.py

@final
@frozen(repr=False, eq=True, order=True)
class DevTag(Tag):
    """Represents the *dev-release* tag of the version (`dev.n`)."""

    DEFAULT_PHASE = PHASE_DEV_DEFAULT
    PHASE_SET = PHASE_DEV_SET

PostTag

Bases: Tag

Represents the post-release tag of the version (post.n).

Source code in versions/segments/tags.py

@final
@frozen(repr=False, eq=True, order=True)
class PostTag(Tag):
    """Represents the *post-release* tag of the version (`post.n`)."""

    DEFAULT_PHASE = PHASE_POST_DEFAULT
    PHASE_SET = PHASE_POST_SET

PreTag

Bases: Tag

Represents the pre-release tag of the version (pre.n).

Source code in versions/segments/tags.py

@final
@frozen(repr=False, eq=True, order=True)
class PreTag(Tag):
    """Represents the *pre-release* tag of the version (`pre.n`)."""

    DEFAULT_PHASE = PHASE_PRE_DEFAULT
    PHASE_SET = PHASE_PRE_SET

Tag

Bases: Representation, String

Represents various version tags (tag.n).

Source code in versions/segments/tags.py

@frozen(repr=False, eq=True, order=True)
class Tag(Representation, String):
    """Represents various version *tags* (`tag.n`)."""

    DEFAULT_PHASE: ClassVar[str] = PHASE_ALL_DEFAULT
    PHASE_SET: ClassVar[AnySet[str]] = PHASE_ALL_SET

    phase: str = field(converter=convert_phase)
    """The phase of the release tag."""

    value: int = field(default=DEFAULT_VALUE)
    """The value of the release tag."""

    @phase.default
    def default_phase(self) -> str:
        return self.DEFAULT_PHASE

    @phase.validator
    def check_phase(self, attribute: Attribute[str], value: str) -> None:
        if value not in self.PHASE_SET:
            raise ValueError(PHASE_NOT_ALLOWED.format(value, get_type_name(self)))

    @classmethod
    def create(cls, phase: Optional[str] = None, value: int = DEFAULT_VALUE) -> Self:
        """Creates a [`Tag`][versions.segments.tags.Tag] from `phase` and `value`.

        Arguments:
            phase: The phase of the tag.
            value: The value of the tag.

        Returns:
            The newly created [`Tag`][versions.segments.tags.Tag].
        """
        if phase is None:
            phase = cls.DEFAULT_PHASE

        return cls(phase, value)

    @classmethod
    def default_phase_with_value(cls, value: int) -> Self:
        """Creates a [`Tag`][versions.segments.tags.Tag] from `value` with the default phase.

        Arguments:
            value: The value of the tag.

        Returns:
            The newly created [`Tag`][versions.segments.tags.Tag].
        """
        return cls(cls.DEFAULT_PHASE, value)

    @property
    def short(self) -> str:
        """The *short* phase of the tag."""
        phase = self.phase

        return PHASE_TO_SHORT.get(phase, phase)

    @property
    def normal(self) -> str:
        """The *normalized* phase of the tag."""
        phase = self.phase

        return PHASE_TO_NORMAL.get(phase, phase)

    def normalize(self) -> Self:
        """Normalizes the version tag.

        Returns:
            The normalized tag.
        """
        return self.set_phase(self.normal)

    def set_phase(self, phase: str) -> Self:
        """Sets the phase of the version tag.

        Arguments:
            phase: The phase to set.

        Returns:
            The version tag with the new phase.
        """
        return evolve(self, phase=phase)

    def set_value(self, value: int) -> Self:
        """Sets the value of the version tag.

        Arguments:
            value: The value to set.

        Returns:
            The version tag with the new value.
        """
        return evolve(self, value=value)

    def next(self) -> Self:
        """Bumps the version tag value.

        Returns:
            The next version tag.
        """
        return self.set_value(increment(self.value))

    def next_phase(self, value: int = DEFAULT_VALUE) -> Optional[Self]:
        """Bumps the version tag phase, if possible.

        Returns:
            The next version tag, if present.
        """
        phase = PHASE_TO_NEXT.get(self.phase)

        return None if phase is None else self.set_phase(phase).set_value(value)

    @classmethod
    def from_string(cls, string: str) -> Self:
        """Parses a [`Tag`][versions.segments.tags.Tag] from `string`.

        Arguments:
            string: The string to parse.

        Returns:
            The parsed tag.
        """
        return TagParser(cls).parse(string)

    def to_string(self) -> str:
        """Converts a [`Tag`][versions.segments.tags.Tag] to its string representation.

        Returns:
            The tag string.
        """
        return concat_dot_args(self.phase, str(self.value))

    def to_short_string(self) -> str:
        """Converts a [`Tag`][versions.segments.tags.Tag] to its *short* string representation.

        Returns:
            The *short* tag string.
        """
        return concat_empty_args(self.short, str(self.value))

phase: str = field(converter=convert_phase) class-attribute instance-attribute

The phase of the release tag.

value: int = field(default=DEFAULT_VALUE) class-attribute instance-attribute

The value of the release tag.

short: str property

The short phase of the tag.

normal: str property

The normalized phase of the tag.

create(phase: Optional[str] = None, value: int = DEFAULT_VALUE) -> Self classmethod

Creates a Tag from phase and value.

Parameters:

Name	Type	Description	Default
phase	Optional[str]	The phase of the tag.	None
value	int	The value of the tag.	DEFAULT_VALUE

Returns:

Type	Description
Self	The newly created Tag.

Source code in versions/segments/tags.py

@classmethod
def create(cls, phase: Optional[str] = None, value: int = DEFAULT_VALUE) -> Self:
    """Creates a [`Tag`][versions.segments.tags.Tag] from `phase` and `value`.

    Arguments:
        phase: The phase of the tag.
        value: The value of the tag.

    Returns:
        The newly created [`Tag`][versions.segments.tags.Tag].
    """
    if phase is None:
        phase = cls.DEFAULT_PHASE

    return cls(phase, value)

default_phase_with_value(value: int) -> Self classmethod

Creates a Tag from value with the default phase.

Parameters:

Name	Type	Description	Default
value	int	The value of the tag.	required

Returns:

Type	Description
Self	The newly created Tag.

Source code in versions/segments/tags.py

@classmethod
def default_phase_with_value(cls, value: int) -> Self:
    """Creates a [`Tag`][versions.segments.tags.Tag] from `value` with the default phase.

    Arguments:
        value: The value of the tag.

    Returns:
        The newly created [`Tag`][versions.segments.tags.Tag].
    """
    return cls(cls.DEFAULT_PHASE, value)

normalize() -> Self

Normalizes the version tag.

Returns:

Type	Description
Self	The normalized tag.

Source code in versions/segments/tags.py

def normalize(self) -> Self:
    """Normalizes the version tag.

    Returns:
        The normalized tag.
    """
    return self.set_phase(self.normal)

set_phase(phase: str) -> Self

Sets the phase of the version tag.

Parameters:

Name	Type	Description	Default
phase	str	The phase to set.	required

Returns:

Type	Description
Self	The version tag with the new phase.

Source code in versions/segments/tags.py

def set_phase(self, phase: str) -> Self:
    """Sets the phase of the version tag.

    Arguments:
        phase: The phase to set.

    Returns:
        The version tag with the new phase.
    """
    return evolve(self, phase=phase)

set_value(value: int) -> Self

Sets the value of the version tag.

Parameters:

Name	Type	Description	Default
value	int	The value to set.	required

Returns:

Type	Description
Self	The version tag with the new value.

Source code in versions/segments/tags.py

def set_value(self, value: int) -> Self:
    """Sets the value of the version tag.

    Arguments:
        value: The value to set.

    Returns:
        The version tag with the new value.
    """
    return evolve(self, value=value)

next() -> Self

Bumps the version tag value.

Returns:

Type	Description
Self	The next version tag.

Source code in versions/segments/tags.py

def next(self) -> Self:
    """Bumps the version tag value.

    Returns:
        The next version tag.
    """
    return self.set_value(increment(self.value))

next_phase(value: int = DEFAULT_VALUE) -> Optional[Self]

Bumps the version tag phase, if possible.

Returns:

Type	Description
Optional[Self]	The next version tag, if present.

Source code in versions/segments/tags.py

def next_phase(self, value: int = DEFAULT_VALUE) -> Optional[Self]:
    """Bumps the version tag phase, if possible.

    Returns:
        The next version tag, if present.
    """
    phase = PHASE_TO_NEXT.get(self.phase)

    return None if phase is None else self.set_phase(phase).set_value(value)

from_string(string: str) -> Self classmethod

Parses a Tag from string.

Parameters:

Name	Type	Description	Default
string	str	The string to parse.	required

Returns:

Type	Description
Self	The parsed tag.

Source code in versions/segments/tags.py

@classmethod
def from_string(cls, string: str) -> Self:
    """Parses a [`Tag`][versions.segments.tags.Tag] from `string`.

    Arguments:
        string: The string to parse.

    Returns:
        The parsed tag.
    """
    return TagParser(cls).parse(string)

to_string() -> str

Converts a Tag to its string representation.

Returns:

Type	Description
str	The tag string.

Source code in versions/segments/tags.py

def to_string(self) -> str:
    """Converts a [`Tag`][versions.segments.tags.Tag] to its string representation.

    Returns:
        The tag string.
    """
    return concat_dot_args(self.phase, str(self.value))

to_short_string() -> str

Converts a Tag to its short string representation.

Returns:

Type	Description
str	The short tag string.

Source code in versions/segments/tags.py

def to_short_string(self) -> str:
    """Converts a [`Tag`][versions.segments.tags.Tag] to its *short* string representation.

    Returns:
        The *short* tag string.
    """
    return concat_empty_args(self.short, str(self.value))