GitHub Integration and Workflow Management with Jupyter and ipywidgets

This module provides a graphical interface within Jupyter notebooks for managing GitHub repositories, streamlining the use of ipywidgets for interactive GitHub integration. Primary functions include repository cloning, changes committing, updates pulling, commits pushing, and repository status checking, complemented by GitHub Actions workflow management.

Subsections

• Widgets:

  Custom ipywidgets classes enhancing text input with validation capabilities and providing styled interactive buttons and command layouts.

• GitHubLazy:

  The central class furnishing methods for interacting with GitHub repositories and orchestrating workflows.

• Interface Layout:

  A utility function to assemble and present the ipywidgets interface within a Jupyter notebook environment.

class docs.CommandLayout(description: str, button: str, callback: Callable | None = None, placeholder: str = '', validate: bool = False, tooltip: str = '')

Bases: object

A layout class that combines a text widget with a custom button for command inputs.

Parameters:

• description (str) – The description for the text widget.

• button (str) – The label for the button.

• callback (Optional[Callable], optional) – The function to call when the button is clicked, by default None.

• placeholder (str, optional) – Placeholder text for the text widget, by default ‘’.

• validate (bool, optional) – Whether to enable validation on the text widget, by default False.

• tooltip (str, optional) – Tooltip text for the text widget, by default ‘’.

button

The custom button associated with the command layout.

Type:

CustomButton

validate_text

The ValidateText widget used for command input.

Type:

ValidateText

layout() → widgets.AppLayout

Returns the widget layout for the command layout, combining the text widget and the button.

text() → str

Gets the current text value of the text widget.

text(value: str)

Sets the text value of the text widget.

__init__(description: str, button: str, callback: Callable | None = None, placeholder: str = '', validate: bool = False, tooltip: str = '')

Construct a CommandLayout instance with integrated text validation and command execution.

Parameters:

• description (str) – A descriptive label for the text input field.

• button (str) – The text to display on the action button.

• callback (Optional[Callable], optional) – The callback function to invoke when the action button is clicked. Default is None.

• placeholder (str, optional) – The placeholder text for the text input when it is empty. Default is an empty string.

• validate (bool, optional) – A flag to indicate if validation should be applied to the text input. Default is False.

• tooltip (str, optional) – A short text to help the user understand what the text input and button are for. Default is an empty string.

Return type:

None

property layout: ipywidgets.AppLayout

Construct the widget layout for the command layout.

Returns:

The layout combining the text widget and the button.

Return type:

widgets.AppLayout

property text: str

Get the current text value of the text widget.

Returns:

The current text value of the text widget.

Return type:

str

class docs.CustomButton(*args: Any, **kwargs: Any)

Bases: Button

A custom button widget with a predefined layout and optional callback functionality.

Parameters:

callback (Optional[Callable], optional) – The function to be called when the button is clicked. Defaults to None.

layout

The layout configuration for the button widget.

Type:

widgets.Layout

__init__(callback: Optional[Callable] = None, \*\*kwargs)

Constructs a CustomButton instance.

Notes

The CustomButton can be linked to a specific functionality through the callback, which triggers upon a button click event.

__init__(callback: Callable | None = None, **kwargs)

Construct a CustomButton instance.

Parameters:

• callback (Optional[Callable], optional) – The function to be invoked when the button is clicked. If not provided, no function will be called. Default is None.

• **kwargs (dict, optional) – Additional keyword arguments to pass to the base Button class.

class docs.GitHubLazy

Bases: object

Handles GitHub operations within a Jupyter notebook using ipywidgets.

This class allows for common GitHub operations such as cloning a repository, committing changes, pulling updates, pushing commits, and checking statuses—all through an interactive IPython widget interface.

GITHUB_PAT

A GitHub Personal Access Token for authentication, retrieved from secrets.

Type:

Optional[str]

GITHUB_NAME

The GitHub username associated with the token, retrieved from secrets.

Type:

Optional[str]

GITHUB_EMAIL

The email address associated with the GitHub account, retrieved from secrets.

Type:

Optional[str]

logger

A widget label for logging output within the Jupyter notebook.

Type:

widgets.Label

__init__()

Initializes the GitHubLazy object with all necessary widgets and configuration.

Raises:

Exception – If a required secret (like GITHUB_PAT) is not set or if an operation fails.

Notes

It is necessary to set the GitHub personal access token (GITHUB_PAT), username (GITHUB_NAME), and email (GITHUB_EMAIL) as secrets prior to using this class for GitHub operations.

Examples

>>> github = GitHubLazy()
>>> github.clone_repository('https://github.com/user/repo.git')
Cloning into 'repo'...
>>> github.commit_changes('Initial commit')
[main (root-commit) 1a2b3c4] Initial commit

GITHUB_EMAIL: str | None = 'GITHUB_EMAIL'

GITHUB_NAME: str | None = 'GITHUB_NAME'

GITHUB_PAT: str | None = 'GITHUB_PAT'

