{"id":13738364,"url":"https://github.com/joaomcteixeira/python-project-skeleton","last_synced_at":"2025-03-22T13:31:23.074Z","repository":{"id":39742187,"uuid":"212405880","full_name":"joaomcteixeira/python-project-skeleton","owner":"joaomcteixeira","description":"An up-to-date and explanatory Python project skeleton with continuous integration services.","archived":false,"fork":false,"pushed_at":"2024-04-04T14:20:07.000Z","size":263,"stargazers_count":80,"open_issues_count":5,"forks_count":17,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-04T03:12:22.853Z","etag":null,"topics":["ci","continuous-integration","project-skeleton","project-structure","python","python-library","python3","readthedocs"],"latest_commit_sha":null,"homepage":"https://python-project-skeleton.readthedocs.io","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/joaomcteixeira.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-10-02T17:52:46.000Z","updated_at":"2024-07-05T09:08:49.000Z","dependencies_parsed_at":"2024-01-12T18:26:25.729Z","dependency_job_id":"8e85747f-6023-4d9e-a7d4-30f557789475","html_url":"https://github.com/joaomcteixeira/python-project-skeleton","commit_stats":null,"previous_names":[],"tags_count":36,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaomcteixeira%2Fpython-project-skeleton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaomcteixeira%2Fpython-project-skeleton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaomcteixeira%2Fpython-project-skeleton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaomcteixeira%2Fpython-project-skeleton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joaomcteixeira","download_url":"https://codeload.github.com/joaomcteixeira/python-project-skeleton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221829984,"owners_count":16887720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ci","continuous-integration","project-skeleton","project-structure","python","python-library","python3","readthedocs"],"created_at":"2024-08-03T03:02:20.193Z","updated_at":"2024-10-28T12:57:01.943Z","avatar_url":"https://github.com/joaomcteixeira.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Python Package Skeleton Template\n================================\n\n.. image:: https://github.com/joaomcteixeira/python-project-skeleton/workflows/ci/badge.svg?branch=main\n    :target: https://github.com/joaomcteixeira/python-project-skeleton/actions?workflow=ci\n    :alt: CI\n\n.. image:: https://codecov.io/gh/joaomcteixeira/python-project-skeleton/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/joaomcteixeira/python-project-skeleton\n    :alt: Codecov\n\n.. image:: https://api.codeclimate.com/v1/badges/d96cc9a1841a819cd4f5/maintainability\n   :target: https://codeclimate.com/github/joaomcteixeira/python-project-skeleton/maintainability\n   :alt: Maintainability\n\n.. image:: https://img.shields.io/codeclimate/tech-debt/joaomcteixeira/python-project-skeleton\n    :target: https://codeclimate.com/github/joaomcteixeira/python-project-skeleton\n    :alt: Code Climate technical debt\n\n.. image:: https://img.shields.io/readthedocs/python-project-skeleton/latest?label=Read%20the%20Docs\n    :target: https://python-project-skeleton.readthedocs.io/en/latest/index.html\n    :alt: Read the Docs\n\nSummary\n-------\n\nThis repository is a **skeleton template** for a **Python application/library**\ncompliant with the latest team-development and software deployment practices\nwithin a continuous integration (CI) framework. You can use this repository as a\nsource of information and a resource to study CI. Also, you can use this\nrepository as a direct template for your repositories.\n\n**Note** that this repository reflects the setup I like the most and that covers\nthe CI needs for my Python projects, which include:\n\n* A robust Python library/application file hierarchy with packages, modules, clients, and documentation:\n    * detailed, yet simple, ``setup.py``\n    * retrievable ``README`` and ``CHANGELOG``\n    * documentation deployed in `ReadTheDocs`_\n    * the unusual adoption of the ``src`` directory layer (love it)\n    * examples of packages and modules hierarchy\n    * examples of Python command-line interfaces\n* A unique testing framework for developers with `tox`_ and `pytest`_\n    * guarantees tests are reproducible for all developers\n    * ensures same lint rules are always applied (local and remotely)\n    * ensures all desired Python versions are covered\n    * adopts `hypothesis`_\n* Fully automated continuous integration services with `GitHub Actions`_\n    * automatic testing on Linux, MacOS, and Windows\n    * automatic testing simulated upon deployment with ``tox``\n    * test coverage report to Codecov\n    * automated version bump with `bump2version`_, git tagging, and Python packaging to PyPI on Pull Request merge\n\nMotivation\n----------\n\nI developed this repository to understand how to implement the best practices\nfor team-based development and automatic deployment of a scientific software\nwritten in Python. Nonetheless, I believe the strategy reviewed here can be\napplied to most general-purpose Python libraries.\n\nThis repository does **not** intend to be a `cookiecutter`_-like repository.\nThere are very well documented cookiecutters, `even for scientific software`_,\nif you are looking for one of those. However, when I started developing Python\nlibraries, I decided that blindly using a cookiecutter would not provide me the\nlearning insights from configuring CI services because I would miss the details\nof what was actually being implemented. Hence, assembling this *template* from\nscratch as a full working repository was my best approach to obtain a useful\nunderstanding of CI.  Now, this repository serves as a reference guide for all\nmy projects and hopefully will serve you, too. I keep constantly updating this\nrepository, expect one to two updates/reviews per year.\n\nAcknowledgments\n---------------\n\nI want to acknowledge `ionel`_ discussions about *Packaging a python library*.\nThey are a pillar in my understanding and decisions on this matter, and I really\nrecommend reading his `blog post`_ and references herein.\n\nI configured the CI pipeline to my needs by taking bits and pieces from many\nplaces. Kudos to `python-nameless`_ and `cookiecutter-pylibrary`_; two primary\nsources of information for the *python-project-skeleton* repository, especially\nin the first versions using Travis and Appveyor.\n\nWhen migrating to GitHub Actions, I based my choices on the version bump and\ndeploying workflows `@JoaoRodrigues \u003chttps://github.com/JoaoRodrigues\u003e`_\nassembled for `pdb-tools`_; on the `tox-gh-actions`_ package; and on\n`structlog`_. Implementation details have evolved with newest versions.\n\nI refer to other important sources of information as comments in the specific\nfiles. Thanks, everyone, for keeping open discussions on internet.\n\nHow to use this repository\n--------------------------\n\nThe `documentation`_ pages explain how to use this template for your projects\nand the implementation details adopted here. The documentation pages also serve\nto demonstrate how to compile documentation with Sphinx and deploy it online\nwith `ReadTheDocs`_.\n\nIssues and Discussions\n----------------------\n\nAs usual for any GitHub-based project, raise an `issue`_ if you find any bug or\nwant to suggest an improvement, or open a `discussion`_ if you want to discuss\nor chat :wink:\n\nProjects using this skeleton\n----------------------------\n\nBelow, a list of the projects using this repository as template or as base for\ntheir CI implementations:\n\n* `julie-forman-kay-lab/IDPConformerGenerator \u003chttps://github.com/julie-forman-kay-lab/IDPConformerGenerator\u003e`_\n* `haddocking/HADDOCK3 \u003chttps://github.com/haddocking/haddock3\u003e`_\n* `THGLab/MCSCE \u003chttps://github.com/THGLab/MCSCE\u003e`_\n* `joaomcteixeira/taurenmd \u003chttps://github.com/joaomcteixeira/taurenmd\u003e`_\n* `MDAnalysis/mdacli \u003chttps://github.com/MDAnalysis/mdacli\u003e`_\n\nIf you use this repository as a reference for your works, let me know, so I\nlist your work above, as well.\n\nVersion\n-------\n\nv0.11.3\n\n.. _GitHub Actions: https://github.com/features/actions\n.. _PyPI: https://pypi.org\n.. _blog post: https://blog.ionelmc.ro/2014/05/25/python-packaging/\n.. _bump2version: https://github.com/c4urself/bump2version\n.. _cookiecutter-pylibrary: https://github.com/ionelmc/cookiecutter-pylibrary\n.. _cookiecutter: https://cookiecutter.readthedocs.io/en/latest/index.html\n.. _discussion: https://github.com/joaomcteixeira/python-project-skeleton/discussions\n.. _documentation: https://python-project-skeleton.readthedocs.io/\n.. _even for scientific software: https://github.com/MolSSI/cookiecutter-cms\n.. _hypothesis: https://hypothesis.readthedocs.io/en/latest/\n.. _ionel: https://github.com/ionelmc\n.. _issue: https://github.com/joaomcteixeira/python-project-skeleton/issues\n.. _latest branch: https://github.com/joaomcteixeira/python-project-skeleton/tree/latest\n.. _master branch: https://github.com/joaomcteixeira/python-project-skeleton/tree/master\n.. _pdb-tools: https://github.com/haddocking/pdb-tools/blob/2a070bbacee9d6608b44bb6d2f749beefd6a7690/.github/workflows/bump-version-on-push.yml\n.. _project's documentation: https://python-project-skeleton.readthedocs.io/en/latest/index.html\n.. _pytest: https://docs.pytest.org/en/stable/\n.. _python-nameless: https://github.com/ionelmc/python-nameless\n.. _structlog: https://github.com/hynek/structlog\n.. _test.pypi.org: https://test.pypi.org\n.. _tox-gh-actions: https://github.com/ymyzk/tox-gh-actions\n.. _tox: https://tox.readthedocs.io/en/latest/\n.. _ReadTheDocs: https://readthedocs.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaomcteixeira%2Fpython-project-skeleton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoaomcteixeira%2Fpython-project-skeleton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaomcteixeira%2Fpython-project-skeleton/lists"}