########################################################################################
python-project-structure
########################################################################################
Python project structure foundation or template
****************************************************************************************
.. list-table::
:class: borderless align-right
* - .. figure:: https://img.shields.io/pypi/v/python-project-structure.svg?logo=pypi&label=PyPI&logoColor=gold
:alt: PyPI latest release version
:target: https://pypi.org/project/python-project-structure/
.. figure:: https://img.shields.io/pypi/dm/python-project-structure.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold
:alt: PyPI downloads per month
:target: https://pypi.org/project/python-project-structure/
.. figure:: https://img.shields.io/pypi/pyversions/python-project-structure.svg?logo=python&label=Python&logoColor=gold
:alt: PyPI Python versions
:target: https://pypi.org/project/python-project-structure/
.. figure:: https://img.shields.io/badge/code%20style-black-000000.svg
:alt: Python code style
:target: https://github.com/psf/black
- .. figure:: https://gitlab.com/rpatterson/python-project-structure/-/badges/release.svg
:alt: GitLab latest release
:target: https://gitlab.com/rpatterson/python-project-structure/-/releases
.. figure:: https://gitlab.com/rpatterson/python-project-structure/badges/main/pipeline.svg
:alt: GitLab CI/CD pipeline status
:target: https://gitlab.com/rpatterson/python-project-structure/-/commits/main
.. figure:: https://gitlab.com/rpatterson/python-project-structure/badges/main/coverage.svg
:alt: GitLab coverage report
:target: https://gitlab.com/rpatterson/python-project-structure/-/commits/main
.. figure:: https://img.shields.io/gitlab/stars/rpatterson/python-project-structure?gitlab_url=https%3A%2F%2Fgitlab.com&logo=gitlab
:alt: GitLab repo stars
:target: https://gitlab.com/rpatterson/python-project-structure
- .. figure:: https://img.shields.io/github/v/release/rpatterson/python-project-structure?logo=github
:alt: GitHub release (latest SemVer)
:target: https://github.com/rpatterson/python-project-structure/releases
.. figure:: https://github.com/rpatterson/python-project-structure/actions/workflows/build-test.yml/badge.svg
:alt: GitHub Actions status
:target: https://github.com/rpatterson/python-project-structure/actions/workflows/build-test.yml
.. figure:: https://codecov.io/github/rpatterson/python-project-structure/branch/main/graph/badge.svg?token=GNKVQ8VYOU
:alt: Codecov test coverage
:target: https://app.codecov.io/github/rpatterson/python-project-structure
.. figure:: https://img.shields.io/github/stars/rpatterson/python-project-structure?logo=github
:alt: GitHub repo stars
:target: https://github.com/rpatterson/python-project-structure/
- .. figure:: https://img.shields.io/docker/v/merpatterson/python-project-structure/main?sort=semver&logo=docker
:alt: Docker Hub image version (latest semver)
:target: https://hub.docker.com/r/merpatterson/python-project-structure
.. figure:: https://img.shields.io/docker/pulls/merpatterson/python-project-structure?logo=docker
:alt: Docker Hub image pulls count
:target: https://hub.docker.com/r/merpatterson/python-project-structure
.. figure:: https://img.shields.io/docker/stars/merpatterson/python-project-structure?logo=docker
:alt: Docker Hub stars
:target: https://hub.docker.com/r/merpatterson/python-project-structure
.. figure:: https://img.shields.io/docker/image-size/merpatterson/python-project-structure?logo=docker
:alt: Docker Hub image size (latest semver)
:target: https://hub.docker.com/r/merpatterson/python-project-structure
- .. figure:: https://img.shields.io/keybase/pgp/rpatterson?logo=keybase
:alt: KeyBase PGP key ID
:target: https://keybase.io/rpatterson
.. figure:: https://img.shields.io/github/followers/rpatterson?style=social
:alt: GitHub followers count
:target: https://github.com/rpatterson
.. figure:: https://img.shields.io/liberapay/receives/rpatterson.svg?logo=liberapay
:alt: LiberaPay donated per week
:target: https://liberapay.com/rpatterson/donate
.. figure:: https://img.shields.io/liberapay/patrons/rpatterson.svg?logo=liberapay
:alt: LiberaPay patrons count
:target: https://liberapay.com/rpatterson/donate
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
- `Docker`_ container images for users and development in which tests are run
- A `Makefile`_ target to format all Python code, including using `Black`_ for style
- A `kitchen sink linter configuration`_ for `Prospector`_ that runs all available
Python code checks
- A `tox.ini`_ configuration for `Tox`_ to run all tests and linters in multiple Python
versions, including some checks not provided by Prospector.
- `VCS hooks`_ to enforce `conventional commits`_ and successful build and test on
commit and push, and release notes on push
- Targets/recipes in the `Makefile`_ to automate releases controlled by `conventional
commits`_ and end-user oriented release notes by `Towncrier`_
- Targets/recipes in the `Makefile`_ to automate upgrading requirements and dependencies
- `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.
.. contents:: Table of Contents
****************************************************************************************
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 ``main`` as CD.
- ``ci-cli``:
The above plus the ``cli`` branch.
- etc.
Do not use the ``develop`` or ``main`` 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 "main" --track "origin/main"
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.
This template publishes pre-releases on all pushes to the ``develop`` branch and final
releases on all pushes to the ``main`` branch. Project owners may decide which types
of changes should go through pre-release before final release and which types of changes
should go straight to final release. For example they may decide that:
- Contributions from those who are not maintainers or owners should be merged into
``develop``. See `the ./CONTRIBUTING.rst file`_ for such an example public
contributions policy and workflow.
- Fixes for bugs in final releases may be committed to a branch off of ``main`` and,
after passing all tests and checks, merged back into ``main`` to publish final
releases immediately.
- Routine version upgrades for security updates may also be merged to ``main`` as
above for bug fixes.
****************************************************************************************
Installation
****************************************************************************************
Install and use either via a local, native installation or a Docker container image:
Local/Native Installation
========================================================================================
Install using any tool for installing standard Python 3 distributions such as `pip`_::
$ pip3 install --user python-project-structure
Optional shell tab completion is available via `argcomplete`_.
Docker Container Image Installation
========================================================================================
The recommended way to use the Docker container image is via `Docker Compose`_. See
`the example ./docker-compose.yml file`_ for an example configuration. Once you have
your configuration, you can create and run the container::
$ docker compose up
Alternatively, you make use the image directly. Pull `the Docker image`_::
$ docker pull "registry.gitlab.org/rpatterson/python-project-structure"
And then use the image to create and run a container::
$ docker run --rm -it "registry.gitlab.org/rpatterson/python-project-structure" ...
Images variant tags are published for the Python version, branch, and major/minor
versions so that users can control when they get new images over time,
e.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310-main``. The
canonical Python version is 3.10 which is the version used in tags without ``py###``,
e.g. ``registry.gitlab.org/merpatterson/python-project-structure:main``. Pre-releases
are from ``develop`` and final releases are from ``main`` which is also the default for
tags without a branch,
e.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310``. The
major/minor version tags are only applied to the final release images and without the
corresponding ``main`` branch tag,
e.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310-v0.8``.
Multi-platform Docker images are published containing images for the following
platforms or architectures in the Python 3.10 ``py310`` variant:
- ``linux/amd64``
- ``linux/arm64``
- ``linux/arm/v7``
****************************************************************************************
Usage
****************************************************************************************
See the command-line help for details on options and arguments::
$ python-project-structure --help
usage: python-project-structure [-h]
Python project structure foundation or template, top-level package.
optional arguments:
-h, --help show this help message and exit
If using the Docker container image, the container can be run from the command-line as
well::
$ docker compose run "python-project-structure" python-project-structure --help
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.
.. _Python: https://docs.python.org/3/library/logging.html
.. _Python "distribution"/project: https://docs.python.org/3/distributing/index.html
.. _pip: https://pip.pypa.io/en/stable/installation/
.. _`Black`: https://github.com/psf/black
.. _`Prospector`: https://prospector.landscape.io
.. _`Tox`: https://tox.wiki
.. _`Towncrier`: https://towncrier.readthedocs.io
.. _argcomplete: https://kislyuk.github.io/argcomplete/#installation
.. _`conventional commits`: https://www.conventionalcommits.org
.. _`This project is hosted on GitLab`:
https://gitlab.com/rpatterson/python-project-structure
.. _`a mirror on GitHub`:
https://github.com/rpatterson/python-project-structure
.. _`Docker`: https://docs.docker.com/
.. _`Docker Compose`: https://docs.docker.com/compose/
.. _the Docker image: https://hub.docker.com/r/merpatterson/python-project-structure
.. _`GitLab CI/CD`: https://docs.gitlab.com/ee/ci/
.. _`GitHub Actions`: https://docs.github.com/en/actions
.. _Makefile:
https://gitlab.com/rpatterson/python-project-structure/blob/main/Makefile
.. _`the example ./docker-compose.yml file`:
https://gitlab.com/rpatterson/python-project-structure/blob/main/docker-compose.yml
.. _`the ./CONTRIBUTING.rst file`:
https://gitlab.com/rpatterson/python-project-structure/blob/main/CONTRIBUTING.rst
.. _`kitchen sink linter configuration`:
https://gitlab.com/rpatterson/python-project-structure/blob/main/.prospector.yaml
.. _`tox.ini`:
https://gitlab.com/rpatterson/python-project-structure/blob/main/tox.ini
.. _`VCS hooks`:
https://gitlab.com/rpatterson/python-project-structure/blob/main/.pre-commit-config.yaml
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/rpatterson/python-project-structure",
"name": "python-project-structure",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "template,structure",
"author": "Ross Patterson",
"author_email": "me@rpatterson.net",
"download_url": "https://files.pythonhosted.org/packages/d4/6c/6e23710cee425419acc56797a70c2bd0c1af2488af6ad7c1381aa9c31e57/python-project-structure-0.8.25.tar.gz",
"platform": null,
"description": "########################################################################################\npython-project-structure\n########################################################################################\nPython project structure foundation or template\n****************************************************************************************\n\n.. list-table::\n :class: borderless align-right\n\n * - .. figure:: https://img.shields.io/pypi/v/python-project-structure.svg?logo=pypi&label=PyPI&logoColor=gold\n :alt: PyPI latest release version\n :target: https://pypi.org/project/python-project-structure/\n .. figure:: https://img.shields.io/pypi/dm/python-project-structure.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold\n :alt: PyPI downloads per month\n :target: https://pypi.org/project/python-project-structure/\n .. figure:: https://img.shields.io/pypi/pyversions/python-project-structure.svg?logo=python&label=Python&logoColor=gold\n :alt: PyPI Python versions\n :target: https://pypi.org/project/python-project-structure/\n .. figure:: https://img.shields.io/badge/code%20style-black-000000.svg\n :alt: Python code style\n :target: https://github.com/psf/black\n\n - .. figure:: https://gitlab.com/rpatterson/python-project-structure/-/badges/release.svg\n\t :alt: GitLab latest release\n\t :target: https://gitlab.com/rpatterson/python-project-structure/-/releases\n .. figure:: https://gitlab.com/rpatterson/python-project-structure/badges/main/pipeline.svg\n :alt: GitLab CI/CD pipeline status\n :target: https://gitlab.com/rpatterson/python-project-structure/-/commits/main\n .. figure:: https://gitlab.com/rpatterson/python-project-structure/badges/main/coverage.svg\n :alt: GitLab coverage report\n\t :target: https://gitlab.com/rpatterson/python-project-structure/-/commits/main\n .. figure:: https://img.shields.io/gitlab/stars/rpatterson/python-project-structure?gitlab_url=https%3A%2F%2Fgitlab.com&logo=gitlab\n\t :alt: GitLab repo stars\n\t :target: https://gitlab.com/rpatterson/python-project-structure\n\n - .. figure:: https://img.shields.io/github/v/release/rpatterson/python-project-structure?logo=github\n\t :alt: GitHub release (latest SemVer)\n\t :target: https://github.com/rpatterson/python-project-structure/releases\n .. figure:: https://github.com/rpatterson/python-project-structure/actions/workflows/build-test.yml/badge.svg\n :alt: GitHub Actions status\n :target: https://github.com/rpatterson/python-project-structure/actions/workflows/build-test.yml\n .. figure:: https://codecov.io/github/rpatterson/python-project-structure/branch/main/graph/badge.svg?token=GNKVQ8VYOU\n :alt: Codecov test coverage\n\t :target: https://app.codecov.io/github/rpatterson/python-project-structure\n .. figure:: https://img.shields.io/github/stars/rpatterson/python-project-structure?logo=github\n\t :alt: GitHub repo stars\n\t :target: https://github.com/rpatterson/python-project-structure/\n\n - .. figure:: https://img.shields.io/docker/v/merpatterson/python-project-structure/main?sort=semver&logo=docker\n :alt: Docker Hub image version (latest semver)\n :target: https://hub.docker.com/r/merpatterson/python-project-structure\n .. figure:: https://img.shields.io/docker/pulls/merpatterson/python-project-structure?logo=docker\n :alt: Docker Hub image pulls count\n :target: https://hub.docker.com/r/merpatterson/python-project-structure\n .. figure:: https://img.shields.io/docker/stars/merpatterson/python-project-structure?logo=docker\n\t :alt: Docker Hub stars\n :target: https://hub.docker.com/r/merpatterson/python-project-structure\n .. figure:: https://img.shields.io/docker/image-size/merpatterson/python-project-structure?logo=docker\n\t :alt: Docker Hub image size (latest semver)\n :target: https://hub.docker.com/r/merpatterson/python-project-structure\n\n - .. figure:: https://img.shields.io/keybase/pgp/rpatterson?logo=keybase\n :alt: KeyBase PGP key ID\n :target: https://keybase.io/rpatterson\n .. figure:: https://img.shields.io/github/followers/rpatterson?style=social\n :alt: GitHub followers count\n :target: https://github.com/rpatterson\n .. figure:: https://img.shields.io/liberapay/receives/rpatterson.svg?logo=liberapay\n :alt: LiberaPay donated per week\n :target: https://liberapay.com/rpatterson/donate\n .. figure:: https://img.shields.io/liberapay/patrons/rpatterson.svg?logo=liberapay\n :alt: LiberaPay patrons count\n :target: https://liberapay.com/rpatterson/donate\n\n\nThis repository is meant to be used as a minimal, yet opinionated baseline for `Python`_\nsoftware projects. It includes:\n\n- Basic `Python \"distribution\"/project`_ metadata\n- Command-line console script with sub-command boilerplate\n- A `Makefile`_ for local development build, test and maintenance tasks\n- `Docker`_ container images for users and development\n- `Docker`_ container images for users and development in which tests are run\n- A `Makefile`_ target to format all Python code, including using `Black`_ for style\n- A `kitchen sink linter configuration`_ for `Prospector`_ that runs all available\n Python code checks\n- A `tox.ini`_ configuration for `Tox`_ to run all tests and linters in multiple Python\n versions, including some checks not provided by Prospector.\n- `VCS hooks`_ to enforce `conventional commits`_ and successful build and test on\n commit and push, and release notes on push\n- Targets/recipes in the `Makefile`_ to automate releases controlled by `conventional\n commits`_ and end-user oriented release notes by `Towncrier`_\n- Targets/recipes in the `Makefile`_ to automate upgrading requirements and dependencies\n- `Makefile`_ recipes/targets used for both local development and on CI/CD platforms\n- A `GitLab CI/CD`_ pipeline integrating those CI/CD recipes/targets\n- A `GitHub Actions`_ workflow/pipeline integrating those CI/CD recipes/targets\n\nThe intended use is to add this repository as a VCS remote for your project. Thus\ndevelopers can merge changes from this repository as we make changes related to Python\nproject structure and tooling. As we add structure specific to certain types of\nprojects (e.g. CLI scripts, web development, etc.), frameworks (e.g. Flask, Pyramid,\nDjango, etc.), libraries and such, branches will be used for each such variation such\nthat structure common to different variations can be merged back into the branches for\nthose specific variations.\n\n.. contents:: Table of Contents\n\n\n****************************************************************************************\nTemplate Usage\n****************************************************************************************\n\nThis is a rough guide to applying this project template to your project. This is not\nthoroughly tested as such tests would be so meta as to be extremely wasteful of\ndeveloper time to create and maintain. So report any issues you have or better yet\nfigure it out and submit a PR with corrections to this section.\n\n#. Choose the right branch to use:\n\n Is your project a CLI utility? A web application? Which project hosting provider\n and/or CI/CD platform will you use? Choose the appropriate branch for your project:\n\n - ``dist``:\n\n Basic Python distribution with build, tests, linters, code formatting and release\n publishing from local developer checkouts.\n\n - ``cli``:\n\n The above plus support for project's that provide an executable CLI.\n\n - ``docker``:\n\n The ``dist`` branch plus Docker containers for both development and\n end-users/deployments.\n\n - ``ci``:\n\n The above plus GitLab CI/CD pipelines that run tests and linters as CI and\n publish releases from ``develop`` and ``main`` as CD.\n\n - ``ci-cli``:\n\n The above plus the ``cli`` branch.\n\n - etc.\n\n Do not use the ``develop`` or ``main`` branches in your project as those branches\n are used to test the CI/CD automatic releases process and as such contain bumped\n versions, release notes, and other release artifacts that shouldn't be merged into\n real projects.\n\n#. Reconcile VCS history:\n\n If starting a fresh project::\n\n $ git clone --origin \"template\" --branch \"ci-cli\" \\\n \"https://gitlab.com/rpatterson/python-project-structure.git\" \"./foo-project\"\n $ cd \"./foo-project\"\n $ git config remote.template.tagOpt --no-tags\n $ git remote add \"origin\" \"git@gitlab.com:foo-username/foo-project.git\"\n $ git config remote.template.tagOpt --no-tags\n $ git switch -C \"main\" --track \"origin/main\"\n\n If merging into an existing project::\n\n $ git remote add \"template\" \\\n \"https://gitlab.com/rpatterson/python-project-structure.git\"\n $ git config remote.template.tagOpt --no-tags\n $ git merge --allow-unrelated-histories \"template/ci-cli\"\n\n#. Rename file and directory paths derived from the project name::\n\n $ git ls-files | grep -iE 'python.?project.?structure'\n\n#. Rename strings derived from the project name and template author identity in project\n files::\n\n $ git grep -iE 'python.?project.?structure|ross|Patterson'\n\n#. Examine ``# TEMPLATE:`` comments and change as appropriate:\n\n These are the bits that need the developer's attention and reasoning to take the\n correct action. So read the comments and address them with care and attention::\n\n $ git grep \"TEMPLATE\"\n\nFinally, remove this section from this ``./README.rst`` and update the rest of it's\ncontent as appropriate for your project. As fixes and features are added to the\nupstream template, you can merge them into your project and repeat steps 3-5 above as\nneeded.\n\nThis template publishes pre-releases on all pushes to the ``develop`` branch and final\nreleases on all pushes to the ``main`` branch. Project owners may decide which types\nof changes should go through pre-release before final release and which types of changes\nshould go straight to final release. For example they may decide that:\n\n- Contributions from those who are not maintainers or owners should be merged into\n ``develop``. See `the ./CONTRIBUTING.rst file`_ for such an example public\n contributions policy and workflow.\n\n- Fixes for bugs in final releases may be committed to a branch off of ``main`` and,\n after passing all tests and checks, merged back into ``main`` to publish final\n releases immediately.\n\n- Routine version upgrades for security updates may also be merged to ``main`` as\n above for bug fixes.\n\n\n****************************************************************************************\nInstallation\n****************************************************************************************\n\nInstall and use either via a local, native installation or a Docker container image:\n\nLocal/Native Installation\n========================================================================================\n\nInstall using any tool for installing standard Python 3 distributions such as `pip`_::\n\n $ pip3 install --user python-project-structure\n\nOptional shell tab completion is available via `argcomplete`_.\n\nDocker Container Image Installation\n========================================================================================\n\nThe recommended way to use the Docker container image is via `Docker Compose`_. See\n`the example ./docker-compose.yml file`_ for an example configuration. Once you have\nyour configuration, you can create and run the container::\n\n $ docker compose up\n\nAlternatively, you make use the image directly. Pull `the Docker image`_::\n\n $ docker pull \"registry.gitlab.org/rpatterson/python-project-structure\"\n\nAnd then use the image to create and run a container::\n\n $ docker run --rm -it \"registry.gitlab.org/rpatterson/python-project-structure\" ...\n\nImages variant tags are published for the Python version, branch, and major/minor\nversions so that users can control when they get new images over time,\ne.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310-main``. The\ncanonical Python version is 3.10 which is the version used in tags without ``py###``,\ne.g. ``registry.gitlab.org/merpatterson/python-project-structure:main``. Pre-releases\nare from ``develop`` and final releases are from ``main`` which is also the default for\ntags without a branch,\ne.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310``. The\nmajor/minor version tags are only applied to the final release images and without the\ncorresponding ``main`` branch tag,\ne.g. ``registry.gitlab.org/merpatterson/python-project-structure:py310-v0.8``.\n\nMulti-platform Docker images are published containing images for the following\nplatforms or architectures in the Python 3.10 ``py310`` variant:\n\n- ``linux/amd64``\n- ``linux/arm64``\n- ``linux/arm/v7``\n\n\n****************************************************************************************\nUsage\n****************************************************************************************\n\nSee the command-line help for details on options and arguments::\n\n $ python-project-structure --help\n usage: python-project-structure [-h]\n\n Python project structure foundation or template, top-level package.\n\n optional arguments:\n -h, --help show this help message and exit\n\nIf using the Docker container image, the container can be run from the command-line as\nwell::\n\n $ docker compose run \"python-project-structure\" python-project-structure --help\n usage: python-project-structure [-h]\n\n Python project structure foundation or template, top-level package.\n\n optional arguments:\n -h, --help show this help message and exit\n\n\n****************************************************************************************\nContributing\n****************************************************************************************\n\nNOTE: `This project is hosted on GitLab`_. There's `a mirror on GitHub`_ but please use\nGitLab for reporting issues, submitting PRs/MRs and any other development or maintenance\nactivity.\n\nSee `the ./CONTRIBUTING.rst file`_ for more details on how to get started with\ndevelopment.\n\n\n****************************************************************************************\nMotivation\n****************************************************************************************\n\nThere are many other Python project templates so why make another? I've been doing\nPython development since 1998, so I've had plenty of time to develop plenty of opinions\nof my own.\n\nWhat I want in a template is complete tooling (e.g. test coverage, linting, formatting,\nCI/CD, etc.) but minimal dependencies, structure, and opinion beyond complete tooling\n(e.g. some non-Python build/task system, structure for frameworks/libraries not\nnecessarily being used, etc.). I couldn't find a template that manages that balance so\nhere we are.\n\nI also find it hard to discern from other templates why they made what choices the did.\nAs such, I also use this template as a way to try out various different options in the\nPython development world and evaluate them for myself. You can learn about my findings\nand the reasons the choices I've made in the commit history.\n\nMost importantly, however, I've never found a satisfactory approach to keeping project\nstructure up to date over time. So the primary motivation is to use this repository as\na remote from which we can merge structure updates over the life of projects using the\ntemplate.\n\n\n.. _Python: https://docs.python.org/3/library/logging.html\n.. _Python \"distribution\"/project: https://docs.python.org/3/distributing/index.html\n.. _pip: https://pip.pypa.io/en/stable/installation/\n.. _`Black`: https://github.com/psf/black\n.. _`Prospector`: https://prospector.landscape.io\n.. _`Tox`: https://tox.wiki\n.. _`Towncrier`: https://towncrier.readthedocs.io\n.. _argcomplete: https://kislyuk.github.io/argcomplete/#installation\n\n.. _`conventional commits`: https://www.conventionalcommits.org\n\n.. _`This project is hosted on GitLab`:\n https://gitlab.com/rpatterson/python-project-structure\n.. _`a mirror on GitHub`:\n https://github.com/rpatterson/python-project-structure\n.. _`Docker`: https://docs.docker.com/\n.. _`Docker Compose`: https://docs.docker.com/compose/\n.. _the Docker image: https://hub.docker.com/r/merpatterson/python-project-structure\n\n.. _`GitLab CI/CD`: https://docs.gitlab.com/ee/ci/\n\n.. _`GitHub Actions`: https://docs.github.com/en/actions\n\n.. _Makefile:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/Makefile\n.. _`the example ./docker-compose.yml file`:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/docker-compose.yml\n.. _`the ./CONTRIBUTING.rst file`:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/CONTRIBUTING.rst\n.. _`kitchen sink linter configuration`:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/.prospector.yaml\n.. _`tox.ini`:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/tox.ini\n.. _`VCS hooks`:\n https://gitlab.com/rpatterson/python-project-structure/blob/main/.pre-commit-config.yaml\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python project structure foundation or template, CLI console scripts.",
"version": "0.8.25",
"split_keywords": [
"template",
"structure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4e6c023b6d392634b0dd9d2895113eca9f4963c591a2bc38df3286a2d759f3f1",
"md5": "74b034d9bb141c44e9af08e863ef1ce5",
"sha256": "0da3508f7de066ce53ccab79aa7ef02327ade48da3a35056786996f74045cdf8"
},
"downloads": -1,
"filename": "python_project_structure-0.8.25-py3-none-any.whl",
"has_sig": true,
"md5_digest": "74b034d9bb141c44e9af08e863ef1ce5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12186,
"upload_time": "2023-04-26T19:33:46",
"upload_time_iso_8601": "2023-04-26T19:33:46.796481Z",
"url": "https://files.pythonhosted.org/packages/4e/6c/023b6d392634b0dd9d2895113eca9f4963c591a2bc38df3286a2d759f3f1/python_project_structure-0.8.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d46c6e23710cee425419acc56797a70c2bd0c1af2488af6ad7c1381aa9c31e57",
"md5": "f46cfab31e1f8a9afd95d626f518514e",
"sha256": "c197546d50e26008c32f4f75efac071b8f607249c39aa1bfaaed34fc4bf42b16"
},
"downloads": -1,
"filename": "python-project-structure-0.8.25.tar.gz",
"has_sig": true,
"md5_digest": "f46cfab31e1f8a9afd95d626f518514e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 57617,
"upload_time": "2023-04-26T19:33:49",
"upload_time_iso_8601": "2023-04-26T19:33:49.346008Z",
"url": "https://files.pythonhosted.org/packages/d4/6c/6e23710cee425419acc56797a70c2bd0c1af2488af6ad7c1381aa9c31e57/python-project-structure-0.8.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-26 19:33:49",
"github": false,
"gitlab": true,
"bitbucket": false,
"gitlab_user": "rpatterson",
"gitlab_project": "python-project-structure",
"lcname": "python-project-structure"
}
JSON