Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

seVersion


CLI to enhance versioning for Python projects.

Badges

Coverage

Quick Start

  • Install locally in editable/development mode:

    pip install -e .

  • Create a package version file and folder:

    seVersion --create --cdne

Tests & Coverage

  • Install test dependencies:

    pip install -r requirements-test.txt

  • Run tests and see coverage report:

    pytest --cov=seVersion --cov-report=html

  • Coverage reports are saved to coverage.xml and htmlcov/ (open htmlcov/index.html locally).

CI

A GitHub Actions workflow is included at .github/workflows/ci.yml. It runs tests on multiple Python versions, caches pip, runs linters, collects coverage, and uploads reports as artifacts. Configure CODECOV_TOKEN as a repo secret to enable Codecov upload (optional).

Notes about FilePath shim

During development the CLI supplies a minimal FilePath shim (in seVersion/cli.py) to avoid pulling the full seCore dependency. For full filepath behavior, install seCore or remove the shim and restore the original import.

Generated _version.py fallback

The generated _version.py template now includes a safe fallback for environments where seVersion is not installed. If importing seVersion fails, the file still defines a minimal local Version implementation so your package can import __version__ and __setuptools__ without crashing.

This makes it easier to ship generated version files in source trees or minimal environments while still allowing the full package to use the real seVersion.Version implementation when installed.

Basic Usage

Install seVersion to local environment with pip install seVersion, then run
seVersion <projectname> --create to create project version file named _version.py
in your project. If folder does not exist you can add --cdne and it will create folder
and _version.py file for project

Note: setting <projectname> to app for examples

$ seVersion app --create --cdne
--------------------------------------------------------------------
seVersion | INFO     |          Creating: FilePath('./app')
seVersion | INFO     | Creating codebase: 2023.10.0
seVersion | INFO     |          Updating: ./app/_version.py
# file: _version.py

"""
Provides `app` version information.
"""
# This file is auto-generated! Do not edit!
# Use `seVersion app` to change this file.

try:
    from seVersion import Version
except ModuleNotFoundError:
    class Version:
        def __init__(self, package, major, minor, micro, build, release_candidate=None, post=None, dev=None):
            self.package = package
            self.major = major
            self.minor = minor
            self.micro = micro
            self.build = build
            self.release_candidate = release_candidate
            self.post = post
            self.dev = dev

        def public(self):
            rc = f".rc{self.release_candidate}" if self.release_candidate is not None else ""
            post = f".post{self.post}" if self.post is not None else ""
            dev = f".dev{self.dev}" if self.dev is not None else ""
            return f"{self.major}.{self.minor}.{self.micro}{rc}{post}{dev}"

        def public_build(self):
            return f"{self.public()} build[{self.build}]"

__version__ = Version("app", 2023, 10, 0, 0)
__setuptools__ = __version__.public()
__all__ = ["__version__", "__setuptools__"]

If __init__.py doesn't exist it will be created, otherwise add the following to your root package's __init__.py.
This will allow users of your project can find your version:

# file: __init__.py

from ._version import __version__, __setuptools__

Incremental Versions

seVersion.Version is a class that represents a version of a given project. It is made up of the following elements (which are given during instantiation):

  • package (required), the name of the package this Version represents.
  • major, minor, micro (all required), the X.Y.Z of your project's Version.
  • release_candidate (optional), set to 1 or higher to mark this Version being of a release candidate/pre-release.
  • post (optional), set to 1 or higher to mark this Version as a post release.
  • dev (optional), set to 1 or higher to mark this Version as a development release.

You can extract a PEP-440 compatible version string by using the .public() method, which returns a str containing the full version. This is the version you should provide to users, or publicly use.
An example output would be "2023.1.0", "2023.1.2dev1", or "2023.1.2rc1".

Calling repr() with a Version will give a Python-source-code representation of it, and calling str() with a Version will provide a string similar to '[<projectname>, version 23.1.0]'.

from app import __version__, __setuptools__

print(f'{"__version__":>25}: {__version__}')
print(f'{"__setuptools__":>25}: {__setuptools__}')
print(f'{".public()":>25}: {__version__.public()}')
print(f'{".public_build()":>25}: {__version__.public_build()}')
print(f'{".repr()":>25}: {repr(__version__)}')
print(f'{".str()":>25}: {str(__version__)}')
    __version__: [app, version 2023.12.0, build 0 ]
 __setuptools__: 2023.12.0
      .public(): 2023.12.0
.public_build(): 2023.12.0 build[0]
        .repr(): Version("app", 2023, 12, 0, 0)
         .str(): [app, version 2023.12.0, build 0 ]

Updating Version

seVersion includes a cli tool called seVersion to automate updating your project's versioning by automatically updating the _version.py file.

seVersion <projectname> <commands> will perform updates on _version.py file:

Return the current version

$ seVersion app
--------------------------------------------------------------------
seVersion | INFO     |      Project Path: ./app/_version.py
seVersion | INFO     |   Current Release: 2023.10.0
seVersion | INFO     |     Build Release: 2023.10.0 build[0]

--create

Will set the project version to <year>.<month>.0

$ seVersion app --create
--------------------------------------------------------------------
seVersion | INFO     | Creating codebase: 2023.10.0
seVersion | INFO     |          Updating: ./app/_version.py

--newversion=2023.10.1.rc1

Sets the project version to a fully-specified version (like 0.9.0 or 2023.2.1.rc1 or 2023.2.1.dev1 or 2023.2.1.post1).

$ seVersion app --newversion=2023.10.1.rc1
--------------------------------------------------------------------
seVersion | INFO     | Updating codebase: 2023.10.1.rc1
seVersion | INFO     |          Updating: ./app/_version.py

--rc

