zensols.relpo package

Submodules

zensols.relpo.app module

A Python project release with Git integration.

class zensols.relpo.app.Application(config_files, temporary_dir)

Bases: object

The application client class to the command line.

__init__(config_files, temporary_dir)

bumptag()

Delete the last tag and create a new one on the latest commit.

check()

Release sanity check (git and change log versions match).

Return type:

int

config()

Output the synthesized build configuration (useful for debugging).

config_files: Path

The relpo.yml configuration file used for substitution.

meta(out=None, format=None)

Print or write the project metadata.

Parameters:

• out (Path) – the output file or dump to standard out if not provided

• format (str) – the output format

mkdoc(out=None)

Create the site documentation.

Parameters:

out (Path) – the directory to output the documentation

mkenvdist(out=None)

Create the environment distribution file.

Parameters:

out (Path) – the output distribution file

mktag(message)

Create a tag using the last change log entry’s version.

Parameters:

message (str) – the message (comment-like) of the tag

pyproject(out=None)

Write the pyproject.toml file.

Parameters:

out (Path) – the output file or dump to standard out if not provided

rmtag()

Remove the most recent tag.

template()

Render a template given as standard in using keys: date, project, config.

temporary_dir: Path

Temporary space for files.

version()

Print the version.

zensols.relpo.cli module

Command line entry point to the application.

zensols.relpo.cli.invoke(action=None, version=False, level='[warn|info|debug]', config='relpo.yml', tmp=PosixPath('temp'), out='<path>', format='<json|yaml>', message='<comment>')

Python project release with Git integration.

actions:

config output the synthesized build configuration meta [-o, -f] output the project metadata pyproject write the pyproject.toml file mktag [-m] create a new tag using the last change log rmtag remove the most recent tag bumptag move the latest tag to the last commit template render standard in with: date, project, config check check for any issues with creating a release mkdoc [-o] create site documentation mkenvdist [-o] create the environment distribution

zensols.relpo.cli.main(args=None)

zensols.relpo.doc module

Classes that are used to write site documentation.

class zensols.relpo.doc.DocConfig(data, stage_dir, config_template_dir, apidoc_template_dir, apidoc_output_dir, python_home, api_config, copy)

Bases: Config

Configuration for API doc generation.

__init__(data, stage_dir, config_template_dir, apidoc_template_dir, apidoc_output_dir, python_home, api_config, copy)

api_config: Dict[str, Any]

The Sphinx API configuration values.

apidoc_output_dir: Path

The sphinx-api output directory.

apidoc_template_dir: Path

The directory used by sphinx-api to generate Sphinx RST files. This is the output directory of the config_template_dir config files.

config_template_dir: Path

The template directory to create the Sphinx API config files.

copy: Dict[str, Any]

Files to copy to the Sphinx source directory.

classmethod instance(data)

Create an instance of this class.

Return type:

DocConfig

python_home: Path

Sphinx Python environment.

stage_dir: Path

Where temporary files are created used by Sphinx.

class zensols.relpo.doc.Documentor(config, template_params, temporary_dir, output_dir)

Bases: object

This class creates files used by sphinx-api and sphinx-build to create a package API documentation. First rendered (from Jinja2 templates) Sphinx configuration (i.e. .rst files) and static files are written to a source directory. Then Sphinx is given the source directory to generate the API documentation.

__init__(config, template_params, temporary_dir, output_dir)

config: DocConfig

The parsed document generation configuration.

generate()

Create the site and API documentation.

output_dir: Path

Where to output the generated site.

template_params: Dict[str, Any]

The context given to Jinja2 as Project used to render the Sphinx API docs.

temporary_dir: Path

Temporary space for files.

zensols.relpo.domain module

Application domain classes.

class zensols.relpo.domain.ChangeLog(path)

Bases: Flattenable

Parses the keepchangelog CHANGELOG.md (markdown) format.

__init__(path)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

property entries: Tuple[ChangeLogEntry, ...]

path: Path

The path to the change log markdown formatted file.

property today: ChangeLogEntry | None

only today’s changelog entry if there is one for today.

class zensols.relpo.domain.ChangeLogEntry(version, date)

Bases: Entry

A ChangeLog entry.

__init__(version, date)

classmethod from_str(s)

Return type:

Optional[ChangeLogEntry]

classmethod str2date(date)

Return type:

date

class zensols.relpo.domain.Commit(date, author, sha, summary)

Bases: Flattenable

A Git commit.

__init__(date, author, sha, summary)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

author: str

The author of the commit.

date: date

The date the commit was created.

sha: str

Unique SHA1 string of the commit.

summary: str

The summary comment.

class zensols.relpo.domain.Config(data)

Bases: Flattenable

A configuration container for sections of the relpo.yml file.

__init__(data)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

data: Dict[str, Any]

The parsed document config.

abstract classmethod instance(data)

Create an instance of this class.

Return type:

Config

class zensols.relpo.domain.Entry(version, date)

Bases: Flattenable

Base class for things that have versions with dates.

