Python Template is a Cookiecutter template for creating a python project. When used with Cookiecutter Python Template will create a fully working python "Hello world" project with unit tests, GitHub Actions, linting, PyPi distribution and sphinx documentation.
Authors: Tom Doel, Stephen Thompson, Matt Clarkson, Thomas Dowrick, Mian Ahmad, Miguel Xochicale
Python Template is part of the SciKit-Surgery software project, developed at the Wellcome EPSRC Centre for Interventional and Surgical Sciences, part of University College London (UCL).
Python Template was developed by the Wellcome EPSRC Centre for Interventional and Surgical Sciences, to assist researchers in the development of small but well engineered software components. It has been widely used in the development of SciKit-Surgery, but can be used as a starting point for any Python project. The template supports and encourages well engineered software by helping researchers with standard software development tasks (Software Process).
The table below lists standard development tasks and how the Python Template helps to deliver them. Paying heed to the following tasks at the earliest stage of development should support the creation of well defined, maintainable, well documented, and well tested code.
| Task | What the Python Template Does |
|---|---|
| Requirements generation | The template creates the file doc/requirements.rst and populates it with some minimum requirements for all SciKit-Surgery projects. Instructions and relevant links are provided to encourage the researcher to add more requirements to the file to describe what the project does, both before and during development. |
| Software design | The Python Template provides a modular framework that integrates with the wider python ecosystem. Providing a highly modular environment enables the researcher to focus on algorithm development, testing and publication, with minimal consideration of the wider software design. |
| Managing source code versions and updates | Source code versioning and updates is handled by git. The Python Template supports several git repository providers, |
| Configuring projects for specific platforms | The Python language is cross platform. The Python Template takes advantage of the pip package manager to create modular projects that can be easily installed on multiple platforms. |
| Compilation and linking | By using the python environment, the Python Template avoids the need for compilation and linking. |
| Testing the code at run time | The Python Platform uses tox to automate tests (pytest), coverage analysis and linting (pylint) comes ready with appropriate unit tests to meet the minimum requirements (see first item). If using GitHub to host the code, cross platform continuous integration testing is set up by default. It is up to the researcher to write further tests as the code is developed. |
| Verifying the validity of output | The validity of output is performed as part of the unit testing. |
| Documenting the code | The Python Template provides a template for code documentation showing how to write in line documentation. Documentation can be automatically built using ReadTheDocs |
| Tracking and repairing bugs | Issue tracking is handled by default by the chosen git repository host. |
Whilst every effort has been made to automate tasks where possible, it is up to the researcher consider software requirements, write documentation, and create unit tests. Templates for each of these tasks are provided, so after creating your project, please take a little time before you start coding to think about what you want your software to achieve, and write it down in the file doc/requirements.rst.
- Install Cookiecutter package and other requirements using virtual environments (VE) in conda or mambaforce by replacing conda with mamba.
conda create -n ssptVE pip -c conda-forge
conda activate ssptVE
python -m pip install -e ".[dev]"- Test template using tox and pytest
conda activate ssptVE
tox3. Run Cookiecutter with the URL of this template. Alternatively, you can run it in the same path of this repository if you are developing a new feature for this template.
cookiecutter https://github.com/SciKit-Surgery/PythonTemplate.git
cookiecutter .4. Answer the questions to configure your template (press enter to choose defaults), for further details on available answers. See "List of parameters for cookiecutter" below.
- Create a local git repository for your new project and commit the files.
cd MyNewProject
git init
python -m pip install -e ".[dev]"
git add .
git commit -m "Initial commit of My New Project"Note: make sure you use "git add ." not "git add * " to pick up hidden files like .gitlab-ci.yml.
- Create a new project on GitHub, making sure the URL matches what you set in step 3.
7. Add a remote in order to link your local repository to your GitHub repository and push the files across. NOTE: use the SSH form of the repository URL for SSH key authentication (so you don't have to enter a username and password).
git remote add origin [email protected]:GITHUB_USERNAME/MyNewProject.git
git push origin master8. If using GitHub, and assuming your URLs are all correct, GitHub Actions should automatically run tests for your project.
- You can verify your project has been set up correctly by installing and running tox.
cd MyNewProject
tox
tox -e lint
tox -e docs
cd ..tox runs several different stages, including pytest for unit tests and pylint for check for PEP8 linting. These can also be run independently:
python -m pytest
pylint --rcfile=tests/pylintrc mynewproject- Install your package in editable mode and build your package
python -m pip install -e .
python -m build10. Take a moment to write some software requirements, and populate the README file with a basic description of what you want to do, then start coding.
|
Name of the project as it will appear in the documentation (can have spaces) |
|
Project name as used in the URL; by default project_name with spaces removed |
|
The main python package name for your project. By default this is the project_slug converted into lower case. pkg_name should not contain dashes (-) |
|
The URL of the git server that will host your code. If you don't want to use any of the predefined options, choose any and modify the project_url later |
|
Your full name, for authorship information, and to suggest your profile name |
|
Your personal profile name on GitHub. Or you can enter a group name that will be used to construct the repository URL |
|
Choose whether you want your project under your personal profile path or in a shared location |
|
The full URL to your project will be constructed from the previous options, and is of the form repository_server/repository_path |
|
Recommend BSD-3 for internal projects, Apache for external collaborations |
|
If you are a member of UCL you should accept the default text |
- Run Cookiecutter with the URL of this template.
cookiecutter .
cd MyNewProject
pip install -r requirements-dev.txt
tox
tox -e lint
tox -e docs
python -m pytest
pylint --rcfile=tests/pylintrc mynewproject
python -m pip install -e .
python -m buildPlease see the contributing guidelines.
Copyright 2017 University College London. Python Template is released under the BSD-3 license. Please see the license file for details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent