{"id":28513020,"url":"https://github.com/sarnold/simple-python-project","last_synced_at":"2026-04-19T15:05:03.760Z","repository":{"id":297846005,"uuid":"998063984","full_name":"sarnold/simple-python-project","owner":"sarnold","description":"Template for setuptools project with workflow automation","archived":false,"fork":false,"pushed_at":"2026-04-08T20:17:54.000Z","size":2865,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T22:21:48.938Z","etag":null,"topics":["actions","automation","doorstop","packaging","python","setuptools","workflows"],"latest_commit_sha":null,"homepage":"https://sarnold.github.io/simple-python-project/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sarnold.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-07T19:38:22.000Z","updated_at":"2026-04-08T20:17:58.000Z","dependencies_parsed_at":"2025-07-16T11:32:15.585Z","dependency_job_id":"ed5b1cb6-be60-4551-baa8-70eb770921a8","html_url":"https://github.com/sarnold/simple-python-project","commit_stats":null,"previous_names":["sarnold/simple-python-project"],"tags_count":3,"template":true,"template_full_name":null,"purl":"pkg:github/sarnold/simple-python-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarnold%2Fsimple-python-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarnold%2Fsimple-python-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarnold%2Fsimple-python-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarnold%2Fsimple-python-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sarnold","download_url":"https://codeload.github.com/sarnold/simple-python-project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarnold%2Fsimple-python-project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32010960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","automation","doorstop","packaging","python","setuptools","workflows"],"created_at":"2025-06-09T01:05:57.367Z","updated_at":"2026-04-19T15:05:03.695Z","avatar_url":"https://github.com/sarnold.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Simple Python Project\n=====================\n\nPython project using simple setuptools project config; note package\ndata, scripts, entry points, etc, **all still work** using pyproject.toml\nper `setuptools documentation`_.\n\nTo create a new repository using this template, click the button labeled\n**Use this template** and select **Create a new repository**.\n\n|ci| |wheels| |bandit| |release|\n\n|pre| |cov| |pylint|\n\n|tag| |license| |reuse| |python|\n\nTemplate repo cleanup\n~~~~~~~~~~~~~~~~~~~~~\n\nAfter creating your repository, replace the example project name \"simple\"\nwith your own:\n\n* change the project name at the top of ``pyproject.toml``\n* change the project name in ``docs/source/conf.py`` *and* ``docs/source/index.rst``\n* change the author and copyright names in all the doorstop doc and config files, ie\n\n  + ``find . -name .doorstop.yml`` and review/edit all files\n\n* then replace all the doorstop content with your own project details\n* create more doorstop items as needed, link specific design and test\n  elements back to related **Shall** statements\n* change the author details in ``pyproject.toml`` *and* ``docs/source/conf.py``\n* change the package directory name under the ``src`` folder\n* change the github URL paths in ``pyproject.toml``\n\nMake a ``badges`` branch\n------------------------\n\nCreate an orphan branch for Pylint and Coverage workflows. In a fresh\ncheckout, run the following commands::\n\n  $ git checkout --orphan badges\n  $ git reset --hard\n  $ git commit --allow-empty -m \"Initializing badges branch\"\n  $ git push origin badges\n  $ git checkout main\n\nMake a ``gh-pages`` branch\n--------------------------\n\nFollow the same steps shown above, changing the branch name to ``gh-pages``.\n\n\n.. _setuptools documentation: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html\n\nGithub workflows and setuptools_scm\n-----------------------------------\n\nThis project uses setuptools_scm_ for dynamic versioning, therefor some\nof the (github) workflows will look for a git tag to set the version in\nCI. If there are no tags, this will result in some failed workflow runs.\nThere are several options to make them succeed:\n\n* create a base tag, eg ``git tag -a 0.0.0``\n* set SETUPTOOLS_SCM_PRETEND_VERSION to the above value in the workflow env\n* disable failing workflows in the Github Actions tab\n* delete any workflows you don't need\n\n\nGithub workflows and repo settings\n----------------------------------\n\nSome of the automation workflows may also fail without some non-default\nrepository settings; the following changes are required to allow these\nworkflows to run.\n\nGo to the repository Settings tab and scroll to the bottom of the General\nsettings and enable these checkboxes under Pull Requests:\n\n* Always suggest updating pull request branches (optional)\n* Allow auto-merge (required)\n* Automatically delete head branches (optional)\n\nNext, in the left-hand menu under the Settings tab, click Actions, then General,\nthen scroll to Workflow permissions:\n\n* make sure *Read repository contents and packages permissions* is selected\n* enable the *Allow GitHub Actions to create and approve pull requests* checkbox,\n  then click Save\n\nIn addition, the provided dependabot config expects some issue labels, so open the\nproject URL below (using your new project name) and add the following new labels:\n\n**https://github.com/\u003cyour_name\u003e/\u003cproject_name\u003e/issues/labels**\n\n* actions\n* dependencies\n* packaging\n\n\nGithub best practices\n---------------------\n\nFinally, best practices for public repositories should include the following\nextra features:\n\n* under Advanced Security enable Code Scanning, Dependabot, Private\n  Vulnerability Reporting, and (default) Codeql config\n* under Rules =\u003e Rulesets add some branch protection rules with required\n  status checks\n\n\nDev tools\n~~~~~~~~~\n\nLocal tool dependencies to aid in development; install them for\nmaximum enjoyment.\n\nDoorstop\n--------\n\nInitial configurations and first-item doc stubs have been created in the\nfollowing directories::\n\n  $ tree reqs/ docs/swd/ tests/docs/\n  reqs/\n  ├── .doorstop.yml\n  └── REQ001.yml\n  docs/swd/\n  ├── assets\n  │   ├── .gitkeep\n  │   └── simple_dependency_graph.svg\n  ├── .doorstop.yml\n  └── SDD001.md\n  tests/docs/\n  ├── .doorstop.yml\n  └── TST001.yml\n\nThe doorstop tool has been added to project [dev] \"extras\" as well as the\ntox dev and docs environments. Use the \"dev\" environment for working with\ndoorstop_ documents, eg::\n\n  tox -e dev\n  source .venv/bin/activate\n  (.venv) doorstop\n  building tree...\n  loading documents...\n  validating items...\n  WARNING: SDD: SDD001: unreviewed changes\n\n  REQ\n  │\n  ├── TST\n  │\n  └── SDD\n\n\nPlease see the doorstop Quick Start for an overview of the relevant doorstop\ncommands. See the `rpmget project`_ for a more fleshed out real-world example\nof using doorstop_ and sphinx together.\n\n.. _doorstop Quick Start: https://doorstop.readthedocs.io/en/latest/getting-started/quickstart.html\n.. _doorstop: https://doorstop.readthedocs.io/en/latest/index.html\n.. _rpmget project: https://github.com/sarnold/rpmget\n\n\nTox\n---\n\nAs long as you have git and at least Python 3.8, then you can install\nand use tox_.  After cloning the repository, you can run the repo\nchecks with the ``tox`` command.  It will build a virtual python\nenvironment for each installed version of python with all the python\ndependencies and run the specified commands, eg:\n\n::\n\n  $ git clone https://github.com/sarnold/simple-python-project\n  $ cd simple-python-project/\n  $ tox -e py\n\nThe above will run the default test command using the (local) default\nPython version.  To specify the Python version and host OS type, run\nsomething like::\n\n  $ tox -e py311-linux\n\nTo build and check the Python package, run::\n\n  $ tox -e build,check\n\nFull list of additional ``tox`` commands:\n\n* ``tox -e dev`` build a python venv and install in editable mode\n* ``tox -e build`` build the python packages and run package checks\n* ``tox -e check`` install the wheel package from above\n* ``tox -e lint`` run ``pylint`` (somewhat less permissive than PEP8/flake8 checks)\n* ``tox -e mypy`` run mypy import and type checking\n* ``tox -e style`` run flake8 style checks\n* ``tox -e reuse`` run the ``reuse lint`` command and install sbom4python\n* ``tox -e changes`` generate a new changelog file\n\nTo build/lint the api docs, use the following tox commands:\n\n* ``tox -e docs`` build the documentation using sphinx and the api-doc plugin\n* ``tox -e ldocs`` run the Sphinx doc-link checking\n* ``tox -e cdocs`` run ``make clean`` in the docs build\n\n\nGitchangelog\n------------\n\nWe use gitchangelog_  to generate a changelog and/or release notes, as\nwell as the gitchangelog message format to help it categorize/filter\ncommits for tidier output.  Please use the appropriate ACTION modifiers\nfor important changes in Pull Requests.\n\nPre-commit\n----------\n\nThis repo is also pre-commit_ enabled for various linting and format\nchecks.  The checks run automatically on commit and will fail the\ncommit (if not clean) with some checks performing simple file corrections.\n\nIf other checks fail on commit, the failure display should explain the error\ntypes and line numbers. Note you must fix any fatal errors for the\ncommit to succeed; some errors should be fixed automatically (use\n``git status`` and ``git diff`` to review any changes).\n\nSee the following sections in the built docs for more information on\ngitchangelog and pre-commit.\n\nYou will need to install pre-commit before contributing any changes;\ninstalling it using your system's package manager is recommended,\notherwise install with pip into your usual virtual environment using\nsomething like::\n\n  $ sudo emerge pre-commit  --or--\n  $ pip install pre-commit\n\nthen install it into the repo you just cloned::\n\n  $ git clone git@github.com:sarnold/simple-python-project.git\n  $ cd simple-python-project/\n  $ pre-commit install\n\nIt's usually a good idea to update the hooks to the latest version::\n\n    pre-commit autoupdate\n\n\nSBOM and license info\n~~~~~~~~~~~~~~~~~~~~~\n\nThis project is now compliant with the REUSE Specification Version 3.3, so the\ncorresponding license information for all files can be found in the ``REUSE.toml``\nconfiguration file with license text(s) in the ``LICENSES/`` folder.\n\nRelated metadata can be (re)generated with the following tools and command\nexamples.\n\n* reuse-tool_ - REUSE_ compliance linting and sdist (source files) SBOM generation\n* sbom4python_ - generate SBOM with full dependency chain\n\nCommands\n--------\n\nUse tox to create the environment and run the lint command::\n\n  $ tox -e reuse                      # --or--\n  $ tox -e reuse -- spdx \u003e sbom.txt   # generate sdist files sbom\n\nNote you can pass any of the other reuse commands after the ``--`` above.\n\nUse the above environment to generate the full SBOM in text format::\n\n  $ source .tox/reuse/bin/activate\n  $ sbom4python --system --use-pip -o \u003cfile_name\u003e.txt\n\nBe patient; the last command above may take several minutes. See the\ndoc links above for more detailed information on the tools and\nspecifications.\n\n.. _Tox: https://github.com/tox-dev/tox\n.. _reuse-tool: https://github.com/fsfe/reuse-tool\n.. _REUSE: https://reuse.software/spec-3.3/\n.. _sbom4python: https://github.com/anthonyharrison/sbom4python\n.. _gitchangelog: https://github.com/sarnold/gitchangelog\n.. _pre-commit: http://pre-commit.com/\n.. _setuptools_scm: https://setuptools-scm.readthedocs.io/en/stable/\n\n\n.. |ci| image:: https://github.com/sarnold/simple-python-project/actions/workflows/ci.yml/badge.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/ci.yml\n    :alt: CI Status\n\n.. |wheels| image:: https://github.com/sarnold/simple-python-project/actions/workflows/wheels.yml/badge.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/wheels.yml\n    :alt: Wheel Status\n\n.. |badge| image:: https://github.com/sarnold/simple-python-project/actions/workflows/pylint.yml/badge.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/pylint.yml\n    :alt: Pylint Status\n\n.. |release| image:: https://github.com/sarnold/simple-python-project/actions/workflows/release.yml/badge.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/release.yml\n    :alt: Release Status\n\n.. |bandit| image:: https://github.com/sarnold/simple-python-project/actions/workflows/bandit.yml/badge.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/bandit.yml\n    :alt: Security check - Bandit\n\n.. |cov| image:: https://raw.githubusercontent.com/sarnold/simple-python-project/badges/main/test-coverage.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/coverage.yml\n    :alt: Test coverage\n\n.. |pylint| image:: https://raw.githubusercontent.com/sarnold/simple-python-project/badges/main/pylint-score.svg\n    :target: https://github.com/sarnold/simple-python-project/actions/workflows/pylint.yml\n    :alt: Pylint Score\n\n.. |license| image:: https://img.shields.io/badge/license-MIT-blue\n    :target: https://github.com/sarnold/simple-python-project/blob/main/LICENSE\n    :alt: License\n\n.. |tag| image:: https://img.shields.io/github/v/tag/sarnold/simple-python-project?color=green\u0026include_prereleases\u0026label=latest%20release\n    :target: https://github.com/sarnold/simple-python-project/releases\n    :alt: GitHub tag\n\n.. |python| image:: https://img.shields.io/badge/python-3.9+-blue.svg\n    :target: https://www.python.org/downloads/\n    :alt: Python\n\n.. |reuse| image:: https://img.shields.io/badge/REUSE-compliant-blue.svg\n    :target: https://reuse.software/spec-3.3/\n    :alt: REUSE status\n\n.. |pre| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\n    :target: https://github.com/pre-commit/pre-commit\n    :alt: pre-commit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarnold%2Fsimple-python-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsarnold%2Fsimple-python-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarnold%2Fsimple-python-project/lists"}