.. SPDX-FileCopyrightText: 2023 Ross Patterson <me@rpatterson.net>
..
.. SPDX-License-Identifier: MIT
########################################################################################
Project Structure
########################################################################################
Project Structure foundation or template
****************************************************************************************
.. list-table::
:class: borderless align-right
* - .. figure:: https://img.shields.io/pypi/v/project-structure.svg?logo=pypi&label=PyPI&logoColor=gold
:alt: PyPI latest release version
:target: https://pypi.org/project/project-structure/
.. figure:: https://img.shields.io/pypi/pyversions/project-structure.svg?logo=python&label=Python&logoColor=gold
:alt: PyPI Python versions
:target: https://pypi.org/project/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://api.reuse.software/badge/gitlab.com/rpatterson/project-structure
:alt: Reuse license status
:target: https://api.reuse.software/info/gitlab.com/rpatterson/project-structure
- .. figure:: https://gitlab.com/rpatterson/project-structure/-/badges/release.svg
:alt: GitLab latest release
:target: https://gitlab.com/rpatterson/project-structure/-/releases
.. figure:: https://gitlab.com/rpatterson/project-structure/badges/main/pipeline.svg
:alt: GitLab CI/CD pipeline status
:target: https://gitlab.com/rpatterson/project-structure/-/commits/main
.. figure:: https://gitlab.com/rpatterson/project-structure/badges/main/coverage.svg
:alt: GitLab coverage report
:target: https://gitlab.com/rpatterson/project-structure/-/commits/main
.. figure:: https://img.shields.io/gitlab/stars/rpatterson/project-structure?gitlab_url=https%3A%2F%2Fgitlab.com&logo=gitlab
:alt: GitLab repository stars
:target: https://gitlab.com/rpatterson/project-structure
- .. figure:: https://img.shields.io/github/v/release/rpatterson/project-structure?logo=github
:alt: GitHub release (latest SemVer)
:target: https://github.com/rpatterson/project-structure/releases
.. figure:: https://github.com/rpatterson/project-structure/actions/workflows/build-test.yml/badge.svg
:alt: GitHub Actions status
:target: https://github.com/rpatterson/project-structure/actions/workflows/build-test.yml
.. figure:: https://codecov.io/github/rpatterson/project-structure/branch/main/graph/badge.svg?token=GNKVQ8VYOU
:alt: Codecov test coverage
:target: https://app.codecov.io/github/rpatterson/project-structure
.. figure:: https://img.shields.io/github/stars/rpatterson/project-structure?logo=github
:alt: GitHub repository stars
:target: https://github.com/rpatterson/project-structure/
- .. figure:: https://img.shields.io/docker/v/merpatterson/project-structure?sort=semver&logo=docker
:alt: Docker Hub image version
:target: https://hub.docker.com/r/merpatterson/project-structure
.. figure:: https://img.shields.io/docker/pulls/merpatterson/project-structure?logo=docker
:alt: Docker Hub image pulls count
:target: https://hub.docker.com/r/merpatterson/project-structure
.. figure:: https://img.shields.io/docker/stars/merpatterson/project-structure?logo=docker
:alt: Docker Hub stars
:target: https://hub.docker.com/r/merpatterson/project-structure
.. figure:: https://img.shields.io/docker/image-size/merpatterson/project-structure?logo=docker
:alt: Docker Hub image size
:target: https://hub.docker.com/r/merpatterson/project-structure
- .. figure:: https://img.shields.io/keybase/pgp/rpatterson?logo=keybase
:alt: KeyBase Pretty Good Privacy (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 provides a minimal, yet opinionated baseline for `Python`_ software
projects. It includes:
- Basic `Python "distribution"/project`_ metadata
- Command-line console script with subcommand boilerplate
- A `Docker`_ container image for end users
- A Docker image for development, which runs tests
- A `Makefile`_ for local development, build, test, and maintenance
- A target that formats all source, including `Black`_ for Python code 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 across supported
Python versions, including some checks not provided by Prospector.
- `Version Control System (VCS) hooks`_ to enforce `conventional commits`_, successful
build and test on commit and push, and `Towncrier`_ end-user oriented release notes on
push
- Targets that automate releases
- Targets that automate dependency upgrades
- Targets used for both local development and on CI/CD platforms
- A `GitLab CI/CD`_ pipeline integrating those CI/CD recipes and targets
- A `GitHub Actions`_ workflow integrating those CI/CD recipes and targets
- `Organize source by feature`_, for example ``\./src/foo/(template|view|model)\..*``,
rather than by source type, for example
``\./src/(templates|views|models)/foo\..*``.
Add a VCS remote for this repository to a real project. When the template adds structure
specific to certain types of projects, for example command-line tools, web services, UI
apps, the it adds branches for each variant. When the template makes changes to
structure common to different variants it can merge those changes into those
variants. Real projects can also merge those changes.
.. _Python: https://docs.python.org/3/library/logging.html
.. _Python "distribution"/project: https://docs.python.org/3/distributing/index.html
.. _`Docker`: https://docs.docker.com/
.. _Makefile: https://gitlab.com/rpatterson/project-structure/-/blob/main/Makefile
.. _`Black`: https://github.com/psf/black
.. _`kitchen sink linter configuration`:
https://gitlab.com/rpatterson/project-structure/-/blob/main/.prospector.yaml
.. _`Prospector`: https://prospector.landscape.io/en/master/
.. _`tox.ini`: https://gitlab.com/rpatterson/project-structure/-/blob/main/tox.ini
.. _`Tox`: https://tox.wiki/en/stable/
.. _`Version Control System (VCS) hooks`:
https://gitlab.com/rpatterson/project-structure/-/blob/main/.pre-commit-config.yaml
.. _`conventional commits`: https://www.conventionalcommits.org
.. _`Towncrier`: https://towncrier.readthedocs.io/en/stable/
.. _`GitLab CI/CD`: https://docs.gitlab.com/ee/ci/
.. _`GitHub Actions`: https://docs.github.com/en/actions
.. _`Organize source by feature`:
https://www.seancdavis.com/posts/organize-components-by-keeping-related-files-close/
.. include-end-before
.. contents:: Table of Contents
.. include-start-after
****************************************************************************************
Template usage
****************************************************************************************
This is a rough guide for how to use this template in your project. This isn't widely
tested. Such tests are meta and wasteful to create and support. Report any issues you
have or better yet submit a PR with corrections.
#. Pick the branch to use:
Pick the branch for your project type:
- ``py``:
Basic Python distribution metadata and packaging.
- ``py-cli``:
The preceding plus boilerplate for a command-line console script with subcommand.
- ``docker``:
Docker images for development and end-users or deployments.
- ``py-docker``:
The preceding Docker images with the Python package installed.
- ``ci``:
The preceding plus GitLab CI/CD pipelines that run tests and linters as CI and
publish releases from ``develop`` and ``main`` as CD.
- ``py-ci``:
The ``py-docker`` and ``ci`` branches merged together.
- ``py-ci-cli``:
All the preceding combined together.
It's important to use one of the preceding branches to merge into your project and
*not* the ``develop`` or ``main`` branches from the template. Template developers use
those branches to test the release process. They contain bumped versions, release
notes, and other release artifacts that real projects shouldn't merge into their code
or history.
#. Merge into your project:
If starting a fresh project::
$ git clone --origin "template" --branch "${TEMPLATE_BRANCH:?}" \
"https://gitlab.com/rpatterson/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 switch -C "main" --track "origin/main"
If merging into an existing project::
$ git remote add "template" \
"https://gitlab.com/rpatterson/project-structure.git"
$ git config remote.template.tagOpt --no-tags
$ git merge --allow-unrelated-histories "template/${TEMPLATE_BRANCH:?}"
#. Rename files and directories derived from the project name::
$ git ls-files | grep -iE 'project.?structure'
#. Rename project name and template creator identity strings::
$ git grep -iE 'project.?structure|ross|Patterson'
#. Make changes described in ``# TEMPLATE:`` comments:
These bits need the developer's attention and reasoning. Read the comments and follow
them with care::
$ git grep "TEMPLATE"
Lastly, remove this `Template usage`_ section and update the rest of this
``./README.rst`` for your project. When the template adds fixes and features, merge them
into your project and repeat steps 3--5.
This template publishes pre-releases on push to the ``develop`` branch and final
releases on push to the ``main`` branch. Project owners can decide the types of changes
that require a pre-release before final release and the types of changes that go
straight to final release. For example they can decide that:
- Merge public contributions into ``develop``. See `the contributing documentation`_ for
an example public contributions policy and workflow.
- Optionally commit fixes for bugs in final releases to a branch off ``main``. After
passing all tests and checks, merge back into ``main`` to publish final releases
directly.
- Optionally also merge version upgrades for security updates directly to ``main``.
****************************************************************************************
Installation
****************************************************************************************
Install locally or use the Docker container image:
Local Installation
========================================================================================
Install by using any tool for installing standard Python 3 distributions such as
`pip`_::
$ pip3 install --user project-structure
Optional shell prompt tab completion is available by using `argcomplete`_.
Docker Container Image
========================================================================================
The recommended way to use the container image is by using `Docker Compose`_. See `the
example ./docker-compose.yml file`_. Write your configuration and run the container::
$ docker compose up
You can also use the image directly. Pull `the Docker image`_. Use it to create and run
a container::
$ docker pull "registry.gitlab.com/rpatterson/project-structure"
$ docker run --rm -it "registry.gitlab.com/rpatterson/project-structure" ...
Use image variant tags to control when the image updates. Releases publish tags for the
branch and for major and minor versions. For example, to keep up to date with a specific
branch, use a tag such as
``registry.gitlab.com/rpatterson/project-structure:main``. Releases from ``develop``
publish pre-releases. Releases from ``main`` publish final releases. Releases from
``main`` also publish tags without a branch, for example
``registry.gitlab.com/rpatterson/project-structure``. Releases from ``main`` also
publish tags for the major and minor version, for example
``registry.gitlab.com/rpatterson/project-structure:v0.8``.
Releases publish multi-platform images for the following platforms:
- ``linux/amd64``
- ``linux/arm64``
- ``linux/arm/v7``
****************************************************************************************
Usage
****************************************************************************************
See the command-line help for details on options and arguments::
$ project-structure --help
usage: project-structure [-h]
project structure foundation or template, top-level package.
Pptional arguments:
-h, --help show this help message and exit
The Docker container image can run the command-line script as well::
$ docker compose run "project-structure" project-structure --help
usage: project-structure [-h]
Project structure foundation or template, top-level package.
optional arguments:
-h, --help show this help message and exit
****************************************************************************************
Contributing
****************************************************************************************
`GitLab hosts this project`_ and `mirrors it to GitHub`_ but use GitLab for reporting
issues, submitting pull or merge requests and any other development or maintenance
activity. See `the contributing documentation`_ for more details on how to get started
with development.
****************************************************************************************
Motivation
****************************************************************************************
.. vale off
Plenty other project templates exists. Why make another? I've been a full-stack web
developer from 1998 on. I've had plenty of time to develop plenty of opinions of my
own. From a template I want a full tool set (for example test coverage, linting,
formatting, CI). Conversely, I want minimal dependencies, structure, and opinion beyond
a full tool set (for example some build or task system, structure for unused frameworks
or libraries). I couldn't find a template that manages that balance and I created this
one.
I also find it hard to discern from other templates why they made what choices the did.
As such, I also use this template to try out different options and learn for myself. You
can learn about my findings and the reasons the choices I've made in the commit history.
Most importantly I've never found a satisfactory approach to keeping project structure
up to date over time. As such, the primary motivation is providing a template upstream
remote, merging structure updates into real projects over their lifetime.
.. vale on
****************************************************************************************
References
****************************************************************************************
.. target-notes::
.. _`the contributing documentation`:
https://gitlab.com/rpatterson/project-structure/-/blob/main/docs/contributing.rst
.. _pip: https://pip.pypa.io/en/stable/installation/
.. _argcomplete: https://kislyuk.github.io/argcomplete/#installation
.. _`Docker Compose`: https://docs.docker.com/compose/
.. _`the example ./docker-compose.yml file`:
https://gitlab.com/rpatterson/project-structure/-/blob/main/docker-compose.yml
.. _the Docker image: https://hub.docker.com/r/merpatterson/project-structure
.. _`GitLab hosts this project`:
https://gitlab.com/rpatterson/project-structure
.. _`mirrors it to GitHub`:
https://github.com/rpatterson/project-structure
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/rpatterson/project-structure",
"name": "project-structure",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "template,structure",
"author": "Ross Patterson",
"author_email": "me@rpatterson.net",
"download_url": "https://files.pythonhosted.org/packages/01/85/4d7db3e29b6edb9aeb9b7331e1d608b1f0e97958a3423c5e6093c15dc977/project-structure-1.0.1.tar.gz",
"platform": null,
"description": ".. SPDX-FileCopyrightText: 2023 Ross Patterson <me@rpatterson.net>\n..\n.. SPDX-License-Identifier: MIT\n\n########################################################################################\nProject Structure\n########################################################################################\nProject Structure foundation or template\n****************************************************************************************\n\n.. list-table::\n :class: borderless align-right\n\n * - .. figure:: https://img.shields.io/pypi/v/project-structure.svg?logo=pypi&label=PyPI&logoColor=gold\n :alt: PyPI latest release version\n :target: https://pypi.org/project/project-structure/\n .. figure:: https://img.shields.io/pypi/pyversions/project-structure.svg?logo=python&label=Python&logoColor=gold\n :alt: PyPI Python versions\n :target: https://pypi.org/project/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 .. figure:: https://api.reuse.software/badge/gitlab.com/rpatterson/project-structure\n :alt: Reuse license status\n :target: https://api.reuse.software/info/gitlab.com/rpatterson/project-structure\n\n - .. figure:: https://gitlab.com/rpatterson/project-structure/-/badges/release.svg\n :alt: GitLab latest release\n :target: https://gitlab.com/rpatterson/project-structure/-/releases\n .. figure:: https://gitlab.com/rpatterson/project-structure/badges/main/pipeline.svg\n :alt: GitLab CI/CD pipeline status\n :target: https://gitlab.com/rpatterson/project-structure/-/commits/main\n .. figure:: https://gitlab.com/rpatterson/project-structure/badges/main/coverage.svg\n :alt: GitLab coverage report\n :target: https://gitlab.com/rpatterson/project-structure/-/commits/main\n .. figure:: https://img.shields.io/gitlab/stars/rpatterson/project-structure?gitlab_url=https%3A%2F%2Fgitlab.com&logo=gitlab\n :alt: GitLab repository stars\n :target: https://gitlab.com/rpatterson/project-structure\n\n - .. figure:: https://img.shields.io/github/v/release/rpatterson/project-structure?logo=github\n :alt: GitHub release (latest SemVer)\n :target: https://github.com/rpatterson/project-structure/releases\n .. figure:: https://github.com/rpatterson/project-structure/actions/workflows/build-test.yml/badge.svg\n :alt: GitHub Actions status\n :target: https://github.com/rpatterson/project-structure/actions/workflows/build-test.yml\n .. figure:: https://codecov.io/github/rpatterson/project-structure/branch/main/graph/badge.svg?token=GNKVQ8VYOU\n :alt: Codecov test coverage\n :target: https://app.codecov.io/github/rpatterson/project-structure\n .. figure:: https://img.shields.io/github/stars/rpatterson/project-structure?logo=github\n :alt: GitHub repository stars\n :target: https://github.com/rpatterson/project-structure/\n\n - .. figure:: https://img.shields.io/docker/v/merpatterson/project-structure?sort=semver&logo=docker\n :alt: Docker Hub image version\n :target: https://hub.docker.com/r/merpatterson/project-structure\n .. figure:: https://img.shields.io/docker/pulls/merpatterson/project-structure?logo=docker\n :alt: Docker Hub image pulls count\n :target: https://hub.docker.com/r/merpatterson/project-structure\n .. figure:: https://img.shields.io/docker/stars/merpatterson/project-structure?logo=docker\n :alt: Docker Hub stars\n :target: https://hub.docker.com/r/merpatterson/project-structure\n .. figure:: https://img.shields.io/docker/image-size/merpatterson/project-structure?logo=docker\n :alt: Docker Hub image size\n :target: https://hub.docker.com/r/merpatterson/project-structure\n\n - .. figure:: https://img.shields.io/keybase/pgp/rpatterson?logo=keybase\n :alt: KeyBase Pretty Good Privacy (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 provides a minimal, yet opinionated baseline for `Python`_ software\nprojects. It includes:\n\n- Basic `Python \"distribution\"/project`_ metadata\n- Command-line console script with subcommand boilerplate\n- A `Docker`_ container image for end users\n- A Docker image for development, which runs tests\n- A `Makefile`_ for local development, build, test, and maintenance\n- A target that formats all source, including `Black`_ for Python code 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 across supported\n Python versions, including some checks not provided by Prospector.\n- `Version Control System (VCS) hooks`_ to enforce `conventional commits`_, successful\n build and test on commit and push, and `Towncrier`_ end-user oriented release notes on\n push\n- Targets that automate releases\n- Targets that automate dependency upgrades\n- Targets used for both local development and on CI/CD platforms\n- A `GitLab CI/CD`_ pipeline integrating those CI/CD recipes and targets\n- A `GitHub Actions`_ workflow integrating those CI/CD recipes and targets\n- `Organize source by feature`_, for example ``\\./src/foo/(template|view|model)\\..*``,\n rather than by source type, for example\n ``\\./src/(templates|views|models)/foo\\..*``.\n\nAdd a VCS remote for this repository to a real project. When the template adds structure\nspecific to certain types of projects, for example command-line tools, web services, UI\napps, the it adds branches for each variant. When the template makes changes to\nstructure common to different variants it can merge those changes into those\nvariants. Real projects can also merge those changes.\n\n.. _Python: https://docs.python.org/3/library/logging.html\n.. _Python \"distribution\"/project: https://docs.python.org/3/distributing/index.html\n.. _`Docker`: https://docs.docker.com/\n.. _Makefile: https://gitlab.com/rpatterson/project-structure/-/blob/main/Makefile\n.. _`Black`: https://github.com/psf/black\n.. _`kitchen sink linter configuration`:\n https://gitlab.com/rpatterson/project-structure/-/blob/main/.prospector.yaml\n.. _`Prospector`: https://prospector.landscape.io/en/master/\n.. _`tox.ini`: https://gitlab.com/rpatterson/project-structure/-/blob/main/tox.ini\n.. _`Tox`: https://tox.wiki/en/stable/\n.. _`Version Control System (VCS) hooks`:\n https://gitlab.com/rpatterson/project-structure/-/blob/main/.pre-commit-config.yaml\n.. _`conventional commits`: https://www.conventionalcommits.org\n.. _`Towncrier`: https://towncrier.readthedocs.io/en/stable/\n.. _`GitLab CI/CD`: https://docs.gitlab.com/ee/ci/\n.. _`GitHub Actions`: https://docs.github.com/en/actions\n.. _`Organize source by feature`:\n https://www.seancdavis.com/posts/organize-components-by-keeping-related-files-close/\n\n.. include-end-before\n.. contents:: Table of Contents\n.. include-start-after\n\n\n****************************************************************************************\nTemplate usage\n****************************************************************************************\n\nThis is a rough guide for how to use this template in your project. This isn't widely\ntested. Such tests are meta and wasteful to create and support. Report any issues you\nhave or better yet submit a PR with corrections.\n\n#. Pick the branch to use:\n\n Pick the branch for your project type:\n\n - ``py``:\n\n Basic Python distribution metadata and packaging.\n\n - ``py-cli``:\n\n The preceding plus boilerplate for a command-line console script with subcommand.\n\n - ``docker``:\n\n Docker images for development and end-users or deployments.\n\n - ``py-docker``:\n\n The preceding Docker images with the Python package installed.\n\n - ``ci``:\n\n The preceding plus GitLab CI/CD pipelines that run tests and linters as CI and\n publish releases from ``develop`` and ``main`` as CD.\n\n - ``py-ci``:\n\n The ``py-docker`` and ``ci`` branches merged together.\n\n - ``py-ci-cli``:\n\n All the preceding combined together.\n\n It's important to use one of the preceding branches to merge into your project and\n *not* the ``develop`` or ``main`` branches from the template. Template developers use\n those branches to test the release process. They contain bumped versions, release\n notes, and other release artifacts that real projects shouldn't merge into their code\n or history.\n\n#. Merge into your project:\n\n If starting a fresh project::\n\n $ git clone --origin \"template\" --branch \"${TEMPLATE_BRANCH:?}\" \\\n \"https://gitlab.com/rpatterson/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 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/project-structure.git\"\n $ git config remote.template.tagOpt --no-tags\n $ git merge --allow-unrelated-histories \"template/${TEMPLATE_BRANCH:?}\"\n\n#. Rename files and directories derived from the project name::\n\n $ git ls-files | grep -iE 'project.?structure'\n\n#. Rename project name and template creator identity strings::\n\n $ git grep -iE 'project.?structure|ross|Patterson'\n\n#. Make changes described in ``# TEMPLATE:`` comments:\n\n These bits need the developer's attention and reasoning. Read the comments and follow\n them with care::\n\n $ git grep \"TEMPLATE\"\n\nLastly, remove this `Template usage`_ section and update the rest of this\n``./README.rst`` for your project. When the template adds fixes and features, merge them\ninto your project and repeat steps 3--5.\n\nThis template publishes pre-releases on push to the ``develop`` branch and final\nreleases on push to the ``main`` branch. Project owners can decide the types of changes\nthat require a pre-release before final release and the types of changes that go\nstraight to final release. For example they can decide that:\n\n- Merge public contributions into ``develop``. See `the contributing documentation`_ for\n an example public contributions policy and workflow.\n\n- Optionally commit fixes for bugs in final releases to a branch off ``main``. After\n passing all tests and checks, merge back into ``main`` to publish final releases\n directly.\n\n- Optionally also merge version upgrades for security updates directly to ``main``.\n\n\n****************************************************************************************\nInstallation\n****************************************************************************************\n\nInstall locally or use the Docker container image:\n\nLocal Installation\n========================================================================================\n\nInstall by using any tool for installing standard Python 3 distributions such as\n`pip`_::\n\n $ pip3 install --user project-structure\n\nOptional shell prompt tab completion is available by using `argcomplete`_.\n\nDocker Container Image\n========================================================================================\n\nThe recommended way to use the container image is by using `Docker Compose`_. See `the\nexample ./docker-compose.yml file`_. Write your configuration and run the container::\n\n $ docker compose up\n\nYou can also use the image directly. Pull `the Docker image`_. Use it to create and run\na container::\n\n $ docker pull \"registry.gitlab.com/rpatterson/project-structure\"\n $ docker run --rm -it \"registry.gitlab.com/rpatterson/project-structure\" ...\n\nUse image variant tags to control when the image updates. Releases publish tags for the\nbranch and for major and minor versions. For example, to keep up to date with a specific\nbranch, use a tag such as\n``registry.gitlab.com/rpatterson/project-structure:main``. Releases from ``develop``\npublish pre-releases. Releases from ``main`` publish final releases. Releases from\n``main`` also publish tags without a branch, for example\n``registry.gitlab.com/rpatterson/project-structure``. Releases from ``main`` also\npublish tags for the major and minor version, for example\n``registry.gitlab.com/rpatterson/project-structure:v0.8``.\n\nReleases publish multi-platform images for the following platforms:\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 $ project-structure --help\n usage: project-structure [-h]\n\n project structure foundation or template, top-level package.\n\n Pptional arguments:\n -h, --help show this help message and exit\n\nThe Docker container image can run the command-line script as well::\n\n $ docker compose run \"project-structure\" project-structure --help\n usage: project-structure [-h]\n\n 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\n`GitLab hosts this project`_ and `mirrors it to GitHub`_ but use GitLab for reporting\nissues, submitting pull or merge requests and any other development or maintenance\nactivity. See `the contributing documentation`_ for more details on how to get started\nwith development.\n\n\n****************************************************************************************\nMotivation\n****************************************************************************************\n\n.. vale off\n\nPlenty other project templates exists. Why make another? I've been a full-stack web\ndeveloper from 1998 on. I've had plenty of time to develop plenty of opinions of my\nown. From a template I want a full tool set (for example test coverage, linting,\nformatting, CI). Conversely, I want minimal dependencies, structure, and opinion beyond\na full tool set (for example some build or task system, structure for unused frameworks\nor libraries). I couldn't find a template that manages that balance and I created this\none.\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 to try out different options and learn for myself. You\ncan learn about my findings and the reasons the choices I've made in the commit history.\n\nMost importantly I've never found a satisfactory approach to keeping project structure\nup to date over time. As such, the primary motivation is providing a template upstream\nremote, merging structure updates into real projects over their lifetime.\n\n.. vale on\n\n\n****************************************************************************************\nReferences\n****************************************************************************************\n\n.. target-notes::\n\n.. _`the contributing documentation`:\n https://gitlab.com/rpatterson/project-structure/-/blob/main/docs/contributing.rst\n\n.. _pip: https://pip.pypa.io/en/stable/installation/\n.. _argcomplete: https://kislyuk.github.io/argcomplete/#installation\n\n.. _`Docker Compose`: https://docs.docker.com/compose/\n.. _`the example ./docker-compose.yml file`:\n https://gitlab.com/rpatterson/project-structure/-/blob/main/docker-compose.yml\n.. _the Docker image: https://hub.docker.com/r/merpatterson/project-structure\n\n.. _`GitLab hosts this project`:\n https://gitlab.com/rpatterson/project-structure\n.. _`mirrors it to GitHub`:\n https://github.com/rpatterson/project-structure\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Project structure foundation or template, CLI console scripts.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://gitlab.com/rpatterson/project-structure"
},
"split_keywords": [
"template",
"structure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "476ec1ff4b36f53c613c7d85306faf0c86c6bcde66a9c17289b4540be0b614f6",
"md5": "9a60772f228df904d5fe054712c882bd",
"sha256": "f7a2937d2e8f81f02ccb27c64f8cc4d105460ec034615c4c6d9691330cd66516"
},
"downloads": -1,
"filename": "project_structure-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a60772f228df904d5fe054712c882bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10260,
"upload_time": "2023-10-31T21:41:38",
"upload_time_iso_8601": "2023-10-31T21:41:38.464579Z",
"url": "https://files.pythonhosted.org/packages/47/6e/c1ff4b36f53c613c7d85306faf0c86c6bcde66a9c17289b4540be0b614f6/project_structure-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "01854d7db3e29b6edb9aeb9b7331e1d608b1f0e97958a3423c5e6093c15dc977",
"md5": "8074b0f2b42383de5460980ba17d1dfb",
"sha256": "639c4a4ff5d4b6a2b2e086560af422848a9d5db946951d1d340ccf560e332b3c"
},
"downloads": -1,
"filename": "project-structure-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8074b0f2b42383de5460980ba17d1dfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 165739,
"upload_time": "2023-10-31T21:41:40",
"upload_time_iso_8601": "2023-10-31T21:41:40.569483Z",
"url": "https://files.pythonhosted.org/packages/01/85/4d7db3e29b6edb9aeb9b7331e1d608b1f0e97958a3423c5e6093c15dc977/project-structure-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 21:41:40",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "rpatterson",
"gitlab_project": "project-structure",
"lcname": "project-structure"
}
JSON