or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

django-integration.mdindex.mdspecification-matching.mdversion-operations.md
tile.json

tessl/pypi-semantic-version

A library implementing the 'SemVer' scheme.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/semantic-version@2.10.x

To install, run

npx @tessl/cli install tessl/pypi-semantic-version@2.10.0

index.mddocs/

Semantic Version

A comprehensive Python library for handling Semantic Versioning (SemVer 2.0.0) that enables developers to create, manipulate, compare, and validate version numbers according to the strict semantic versioning specification. It offers robust version parsing capabilities including coercion of version-like strings, supports version bumping operations (major, minor, patch), and provides flexible version requirement specifications through SimpleSpec and NpmSpec classes for filtering and selecting versions based on ranges.

Package Information

  • Package Name: semantic_version
  • Language: Python
  • Installation: pip install semantic-version

Core Imports

import semantic_version

Common patterns:

from semantic_version import Version, SimpleSpec, NpmSpec
from semantic_version import compare, match, validate
from semantic_version import Spec, SpecItem  # Deprecated classes

Basic Usage

import semantic_version

# Create and work with versions
version = semantic_version.Version('1.2.3-alpha.1+build.456')
print(version.major)       # 1
print(version.minor)       # 2
print(version.patch)       # 3
print(version.prerelease)  # ('alpha', '1')
print(version.build)       # ('build', '456')

# Compare versions
v1 = semantic_version.Version('1.2.3')
v2 = semantic_version.Version('1.2.4')
print(v1 < v2)  # True

# Version bumping
next_version = v1.next_minor()
print(next_version)  # Version('1.3.0')

# Validate version strings
print(semantic_version.validate('1.2.3'))     # True
print(semantic_version.validate('invalid'))   # False

# Match versions against specifications
spec = semantic_version.SimpleSpec('>=1.0.0,<2.0.0')
print(semantic_version.Version('1.5.0') in spec)  # True

# Filter versions
versions = [
    semantic_version.Version('0.9.0'),
    semantic_version.Version('1.2.0'),
    semantic_version.Version('2.1.0')
]
compatible = list(spec.filter(versions))
print(compatible)  # [Version('1.2.0')]

Architecture

The semantic_version library is built around several core concepts:

  • Version Objects: Immutable representation of semantic versions with full SemVer 2.0.0 compliance
  • Specification Classes: Flexible version requirement matching with multiple syntax support
  • Utility Functions: Convenient functions for common operations like comparison and validation
  • Django Integration: Model fields for seamless database storage and retrieval

Capabilities

Core Version Operations

Fundamental version creation, manipulation, and comparison functionality. The Version class provides complete SemVer 2.0.0 support with parsing, validation, comparison, and version bumping capabilities.

class Version:
    def __init__(self, version_string=None, major=None, minor=None, patch=None, prerelease=None, build=None, partial=False): ...
    @classmethod
    def parse(cls, version_string, partial=False, coerce=False): ...
    @classmethod 
    def coerce(cls, version_string, partial=False): ...
    def next_major(self): ...
    def next_minor(self): ...
    def next_patch(self): ...
    def truncate(self, level='patch'): ...
    @property
    def precedence_key(self): ...

def compare(v1: str, v2: str) -> int: ...
def validate(version_string: str) -> bool: ...

Version Operations

Specification Matching

Version requirement specifications for filtering and selecting versions based on ranges. Supports both simple syntax and NPM-style range specifications for flexible version matching.

class SimpleSpec:
    def __init__(self, expression: str): ...
    def match(self, version): ...
    def filter(self, versions): ...
    def select(self, versions): ...

class NpmSpec:
    def __init__(self, expression: str): ...
    def match(self, version): ...
    def filter(self, versions): ...
    def select(self, versions): ...

def match(spec: str, version: str) -> bool: ...

Specification Matching

Django Integration

Django model fields for storing Version and specification objects in databases with automatic serialization/deserialization and migration support.

class VersionField(models.CharField):
    def __init__(self, partial=False, coerce=False, **kwargs): ...

class SpecField(models.CharField):
    def __init__(self, syntax='simple', **kwargs): ...

Django Integration

Advanced Specification Architecture

Internal classes that power the specification matching system. While primarily internal, understanding these can help with advanced usage and debugging.

class BaseSpec:
    @classmethod
    def parse(cls, expression, syntax='simple'): ...
    def filter(self, versions): ...
    def match(self, version): ...
    def select(self, versions): ...

# Internal specification matching classes
class Range:
    def __init__(self, operator, target, prerelease_policy='natural', build_policy='implicit'): ...
    def match(self, version): ...

class Always:
    def match(self, version): ...  # Always returns True

class Never:
    def match(self, version): ...  # Always returns False

These classes form the internal architecture of version matching but are generally not needed for typical usage.

Legacy Support (Deprecated)

Legacy classes and functionality maintained for backward compatibility but deprecated and scheduled for removal in future versions.

class Spec:  # Deprecated, use SimpleSpec
    def __init__(self, *expressions): ...

class SpecItem:  # Deprecated
    def __init__(self, requirement_string: str): ...

These legacy components are deprecated and will be removed in future versions. Use SimpleSpec and NpmSpec instead.

Types

# Version component types
# tuple of (major, minor, patch, prerelease, build)
# where minor/patch can be None for partial versions (deprecated)
# prerelease and build are tuples of strings

# Specification syntax options
# 'simple' or 'npm'

# Version comparison result  
# -1 if first < second, 0 if equal, 1 if first > second