__init__(version, date)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

date: date

The date the entry was created.

property is_today: bool

Whether the log as created today.

version: Version

The version of the entry.

class zensols.relpo.domain.Flattenable

Bases: object

A class that that generates a dictionary recursively from data classes and primitive data structures.

__init__()

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

asjson(**kwargs)

Return build information in JSON format.

Return type:

str

asyaml()

Return type:

str

exception zensols.relpo.domain.ProjectRepoError

Bases: Exception

Raised for project repository related errors.

__module__ = 'zensols.relpo.domain'

__weakref__

list of weak references to the object

class zensols.relpo.domain.Release(tag, change_log_entry)

Bases: Flattenable

A matching entry between a release tag the change log.

__init__(tag, change_log_entry)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

change_log_entry: ChangeLogEntry

property date_match: bool

Whether the dates match between the Git tag and the change log.

property issue: str | None

The human readable reason why release is not valid, or None if it is valid.

tag: Tag

property version_match: bool

Whether the versions match between the Git tag and the change log.

class zensols.relpo.domain.Tag(version, date, name, sha, message)

Bases: Entry

A git tag that was used for a previous release or a current release.

__init__(version, date, name, sha, message)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

message: str

The comment given at tag creation.

name: str

The name of the tag.

sha: str

Unique SHA1 string of the commit.

class zensols.relpo.domain.Version(major=0, minor=0, debug=1)

Bases: Flattenable

A container class for a tag version. All tags have an implicit format by sorting in decimal format (i.e. <major>.<minor>.<version>). This class contains methods that make it sortable.

__init__(major=0, minor=0, debug=1)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

debug: int = 1

static from_str(s)

Create a version instance from a string formatted version.

Return type:

Version

Returns:

a new instance of Version

increment(decimal='debug', inc=1)

Increment the version in the instance. By default the debug portion of the instance is incremented.

major: int = 0

minor: int = 0

property name: str

The name of the version, which as a v prepended followed by the numerical (simple) version.

property simple: str

The simple decimal version, which has the form:

(i.e. ``<major>.<minor>.<version>``)

zensols.relpo.domain.represent_ordereddict(dumper, data)

zensols.relpo.envdist module

Environment distribution file build.

class zensols.relpo.envdist.Dependency(is_conda, source)

Bases: Flattenable

A lock dependency.

__init__(is_conda, source)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

property conda_platform: str | None

The platform of the conda dependency, or None if not a conda dependnecy.

property dist_name: str

The file name (sans directory) used in the distribution.

is_conda: bool

Whether the dependency is conda as apposed to pypi.

property is_direct: bool

Whether this is a Pip direct URL (i.e. <name> @ <url>).

property is_file: bool

Whether or not the dependency is a project local file. This is not to be confused with a cached file downloaded to the local file system.

property is_platform_independent: bool

Whether this is platform independent (i.e. py3-none-any).

property local_file: Path

The downloaded and cached file on the local file system.

See:

file

property name: str

The dependency name (i.e. numpy in numpy==1.26.0).

property native_file: Path | None

The local file dependency path if is_file is True. These are usually added to the repository and not to be confused with the cached / downloaded file.

See:

local_file

source: str

The URL of the resource.

property source_file: str

The file name porition of the url, which is the file name.

property url: str | None

The URL portion of the source (if it is a URL).

property version: str

The dependency version (i.e. 1.26.0 in numpy==1.26.0).

class zensols.relpo.envdist.Environment(name, platforms)

Bases: Flattenable

A pixi environment.

__init__(name, platforms)

add_env(env, platform)

name: str

The name of the Pixi enviornment (i.e. default).

platforms: Dict[str, Platform]

The Pixi platforms (i.e. linux-64).

class zensols.relpo.envdist.EnvironmentDistBuilder(config, template_params, temporary_dir, output_file, progress)

Bases: Flattenable

This class creates files used by sphinx-api and sphinx-build to create a package API documentation. First rendered (from Jinja2 templates) Sphinx configuration (i.e. .rst files) and static files are written to a source directory. Then Sphinx is given the source directory to generate the API documentation.

__init__(config, template_params, temporary_dir, output_file, progress)

config: EnvironmentDistConfig

The parsed document generation configuration.

generate()

Create the environment distribution file.

get_environment_file(platform_name)

The contents of the a platform’s Conda environment.yml file

Return type:

str

property lock: Dict[str, Any]

The parsed data from the pixi.lock file.

output_file: Path

Where to output the environment distribution file.

progress: bool

Whether to display the progress bar.

template_params: Dict[str, Any]

The context given to Jinja2 as Project used to render any configuration files or install scripts.

temporary_dir: Path

Temporary space for files.

class zensols.relpo.envdist.EnvironmentDistConfig(data, cache_dir, pixi_lock_file, environment, platforms, injects)

Bases: Config

Configuration for API doc generation.

__init__(data, cache_dir, pixi_lock_file, environment, platforms, injects)

cache_dir: Path

The directory to cache conda and PyPi library files.

environment: str

