base

Base classes implementing the command pattern for GitHub operations.

This module provides foundational classes that follow the command pattern design, where complex operations are encapsulated within objects that contain all the information needed to execute the operation. Each class acts as a self-contained command that can be configured with parameters, executed independently, and provides clear interfaces for logging and error handling.

The command pattern is particularly well-suited for GitHub API operations because:

• It encapsulates API credentials, repository information, and operation parameters

• It provides consistent logging and error handling across different operations

• It enables easy testing by allowing dependency injection (like custom printers)

• It supports caching of expensive resources (like API clients) through properties

• It makes complex workflows readable by breaking them into discrete, reusable commands

Classes in this module serve as building blocks for more specialized GitHub operations like release management, tag creation, and repository synchronization.

class pygithub_mate.base.BaseLogger(verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>)

Base logging functionality with configurable output control.

Provides simple message logging with optional verbosity control and customizable output destination following the command pattern.

Parameters:

• verbose – Enable or disable message output

• printer – Function to handle message output (defaults to print)

printer(*, sep=' ', end='\n', file=None, flush=False)

Prints the values to a stream, or to sys.stdout by default.

sep

string inserted between values, default a space.

end

string appended after the last value, default a newline.

file

a file-like object (stream); defaults to the current sys.stdout.

flush

whether to forcibly flush the stream.

info(msg: str)

Log an informational message if verbose mode is enabled.

This method provides controlled logging output that can be disabled via the verbose flag. It follows specific guidelines for when and how to log messages in workflow methods.

When to Add Logging:

• Simple API wrappers: Do NOT add logging to methods that are just wrappers around single API calls (e.g., get_git_tag_and_ref, delete_tag, create_tag_on_commit)

• Complex workflows: DO add logging to methods that involve multi-step decision-making and perform different actions based on conditions (e.g., put_tag_on_commit, put_release)

• First log pattern: For complex workflow methods, the first log message should typically follow the pattern: “— ${description of what this function does}”

Examples:

Complex workflow logging:

self.info("--- Put tag on commit abcd123 ...")
self.info("Check if tag exists ...")
self.info("Tag exists.")
self.info("Check if tag points to the desired commit ...")

Parameters:

msg – Message to log to the configured printer function

Note

This approach keeps logs focused on meaningful workflow steps while avoiding noise from simple operations.

shorten_sha(sha: str) → str

Shorten a Git SHA to its first 7 characters for display.

Parameters:

sha – Full Git SHA string

Returns:

Shortened SHA (first 7 characters)

class pygithub_mate.base.BaseGitHubApiRunner(verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>, github_kwargs: dict[str, ~typing.Any] = REQ, data: dict[str, ~typing.Any] = <factory>)

Base class for GitHub API operations with authentication and logging.

Combines logging capabilities with GitHub API client management. Stores GitHub API configuration as attributes and provides a cached GitHub client instance following the command pattern.

Parameters:

• github_kwargs – Configuration parameters for GitHub API client

• data – Additional data storage for derived classes

property gh: Github

GitHub API client instance.

Returns:

Configured GitHub API client using stored credentials

class pygithub_mate.base.TagAndRef(tag: GitTag | None = None, ref: GitRef | None = None)

A container for holding a Git tag and its corresponding reference.

Parameters:

• tag – The Git tag object (or None if it doesn’t exist)

• ref – The Git reference object (or None if it doesn’t exist)

exists() → bool

Check if the Git tag exists.

Returns:

True if tag is not None, False otherwise

class pygithub_mate.base.ReleaseAndTagAndRef(release: GitRelease | None = None, tag_and_ref: TagAndRef = REQ)

A container for holding a GitHub release, its corresponding tag, and reference.

Parameters:

• release – The GitHub release object (or None if it doesn’t exist)

• tag_and_ref – The TagAndRef object containing the tag and reference

exists() → bool

Check if the GitHub release exists.