Metadata-Version: 2.1
Name: scmver
Version: 1.7
Summary: A package version manager based on SCM tags
Author-email: Akinori Hattori <hattya@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/hattya/scmver
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: cli
Requires-Dist: click; extra == "cli"
Provides-Extra: toml
Requires-Dist: tomli; python_version < "3.11" and extra == "toml"

scmver
======

scmver is a package version manager based on SCM tags.

It can be used to pass the version to the ``setup`` function in a ``setup.py``,
or to generate a file which contains the version.

.. image:: https://img.shields.io/pypi/v/scmver.svg
   :target: https://pypi.org/project/scmver

.. image:: https://github.com/hattya/scmver/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/hattya/scmver/actions/workflows/ci.yml

.. image:: https://ci.appveyor.com/api/projects/status/l9flwehcgr5pxi33?svg=true
   :target: https://ci.appveyor.com/project/hattya/scmver

.. image:: https://codecov.io/gh/hattya/scmver/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/hattya/scmver


Installation
------------

.. code:: console

   $ pip install scmver


Requirements
------------

- Python 3.8+
- setuptools


Usage
-----

pyproject.toml
--------------

.. code:: toml

   [build-system]
   requires = [
       "setuptools >= 42.0",
       "scmver[toml] >= 1.5",
   ]
   build-backend = "setuptools.build_meta"

   [tool.scmver]
   spec = "micro"
   write-to = "scmver/__version__.py"
   fallback = {attr = "scmver:__version__"}

write-to
  An alias for ``write_to``, but it takes precedence.

fallback
  ``attr``
    A ``string`` which is described in ``fallback`` in Configuration_.

  ``path`` (optional)
    A path to import the module.

See Configuration_ for key/value pairs.


setuptools
~~~~~~~~~~

.. code:: python

   from setuptools import setup

   setup(setup_requires=['scmver'],
         scmver=True)

``scmver`` is either following values:

``True``
  It is same as an empty ``dict``.

``callable object``
  It should return a ``dict``.

``dict``
  See Configuration_ for details.


distutils
~~~~~~~~~

.. code:: python

   from distutils.core import setup

   import scmver

   setup(version=scmver.get_version())

See Configuration_ for the ``scmver.get_version`` arguments.


Configuration
-------------

root
  A path of the working directory.

  Default: ``'.'``

spec
  A version specifier to construct the public version identifiers. It will be
  incremented by the number of commits from the latest tag.

  ``major``
    It will increment the major version.

  ``minor``
    It will increment the minor version.

  ``micro`` or ``patch``
    It will increment the micro (patch) version.

  ``post``
    It will increment the post-release segment.

  ``major.dev``
    It will increment the development release segment after incrementing the
    major version by 1.

  ``minor.dev``
    It will increment the development release segment after incrementing the
    minor version by 1.

  ``micro.dev`` or ``patch.dev``
    It will increment the development release segment after incrementing the
    micro (patch) version by 1.

  Default: ``'post'``

local
  A ``string`` or ``callable object`` to construct the local version
  identifiers.

  ``string``
    A format string.

    Available keywords:

    - ``{distance}``
    - ``{revision}``
    - ``{branch}``
    - ``{utc}``      - Return value of ``datetime.datetime.now(datetime.timezone.utc)``
    - ``{local}``    - Return value of ``datetime.datetime.now()``

  ``callable object``
    It will be called with ``scmver.core.SCMInfo``.

  Default: ``'{local:%Y-%m-%d}'``

version
  A regular expression object to extract the version from SCM tags. It should
  contain the version group.

write_to
  A path to a file which will be generated using ``template``.

template
  A format string which is used by ``write_to``.

  Available keywords:

  - ``{version}``
  - ``{revision}``
  - ``{branch}``

fallback
  It will be used when there is outside of a working copy.

  ``string``
    It is in the ``'package.module:some.attribute'`` format
    (ex: ``'scmver:__version__'``).

  ``list``
    It consists of a ``string`` which is described above, and a path to import
    the module.

  ``callable object``
    It should return the version.

bazaar.tag
  A regular expression pattern to filter tags.

darcs.tag
  A regular expression pattern to filter tags.

fossil.tag
  A regular expression pattern to filter tags.

git.tag
  It will be passed to ``git describe`` as ``--match``.

mercurial.tag
  A regular expression pattern to filter tags.

subversion.tag
  A regular expression pattern to filter tags.

subversion.trunk
  A relative repository path of the trunk directory.

  Default: ``'trunk'``

subversion.branches
  A relative repository path of the directory where branches are located.

  Default: ``'branches'``

subversion.tags
  A relative repository path of the directory where tags are located.

  Default: ``'tags'``


License
-------

scmver is distributed under the terms of the MIT License.
