python-tooling
python-tooling copied to clipboard
UCL-ARC
Python package template for new research software projects
UCL ARC Python Recommendations
This repository collects the UCL ARC recommendations for a research software
project in Python. It contains a template for new Python packages and a
website documenting our recommendations. We've turned on
discussions for this
repo, and we welcome questions there or in the #helpme channel on the
UCL research programming hub Slack.
🍪 Our template is a cookiecutter template which automatically creates new Python packages with our recommended tooling set up and ready to go.
Note If you're making a package within a community that has an existing package template (e.g.,
scikit-hep), we recommend using their template instead of this one.
Using this template
-
Install cookiecutter in a Conda or
venvenvironment (commented lines for Conda example).# conda create --channel conda-forge --name new-env-name # conda activate new-env-name # conda install pip pip install cookiecutter -
Run cookiecutter in the desired directory
cookiecutter gh:ucl-arc/python-toolingIf you have this repo locally (this may be the case if you are developing), you can run the following:
cookiecutter /path/to/your/checkout/of/python-tooling -
A series of questions will pop up to configure the project. Type the answer or hit return to use the default option (shown in square brackets).
Note that these project variables are defined in the
cookiecutter.jsonfile. -
This will create a specific directory structure.
For example, for a project with the following variables:
project_name [Python Template]: PROJECT_NAME project_slug [python-template]: PROJECT_SLUGwe will get a project folder named
PROJECT_SLUG, structured like this:PROJECT_SLUG ├── ... ├── README.md ├── pyproject.toml ├── src │ └── PROJECT_SLUG │ └── PROJECT_SLUG.py └── tests └── test_dummy.pyAnd the
PROJECT_NAMEwill appear in the README.md as the human-readable name of the project.cat PROJECT_SLUG/README.md # PROJECT_NAME ... -
To work on your project, initialise a git repository and install it in editable mode.
cd PROJECT_SLUG git init python -m pip install -e ".[dev]" -
Build your package
python -m build
Notes for developers
Click to expand...
First, clone repository
- (Optional) Generate your SSH keys as suggested here
- (Optional) GitHub CLI as suggested here
- Clone the repository by typing (or copying) the following line in a terminal at your selected path in your machine:
git clone [email protected]:UCL-ARC/python-tooling.git
cd python-tooling
Developing the cookiecutter template
-
To create and remove your virtual environment
conda create -n ptoolingVE pip -c conda-forge conda activate ptoolingVE conda deactivate ptoolingVE conda remove -n ptoolingVE --all -
To run template in the same path of this repo. We do a test cookiecut of a dummy package and install it to ensure the template setup works.
cookiecutter . cd python-template git init python -m pip install -e ".[dev]" -
To run cookiecutter using a specific branch of the template:
cookiecutter https://github.com/UCL-ARC/python-tooling --checkout <branch-name> -
To run the tests locally:
pytest -s
Developing the recommended tooling pages
Pages all live in the docs/pages sub-directory, and are written in markdown.
To build the webpage locally (for testing)
- Install jekyll
- Run
bundle installfrom thedocs/directory of this repository to install dependencies. - Run
bundle exec jekyll servefrom the root directory of this repository. This should fire up a local web server and tell you its address. By default the server will automatically refresh the HTML pages if any changes are made to the markdown sources.
See the jekyll docs for more info.
UCL-ARC