Navigation

Project Links

Meta

Maintainers

Project Description

Basement is an extensible little tool for generating Python project scaffoldingbased on mustache templates and common data you provide in a config file. It'ssuper straightforward.

## Installation

```pip install basement```

Not much more to say!

## Some Assembly Required (Usage)

Basement ships with two commands, `basement` and `ment`. `ment` is a shorthandfor `basement` and thus is exactly the same.

Some assembly is required, and you'll have to break out a screwdriver. Basementis mostly useful because you can customize it! You can add your own templates(which we will go over in the next section) as well as configure filler data forall templates. We'll go over data the built in templates can make use of, aswell as what the built in templates are.

### Built In Templates

Basement comes with three built in templates:

* `default`: the default template (as you may have guessed) that is used when you don't specify a different one.* `app`: a template defining a skeleton project using `click` to make a simple program with a command line interface.* `flask`: a template defining a skeleton Flask website.

You specify which template to use with the `-t` flag.

```ment foo -t app```

The above example would use the `app` template to generate the `foo` project.

### DATA

Templates aren't terribly useful until you fill them up with fillerdata. Basement uses a [toml](https://github.com/toml-lang/toml) configurationfile to define this data. Create a file called `~/.basement` containingsomething like the following:

Notice all the `{{}}` things (mustaches)? These are mustache artifacts. When youcreate a project based on this template, those will be mapped to keys in yourconfiguration file and filled in with the data present there. If I render basedon my config file, I get this:

Sometimes you don't want to touch certain files, in particular binaryfiles. `pystache`, the library basement uses to render mustache templates, oftendoes not like being fed binary files and you most certainly don't want hugefiles to be read into memory to be rendered! For these situations, basementprovides a flexible mechanism for ignoring files. It works like so:

```pass = ['path/to/be/ignored/.*']```

`pass` can appear in your configuration and as each file is rendered, it ischecked against the regular expressions using Python's `re.search` function. Ifany of the patterns match that file path, it is ignored and simply passedthrough.

Note that you can also use the special file extension `.basement-ignore` aswell, as demonstrated in the next section.

## Creating Templates

Basement is designed so you can create your own templates really easily. All youhave to do is create a directory in `~/.basement-templates` where all templatesare stored and simply fill it with whatever files and content that you want,adding mustaches wherever you want to fill in data from your config.

One thing to note is that `project-name` is filled in with the basename of theoutput path you give basement. So if you run `ment path/to/project`, your`project-name` will be `project`.

### Special Files

While writing your template (particularly if you wanted to write one to beincluded with basement), you'd likely notice that upon compilation setuptoolstries to generate pyc files from your template py files and that'll likely causeerrors (mustache isn't valid Python syntax for some reason ;)). The way aroundthat is to add a special extension:

```foo.py.basement-template```

This will keep Python from compiling the file and basement will rename it whengenerating a project

Another important special extension is `.basement-ignore`, which tells basementto not try to render the contents of the file (though if mustaches appear in thefile name itself, those will be rendered). This is useful when you have filesthat contain `{{}}` mustaches but you don't want them to be rendered. Forexample, jinja templates.

### Template-Specific Configuration

You can add configuration specifically for certain templates and any keyspresent there that are also present at the top level override the top-levelkeys. You simply use toml sections like so:

Given this configuration, when you create a project based on the `app` template,`license` mustaches will be set to `EPL` rather than `MIT`. You can addconfiguration specific to your own templates by doing the same thing, simplyadding sections with the name of the templates.

## Updating Basement

When you decide to update your basement (perhaps you want to add a pool table),there are some updating mechanisms in place. When you run basement, it _always_wipes its templates and re-adds them. This means that you *cannot* make changesto the built in templates. If you want to make changes, you should make a newtemplate.