This project template codifies my best practices for python code organization, testing, documentation, and automation. It is meant to help new python projects get started quickly, letting the user focus on writing code.
These prerequisites for Copier are defined here.
- Python > 3.7
- Git > 2.27
- pipx (nice to have, conda and pip work too, but can be more difficult to reason about later)
Given that you have all the prerequisites satisfied, install Copier.
>> pipx install copier
Choose where you would like to create your new project and call copier with the template.
>> copier gh:myrontuttle/python-copier-template <path/to/destination>
After providing answers to the prompts, Copier will hydrate a project template and save it in the specified location. Additionally Copier will run git init in the new project directory to initialize it as a local repository and add the copied files to an initial commit on a 'main' branch.
At this point, your new project is hydrated and ready for you to start coding. But there's a lot more that this template has to offer.
- PDM setup, with pre-defined
pyproject.toml- Install dependencies
pdm add requests flask
You can add multiple dependencies in the same command. You can check the pdm.lock file to see what is locked for each package.
- Pre-configured tools for code formatting, quality analysis and testing:
- Makefile for convenience
- GitHub Actions (CI)
- Dependabot to check for dependency updates weekly
- Auto-approve-and-merge to approve and merge pr's raised by dependabot if all quality checks and tests pass
- Build to build and test your project
- Publish-to-pypi to publish library releases
Create a new repository in GitHub: (GitHub How-to)
>> git remote add origin https://github.com/<owner>/<remote_repository>
>> git push origin <local_branch_name>
Notice that when you create a PR in GitHub, a set of tests for Continuous Integration starts up to verify that the project can build successfully and that all the unit tests pass.
Notice that this template contains a .github/workflows directory with actions files. Any project created from this template that uses GitHub as a repository will automatically have CI enabled.
GitHub workflows are extremely useful, for more information, check out the About workflows page.
The GitHub workflow that runs when a new commit is pushed to a pull request, will automatically run unit tests and output code coverage into an xml file. To easily see if code coverage is changing as a result of new work, you should install the GitHub app, Codecov.
- Go to the Codecov app page - https://github.com/apps/codecov
- Click "Configure"
- Select your repository and follow the instructions
Future pull requests and commits will now include code coverage information.
If you have connected your GitHub account to ReadTheDocs you should be able to automatically import the documentation from your project. To connect your GitHub account to ReadTheDocs, simply sign in to ReadTheDocs using your GitHub account.
On your dashboard, you'll see an "Import a Project" button that will take you to a list of repositories that can be automatically imported. If you don't see the repository you expect, it is possible that you do not have sufficient permissions configured in your GitHub organization. Talk to an administrator of the organization, and let them know what you're trying to do.
A GitHub workflow is included that will automatically publish the packaged work to PyPI when a new release is created. To support this, you'll need to configure your repository.
- Create and verify an account on PyPI - https://pypi.org/account/register/
- Create a PyPI API token - https://pypi.org/help/#apitoken
- Save the API token in your new repository following these instructions. Save your secret API token with the name: PYPI_API_TOKEN
Now, when you create a new release from your repository, a workflow will run that will package and deploy the code to PyPI.
Once your project is under version control you'll be able to keep your project up to date by running copier update.
Copier will automatically check to see if a newer version of the original template is available and if so the changes will be automatically applied.
And of course, because your project is under version control, if you don't like the new changes, you can always revert back to the previous state. 😀
Add yourself as the assignee on an existing issue so that we know who's working on what. ( If you're not actively working on an issue, unassign yourself 😉 )
If there isn't an issue for the work you want to do, please create one and include a description - it's just polite.
It is preferable that you create a new branch with a name like issue/##/<short-description>. GitHub makes it pretty easy to associate branches and tickets, but it's nice when it's in the name.
The current best way to test the template is to clone this repository locally, and use Copier to generate a test project locally, then verify your expected results.
Copier will look for git tags to determine which version of the template to use. You probably don't want to create new tags while you're working on the template. Create a test project using the following command to let Copier know to use the latest local version.
>> copier --vcs-ref HEAD </local/path/to/template> </test/project/directory>
Notes:
- Any changes to the template will need to be committed (not pushed) to be picked up by Copier.
- If there's an opportunity for introducing an automated test, please take it.
- This project has some automated testing, to ensure that the template can hydrate a reasonable output project - feel free to extend that if it's reasonable.
- See the Copier documentation for more information.
Please use PR best practices, and get someone to review your code.
Once your PR is merged you should create a new release to make your changes available. GitHub's instructions for doing so are here. Use your best judgement when incrementing the version. i.e. is this a major, minor, or patch fix.
This project is based on copier-pdm and python-project-template.
This project is open sourced under MIT license, see the LICENSE file for more details.