README.md
# Tyrannosaurus
[](https://pypi.org/project/tyrannosaurus)
[](https://pypi.org/project/tyrannosaurus)
[](https://github.com/dmyersturnbull/tyrannosaurus/releases)
[](https://hub.docker.com/repository/docker/dmyersturnbull/tyrannosaurus)
[](https://anaconda.org/conda-forge/tyrannosaurus)\
[](https://github.com/dmyersturnbull/tyrannosaurus/actions)
[](https://tyrannosaurus.readthedocs.io/en/stable/)
[](https://coveralls.io/github/dmyersturnbull/tyrannosaurus?branch=main)
[](https://codecov.io/gh/dmyersturnbull/tyrannosaurus)\
[](https://codeclimate.com/github/dmyersturnbull/tyrannosaurus/maintainability)
[](https://scrutinizer-ci.com/g/dmyersturnbull/tyrannosaurus/?branch=main)
[](https://www.codefactor.io/repository/github/dmyersturnbull/tyrannosaurus)
[](https://opensource.org/licenses/Apache-2.0)
[](https://doi.org/10.5281/zenodo.4485186)
[](https://github.com/dmyersturnbull/tyrannosaurus)
An opinionated, forwards-looking Python template for 2021+.
Generate elegant, ready-to-use Python
projects that have excellent continuous integration and deployment (CI/CD). Integrated with
Docker Hub, the GitHub Container Registry, Azure, Conda-Forge, and an array of linting, static analysis,
security testing, documentation, dependency management, and CI/CD tools, including an optional
custom tool to keep all duplicate project metadata synchronized to pyproject.toml.
### 🎨 Design / generating a new project
This is a modern template built with [Poetry](https://python-poetry.org/),
[GitHub Actions](https://github.com/features/actions), and
[no legacy files](https://dmyersturnbull.github.io/#-the-python-build-landscape) or tools.
See below for a [comparison to other tools](https://github.com/dmyersturnbull/tyrannosaurus#-similar-templates-and-tools).
Also see Tyrannosaurus’s little sister
[science-notebook-template 🧪](https://github.com/dmyersturnbull/science-notebook-template)
for scientific publication repos.
Don’t make 55 commits trying to configure CI/CD workflows.
After creating an empty GitHub repo called `myproject`:
```bash
pip install tyrannosaurus
tyrannosaurus new myproject --track
# if on a GitHub organization, pass --user my-org-name
```
After initializing your project, Tyrannosaurus will list manual steps like adding API keys.
Just delete files you don’t want. Or pass `--extras` to include extra files like
azure-pipelines config and `codemeta.json`.
### 💡 Main behavior / features
Generated projects are integrated with various tools (from PyPi) and external CI/CD/code-quality systems.
GitHub Actions are used by default, but config files for Travis and Azure Pipelines are also provided.
You can swap out, modify, or disable anything as you see fit.
**[See the docs 📚](https://tyrannosaurus.readthedocs.io/en/stable/)** for more information.
Here’s how your new project will behave when first set up:
- **Commit** ⇒ Files are linted and verified for integrity
- **Make a pull request** ⇒ Code is built and tested
- **Push to the main branch** ⇒ Code is built and tested; code quality, coverage, and security badges are updated
- **Make a GitHub release** ⇒ Artifacts are sent to GitHub, PyPi, Docker Hub, the GCR, and readthedocs
- `tox` ⇒ Tests are run locally
- `tyrannosaurus sync` ⇒ Project metadata is synced to pyproject.toml
- `tyrannosaurus update` ⇒ New dependency versions from PyPi and/or Conda are listed
- `tyrannosaurus [--aggressive] clean` ⇒ Remove temp files
### 🎁 Full features / integrations
<details>
- Packaging and dependency management with [Poetry](https://python-poetry.org/)
- Python 3.6 thru 3.11
- Only modern files: _no_ manifest file, setup.py, requirements.txt, setup.cfg, or eggs
- Continuous integration with [GitHub Actions](https://github.com/features/actions),
[Travis](https://www.travis-ci.com/), or
[Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/)
- Docker and Vagrant configuration
- Continuous deployment to [PyPi](http://pypi.org/) and [Docker Hub](https://hub.docker.com/).
- Deployment to the [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry);
plus to any other desired container registries with a simple modification.
- Automatic attachment of [sdits](https://docs.python.org/3/distutils/sourcedist.html)
and [wheels](https://pythonwheels.com/) to
[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
- Good default GitHub settings, synchronized via [Probot settings](https://github.com/probot/settings)
- Documentation sent to [readthedocs](https://readthedocs.org/)
- Nice documentation defaults with
[Sphinx extensions](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)
- Test automation with [Tox](https://tox.readthedocs.io)
- Commit linting and changelog generation with [Commitizen](https://github.com/commitizen-tools/commitizen)
- [Shields](https://github.com/badges/shields) with
[Coveralls](https://coveralls.io/),
[codecov](https://about.codecov.io/),
[CodeClimate](https://codeclimate.com/),
and [Scrutinizer](https://scrutinizer-ci.com/)
that reflect the main branch
- Code linting with [pre-commit](https://pre-commit.com/), [Black](https://pypi.org/project/black/),
[Prettifier](https://prettier.io/), [Dockerfile-lint](https://github.com/Lucas-C/pre-commit-hooks-nodejs),
and [markdown-lint-check](https://github.com/gaurav-nelson/github-action-markdown-link-check)
- Security analysis with [Bandit](https://github.com/PyCQA/bandit),
[CodeQL](https://github.com/github/codeql-action),
and [safety](https://github.com/pyupio/safety) †
- Static type analysis with [mypy](https://mypy.readthedocs.io)
- [Conda-Forge](https://conda-forge.org/) [recipes](https://conda-forge.org/docs/maintainer/adding_pkgs.html#the-recipe-meta-yaml)
and [environment YML](https://medium.com/@balance1150/how-to-build-a-conda-environment-through-a-yaml-file-db185acf5d22)
with [Grayskull](https://github.com/conda-incubator/grayskull)
and [Tyrannosaurus](https://tyrannosaurus.readthedocs.io/)
- IDE hints via [EditorConfig](https://editorconfig.org/) with good defaults for most languages
- Fancy [issue labels](https://github.com/crazy-max/ghaction-github-labeler)
- Fancy GitHub-recognized readme, license,
[contributing guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors),
[issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates), and
[pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates)
- Nice gitignore, dockerignore, [ChangeLog](https://keepachangelog.com), and other misc files
- [CodeMeta](https://codemeta.github.io/user-guide/) and [CITATION.cff](https://citation-file-format.github.io/)
- Dependency updating with [Dependabot](https://dependabot.com/)
- `tyrannosaurus clean` to clean temp files
- `tyrannosaurus update` that lists dependency versions to bump
- `tyrannosaurus sync` to synchronize project metadata to pyproject.toml ‡
† [Temporary issue in safety](https://github.com/pyupio/safety/issues/201)
‡ This feature is experimental and does not yet support
all [intended sync targets](https://github.com/dmyersturnbull/tyrannosaurus/issues/12).
</details>
### ✏️ Syncing to pyproject.toml
<details>
_Note: This feature is only partly complete._
Tyrannosaurus has an optional `sync` command that synchronizes metadata from `pyproject.toml` to other files,
so that **all of your metadata is in pyproject.toml**.
There are 16 available target files, including `docs/conf.py`, `tox.ini`, `.pre-commit-config.yaml`, `readthedocs.yml`,
`.travis.yml`, and `__init__.py`.
Settings like dev dependencies, project version, license headers, and preferred line length can be listed exactly once,
in pyproject.toml.
Tyrannosaurus itself can be included as a dependency (but is not by default).
Running `tyrannosaurus build` will run poetry lock, synchronize project metadata (via `sync`), build, run tests,
install, and clean up.
Target files can be disabled in `[tool.tyrannosaurus.targets]`.
</details>
### 🔨 Building your project locally
<details>
You can test your project locally. Install [Poetry](https://github.com/python-poetry/poetry)
and [Tox](https://tox.readthedocs.io/en/latest/) (`pip install tox`).
Then just type `tox` to build artifacts and run tests.
You can install locally with `poetry install .` or just `pip install .`.
To create an initial Anaconda recipe or environment file, run `tyrannosaurus recipe` or `tyrannosaurus env`.
After that, you can use `sync` to keep them up-to-date with pyproject.toml.
</details>
### 🎯 Similar templates and tools
There are various other templates based on [cookiecutter](https://github.com/cookiecutter/cookiecutter)
and [copier](https://github.com/copier-org/copier). See which best suits your needs and style.
I designed Tyrannosaurus to solve issues with existing tools.
Here are features that other tools lack:
- An **elegant CI/CD workflow**: The workflow gets kicked off only via `git push` and GitHub releases.
- **Interoperability with Conda**, including recipes and environment files, by mapping dependencies and metadata.
- **Automated publishing** to PyPi, Conda-Forge, Docker Hub, the GitHub Container Registry, and readthedocs.
- **No duplication** between project files. (Not 100%: some duplication remains.)
- Built-in optional support for **extra/alternative tools**, such as Travis and codemeta.
- Complete **absence of legacy tools**, files, and Python 2 support.
### 🏁 Feature table
| Tool | Main techs | CD kickoff | N int.† | modern‡ | Docker | Conda | sync | any-OS |
| ---------------------------------------------------------------------------------------- | -------------------------- | -------------- | ------- | ------- | ------ | ----- | ---- | ------ |
| Tyranosaurus | Actions, Poetry, Tox | git, GitHub | 30 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| [hypermodern-python](https://github.com/cjolowicz/cookiecutter-hypermodern-python) | Actions, Poetry, Nox | git, Poetry | 20 | ✔️ | | | | ✔️ |
| [copier-poetry](https://github.com/pawamoy/copier-poetry) | Actions, Poetry, Make | git, manual | 15 | | ✔️ | | ✔️ | |
| [python-package-template](https://github.com/TezRomacH/python-package-template) | Actions, Poetry, Tox, Make | git, Make | 20 | ✔️ | ✔️ | | | |
| [pyscaffold](https://github.com/pyscaffold/pyscaffold) | setuptools, Tox | Gitlab, manual | 10 | | | | | ✔️ |
| [wemake-python-package](https://github.com/wemake-services/wemake-python-package) | Actions, Poetry, Make | git, Poetry | 10 | ✔️ | | | | |
| [best-practices](https://github.com/sourcery-ai/python-best-practices-cookiecutter) | Actions, pipenv | git, pipenv | 10 | | ✔️ | | | ✔️ |
| [python-blueprint](https://github.com/johnthagen/python-blueprint) | Actions, setuptools, Tox | git, manual | 5 | | ✔️ | | | ✔️ |
| [cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) | Travis, setuptools, Tox | git, manual | 10 | | | | | |
| [cookiecutter-pylibrary](https://github.com/ionelmc/cookiecutter-pylibrary) | Travis, setuptools, Tox | git, manual | 20 | | | | | ✔ |
| [cookiecutter-django](https://github.com/pydanny/cookiecutter-django) | Actions, setuptools, Tox | git, manual | 15 | | ✔️ | | | ✔️ |
| [django-init](https://github.com/Fueled/django-init) | Actions, setuptools, Make | git, manual | 15 | | ✔️ | | | ✔️ |
| [docker-science](https://github.com/docker-science/cookiecutter-docker-science) | Make, Docker, setuptools | no CI/CD | 15 | | ✔️ | | | |
| [science-notebook-template](https://github.com/dmyersturnbull/science-notebook-template) | Conda | no CI/CD | 5 | | ✔️ | | | ✔️ |
**Notes:**
<details>
**† _N int._**: Approximate number of built-in integrations with tools and standards. What counts is very roughly defined.
**‡ _Modern_**: Lacks legacy files and tools. I’m including Make, setuptools, pipenv, and some others.
**Note:** [copier](https://github.com/copier-org/copier) syncs with a remote template. It’s a neat idea that Tyrannosaurus lacks.
Some of the packages in the table above need more explanation:
- [hypermodern-python](https://github.com/cjolowicz/hypermodern-python)
([template](https://github.com/cjolowicz/cookiecutter-hypermodern-python)), a Poetry-powered Python
template. It’s good, but it made a few unusual choices, such as [Nox](https://github.com/theacodes/nox), which has <500 GitHub stars.
- Both [cookiecutter-django](https://github.com/pydanny/cookiecutter-django) and
[django-init](https://github.com/Fueled/django-init) have fantastic setups for Django projects.
- [Cookiecutter-docker-science](https://github.com/docker-science/cookiecutter-docker-science) is an interesting project
that doesn’t quite fit in this list.
</details>
### ✨ Projects made with Tyrannosaurus
<details>
These are some example projects that were generated with Tyrannosaurus:
- [Tyrannosaurus](https://github.com/dmyersturnbull/tyrannosaurus)
- [Mandos](https://github.com/dmyersturnbull/mandos)
- [typed-dfs](https://github.com/dmyersturnbull/typed-dfs)
- [Valarpy](https://github.com/dmyersturnbull/valarpy)
- [Sauronlab](https://github.com/dmyersturnbull/sauronlab)
- [SauronX](https://github.com/dmyersturnbull/sauronx)
- [suretime](https://github.com/dmyersturnbull/suretime)
- [service-it](https://github.com/dmyersturnbull/service-it)
- [chemserve](https://github.com/dmyersturnbull/chemserve)
- [pocketutils](https://github.com/dmyersturnbull/pocketutils)
- [auth_capture_proxy](https://github.com/alandtse/auth_capture_proxy)
</details>
### 🍁 Contributing
[New issues](https://github.com/dmyersturnbull/tyrannosaurus/issues) and pull requests are welcome.
Please refer to the [contributing guide](https://github.com/dmyersturnbull/tyrannosaurus/blob/master/CONTRIBUTING.md)
and [security policy](https://github.com/dmyersturnbull/tyrannosaurus/blob/main/SECURITY.md).
Generated with tyrannosaurus: `tyrannosaurus new tyrannosaurus`
```text
.++++++++++++.
.++HHHHHHH^^HHH+.
.HHHHHHHHHH++-+-++.
.HHHHHHHHHHH:t~~~~~
.+HHHHHHHHHHjjjjjjjj.
.+NNNNNNNNN/++/:--..
........+NNNNNNNNNN.
.++++BBBBBBBBBBBBBBB.
.tttttttt:.. .++BBBBBBBBBBBBBBBBBBB.
+tt+. `` .+BBBBBBBBBBBBBBBBBBBBB+++cccc.
ttt. .-++BBBBBBBBBBBBBBBBBBBBBB++.ccc.
+ttt++++:::::++++++BBBBBBBBBBBBBBBBBBBBBBB+..++.
.+TTTTTTTTTTTTTBBBBBBBBBBBBBBBBBBBBBBBBB+. .ccc.
.++TTTTTTTTTTBBBBBBBBBBBBBBBBBBBBBBBB+. .cc.
..:++++++++++++++++++BBBBBB++++BBBB.
....... -LLLLL+. -LLLLL.
-LLLL+. -LLLL+.
+LLL+ +LLL+
+LL+ +ff+
+ff++ +++:
++++:
```