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.
You interact with an angreal in two steps :
# 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
angreal
command line interface. This can only happen after the template has
been rendered.# From within an angreal based template
$: angreal <command to run>
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.
$: angreal init https://github.com/angreal/python.git
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
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
$: 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
$: 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
========
$: pip install angreal
$: git clone https://github.com/dylanbstorey/angreal-test-project
$: cd angreal-test-project
$: angreal dev-setup