qCradle 0.1.16

CLI to create repos

qCradle

qcradle is a command line tool to create repos based on a group of templates.

The tool is very similar to the popular Cookiecutter project.

Install gh

Please install GitHub's official command line tool gh. This tool is used to create GitHub repos from the command line.

Verify the existence of the tool and a valid SSH connection with

ssh -T [e-mail]
gh --version

A new SSH connection could be established here.

Install uv and uvx

uv is a modern, high-performance Python package manager and installer written in Rust. It serves as a drop-in replacement for traditional tools like pip and pipx. For macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

For Windows follow the instructions here

Understanding uvx

uvx is a command provided by uv to run tools published as Python packages without installing them permanently. It creates temporary, isolated environments for these tools:

uvx qcradle

This command will:

• Resolve and install the repo-launcher package in a temporary environment.
• Execute the repo-launcher command.

Note: If you plan to use a tool frequently, consider installing it permanently using uv:

uv tool install qcradle

Once the tool is permanently installed it is enough to start it with

qcradle

Templates

You could create your own templates and standardize project structures across your team or organization. It's essentially a project scaffolding tool that helps maintain consistency in Python projects.

We currently offer $4$ standard templates out of the box

• The document template
• The experiments template
• The package template
• The R template

Standard Templates

We follow the one template, one repository policy. You are encouraged to create your own templates and we give $3$ examples that may serve as inspiration

The document template

The template supports the fast creation of repositories of LaTeX documents. The repo can compile your LaTeX documents with every commit and put them on a dedicated branch.

The experiments template

Here we support the creation of notebooks without the ambition to release software. The repo is not minimalistic but comes with a curated set of pre-commit hooks and follows modern and established guidelines. The notebooks are based on Marimo.

The package template

The package template is most useful when the final goal is the release of software to a registry, e.g. pypi. It offers full uv support and compiles documentation into a Jupyter Book.

The R template

Here we expose R Studio in a devcontainer.

Proprietary templates

Creation

You can create your very own templates and we recommend to start with forking the dedicated repo for the job.

Templates rely on Jinja. At the root level the repo needs a 'copier.yml' file and a 'template' folder.

Each template is tested using act, e.g. we render the project template and test the workflows of the created project. This helps to avoid creating projects starting their life in a broken state.

Usage

We essentially expose the copier interface directly with minor modifications, e.g. if the user is not submitting a source template we offer to choose one of the standard templates.

Any cradle template could be used directly as the first 'template' argument

uvx qcradle --template=[e-mail]:tschm/paper.git

By default, Copier (and hence the repo-launcher) will copy from the last release found in template Git tags, sorted as PEP 440.

Update existing projects

Templates are moving targets in most professional setups. It is possible to update projects created with the help of the qcradle by specifying an existing path instead of a template.

uvx qcradle --dst_path=/Users/thomasschmelzer/projects/my_marimo_experiments

The tool expects a full path. Your repo should contain your previous answers in a file '.copier-answers.yml' which serve as default arguments for the questions you have been asked before. All standard templates create the file.

:warning: Private repositories

Using workflows in private repos will eat into your monthly GitHub bill. You may want to restrict the workflow to operate only when merging on the main branch while operating on a different branch or deactivate the flow.