Sets the current version <major>.<minor>.<micro> to <major>.<minor>.<micro>.rc1 if the current version is not a release candidate, or bump the release candidate number by 1 if it is.

$ seVersion app --rc
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.1.rc1
seVersion | INFO     | Updating codebase: 2023.10.1.rc2
seVersion | INFO     |          Updating: ./app/_version.py

--dev

Sets the project development release number to 0 if it is not a development release, or bump the development release number by 1 if it is.

$ seVersion app --dev
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.1.rc2
seVersion | INFO     | Updating codebase: 2023.10.1.dev0
seVersion | INFO     |          Updating: ./app/_version.py

--post

Sets the project post release number to 0 if it is not a post release, or bump the post release number by 1 if it is. This will also reset the release candidate and development release numbers.

$ seVersion app --post
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.1.dev0
seVersion | INFO     | Updating codebase: 2023.10.1.post0
seVersion | INFO     |          Updating: ./app/_version.py

--patch

Increments the patch number of the release. This will also reset the release candidate number, pass --rc at the same time to increment the patch number and make it a release candidate.

$ seVersion app --patch
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.1.post0
seVersion | INFO     | Updating codebase: 2023.10.2
seVersion | INFO     |          Updating: ./app/_version.py

--release

This will reset the release candidate, development and post number making it a "full release".

$ seVersion app --release
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.2.post0
seVersion | INFO     |   Current Release: 2023.10.2
seVersion | INFO     |          Updating: ./app/_version.py

--minor

Increments the minor number of the release, and reset the patch/micro number to 0.

$ seVersion app --minor
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.10.2
seVersion | INFO     | Updating codebase: 2023.11.0
seVersion | INFO     |          Updating: ./app/_version.py

--major

Increment the major number of the release, reset minor number to and reset the patch/micro number to 0.

$ seVersion app --major
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2023.11.0
seVersion | INFO     | Updating codebase: 2024.10.0
seVersion | INFO     |          Updating: ./app/_version.py

--build

Increments the build number, and does not get reset unless --create is used.

$ seVersion app --build
--------------------------------------------------------------------
seVersion | INFO     |  Current codebase: 2024.10.0 build[0]
seVersion | INFO     | Updating codebase: 2024.10.0 build[1]
seVersion | INFO     |          Updating: ./app/_version.py

--clean

Removes _version.py from codebase.

$ seVersion app --clean
--------------------------------------------------------------------
seVersion | INFO     | Cleaning codebase: Removing FilePath('./app/_version.py')

Error/Warning Codes

SE-01100

Could not find project/package

seVersion | WARNING  |       SE-01100: Can't find `<project/package>` under `./src` or `./`
seVersion | WARNING  |                    Check the package name is right (note that we expect your package name to be lower cased), or pass it using '--path' 
seVersion | WARNING  |                    or add `--cdne` to automatically initialize the project to create folder and files

SE-01300

Do not add any extra command to --create

seVersion | ERROR    |       SE-01300: --create error, only --cdne is allowed to be used with this command to create package\project folder if does not exist

SE-01301

Do not add any extra command to --newversion

seVersion | ERROR    |       SE-01301: --newversion=?.?.? error, no other commands need to be used

SE-01302

Do not add any extra command to --dev

seVersion | ERROR    |       SE-01302: --dev error, no other commands need to be used

SE-01303

Do not add any extra command to --rc

seVersion | ERROR    |       SE-01303: --rc error, no other commands need to be used

SE-01304

Do not add any extra command to --patch

seVersion | ERROR    |       SE-01304: --patch error, no other commands need to be used

SE-01305

Do not add any extra command to --major

seVersion | ERROR    |       SE-01305: --major error, no other commands need to be used

SE-01306

Do not add any extra command to --minor

seVersion | ERROR    |       SE-01306: --minor error, no other commands need to be used

SE-01307

Do not add any extra command to --build

seVersion | ERROR    |       SE-01307: --build error, no other commands need to be used

SE-01308

Do not add any extra command to --post

seVersion | ERROR    |       SE-01308: --post error, no other commands need to be used

SE-01309

Do not add any extra command to --release

seVersion | ERROR    |       SE-01309: --release error, no other commands need to be used

SE-01310

Do not add any extra command to --clean

seVersion | ERROR    |       SE-01310: --clean error, no other commands need to be used

Metadata

Release files for seversion 2026.9.1rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for seversion 2026.9.1rc1
File Size Uploaded Provenance Actions
seversion-2026.9.1rc1.tar.gz 17.7 kB Without provenance Details for seversion-2026.9.1rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for seversion 2026.9.1rc1
File Interpreter ABI Platform Actions
seversion-2026.9.1rc1-py3-none-any.whl Python 3 none any Details for seversion-2026.9.1rc1-py3-none-any.whl

Total release size: 31.2 kB

Release files / seversion-2026.9.1rc1.tar.gz

Download URL seversion-2026.9.1rc1.tar.gz
Size 17.7 kB
Tags Source
SHA-256 checksum
How to use checksums
736d71cc8c6c401c6cb7a97bdc428459da12a5f2422c40b837c4fea8354f2f75
BLAKE2b-256 checksum
How to use checksums
65a042b0fad5dd4002f5922475aaafc1688e34dbd0b7f1f4d7883e500326431e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / seversion-2026.9.1rc1-py3-none-any.whl

Download URL seversion-2026.9.1rc1-py3-none-any.whl
Size 13.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38c5da7015de91ed3731916df21352a0b7e6db73af5d40f6733eed9d9b170cbe
BLAKE2b-256 checksum
How to use checksums
109366e92289f98ca94885bf6fe882f73173e97a831040d59269b054fab44b76
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for seversion 2026.9.1rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page