versioningit

https://versioningit.readthedocs.io/
Admin
versioningit is a Python packaging plugin that automatically determines your package's version based...
Tokens:2,280
Snippets:46
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Minimal versioningit Configuration

Source: https://versioningit.readthedocs.io

An empty [tool.versioningit] table in pyproject.toml is the minimal configuration to get started.

```toml
[tool.versioningit]

```

--------------------------------

### Install versioningit

Source: https://versioningit.readthedocs.io

Install versioningit and its dependencies using pip. This is typically done in the build-system.requires key of pyproject.toml.

```bash
python3 -m pip install versioningit

```

--------------------------------

### Setuptools-scm Style Next Version Format

Source: https://versioningit.readthedocs.io

Configure versioningit to use the 'smallest' method for next version calculation and apply a format similar to setuptools_scm.

```toml
[tool.versioningit.next-version]
method = "smallest"

[tool.versioningit.format]
distance = "{next_version}.dev{distance}+{vcs}{rev}"
# Example formatted version: 1.2.4.dev42+ge174a1f

dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922

distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.4.dev42+ge174a1f.d20230922

```

--------------------------------

### Setuptools Build System Configuration

Source: https://versioningit.readthedocs.io

Configure setuptools to use versioningit by including it in the build-system.requires list in pyproject.toml.

```toml
[build-system]
requires = [
    "setuptools",
    "versioningit",
]
build-backend = "setuptools.build_meta"

```

--------------------------------

### Hatch Build System Configuration

Source: https://versioningit.readthedocs.io

Configure Hatchling to use versioningit by including it in the build-system.requires list and setting the version source in pyproject.toml.

```toml
[build-system]
requires = [
    "hatchling",
    "versioningit",
]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "versioningit"

```

--------------------------------

### Versioneer Style Format Configuration

Source: https://versioningit.readthedocs.io

Configure versioningit's format to mimic the style used by versioneer, using distance and VCS revision information.

```toml
[tool.versioningit.format]
distance = "{base_version}+{distance}.{vcs}{rev}"

```

--------------------------------

### Default versioningit Format Configuration

Source: https://versioningit.readthedocs.io

The default format configuration for versioningit, specifying templates for distance, dirty, and distance-dirty states.

```toml
[tool.versioningit.format]

# Format used when there have been commits since the most recent tag:
distance = "{base_version}.post{distance}+{vcs}{rev}"
# Example formatted version: 1.2.3.post42+ge174a1f

# Format used when there are uncommitted changes:
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922

# Format used when there are both commits and uncommitted changes:
distance-dirty = "{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3.post42+ge174a1f.d20230922

```

--------------------------------

### Configure versioningit format strings

Source: https://versioningit.readthedocs.io

Defines versioningit format strings for distance and dirty states in the pyproject.toml configuration.

```toml
[tool.versioningit.format]
distance = "{base_version}.post{distance}"
# Example formatted version: 1.2.3.post42

dirty = "{base_version}"
# Example formatted version: 1.2.3

distance-dirty = "{base_version}.post{distance}"
# Example formatted version: 1.2.3.post42
```

--------------------------------

### Versioningit Class API

Source: https://versioningit.readthedocs.io

The primary low-level class for programmatic control over the versioning process.

```APIDOC
## Class: Versioningit

### Methods
- **from_project_dir(project_dir)**: Initializes the Versioningit instance from a specific directory.
- **get_version()**: Retrieves the version using the configured methods.
- **run()**: Executes the full versioning process.
- **do_vcs()**: Performs the VCS-specific version extraction.
- **do_tag2version()**: Converts a VCS tag to a version string.
- **do_next_version()**: Calculates the next version.
- **do_format()**: Formats the version string based on configuration.
- **do_write()**: Writes the version to the specified files.
```

--------------------------------

### High-Level Library Functions

Source: https://versioningit.readthedocs.io

Core functions for retrieving version information and configuring build system command classes.

```APIDOC
## High-Level Functions

### get_version()
- **Description**: Calculates and returns the current version of the project.

### get_next_version()
- **Description**: Calculates the next version based on the current configuration.

### get_cmdclasses()
- **Description**: Returns the set of command classes for integration with build systems like setuptools.
```
Tokens:
Raw