Metadata-Version: 2.4
Name: pyverno
Version: 1.0.0
Summary: Python package version checker/updater
Project-URL: Home, https://github.com/dimagi/pyverno
Author-email: Daniel Miller <millerdev@gmail.com>
License: Copyright (c) 2025, Dimagi Inc., and individual contributors.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
            * Redistributions of source code must retain the above copyright
              notice, this list of conditions and the following disclaimer.
            * Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in the
              documentation and/or other materials provided with the distribution.
            * Neither the name Dimagi, nor the names of its contributors, may be used
              to endorse or promote products derived from this software without
              specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL DIMAGI INC. BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Python package version checker/updater

Check or update the version number defined in a Python source file such as
`__init__.py`

## Sub-commands

- `check` - Verify that the `__version__` in `PY_FILE` matches the one embedded
  in `GIT_TAG_REF`.
- `update` - Append a timestamped dev version component formatted as
  `.devYYYYmmddHHMMSS` to the `__version__` string in `PY_FILE`.

Usage:
```sh
pyverno check PY_FILE GIT_TAG_REF

pyverno update PY_FILE
```

## Conventions

- The version must be assigned to a variable named `__version__` in the
  provided `PY_FILE`. The assignment must be at the beginning of the line and
  have single-character string delimiters, e.g. `__version__ = "X.Y.Z"`.
- `GIT_TAG_REF` is formatted as `refs/tags/vX.Y.Z`. This implies that git
  version tags should have the format `vX.Y.Z`, where the `X.Y.Z` portion uses
  whatever version number format makes sense for the project.

`pyverno` is not opinionated about version number formats. The only restriction
is that a version number may not contain quote characters of the same style used
to delimit the version string. Exmaples of valid version numbers: `1.0.0`,
`2025-05-22`, `20250522`

## Purpose

`pyverno` was developed to automate a version check or update during
[trusted publishing to PyPI](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
The `check` command is useful when publishing a new final release, and the
`update` command is useful to create a reasonably unique version number when
publishing to https://test.pypi.org.

## Publishing new versions to PyPI

Push a new tag to Github using the format `vX.Y.Z` where `X.Y.Z` matches the
version in [`pyverno.py`](pyverno.py).

A new version is published to https://test.pypi.org/p/pyverno on every
push to the *main* branch.

Publishing is automated with [Github Actions](.github/workflows/pypi.yml).
