To contribute to the cookiecutter-shell-package
template,
you’ll need:
-
The Python version manager
pyenv
. -
The Python dependency manager
poetry
. -
The JavaScript version manager
nvm
. -
The JavaScript package manager
yarn
.
You’ll need the Python version manager pyenv
.
While pyenv
doesn’t support Windows, you can use a drop-in
replacement called pyenv-win
.
To install pyenv-win
on Windows, go to
github.com/pyenv-win/pyenv-win
and follow one of the installation methods.
To install pyenv
on Linux or WSL2, first make sure Python 3 is
installed. Then follow the Basic GitHub Checkout method described
at github.com/pyenv/pyenv.
To install pyenv
on macOS, run:
brew install pyenv
To verify pyenv
is working, run:
pyenv --version
You’ll need poetry
to manage development dependencies and the venv.
To install Poetry on Windows, use one of the installation methods described in Poetry’s documentation.
If you’re on Linux or WSL2, use your system package manager to install Poetry.
Alternatively, use one of the installation methods described in Poetry’s documentation.
To install Poetry on macOS, run:
brew install poetry
To verify Poetry is working, run:
poetry --version
Cookiecutter is already included as a development dependency, so Poetry will take care of installing it for you. You don’t need to have it installed as a stand-alone tool, but you may still want to do so for your convenience.
To install Cookiecutter as a stand-alone tool, follow Cookiecutter’s installation instructions.
To set up your virtual environment, follow these steps:
-
Go to the project root directory.
-
Run
pyenv install -s
. -
Run
pyenv exec pip install poetry
. -
Run
pyenv exec poetry install
.
You need to do the above steps only once.
To update your dependencies after a git pull
, run poetry install
.
To see a list of available tasks, run: poetry run poe tasks
To execute the end-to-end test, run: poetry run poe e2e
Q: Why is pyenv
required even though Cookiecutter accepts any
Python version?
A: Especially because Cookiecutter accepts any Python version, you’ll want your code to work equally well on all of those supported Pythons. We achieve that by pinning the minimum Python version that Cookiecutter supports as our development dependency.
Q: Do I have to add pyenv
shims to my PATH?
A: No, because this guide doesn’t use pyenv’s shims. It’s still ok to have them in your PATH if you prefer so.
Q: Do I have to add the poetry
binary to my PATH?
A: You’ll need to have add the poetry
binary to your PATH if the
installation method you’ve chosen says so.
Q: Why install Poetry with pyenv even though I already have a stand-alone Poetry install?
A: I couldn’t find any convenient, platform-independent, and
easy-to-document method to convince Poetry to set up a venv that
uses the exact Python version we want.
Workarounds such as poetry env use $(pyenv which python)
(source) are platform-specific and thus
more cumbersome to document.
Q: Why is Cookiecutter a development dependency even though I already have a stand-alone Cookiecutter install?
A: This is so your IDE gets to know Cookiecutter’s modules at development time.