User Guide¶

Reason why¶

Essentially, in BuildNN we use a custom full automation in package release cycle. Therefore, we needed a tool to update package versions with a minimal overhead.

We embrace the config paradigma for package metadata: take away metadata from setup.py and move them to setup.cfg or pyproject.toml

NOTE: full pyproject.toml and poetry support will come soon…

Explore the CLI¶

$ pymetager --help
Usage: pymetager [OPTIONS] COMMAND [ARGS]...

Options:
  -q, --quiet       Flag for minimal output.
  --config_fp FILE  Custom path for setup.cfg.  [default: ./setup.cfg]
  --help            Show this message and exit.

Commands:
  echo-meta-elm
  increment

let’s use info print function

$ pymetager echo-meta-elm --help
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Usage: pymetager echo-meta-elm [OPTIONS] [NAME]

Options:
  -s, --section TEXT
  --help              Show this message and exit

$ pymetager echo-meta-elm version
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
0.0.1

Or, concisely

$ pymetager -q echo-meta-elm version
0.0.1

Increment Version¶

Strictly following Python’s PEP440 Guidelines

[A] Increment micro version¶

$ pymetager increment micro
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.1` to `0.0.2`.
Writing back config...

[B] Increment minor version¶

$ pymetager increment minor
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.1` to `0.1`.
Writing back config...

[C] Increment major version¶

$ pymetager increment major
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.1` to `1.0`.
Writing back config...

Major version increment will be visible in setup.cfg as you will see opening the file
 $ cat setup.cfg
...
[metadata]
name = my-awesome-package
version = 1.0
...

[D] Increment version segment (dev, pre, post)¶

[D1] Increment dev¶

Let’s say we are at version 0.0.1.

$ pymetager echo-meta-elm version
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
0.0.1

The following attempt to pass to dev version segment will fail (we can not move from full release back to dev)…

$ pymetager increment segment -s dev
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Traceback (most recent call last):
  ... <traceback stuff>
  File "<>/pymetager/src/pymetager/cli.py", line 64, in increment
    update_config_version(
  File "<>/pymetager/src/pymetager/version_manager.py", line 177, in update_config_version
    new_version = _version_ops[element](version, **kwargs)
  File "<>/pymetager/src/pymetager/version_manager.py", line 123, in increment_segment
    raise ValueError("Current version Segment is higher than the required one!")
ValueError: Current version Segment is higher than the required one!

What we can do, is to pass from current version to a new one (eg. incrementing the upstream micro version) in dev segment:

$ pymetager increment segment -s dev -u micro
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.1` to `0.0.2.dev0`.
Writing back config...

[D2] Increment pre¶

Note: pre segment is prior to release, thus from release on you cannot revert back to pre or dev. You can update to pre only dev.

$ pymetager increment segment -s pre
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.2.dev0` to `0.0.2rc0`.
Writing back config...

Note: rc stands for release candidate :)

[D3] Increment –> Release¶

After release candidate validation or directly from dev, we can go with full release:

$ pymetager increment release
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.2rc0` to `0.0.2`.
Writing back config...

[D4] Increment post¶

Note: you can increment to post from release and every other segment type. Once in post segment, you can go only to the next release (or to its dev, using --increment_upstream) Post is used for small bugfix after release in prod

$ pymetager increment segment -s post
--- PYPACK-METAGER ---
A BuildNN Open Source project.
Reading/Writing from/to ./setup.cfg
Read config from ./setup.cfg
Updating version `0.0.2` to `0.0.2.post0`.
Writing back config...

pymetager 0.0.1 documentation