The environment to export (i.e. default, testur).

injects: Dict[str, List[Dict[str, str]]]

Local files as glob patterns to add to the distribution.

classmethod instance(data)

Create an instance of this class.

Return type:

EnvironmentDistConfig

pixi_lock_file: Path

The pixi lock file (pixi.lock).

platforms: Set[str]

The platforms to export (i.e. linux-64).

class zensols.relpo.envdist.Platform(name, dependencies)

Bases: Flattenable

A parsed platform from the Pixi lock file.

__init__(name, dependencies)

dependencies: List[Dependency]

The platform dependnecies

name: str

The name of the platform (i.e. linux-64').

zensols.relpo.project module

A utility class that represents a Git tag.

class zensols.relpo.project.Project(config_files, temporary_dir)

Bases: Flattenable

The project and related data of a Python source code repository.

__init__(config_files, temporary_dir)

asdict()

Serialize the object data into a flat dictionary recursively.

Return type:

Dict[str, Any]

property change_log: ChangeLog

The change log found in the release.

property config: ProjectConfig

The project config used to populate templates. This is the parsed data from all configuration files (config_files).

config_files: Tuple[Path, ...]

The project config files used to populate templates and docs.

create_doc(output_dir)

Create the site and API documentation.

create_env_dist(output_file, progress)

Create the environment distribution file.

property issue: str

The human readable reason why release is not valid, or None if it is valid.

property pyproject: str

The pyproject.toml rendered content as a string.

Parameters:

template_dir – the directory to the zenbuild toml template files

read_config()

Return the parsed config_files with each configuration file as an element of the returned list.

Return type:

List[Dict[str, Any]]

property releases: Tuple[Release, ...]

render(template_content, params=None)

Render a template using: :rtype: str

• date: the current (now) datetime

• project: a reference to this class instance

• env: operating system environment

• config: the project config (config)

property repo: ProjectRepo

The Git repository and its metadata.

temporary_dir: Path

Temporary space for files.

class zensols.relpo.project.ProjectConfig(data, proj_dir, template_dir, pyproject_template_files, table_appends, change_log_file_name)

Bases: Config

The Project configuration.

__init__(data, proj_dir, template_dir, pyproject_template_files, table_appends, change_log_file_name)

asdict()

Serialize the object data into a flat dictionary recursively.

change_log_file_name: str

The name of the change log file.

property envdist_config: EnvironmentDistConfig

The environment distribution configuraiton.

classmethod instance(data)

Create an instance from parsed data.

Return type:

ProjectConfig

proj_dir: Path

The root Git repo directory.

pyproject_template_files: Tuple[Path, ...]

Additional template files used to render the pyproject.toml file.

property site_doc_config: DocConfig

The Sphinix documentation configuraiton.

table_appends: Dict[str, Any]

Table name/value TOML appends to add to the pyproject.toml file. These entries have the TOML path as keys and the contents of an inline table to add as values.

template_dir: Path

The directory with the pyproject.toml Jinja2 template files.

class zensols.relpo.project.ProjectFactory(config_files, temporary_dir)

Bases: object

Creates and caches the project data.

__init__(config_files, temporary_dir)

config_files: Tuple[Path, ...]

The project config files used to populate templates and docs.

create()

Return type:

Project

reset()

temporary_dir: Path

Temporary space for files.

zensols.relpo.repo module

Project and git repository classes.

class zensols.relpo.repo.GitRemote(name, url)

Bases: Flattenable

A Git remote created with a command such as:

``git remote add <name> <url>``

__init__(name, url)

name: str

The remote name.

url: str

The URL of the remote.

class zensols.relpo.repo.ProjectRepo(repo_dir, commit_limit=20)

Bases: Flattenable

A Python source code Git repository. It’s main use is determining the last tag in a sorted (by version) used to increment to the next version. However, it also creates tags and provides additional information about existing tags.

All tags have an implicit format by sorting in decimal format (i.e. <major>.<minor>.<version>).

__init__(repo_dir, commit_limit=20)

asdict()

Return information about the last commit and a build time with the current time.

Return type:

Dict[str, Any]

bump_tag()

Delete the last tag and create a new one on the latest commit.

Return type:

str

commit_limit: int = 20

The maximum most recent commits to track and returned from commits.

property commits: Tuple[Commit, ...]

create_tag(version, message)

Create a new tag.

Parameters:

• tag_name – the text of the tag

• message (str) – the message (comment-like) of the tag

Return type:

str

delete_last_tag()

Delete the most recent commit tag.

Return type:

str

property git_remotes: Tuple[GitRemote, ...]

The Git remotes for this repository.

property git_repo: Repo

increment_tag(message, version_increment_level='debug')

Create a new tag incremented from the version of the latest commit.

Parameters:

• tag_name – the text of the tag

• version_increment_level (str) – which part of the version to increment

Return type:

Version

repo_dir: Path

The root Git repo directory.

property tags: Tuple[Tag, ...]

Return the tags in the repo in order of version. Only those that match the version pattern are returned.

Module contents