Metadata-Version: 2.4
Name: scooped
Version: 1.1.1
Summary: A CLI for project setup from generalised templates
Author-email: ArchmagePsy <SeaOfCodeSi@gmail.com>
Requires-Python: >=3.12
Requires-Dist: click>=8.4.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: rich>=15.0.0
Description-Content-Type: text/markdown

# 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:

```bash
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.

```bash
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.

```bash
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.

```toml
[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:

```toml
[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:

```toml
[season]
greetings = "merry christmas!"
```

would be templated into the following `greet.py.j2`:
```python
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:

```toml
[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.
