Python project structure foundation or template, CLI console scripts.
Project description
|
|
|
|
This repository is meant to be used as a minimal, yet opinionated baseline for Python software projects. It includes:
Basic Python “distribution”/project metadata
Command-line console script with sub-command boilerplate
A Makefile for local development build, test and maintenance tasks
Docker container images for users and development
Targets/recipes in the Makefile to automate releases
Makefile recipes/targets used for both local development and on CI/CD platforms
A GitLab CI/CD pipeline integrating those CI/CD recipes/targets
A GitHub Actions workflow/pipeline integrating those CI/CD recipes/targets
The intended use is to add this repository as a VCS remote for your project. Thus developers can merge changes from this repository as we make changes related to Python project structure and tooling. As we add structure specific to certain types of projects (e.g. CLI scripts, web development, etc.), frameworks (e.g. Flask, Pyramid, Django, etc.), libraries and such, branches will be used for each such variation such that structure common to different variations can be merged back into the branches for those specific variations.
Template Usage
This is a rough guide to applying this project template to your project. This is not thoroughly tested as such tests would be so meta as to be extremely wasteful of developer time to create and maintain. So report any issues you have or better yet figure it out and submit a PR with corrections to this section.
Choose the right branch to use:
Is your project a CLI utility? A web application? Which project hosting provider and/or CI/CD platform will you use? Choose the appropriate branch for your project:
dist:
Basic Python distribution with build, tests, linters, code formatting and release publishing from local developer checkouts.
cli:
The above plus support for project’s that provide an executable CLI.
docker:
The dist branch plus Docker containers for both development and end-users/deployments.
ci:
The above plus GitLab CI/CD pipelines that run tests and linters as CI and publish releases from develop and master as CD.
ci-cli:
The above plus the cli branch.
etc.
Do not use the develop or master branches in your project as those branches are used to test the CI/CD automatic releases process and as such contain bumped versions, release notes, and other release artifacts that shouldn’t be merged into real projects.
Reconcile VCS history:
If starting a fresh project:
$ git clone --origin "template" --branch "ci-cli" \ "https://gitlab.com/rpatterson/python-project-structure.git" "./foo-project" $ cd "./foo-project" $ git config remote.template.tagOpt --no-tags $ git remote add "origin" "git@gitlab.com:foo-username/foo-project.git" $ git config remote.template.tagOpt --no-tags $ git switch -C "master" --track "origin/master"
If merging into an existing project:
$ git remote add "template" \ "https://gitlab.com/rpatterson/python-project-structure.git" $ git config remote.template.tagOpt --no-tags $ git merge --allow-unrelated-histories "template/ci-cli"
Rename file and directory paths derived from the project name:
$ git ls-files | grep -iE 'python.?project.?structure'
Rename strings derived from the project name and template author identity in project files:
$ git grep -iE 'python.?project.?structure|ross|Patterson'
Examine # TEMPLATE: comments and change as appropriate:
These are the bits that need the developer’s attention and reasoning to take the correct action. So read the comments and address them with care and attention:
$ git grep "TEMPLATE"
Finally, remove this section from this ./README.rst and update the rest of it’s content as appropriate for your project. As fixes and features are added to the upstream template, you can merge them into your project and repeat steps 3-5 above as needed.
Installation
Install using any tool for installing standard Python 3 distributions such as pip:
$ sudo pip3 install python-project-structure
Optional shell tab completion is available via argcomplete.
Or use the Docker image. See the example ./docker-compose.yml file for usage details.
Optional shell tab completion is available via argcomplete.
Usage
See the command-line help for details on options and arguments:
$ usage: python-project-structure [-h] Python project structure foundation or template, top-level package. optional arguments: -h, --help show this help message and exit
CONTRIBUTING
NOTE: This project is hosted on GitLab. There’s a mirror on GitHub but please use GitLab for reporting issues, submitting PRs/MRs and any other development or maintenance activity.
See the ./CONTRIBUTING.rst file for more details on how to get started with development.
Motivation
There are many other Python project templates so why make another? I’ve been doing Python development since 1998, so I’ve had plenty of time to develop plenty of opinions of my own.
What I want in a template is complete tooling (e.g. test coverage, linting, formatting, CI/CD, etc.) but minimal dependencies, structure, and opinion beyond complete tooling (e.g. some non-Python build/task system, structure for frameworks/libraries not necessarily being used, etc.). I couldn’t find a template that manages that balance so here we are.
I also find it hard to discern from other templates why they made what choices the did. As such, I also use this template as a way to try out various different options in the Python development world and evaluate them for myself. You can learn about my findings and the reasons the choices I’ve made in the commit history.
Most importantly, however, I’ve never found a satisfactory approach to keeping project structure up to date over time. So the primary motivation is to use this repository as a remote from which we can merge structure updates over the life of projects using the template.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python-project-structure-0.8.16.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1b45176249429e6e0ecced4687d60cbd7a2ac05a65784cabe1addd172a79b713 |
|
| MD5 | f7c8ff430e7cd83b1afefcf0c25df7b8 |
|
| BLAKE2b-256 | 81f47c3cdd74522ceba2e39792483724c22b87174b99eca14c0607786c8d5788 |
Hashes for python_project_structure-0.8.16-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | aa0c56d1d50e5e5b018d7d2224fa7f2d89e35eb47fab6a4d26666a5726f8a9f3 |
|
| MD5 | ac20c29e1652b9d8a1bb46c88bfcca0e |
|
| BLAKE2b-256 | cb588747de6d2feebf85156e4b0e09550bccfa9b9bcb76414453754cdcbf1991 |
