Footing Package

footing.setup

Creates and initializes a project from a template

footing.setup.setup(template, version=None)

Sets up a new project from a template

Note that the footing.constants.FOOTING_ENV_VAR is set to ‘setup’ during the duration of this function.

Parameters

• template (str) – The git path to a template

• version (str, optional) – The version of the template to use when updating. Defaults to the latest version

footing.update

Updates a footing project with the latest template

footing.update.up_to_date(version=None)

Checks if a footing project is up to date with the repo

Note that the footing.constants.FOOTING_ENV_VAR is set to ‘update’ for the duration of this function.

Parameters

version (str, optional) – Update against this git SHA or branch of the template

Returns

True if up to date with version (or latest version), False otherwise

Return type

boolean

Raises

• NotInGitRepoError – When running outside of a git repo

• InvalidFootingProjectError – When not inside a valid footing repository

footing.update.update(old_template=None, old_version=None, new_template=None, new_version=None, enter_parameters=False)

Updates the footing project to the latest template

Proceeeds in the following steps:

1. Ensure we are inside the project repository

2. Obtain the latest version of the package template

3. If the package is up to date with the latest template, return

4. If not, create an empty template branch with a new copy of the old template

5. Create an update branch from HEAD and merge in the new template copy

6. Create a new copy of the new template and merge into the empty template branch

7. Merge the updated empty template branch into the update branch

8. Ensure footing.yaml reflects what is in the template branch

9. Remove the empty template branch

Note that the footing.constants.FOOTING_ENV_VAR is set to ‘update’ for the duration of this function.

Two branches will be created during the update process, one named _footing_update and one named _footing_update_temp. At the end of the process, _footing_update_temp will be removed automatically. The work will be left in _footing_update in an uncommitted state for review. The update will fail early if either of these branches exist before the process starts.

Parameters

• old_template (str, default=None) – The old template from which to update. Defaults to the template in footing.yaml

• old_version (str, default=None) – The old version of the template. Defaults to the version in footing.yaml

• new_template (str, default=None) – The new template for updating. Defaults to the template in footing.yaml

• new_version (str, default=None) – The new version of the new template to update. Defaults to the latest version of the new template

• enter_parameters (bool, default=False) – Force entering template parameters for the project

Raises

• NotInGitRepoError – When not inside of a git repository

• InvalidFootingProjectError – When not inside a valid footing repository

• InDirtyRepoError – When an update is triggered while the repo is in a dirty state

• ExistingBranchError – When an update is triggered and there is an existing update branch

Returns

True if update was performed or False if template was already up to date

Return type

boolean

footing.ls

Lists all footing templates and projects spun up with those templates

footing.ls.ls(forge, template=None)

Lists all templates under a root path or list all projects spun up under a root path and a template path.

The root path must be either a Github organization/user (e.g. github.com/organization) or a Gitlab group (e.g. gitlab.com/my/group).

Note that the footing.constants.FOOTING_ENV_VAR is set to ‘ls’ for the duration of this function.

Parameters

• root (str) – A root git storage path. For example, a Github organization (github.com/Organization) or a gitlab group (gitlab.com/my/group).

• template (str, default=None) – An optional template path. If provided, the returned values are projects under root created using the template.

Returns

A dictionary of repository information keyed on the url.

Return type

dict

Raises

InvalidForgeError – When forge is invalid

footing.constants

Constants for footing

footing.constants.FOOTING_CONFIG_FILE = 'footing.yaml'

The footing config file in each repo

footing.constants.FOOTING_DOCS_URL = 'https://github.com/Opus10/footing'

Footing docs URL

footing.constants.FOOTING_ENV_VAR = '_FOOTING'

The environment variable set when running any footing command. It is set to the name of the command

footing.constants.GITHUB_API_TOKEN_ENV_VAR = 'GITHUB_API_TOKEN'

The Github API token environment variable

footing.constants.GITLAB_API_TOKEN_ENV_VAR = 'GITLAB_API_TOKEN'

The Gitlab API token environment variable

footing.constants.UPDATE_BRANCH_NAME = '_footing_update'

The temporary branches used for updates

footing.exceptions

Footing exceptions

exception footing.exceptions.CheckRunError

When running footing update --check errors

exception footing.exceptions.Error

The top-level error for footing

exception footing.exceptions.ExistingBranchError

Thrown when a specifically named branch exists or doesn’t exist as expected.

exception footing.exceptions.InDirtyRepoError

Thrown when running in a dirty git repo

exception footing.exceptions.InGitRepoError

Thrown when running inside of a git repository

exception footing.exceptions.InvalidCurrentBranchError

Thrown when a command cannot run because of the current git branch

exception footing.exceptions.InvalidEnvironmentError

Thrown when required environment variables are not set

exception footing.exceptions.InvalidFootingProjectError

Thrown when the repository was not created with footing

exception footing.exceptions.InvalidForgeError

An invalid forge was passed to ls.

exception footing.exceptions.InvalidGitlabGroupError

Thrown when an invalid Gitlab group is provided

exception footing.exceptions.InvalidTemplatePathError

Thrown when a template path is not a Github SSH path

exception footing.exceptions.NotInGitRepoError

Thrown when not running inside of a git repo

exception footing.exceptions.NotUpToDateWithTemplateError

Thrown when a footing project is not up to date with the template