Why Angreal ?

Why use this tool?

Imagine you make a practice of writing lots of software packages either as an individual or as part of a team. Every time you have to create the directory and file structure, you probably do this by hand. You probably do it just a little differently each time, making small inconsistencies on each project. Now imagine you also have to work on multiple software packages and each one is set up a little differently, with slightly different way of doing basic tasks like running unit tests. You would spend at least some amount of resources : remembering the differences between each project or fixing little mistakes between them.

The whole point of angreal is to allow you to forget how to set up a project AND how to interact with it. By using templates for both project structure AND administration, you don't have to remember how to do a task - just that it can be done.

How do I use them ?

You interact with an angreal in two steps :

  1. Initialization : Initializing an angreal means rendering a described template into a usable form. Templates can exist in one of three locations : local directories, remote git repositories, or pypi modules. Where an angreal template is distributed from is decided by whomever made that particular template.
# initialize and render the template angreal at the remote URI
$: angreal init https://github.com/angreal/python.git
# If you've used this template before you simply need to ...
$: angreal init python
  1. Execution : Executing an angreal task through the angreal command line interface. This can only happen after the template has been rendered.
# From within an angreal based template
$: angreal <command to run>

A Quick Example

Let's say you're starting a new software project and plan on using python 3. You also want to make sure that you're following good practices and have documentation, testing, and type hinting as part of the project.

You identify that the python3 angreal fits your needs well and choose to use it.

  1. You initialize the project with :
$: angreal init https://github.com/angreal/python.git
  1. You provide values for template variables with the interactive CLI :
author_name? ["Your name"]
Dylan Storey
author_email? ["Your email address (eq. you@example.com)"]
dylan.storey@gmai.com
github_username? ["yourname"]
dylanbstorey
project_name? ["Name of the project (will be shown e.g. as the title in the readme)"]
Angreal Python Demo
project_slug? ["angreal-python-demo"] #enter accepts the provided devault value

package_name? ["angreal_python_demo"]

project_short_description? ["A short description of the project"]
A demo project
  1. Angreal creates a project for you, using your provided variables to fill in some of the blanks.
cd angreal-python-demo && tree
.
├── angreal_python_demo
│   ├── __init__.py
│   └── __main__.py
├── CHANGELOG.md
├── conftest.py
├── LICENCE
├── MANIFEST.in
├── pyproject.toml
├── README.md
├── setup.cfg
├── setup.py
└── tests
    ├── integration
    │   └── __init__.py
    └── unit
        └── __init__.py

4 directories, 12 files
  1. Next lets find out what tasks come with the template
$: angreal                                                                                                                                       ─╯
angreal 2.0.0-rc.1

USAGE:
    angreal [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help       Print help information
    -v, --verbose    verbose level, (may be used multiple times for more verbosity)
    -V, --version    Print version information

SUBCOMMANDS:
    build        build your project for distribution
    clean        cleans out generated cruft
    dev-setup    setup a development environment
    help         Print this message or the help of the given subcommand(s)
    init         Initialize an Angreal template from source.
    run-tests    run our test suite. default is unit tests only
  1. Now you do your thing and start developing on your software. At some point (hopefully early and often) you'll need to run unit tests.
$: angreal run-tests --open

================================================================ test session starts ================================================================platform linux -- Python 3.8.10, pytest-7.2.0, pluggy-1.0.0 -- /home/dstorey/.venvs/angreal-2/bin/python3
cachedir: .pytest_cache
rootdir: /home/dstorey/angreal-python-demo, configfile: setup.cfg
plugins: cov-4.0.0
collected 0 items
/home/dstorey/.venvs/angreal-2/lib/python3.8/site-packages/coverage/control.py:836: CoverageWarning: No data was collected. (no-data-collected)
  self._warn("No data was collected.", slug="no-data-collected")


---------- coverage: platform linux, python 3.8.10-final-0 -----------
Name                              Stmts   Miss  Cover
-----------------------------------------------------
angreal_python_demo/__init__.py       1      1     0%
angreal_python_demo/__main__.py       2      2     0%
-----------------------------------------------------
TOTAL                                 3      3     0%
Coverage HTML written to dir htmlcov

========
  1. Or maybe you just started developing on a new computer and want to make sure you're setup :
$: pip install angreal
$: git clone https://github.com/dylanbstorey/angreal-test-project
$: cd angreal-test-project
$: angreal dev-setup