Metadata-Version: 2.4
Name: skbs
Version: 3.0.1
Summary: SKeleton BootStrap, a full-powered yet trivial to use and customize template based bootstrap or code generation tool
Author-email: Léo Flaventin Hauchecorne <hl037.prog@gmail.com>
License: GPLv3
Project-URL: Homepage, https://github.com/hl037/skbs
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Other Scripting Engines
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: cyclopts>=4.25
Requires-Dist: appdirs>=1.4.4
Requires-Dist: tempiny>=1.5
Requires-Dist: addict
Provides-Extra: click
Requires-Dist: click>=0.7; extra == "click"
Provides-Extra: test
Requires-Dist: pytest>=6.2.2; extra == "test"
Requires-Dist: pytest_datadir_ng>=1.1.1; extra == "test"
Requires-Dist: pytest-cov>=2.11.1; extra == "test"
Requires-Dist: click>=0.7; extra == "test"
Dynamic: license-file

# Welcome to SKBS

![PyPI](https://img.shields.io/pypi/v/skbs)
![Python versions](https://img.shields.io/pypi/pyversions/skbs)
![License](https://img.shields.io/badge/license-GPLv3-blue)

SKBS means SKeleton BootStrap: templates are just plain Python — no new language to learn.

```
$ cat greeting.txt
## # {{__skbs_template__}}
## for name in ('Alice', 'Bob'):
Hello {{name}}!
## -

$ skbs gen greeting.txt out.txt --
$ cat out.txt
Hello Alice!
Hello Bob!
```

Loops, conditions, functions, imports — all of Python, right in your template. And since the syntax is self-declared on the first line, you can adapt it to whatever language you're generating: use `%#`/`<<`/`>>` for LaTeX, `//#` for C, or your own — see the Tutorial.

Moreover, contrary to other template language, it is possible to change the delimiters to avoid the need for escaping.

# Features

  * Turing complete
  * Easy to create, install, use, and share templates
  * Install a template straight from a git URL (no manual clone needed)
  * Compose templates: call one template from another with `skbs.gen()`
  * Section to keep user edits on a previously generated file
  * Dynamic file and directory names
  * In-template CLI argument parsing via `cyclopts` (always available), or `click` if you prefer it (optional)
  * Heavily tested with `pytest`

# Regenerate without losing your edits

Most template tools are one-shot: run once, then you're on your own. SKBS can treat a file as already generated: wrap anything a user might hand-edit in a "section", and later runs regenerate everything else while leaving that section's content alone.

```
## # {{__skbs_template__}}
## keep_only_sections = True
Header (auto-generated, do not edit)
## beginSection(overwrite=False)
--- BEGIN CUSTOM ---
--- END CUSTOM ---
## endSection()
Footer
```

Generate it once, hand-edit the content between `BEGIN CUSTOM`/`END CUSTOM`, then run `skbs gen` again on the same destination: your edit survives, because `overwrite=False` tells SKBS to keep what's already in the file for that section — while `Header`/`Footer` above regenerate normally if you change the template. (`keep_only_sections = True` is what makes the *rest* of the file follow the template on every run; without it, the whole file freezes after the first generation, sections included.)

# Why not Cookiecutter / Copier / Yeoman?

  * **Cookiecutter / Copier** use Jinja2: a templating *language* with its own limited logic (loops, conditionals, filters). SKBS templates are plain Python: no sandbox, no missing feature — if Python can do it, so can your template.
  * **Yeoman** generators are npm packages you write in JS and publish/install like any package. SKBS templates are just files: write one, `skbs install --symlink` it, done — no packaging step, no separate ecosystem to learn.
  * None of the above let you re-run a template over a file you've since hand-edited without clobbering your changes — see "Regenerate without losing your edits" above.

Coming from Cookiecutter specifically? See the step-by-step guide ( https://github.com/hl037/skbs/wiki/From_Cookiecutter ) — same options/dynamic-name/conditional-file patterns, built as a working skbs template.

# Install

`pip` is the preferred way. Then you should generate the configuration (simply where the template are installed...)

By default, the config is installed at the default location for user configs (`~/.config/skbs/` for unix-like)

```
pip install skbs
skbs create-config
```

Then, you can "install" the default templates (`skbs` and `skbs.sft`) that come with skbs (they are the boilerplate to create templates).

I recommend you to read the Tutorial ( https://github.com/hl037/skbs/wiki/Tutorial ) for a friendly introduction to all skbs features, and API_Reference ( https://github.com/hl037/skbs/wiki/API_Reference ) if you need further details

# Usage

```
Usage: skbs [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config PATH  Override the default configuration path
  --help             Show this message and exit.

Commands:
  config-path       Prints the path to the in-use configuration file.
  create-config     Create / reset to default the configuration file.
  gen               Generate a skeleton from a template.
  install           Install a new template.
  install-defaults  Install default provided templates
  list              List installed templates.
  uninstall         Uninstall a template
```

Usage of `skbs gen`

```
Usage: skbs gen [OPTIONS] TEMPLATE DEST [ARGS]...

  Generate a skeleton from a template.

  template : if template starts with an '@', it will look for an installed
  template. Else, it will be considered as the template path. dest : the
  output directory (parents will be created if needed) args : argument passed
  to the template ( skbs gen <template_name> -- --help for more informations )

Options:
  -g, --debug
  --stdout           Only for single file templates : output to stdout.
                     --single-file is implied
  -s, --single-file  Authorize single file template for non installed
                     templates.
  --help             Show this message and exit.
```

# (Very) Quick start

This section will cover only the very basic, without too much explanation, see it only as a cheat sheet. Read the full Tutorial ( https://github.com/hl037/skbs/wiki/Tutorial ) to leverage the full potential of SKBS.

You may also find the API_Reference ( https://github.com/hl037/skbs/wiki/API_Reference ) useful

------

Install the default-provided templates :
```
skbs install-defaults
```

To request a template's help, use `@help` as destination (or pass `--help` as first template argument, after the `--`:

```
skbs gen @skbs.sft @help
#or
skbs gen @skbs.sft foo_bar -- --help
```
------

To create a self-contained single file template:
```
skbs gen @skbs.sft my_template -- --cyclopts
```

Where `my_template` is the name you want to give it.
Edit my template.

Any file starting with a line :
```
## # {{__skbs_template__}}
```

Is considered a dynamic file, with python support. If this line is not present, it is considered a raw file and is copied as is.

Every line starting with `##` are python, and are not output. Indent level increments on lines ending with `:`, and decrements on line containing a single `-`.

Other lines are printed as they are (possibly multiple time if the python execution flow reach them again).

`{{` and `}}` in a normal line delimit a python expression. It is evaluated and its result replaces the whole `{{...}}` pattern.

This syntax can be changed by modifying the header line as described in the Tutorial ( https://github.com/hl037/skbs/wiki/Tutorial ).

------

To create a multi-file template :
```
skbs gen @skbs my_second_template -- --cyclopts
```

Where `my_second_template` is the name of the template.

Inside `my_second_template`, `plugin.py` is the entry point where you can parse the `args` user-provided argument after the `--`.

The content of the `root` directory will be put inside the destination the user provided, each file will be checked for a template header line, and if found, will be parsed and executed as for the self-contained single file template.

Templates can call each other with `skbs.gen(template_name, dest, *args)`, injected as `skbs` in `plugin.py` and per-file templates — handy to compose a bigger template out of smaller reusable ones. See the Tutorial ( https://github.com/hl037/skbs/wiki/Tutorial ) for the full semantics, and API_Reference ( https://github.com/hl037/skbs/wiki/API_Reference ) for the exact signature.

------

To install a template (or a directory containing template :

```
skbs install -s my_template -n <name>
```

Where `<name>` should be replaced by the name you want to use to recall the template.

You can also install directly from a git URL — skbs clones it for you, under a name derived from the URL (`domain-name.com/path...`) unless you pass `-n`:

```
skbs install https://github.com/some/repo.git
```

This requires `git` to be available on `PATH`.

------

You can list installed template with :

```
skbs list
```
------

...Then you can recall any template in this list using :
```
skbs gen @<name> [...]
```
Where `<name>` is a line that appear in `skbs list`.

