check-version

Overview

The **check-version** script is a simple utility designed to verify version consistency between two key project configuration files commonly used in software projects: `Cargo.toml` (for Rust projects) and `pyproject.toml` (for Python projects). It reads the version number specified in each file and asserts that both versions are identical. This ensures synchronization between Rust and Python components of a project, which is particularly useful in mixed-language codebases or polyglot projects that maintain consistent versioning across different package managers or build tools.

Detailed Explanation

File Purpose

Read versions from Cargo.toml and pyproject.toml.
Print the extracted version numbers.
Assert that the versions are the same, failing if they differ.

This script helps maintain version parity across different parts of a project, preventing mismatches that could cause dependency issues, release confusion, or deployment errors.

Code Breakdown

#!/usr/bin/env python3
# SPDX-License-Identifier: (Apache-2.0 OR MIT)

from pathlib import Path
import tomllib

cargo_doc = tomllib.loads(Path("Cargo.toml").read_text(encoding="utf-8"))
pyproject_doc = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))

cargo_version = cargo_doc["package"]["version"]
pyproject_version = pyproject_doc["project"]["version"]

print(f"Cargo.toml version: {cargo_version}")
print(f"pyproject.toml version: {pyproject_version}")

assert cargo_version == pyproject_version

Imports

pathlib.Path: Used for filesystem path operations in an OS-independent way.
tomllib: A standard Python library (introduced in Python 3.11) used to parse TOML files.

Variables and Data Extraction

cargo_doc: Dictionary representation of the parsed Cargo.toml file.
pyproject_doc: Dictionary representation of the parsed pyproject.toml file.

The script reads and parses each file as follows:

Path("Cargo.toml").read_text(encoding="utf-8")

Reads the entire `Cargo.toml` file as UTF-8 text.

tomllib.loads(...)

Parses the TOML-formatted string into a Python dictionary.

Then, it extracts the version strings:

cargo_version = cargo_doc["package"]["version"]
pyproject_version = pyproject_doc["project"]["version"]

Output

Prints the versions extracted for visibility:

print(f"Cargo.toml version: {cargo_version}")
print(f"pyproject.toml version: {pyproject_version}")

Assertion

The script enforces that both versions match:

assert cargo_version == pyproject_version

If the versions differ, the script will raise an AssertionError and terminate with an error, indicating a version mismatch.

Usage Example

**Typical usage scenario:**

Run the script from the project root directory where both `Cargo.toml` and `pyproject.toml` exist.

$ ./check-version
Cargo.toml version: 1.2.3
pyproject.toml version: 1.2.3

If versions mismatch:

$ ./check-version
Cargo.toml version: 1.2.3
pyproject.toml version: 1.2.4
Traceback (most recent call last):
  File "./check-version", line 13, in <module>
    assert cargo_version == pyproject_version
AssertionError

Important Implementation Details

TOML Parsing: Uses Python’s built-in tomllib module, which is efficient and adheres to the TOML v1.0 specification.
Error Handling: The script relies on Python’s built-in assertion to fail on version mismatch. No custom error messages or exception handling are implemented.
Encoding: UTF-8 encoding is explicitly specified when reading files to ensure consistent behavior across platforms.
No External Dependencies: Since tomllib is part of Python 3.11+, no third-party dependencies are required.

Interaction with Other System Components

Project Configuration Files:
- Reads Cargo.toml (Rust project manifest).
- Reads pyproject.toml (Python project configuration).
Build/Release Pipelines:
- Can be integrated into CI/CD pipelines to enforce version consistency before packaging or deployment.
Multi-language Projects:
- Ensures Rust and Python components remain synchronized in versioning.
Version Control Hooks:
- Could be run as a pre-commit or pre-release hook to prevent version mismatches from entering the codebase.

Visual Diagram

flowchart TD
    A[Start: Run check-version script]
    B[Read Cargo.toml]
    C[Parse Cargo.toml to cargo_doc]
    D[Extract cargo_version]
    E[Read pyproject.toml]
    F[Parse pyproject.toml to pyproject_doc]
    G[Extract pyproject_version]
    H{Compare cargo_version == pyproject_version}
    I[Print Cargo.toml version]
    J[Print pyproject.toml version]
    K[Assertion passes -> End]
    L[Assertion fails -> Raise AssertionError]

    A --> B --> C --> D
    A --> E --> F --> G
    D --> H
    G --> H
    H -->|True| I --> J --> K
    H -->|False| I --> J --> L

Summary

The **check-version** script is a lightweight, focused utility that verifies version synchronization between the Rust and Python components of a project by comparing the version fields of `Cargo.toml` and `pyproject.toml`. It is a valuable tool in multi-language environments to prevent version drift and ensure consistent releases.

**End of documentation**