https://github.com/willynilly/verple
Verple is a ridiculously strict and ultra-conservative universal version format, comparator, serializer, and protocol.
https://github.com/willynilly/verple
pep440 semver version-parser versioning versioning-semantics
Last synced: 24 days ago
JSON representation
Verple is a ridiculously strict and ultra-conservative universal version format, comparator, serializer, and protocol.
- Host: GitHub
- URL: https://github.com/willynilly/verple
- Owner: willynilly
- License: apache-2.0
- Created: 2025-06-12T15:22:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-12T23:06:38.000Z (about 1 year ago)
- Last Synced: 2025-11-27T13:35:39.355Z (7 months ago)
- Topics: pep440, semver, version-parser, versioning, versioning-semantics
- Language: Python
- Homepage:
- Size: 28.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Verple
**Verple** is a ridiculously strict and ultra-conservative universal version format, comparator, serializer, and protocol.
## Design Goals
- 🔒 **Ultra-conservative equality**: versions are considered different if any field differs (`release`, `prerelease`, `postrelease`, `devrelease`, `local`).
- ⚖ **Strict conservative ordering**: ordering is only permitted when local metadata matches exactly; otherwise ordering raises `ValueError` to avoid ambiguity.
- 🔎 **Multi-standard input support**: parses version strings from PEP 440, SemVer, Canonical, and Calendar Versioning (CalVer).
- 🔁 **Canonical serialization**: provides fully reversible serialization via `to_canonical_string()` and parsing via `from_canonical_string()`.
- 🧮 **Hashable and set-safe**: fully hashable and safe for use in sets and dictionaries, with hashes consistent with strict equality.
- 📦 **JSON-LD serialization**: supports semantic serialization with provenance (`sourceFormat` and `sourceInput` fields).
- 🔐 **Versioned deserialization protocol**: fully versioned serialization model allowing future-safe protocol evolution.
- 📚 **Use Case Domains**: reproducible builds, registries, deployment pipelines, archival systems, provenance tracking, scientific reproducibility.
## Supported Python Versions
- Python >= 3.10
## Installation
```bash
pip install verple
```
## Example Usage
```python
from verple import Verple
# Parse version string
v1 = Verple.parse("1.2.3a1.post2.dev3+build99")
print(v1.to_canonical_string()) # 1.2.3-a1.post2.dev3+build99
# Strict equality
v2 = Verple.parse("1.2.3a1.post2.dev3+build99")
assert v1 == v2
# Hashable and set-safe
versions = {v1, v2}
assert len(versions) == 1
# Conservative ordering (only if local metadata matches)
v3 = Verple.parse("1.2.4+build99")
assert v1 < v3
# JSON-LD serialization
jsonld = v1.to_jsonld()
v1_roundtrip = Verple.from_jsonld(jsonld)
assert v1 == v1_roundtrip
```
## Canonical Serialization Format
Verple canonical strings follow this grammar:
```
[-][.post][.dev][+]
```
Example:
- `1.2.3-a1.post2.dev3+build99`
## JSON-LD Serialization Format
Verple also supports semantic serialization:
```json
{
"@context": "https://gitlab.com/willynilly/verple/-/raw/main/src/verple/context/v1.0.0.jsonld",
"@type": "Verple",
"verple": "1.0.0",
"sourceFormat": "pep440",
"sourceInput": "1.2.3a1.post2.dev3+build99",
"release": [1, 2, 3],
"prerelease": ["a", 1],
"postrelease": 2,
"devrelease": 3,
"local": "build99"
}
```
This allows full provenance and schema evolution.
## Tests
This project uses `pytest`:
```bash
pytest tests/
```
## Protocol Semantics
### Normalization
Verple normalizes versions into a fully structured model with the following fields:
- `release`: tuple of integers (major, minor, patch, or calendar parts)
- `prerelease`: tuple of `(label: str, num: int)` or `None`
- `postrelease`: integer or `None`
- `devrelease`: integer or `None`
- `local`: string or `None`
- `sourceInput`: original version string
- `sourceFormat`: the parsed format (`pep440`, `semver`, `canonical`, `calver`)
All formats (PEP 440, SemVer, Canonical, CalVer) are converted into this internal structure.
### Equality Algorithm
Two versions are equal if and only if all of the following fields are equal:
- `release`
- `prerelease`
- `postrelease`
- `devrelease`
- `local`
Fields are compared strictly; any difference implies inequality.
### Ordering Algorithm
Ordering is permitted only if both versions have identical `local` metadata. If `local` differs, ordering is refused.
If allowed, versions are compared using the tuple:
```
(
release,
prerelease_key(prerelease),
postrelease or -1,
devrelease or infinity
)
```
Where:
- `prerelease_key(None)` → `(infinity,)` (normal releases sort after prereleases)
- `prerelease_key((label, num))` → `(label, num)` (string then numeric comparison)
The algorithm aligns with PEP 440 precedence where applicable.
### Canonical Form Algorithm
Serialization via `to_canonical_string()` reconstructs the version string as:
```
[-][.post][.dev][+]
```
Fields that are `None` are omitted.
### JSON-LD Serialization
The full semantic model is serialized as JSON-LD, including provenance fields `sourceFormat` and `sourceInput` for full reproducibility.
## Field Definitions
The following fields are used throughout Verple's internal model, canonical serialization, and JSON-LD serialization:
| Field | Type | Meaning |
|--------------|------------------|-------------------------------------------------------------|
| `release` | tuple of int | Core version numbers: major.minor.patch or calendar parts |
| `prerelease` | tuple (str, int) or None | Pre-release stage (alpha, beta, rc, etc.) and stage number |
| `postrelease` | int or None | Post-release revision applied after final release |
| `devrelease` | int or None | Development release version for pre-release internal builds |
| `local` | str or None | Local build metadata identifier (build info, git hash, etc.) |
| `sourceInput` | str | The original version string provided as input |
| `sourceFormat` | str | The detected format: `pep440`, `semver`, `canonical`, or `calver` |
| `verple` | str | Serialization format version (e.g. `"1.0.0"`) |
| `@context` | URL | JSON-LD context URL defining linked data vocabulary |
| `@type` | str | Always `"Verple"` |
### Conceptual Definitions
- **release**: The main numeric version (e.g. `1.2.3`), structured as Major.Minor.Patch (SemVer, PEP 440) or Year.Month.[Day] (CalVer).
- **prerelease**: A pre-final release marker such as `alpha`, `beta`, or `rc`, optionally followed by a stage number (e.g. `rc1`).
- **postrelease**: Identifies patches or hotfixes applied after a final release (`.postN`).
- **devrelease**: Development snapshots issued before formal releases (`.devN`), typically for internal or unstable builds.
- **local**: Build metadata or local identifiers following `+build` semantics, capturing build environment or other internal state.
- **sourceInput**: The raw version string provided by the caller.
- **sourceFormat**: Indicates which parser was used to interpret the input (`pep440`, `semver`, `canonical`, `calver`).
- **verple**: The version of the Verple serialization protocol used to encode the JSON-LD document.
- **@context / @type**: JSON-LD linked data metadata used to enable semantic parsing of Verple objects.
## License
Apache 2.0
## Author
- Will Riley
- Co-developed with ChatGPT-4o during protocol design.