Spells (API reference)

This is an API reference for the all the Invoke tasks and helper functions that are included in the Conjuring package.

`conjuring.spells.aws`

AWS: ECR login.

`clean_ecr_url(c, url=None)`

Clean an AWS ECR URL.

Source code in src/conjuring/spells/aws.py

def clean_ecr_url(c: Context, url: str | None = None) -> str:
    """Clean an AWS ECR URL."""
    if not url:
        account = fzf_aws_account(c)
        region = fzf_aws_region(c)
        return f"{account}.dkr.ecr.{region}.amazonaws.com"
    return urlparse(url).netloc

`ecr_login(c, url='')`

Log in to AWS ECR.

Using Amazon ECR with the AWS CLI - Amazon ECR

Source code in src/conjuring/spells/aws.py

@task
def ecr_login(c: Context, url: str = "") -> None:
    """Log in to AWS ECR.

    [Using Amazon ECR with the AWS CLI - Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-authenticate-registry)
    """
    profile = fzf_aws_profile(c)
    url = clean_ecr_url(c, url)
    run_command(
        c,
        "aws ecr get-login-password --profile",
        profile,
        "| docker login --username AWS --password-stdin",
        url,
    )

`fzf_aws_account(c)`

Select an AWS account from the config file.

Source code in src/conjuring/spells/aws.py

def fzf_aws_account(c: Context) -> str:
    """Select an AWS account from the config file."""
    return run_with_fzf(c, f"rg -o 'aws:iam::[^:]+' {AWS_CONFIG} | cut -d ':' -f 4 | sort -u")

`fzf_aws_profile(c, partial_name=None)`

Select an AWS profile from a partial profile name using fzf.

Source code in src/conjuring/spells/aws.py

def fzf_aws_profile(c: Context, partial_name: str | None = None) -> str:
    """Select an AWS profile from a partial profile name using fzf."""
    if not partial_name and (aws_profile := os.environ.get("AWS_PROFILE")) and aws_profile:
        typer.echo(f"Using env variable AWS_PROFILE (set to '{aws_profile}')")
        return aws_profile

    return run_with_fzf(c, LIST_AWS_PROFILES_COMMAND, query=partial_name or "")

`fzf_aws_region(c)`

Select an AWS region from the config file.

Source code in src/conjuring/spells/aws.py

def fzf_aws_region(c: Context) -> str:
    """Select an AWS region from the config file."""
    return run_with_fzf(c, f"rg -o '^region.+' {AWS_CONFIG} | tr -d ' ' | cut -d'=' -f 2 | sort -u")

`list_aws_profiles(c)`

List AWS profiles from the config file.

Source code in src/conjuring/spells/aws.py

def list_aws_profiles(c: Context) -> list[str]:
    """List AWS profiles from the config file."""
    return run_lines(c, LIST_AWS_PROFILES_COMMAND)

`run_aws_vault(c, *pieces, profile=None)`

Run AWS vault commands in a subshell, or open a subshell if no commands were provided.

Source code in src/conjuring/spells/aws.py

def run_aws_vault(c: Context, *pieces: str, profile: str | None = None) -> Result:
    """Run AWS vault commands in a subshell, or open a subshell if no commands were provided."""
    return run_command(c, "aws-vault exec", fzf_aws_profile(c, profile), "--", *pieces, pty=False)

`conjuring.spells.direnv`

direnv: init local dir.

`init(c, source_up=False, dotenv=False, all_=False)`

Configure direnv in the local dir.

Source code in src/conjuring/spells/direnv.py

@task()
def init(c: Context, source_up: bool = False, dotenv: bool = False, all_: bool = False) -> None:
    """Configure direnv in the local dir."""
    if all_:
        source_up = dotenv = True
    if not (source_up or dotenv or all_):
        print_error("Choose one of the options: --source-up, --dotenv, --all")
        return

    envrc = Path(ENVRC)
    content = envrc.read_text() if envrc.exists() else ""

    if source_up and SOURCE_UP_IF_EXISTS not in content:
        content += SOURCE_UP_IF_EXISTS_TEMPLATE

    if dotenv and DOTENV_IF_EXISTS not in content:
        content += DOTENV_IF_EXISTS_TEMPLATE

    if content:
        envrc.write_text(content)
        c.run("direnv allow")

    bat(c, ".env*")