__init__()

Initialize the GitHubLazy object with all necessary widgets and configuration.

Raises:

Exception – If a required secret (like GITHUB_PAT) is not set or if an operation fails.

clone(evt: ipywidgets.Button | None = None) → None

Clone a GitHub repository.

This method is designed to clone a GitHub repository using the repository URL provided through the clone_layout text widget interface.

Parameters:

evt (Optional[widgets.Button], optional) – The button event that triggers the cloning process. If no event is provided, the method can be called programmatically without any event context. Default is None.

Raises:

subprocess.CalledProcessError – If the cloning process encounters an error.

Examples

>>> github = GitHubLazy()
>>> github.clone(None)
# Assume the URL is already provided through the interface; this will start the cloning process.

commit(evt: ipywidgets.Button | None = None) → None

Commit changes to the local repository with a message.

The commit message is provided through the commit_layout’s text widget. This allows users to specify what changes they’re committing.

Parameters:

evt (Optional[widgets.Button], optional) – The event associated with the commit button that, when triggered, calls this method. If None, the method can be called without an event, allowing for programmatic commits (default is None).

Raises:

subprocess.CalledProcessError – If the commit process fails due to underlying issues with the Git command.

Examples

>>> github_lazy = GitHubLazy()
>>> github_lazy.commit(None)  # This assumes that the commit message is pre-set.

copy_workflow(workflow: Path) → None

Copies the specified GitHub Actions workflow file to the repository’s workflow directory.

Parameters:

workflow (Path) – The Path object representing the workflow file to be copied to the repository’s workflow directory.

logger: ipywidgets.Label = ''

pull(evt: ipywidgets.Button | None = None) → None

Fetch the most recent changes from the remote repository and merge them with the local branch.

This will update the local copy of the repository with any changes that have been made remotely.

Parameters:

evt (Optional[widgets.Button], optional) – The button event that triggers the pull operation. If the method is called without an associated event, it’s assumed to be a manual call. Defaults to None.

Examples

>>> github_lazy = GitHubLazy()
>>> github_lazy.pull()  # Pulls changes without a button event.

push(evt: ipywidgets.Button | None = None) → None

Pushes local commits to the remote repository.

This method will push all committed changes in the local repository to the remote repository defined in the repository’s Git configuration.

Parameters:

evt (Optional[widgets.Button], optional) – The button event that triggers this method. If the method is called programmatically without a button event, this argument should be None. Default is None.

run_command(command: str, path: str = '.', silent: bool = True) → None

Execute a given shell command in the specified directory path.

Parameters:

• command (str) – The shell command to execute.

• path (str, optional) – The directory path where the command is to be executed. Default is the current directory.

• silent (bool, optional) – If True, suppresses the logging output. Default is True.

status(evt: ipywidgets.Button | None = None) → None

Checks the current status of the local Git repository.

This method displays the current status of files in the local repository, indicating if files are staged, unstaged, or untracked, and if the branch is ahead, behind, or has diverged from the remote branch it tracks.

Parameters:

evt (Optional[widgets.Button], optional) – The button event that triggers the status check. If the method is called without an associated event, it’s assumed to be a manual call. Default is None.

class docs.ValidateText(*args: Any, **kwargs: Any)

Bases: Text

Custom widget class extending ipywidgets.Text to provide validation.

This widget augments the textual input with validation, altering an associated button’s style to reflect validity status.

Parameters:

**kwargs (dict) – Additional keyword arguments to configure the widget.

validate

Indicates whether the validation mechanism is active.

Type:

bool

button

Button whose style changes based on the validation status.

Type:

widgets.Button

_update_style(change)

Updates the button’s style dependent on the validity of the input text.

Parameters:

change (dict) – Information about the change, including ‘type’, ‘name’, ‘old’, and ‘new’.

__init__(**kwargs)

Initialize the ValidateText widget.

Parameters:

• validate (bool, optional) – A flag to activate validation. Default is False.

• button (widgets.Button, optional) – A button widget linked to this text widget. Default is None.

_update_style(change: dict) → None

Update the style of the associated button based on the validation condition.

Parameters:

change (dict) – A dictionary containing the details of the change event. This includes keys such as ‘type’, ‘name’, ‘old’, and ‘new’ corresponding to the change event properties.

Return type:

None

docs.__lab__() → ipywidgets.GridspecLayout

Creates and displays a GitHub management interface using ipywidgets.

This function initializes the GitHubLazy class and arranges its components into a GridspecLayout for display.

Returns:

A grid layout containing the GitHubLazy interface components.

Return type:

widgets.GridspecLayout

docs.delete_secrets() → None

Removes saved GitHub secrets from storage.

This function clears out the GitHub Personal Access Token (PAT), GitHub username, and GitHub email address stored securely, ensuring these sensitive details are no longer retained in the system.

Raises:

KeyError – If a secret key does not exist in the storage when attempted to be deleted.