versionoverlord 2.5.0

Dependency Manager

Rationale

These utilities are meant to solve a problem with related repositories and their dependency relationships

Projects may have hierarchical dependencies. See the following Pyut dependency diagram.

---
title: Pyut Dependency Graph
---
flowchart
	direction RL
	
  pyut(Pyut 9.6.0) --> oglio(oglio 2.3.4)
  pyut(Pyut 9.6.0) --> pyutplugins(pyutplugins 3.2.3)
  
  pyutplugins(pyutplugins 3.2.3) -.-> oglio(oglio 2.3.4)
  pyutplugins(pyutplugins 3.2.3) & oglio(oglio 2.3.4) --> untanglepyut.2.6.3

   pyut(Pyut 9.6.0) & oglio(oglio 2.3.4) & untanglepyut.2.6.3 --> ogl.3.6.7
   
   pyut(Pyut 9.6.0) &  pyutplugins(pyutplugins 3.2.3) &  oglio(oglio 2.3.4) &  untanglepyut.2.6.3 &  ogl.3.6.7 -...-> pyutmodelv2.2.2.3
   pyut(Pyut 9.6.0) & pyutplugins(pyutplugins 3.2.3) & ogl.3.6.7 ----> codeallybasic.1.9.0

    style pyut fill:#ee4,stroke:#333,stroke-width:
    %% linkStyle 1 stroke:#ff3,stroke-width:4px,color:red;

The above diagram illustrates how low-level dependencies ripple up the dependency tree.

Dependency Locations

Additionally, projects may specify dependencies in different places. Examples of the dependency locations are

• pyproject.toml
• setup.py
• requirements.txt
• .circleci/config.yml
• .travis.yml

Python Console Scripts

VersionOverlord means to handle this problem by providing a set of Python command line scripts to automate updating the first three of the above dependency specification locations

• versionoverlord -- lists all the commands and their short names

• querySlugs -- queries repositories for their latest release version

• createSpecification -- creates a dependency specification for a project

• updateDependencies -- updates the supported dependency locations using the generated specification

• draftRelease -- This command creates draft release in the appropriate repository. You must provide a repository slug

• bumpVersion -- Bump version looks for file in src/<moduleName>/_version.py. It echoes it to stdout and asks the developer to provide an updated value.

• pickDependencies

  • Reads pyproject.toml and picks the dependencies from the dependencies section.
  • It displays them in an editor.
  • The developer removes dependencies he/she does not want to update.
  • This command updates the dependency csv file in the same format as the createSpecification command.
  • It then invokes the updateDependencies command to update the files. Unlike createSpecification, pickDependencies queries pypi to get the module versions

• publishRelease -- Publishes a previously created draft release

Required Environment Variables

The above commands depend on the following environment variables.

GH_TOKEN       - A personal GitHub access token necessary to read repository release information
PROJECTS_BASE  - The local directory where the python projects are based
PROJECT        - The name of the project;  It should be a directory name

See the GitHub Documentation for instructions on how to create a usable access token. These scripts assume that a developer keeps all checked out repositories in a single directory. An example, of a PROJECTS_BASE is:

export PROJECTS_BASE="${HOME}/PycharmProjects" 

This should be set in your shell startup script. For example .bash_profile.

The developer sets the PROJECT environment variable on a project by project basis.
I recommend you use direnv to manage these. An example of a .envrc follows:

export PROJECT=pyutmodel
export GH_TOKEN=DEADBEEF
source pyenv-3.10.6/bin/activate

Advanced Slugs

The command line options for querySlug and createSpecification are advanced GitHub slugs. For example, for the following repositories

https://github.com/hasii2011/pyutmodel

https://github.com/hasii2011/code-ally-basic

The slugs are hasii2011/pyutmodel and hasii2011/code-ally-basic,codeallybasic, respectively. Note the advanced part of the third slugs because the package name does not match the repository name;

Usage

From the above dependency diagram assume the following:

Both the pyutmodel and code-ally-basic repositories releases have been updated. We need to update the ogl dependencies to match the latest of both. Assume both GH_TOKEN and PROJECTS_BASE are correctly set and PROJECT is set to 'ogl'. Use the following CLI invocation to create the specification file.

createSpecification -s hasii2011/pyutmodel -s hasii2011/code-ally-basic,codeallybasic

The command creates the file versionSpecification.csv with the following contents.

PackageName,OldVersion,NewVersion
pyutmodel,1.4.0,1.4.1
codeallybasic,0.0.7,0.1.0                   

Again assuming, the previously mentioned environment variables are set the following CLI invocation;

updateDependencies

correctly updates the following

• setup.py
• requirements.txt
• .circleci/config.yml
• .travis.yml
• pyproject.toml

Installation

pip install versionoverlord

or

pipx install versionoverlord

---

Written by Humberto A. Sanchez II (C) 2025

Note

For all kind of problems, requests, enhancements, bug reports, etc., drop me an e-mail.

---

I am concerned about GitHub's Copilot project

I urge you to read about the Give up GitHub campaign fromthe Software Freedom Conservancy.

While I do not advocate for all the issues listed there, I do not like that a company like Microsoft may profit from open source projects.

I continue to use GitHub because it offers the services I need for free. I continue to monitor their terms of service.

Any use of this project's code by GitHub Copilot, past or present, is done without my permission. I do not consent to GitHub's use of this project's code in Copilot.