scooped 1.1.0

A CLI for project setup from generalised templates

Scooped

A generalised project generation command using jinja2 templates

Usage

Scooped is a simple commandline program used to build boilerplate projects from templates. Templates are simply projects with jinja2 templates and a special config file at their root scooped.toml. Any github repository that meets these requirements can be installed as a template, or alternatively you may find templates at http endpoints as zip archives with a single directory containing the config at their root.

Scooped templates are ideal for developers who find themselves repeating certain steps across their projects e.g. configuring deployment scripts, IaC, setting up unittest suites, and any other repetetive tasks.

Installation

Scooped can be installed from pypi with the following command:

pip install scooped

Since scooped is primarily a commandline tool you may want to use pipx to install it instead.

Getting Started

Run one of the following commands with the template of your choosing to install it on your system.

scooped install owner/repository # used for a github repository
scooped install https://yoursite.com/path/to/your/template.zip # used for custom http servers

When you run scooped list you should see the newly installed template and it should have a check mark at the end of the row to show that it is valid otherwise there is a problem with the template's config. Using your newly installed template you can create a new project.

scooped create --project-name="Your Project Name" YourTemplate # use the name of the template from 'scooped list' not necessarily the name of the downloaded file

This will create a new folder in the current working directory with the name of your project and generate all the boilerplate from the template. Advanced usage will allow you to create projects in existing folders, pass parameters on the commandline with json or read them in from files. Take a look at scooped create --help for more.

Settings

There are some basic settings that can be configured for scooped but first we must create the config file in either C:\Users\<User>\AppData\Local\ArchmagePsy\scooped on Windows or ~/.config/scooped on Linux. Below is a basic config.toml with some of the common changes we might make to the default settings.

[scooped.create]
project-name-format = "kebab"

[scooped.install]
provider = "github"

this will set github as the default provider and convert all project names to kebab case by default.

Creating your own Templates

The easiest way to host your own templates is to create a github repository to push them to, we assume that you already have a git repository set up with a remote configured. At the root of your project create the scooped.toml file like below:

[template]
name = "MyTemplate" # this is the name users will invoke your template with
author = "owner" # this is you, it's best to set it to the repository owner as it and the name can be used to infer where to find updates for the template
description = "a short description of what the template is for"

# ignore = [] # a list of globs much like a gitignore used to exclude files from template generation, uncomment as needed

these are some of the basic options you can configure for a template, additional configuration options for the github provider and jinja templating engine are available but we wont cover them here. Any keys not included in the [template] section will be based to the jinja templates and expressions as parameters, for example:

[season]
greetings = "merry christmas!"

would be templated into the following greet.py.j2:

print("{{ season.greetings }}")

any file in the template with an extension of j2, jinja, or jinja2 will be processed as a jinja template (after which the jinja extension will be stripped). File and folder names will also be processed, for example, a file at the path {{ project_name }}-core/main.py would become your-project-name-core/main.py.

Once we commit these changes and push them to the remote repository we are ready to install and use the template to create projects.

Making Templates interactive

Sometimes you want a guided experience for the setup of a project, in such cases scooped supports interactive templates where users can enter parameters by answering a series of questions. The following example illustrates how a template may ask for a specific python version:

[template.interactive.python_version]
prompt = "Please enter the version of python you would like to use"
type = "string"
default = "3.12"
validation = "[0-9]+(\\.[0-9]+){0,2}"
errorMessage = "Please enter a valid version of python in the format x.y.z"

Interactive parameters will be skipped if a user provides a valid value for them on the command line.

Why the name 'Scooped'?

To be 'scooped' is a slang term used to explain when you discover that an idea you have had has been previously explored by someone else. This project was originally called 'stencil' the idea being that you could create templates and use them to generate boilerplate projects and save time, the same way you would use a stencil to save you time and effort drawing a shape: precise and consistent results with minimal effort.

As it turns out, when I attempted to publish my project to PyPI someone else had already had a similar idea to mine 15 years ago with unfortunately the exact same name. Because I am proud of the tool I have written and believe it fills a different (albeit very similar) niche I have decided to stick with it and rename it to 'scooped' a nod to this hilariously embarrassing situation.