`conjuring.spells.docker`

Docker: remove containers and volumes.

`rm_containers(c, container='', all_=False, exited=False)`

Remove Docker containers.

Source code in src/conjuring/spells/docker.py

@task(
    help={
        "container": "Container name to remove (regexp)",
        "all_": "All containers",
        "exited": "Exited containers",
    },
)
def rm_containers(c: Context, container: str = "", all_: bool = False, exited: bool = False) -> None:
    """Remove Docker containers."""
    cmd = []
    if all_:
        cmd = ["docker ps -a"]
    elif exited:
        cmd = ["docker ps -a -f status=exited"]
    elif container:
        cmd = ["docker ps -a | grep -e", container]
    if not cmd:
        print_error("Choose one argument. Run with --help to see available argument")
        return

    run_command(c, *cmd, dry=False)
    run_command(c, *cmd, "| tail +2 | awk '{print $1}' | xargs docker rm -f")
    run_command(c, *cmd)

`rm_volumes(c, dangling=False)`

Remove Docker volumes.

Source code in src/conjuring/spells/docker.py

@task(help=({"dangling": "Dangling volumes"}))
def rm_volumes(c: Context, dangling: bool = False) -> None:
    """Remove Docker volumes."""
    cmd = ""
    if dangling:
        cmd = 'docker volume ls -f "dangling=true"'
    if not cmd:
        print_error("Choose one argument. Run with --help to see available argument")
        return

    run_command(c, cmd, dry=False)
    run_command(c, f"docker volume rm $({cmd} -q)")
    run_command(c, cmd)

`conjuring.spells.duplicity`

Backup and restore with Duplicity.

`backup(c)`

Backup files with Duplicity.

Source code in src/conjuring/spells/duplicity.py

@task
def backup(c: Context) -> None:
    """Backup files with Duplicity."""
    host = print_hostname(c)
    backup_dir = f"file://{BACKUP_DIR}/{host}/duplicity/"
    # To back up directly on OneDrive:
    # backup_dir = f"onedrive://Backup/{host}/duplicity/"
    typer.echo(f"Backup dir: {backup_dir}")

    template_file = Path("~/dotfiles/backup-duplicity-template.cfg").expanduser()
    typer.echo(f"Template file: {template_file}")

    template_contents = template_file.read_text()
    duplicity_config = Template(template_contents).substitute({"HOME": Path.home()})

    with NamedTemporaryFile("r+", delete=False) as temp_file:
        temp_file.write(duplicity_config)
        temp_file.flush()
        run_command(
            c,
            "duplicity",
            f"--name='{host}-backup'",
            "-v info",
            f"--include-filelist={temp_file.name}",
            "--exclude='**' $HOME/",
            backup_dir,
        )

`print_hostname(c)`

Print the hostname of the current machine.

Source code in src/conjuring/spells/duplicity.py

def print_hostname(c: Context) -> str:
    """Print the hostname of the current machine."""
    host = c.run("hostname | sed 's/.local//'", dry=False).stdout.strip()
    typer.echo(f"Host: {host}")
    return host

`restore(c)`

Restore files with Duplicity. You will be prompted to choose the source dir. Restore dir is ~/Downloads.

Source code in src/conjuring/spells/duplicity.py

@task
def restore(c: Context) -> None:
    """Restore files with Duplicity. You will be prompted to choose the source dir. Restore dir is ~/Downloads."""
    print_hostname(c)
    chosen_dir = run_with_fzf(c, f"fd -d 2 -t d duplicity {BACKUP_DIR}")
    if not chosen_dir:
        return

    source_computer = Path(chosen_dir).parent.name
    c.run(f"duplicity restore file://{chosen_dir} ~/Downloads/duplicity-restore/{source_computer}/")

`conjuring.spells.fork`

GitHub forks: configure remote and sync.

`remote(c, username, remote_='upstream')`

Configure a remote for a fork.

Source code in src/conjuring/spells/fork.py

@task(
    help={
        "username": "The owner of the original repository. Required",
        "remote": "The remote to sync with (default: upstream)",
    },
)
def remote(c: Context, username: str, remote_: str = "upstream") -> None:
    """[Configure a remote for a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork)."""
    if username.startswith("-"):
        msg = "Arguments should be: username [--remote]"
        raise Exit(msg)
    if not remote_:
        remote_ = username

    project = c.run(r"git remote -v | rg origin | head -1 | rg -o '/(.+)\.git' -r '$1'", pty=False).stdout.strip()
    c.run(f"git remote add {remote_} https://github.com/{username}/{project}.git", warn=True)
    c.run("git remote -v")

`sync(c, remote_='upstream')`

Sync a fork.

Source code in src/conjuring/spells/fork.py

@task(help={"remote": "The remote to sync with (default: upstream)"})
def sync(c: Context, remote_: str = "upstream") -> None:
    """[Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)."""
    c.run(f"git fetch {remote_}")
    existing_branch = Git(c).checkout("master", "main")
    c.run(f"git merge {remote_}/{existing_branch}")
    c.run("git push")

`conjuring.spells.generic`

Generic spells: list to-do items in files.

`Location` `dataclass`

Location of a to-do item in a file.

Source code in src/conjuring/spells/generic.py

@dataclass
class Location:
    """Location of a to-do item in a file."""

    path: str
    line: int | str
    comment: str

    def __post_init__(self) -> None:
        self.line = int(self.line)
        self.comment = self.comment.strip()

`ToDoItem` `dataclass`

A to-do item.

Source code in src/conjuring/spells/generic.py

@dataclass(frozen=True)
class ToDoItem:
    """A to-do item."""

    which: str
    assignee: str
    description: str

    @property
    def sort_key(self) -> str:
        """Key to sort the instance.

        String concatenation works.
        Checking both fields separately with ``and`` conditions didn't work: sort order was not as expected
        (meaning fix-me tasks first, then to-do tasks).
        """
        return f"{self.which.casefold()}-{self.assignee.casefold()}-{self.description.casefold()}"

    def __lt__(self, other: ToDoItem) -> bool:
        return self.sort_key < other.sort_key

`sort_key: str` `property`

Key to sort the instance.

String concatenation works. Checking both fields separately with and conditions didn't work: sort order was not as expected (meaning fix-me tasks first, then to-do tasks).

`todo(c, cz=False, valid=True, invalid=True, short=False, priority='', markdown=False)`

List to-dos and fix-mes in code. Optionally check if the description follows Conventional Commits (cz check).

Source code in src/conjuring/spells/generic.py

@task(
    help={
        "cz": "Run commitizen (cz check) to validate the description of the to-do item as a commit message",
        "valid": "When using cz check, print valid to-do items",
        "invalid": "When using cz check, print invalid to-do items",
        "short": "Short format: only the description, without the lines of code where to-do items were found",
        "priority": "Specify an assignee and show only higher priority tasks for them"
        f" ({FIX_ME} or {TO_DO}(<assignee>)",
        "markdown": "Print the output in Markdown format",
    },
)
def todo(  # noqa: PLR0913
    c: Context,
    cz: bool = False,
    valid: bool = True,
    invalid: bool = True,
    short: bool = False,
    priority: str = "",
    markdown: bool = False,
) -> None:
    """List to-dos and fix-mes in code. Optionally check if the description follows Conventional Commits (cz check)."""
    all_todos: dict[ToDoItem, list[Location]] = _parse_all_todos(c, priority)

    if markdown:
        _print_todos_as_markdown(all_todos, short)
        return

    for item, locations in sorted(all_todos.items()):  # type: ToDoItem, list[Location]
        func = print_success
        if cz:
            result = run_command(c, "cz check -m", quote(item.description), hide=True, warn=True)
            if result.ok:
                if not valid:
                    continue
            else:
                if not invalid:
                    continue
                func = print_error

        assignee_str = f"({item.assignee.upper()})" if item.assignee else ""
        func(f"{item.which}{assignee_str}: {item.description}")

        if short:
            continue
        for loc in locations:  # type: Location
            typer.echo(f"   {loc.path}:{loc.line} {loc.comment}")