{"id":19507401,"url":"https://github.com/radonirinaunimi/python-template","last_synced_at":"2025-02-25T22:26:20.978Z","repository":{"id":52593235,"uuid":"275644763","full_name":"Radonirinaunimi/python-template","owner":"Radonirinaunimi","description":"Python project template 🐍.","archived":false,"fork":false,"pushed_at":"2021-04-24T09:07:28.000Z","size":1529,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-08T11:19:04.109Z","etag":null,"topics":["coverage","development-workflow","documentation","python","python-template","sphinx","template-repository","unittest"],"latest_commit_sha":null,"homepage":"","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/Radonirinaunimi.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2020-06-28T18:28:21.000Z","updated_at":"2021-06-08T06:44:13.000Z","dependencies_parsed_at":"2022-09-06T20:50:30.776Z","dependency_job_id":null,"html_url":"https://github.com/Radonirinaunimi/python-template","commit_stats":null,"previous_names":[],"tags_count":2,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Radonirinaunimi%2Fpython-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Radonirinaunimi%2Fpython-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Radonirinaunimi%2Fpython-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Radonirinaunimi%2Fpython-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Radonirinaunimi","download_url":"https://codeload.github.com/Radonirinaunimi/python-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240756573,"owners_count":19852593,"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":["coverage","development-workflow","documentation","python","python-template","sphinx","template-repository","unittest"],"created_at":"2024-11-10T22:42:51.165Z","updated_at":"2025-02-25T22:26:20.927Z","avatar_url":"https://github.com/Radonirinaunimi.png","language":"Python","readme":"\u003ctable style=\"width:100%\"\u003e\n  \u003ctr\u003e\n    \u003ctd rowspan=\"2\" style=\"width:50px\"\u003e\n      \u003cimg alt=\"Logo\" src=\"https://github.com/Radonirinaunimi/python-template/blob/master/logo/logo.png\" width=100%\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg src=\"https://img.shields.io/badge/python_template-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\"/\u003e\n      \u003cimg src=\"https://img.shields.io/badge/LICENSE:_MIT-ED1C24?style=for-the-badge\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e \n      \u003cp align=\"justify\"\u003e\n        \u003cb\u003epytemplate\u003c/b\u003e serves as a general template to start a python project. It aims to automate the development workflow: from \n        packaging the code, generating documentation, versioning, deploying and releasing the package.\n      \u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Description\n\nThe development workflow is based on the following steps:\n\u003cp align=\"justify\"\u003e\n  \u003cb\u003e Packaging \u003c/b\u003e 📦\n  The packaging of the distribution is managed by the \n  \u003ca href=\"https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/introduction.html\"\u003eDistribution Utilities\u003c/a\u003e (Disutils).\n  This allows users (or developers) to easily install the package (or to simulate the installation by adding a symbolic link for easy debug) \n  into a particular environment.\n\u003c/p\u003e\n\n\u003cp align=\"justify\"\u003e\n  \u003cb\u003e Continuous testing \u003c/b\u003e 🛠️\n  For stability, the modules of the packaged-library can be automatically tested using \u003cb\u003epytest\u003c/b\u003e. This helps prevent breaking the code \n  when new features are added. These tests can be run as github-actions when the events are triggered (as will be detailed further). The \n  coverage of the tests can then be assessed afterward; the more modules undergo testing the less likely bugs occur. Refer to the web\n  \u003ca href=\"https://docs.pytest.org/en/stable/\"\u003edocumentation\u003c/a\u003e for further details on how to use pytest for testing.\n\u003c/p\u003e\n\n\u003cp align=\"justify\"\u003e\n  \u003cb\u003e Documentation \u003c/b\u003e 📚\n  The documentation of nodules is built using the following \n  \u003ca href=\"https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/introduction.html\"\u003estyle\u003c/a\u003e with \u003cb\u003esphinx\u003c/b\u003e. To \n  familiarize with sphinx, have a look at the following \u003ca href=\"https://www.sphinx-doc.org/en/master/usage/quickstart.html\"\u003edocumentation\u003c/a\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"justify\"\u003e\n  \u003cb\u003e Deploying docs and Publishing to PyPI \u003c/b\u003e 🚀\n  Finally, all of the above can be integrated within github using \u003ca href=\"https://docs.pytest.org/en/stable/\"\u003egithub actions\u003c/a\u003e\n  \u003ca href=\"https://github.blog/2019-08-08-github-actions-now-supports-ci-cd/\"\u003eCI/CD\u003c/a\u003e. This allows one to test the package at every \n  push (for instance) and deploys the documentation. The follwoing \n  \u003ca href=\"https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions\"\u003edocumentation\u003c/a\u003e explains the syntax for writting \n  a github action.\n\u003c/p\u003e\n\n\n## How to use this template\n\n### Setting up ⚙️\n\n\u003cp align=\"justify\"\u003e\n  In order to use this template, first, click on \u003ca href=\"https://github.com/Radonirinaunimi/python-template/generate\"\u003euse this template\u003c/a\u003e. \n  Then, replace all mentions of package_name in the following files \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/setup.py#L16\"\u003e\n  setup.py\u003c/a\u003e, \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/doc/Makefile#L12\"\u003eMakefile\u003c/a\u003e, \n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/.github/workflows/test_modules.yml\"\u003etest_modules.yml\u003c/a\u003e, \n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/doc/source/conf.py#L14\"\u003econf.py\u003c/a\u003e by the \u003cb\u003ename\u003c/b\u003e of the package. \n  The next step is to add the requierements the package is depending to \n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/requirements.txt\"\u003erequirements.txt\u003c/a\u003e. Essentially, these the only things \n  one need to package the distribution. The package is now ready for installation by running the following:  \n\u003c/p\u003e\n\n```bash\npython setup.py install [--user]\n```\nor alternatively (if you are a developer) by adding symbolic links which immediately reflects the changes after every save:\n```bash\npython setup.py develop [--user]\n```\n\n### Checking, formatting and testing the code\n\n\u003cp align=\"justify\"\u003e\n  Using static code analysis tools can be extremely helpful in terms of checking programming errors and enforcing coding standards. As an analysis tool,\n  this template uses \u003ca href=\"https://pylint.org/\"\u003epylint\u003c/a\u003e which is highly customazable. The default configurations are given in the\n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/.pylintrc\"\u003e.pylintrc\u003c/a\u003e file. To check a given python file, it suffices to\n  run:\n\u003c/p\u003e\n\n```bash\npylint \u003cpython_file\u003e.py\n```\n\n\u003cp align=\"justify\"\u003e\n  For an automated code formatting, one may also resort to \u003ca href=\"https://github.com/psf/black\"\u003eblack\u003c/a\u003e which is a very high efficient code\n  formatter. Finally, the test of the modules can be performed using \u003ca href=\"https://docs.pytest.org/en/6.2.x/\"\u003epytest\u003c/a\u003e. The test files can\n  be put inside the \u003ca href=\"https://github.com/Radonirinaunimi/python-template/tree/master/tests\"\u003etests\u003c/a\u003e. Then, to peform the tests, just run:\n\u003c/p\u003e\n\n```bash\npytest \u003cpython_file\u003e.py or pytest --cov=\u003cpackage_name\u003e tests/ (if you want to generare reports)\n```\n\n\n### Writing and building documentation 📘\n\n\u003cp align=\"justify\"\u003e\n  In order to adopt good practices for writing documentation, refer to the \u003ca href=\"https://docs.python-guide.org/writing/documentation/\"\u003efollowing\u003c/a\u003e\n  short guidelines. As default, this template uses \u003cb\u003esphinx\u003c/b\u003e as a python documentation tool which (for a local build) requires the installation of\n  \u003cb\u003esphinx\u003c/b\u003e and \u003cb\u003eshpinx_rtd_theme\u003c/b\u003e. For a deep dive into the sphinx tool, have a look at\n  \u003ca href=\"https://www.sphinx-doc.org/en/master/contents.html\"\u003ethis\u003c/a\u003e documentation.\n\u003c/p\u003e\n  \n\u003cp align=\"justify\"\u003e\n  In order to build the documentation in your local machine, go inside the \n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/tree/master/doc\"\u003edoc\u003c/a\u003e folder and run the following command:\n\u003c/p\u003e\n\n```bash\nmake html\n```\n\u003cp\u003e and to view the rendered document, just run: \u003c/p\u003e\n\n```bash\nmake view\n```\n\n### Tagging versions 🎉\n\n\u003cp align=\"justify\"\u003e\n  Semantic versioning is an important part in building packages. For the best practices in tagging versions, refer to the following\n  \u003ca href=\"https://semver.org/\"\u003edocumentation\u003c/a\u003e. As a version management tool, this templates uses \u003cb\u003ebump2version\u003c/b\u003e whose configuration\n  file is defined in .bumpversion.cfg. The current version is \u003cb\u003e0.1.0-dev\u003c/b\u003e, and in order to update if, run the following command:\n\u003c/p\u003e\n\n```bash\nbump2version minor # or major\n```\n\nFor more details about the configuration of bump2version, head on to this \u003ca href=\"https://github.com/c4urself/bump2version\"\u003egithub repository\u003c/a\u003e.\n\n\n## Automating pipeline with github actions 🛡️\n\n\u003cp align=\"justify\"\u003e\n  Before pushing to the github , make sure to modify the actions in the \n  \u003ca href=\"https://github.com/Radonirinaunimi/python-template/blob/master/.github/workflows/\"\u003eworkflows\u003c/a\u003e folder. Specifically, one must replace \n  the value \u003cb\u003enever\u003c/b\u003e in the \u003cb\u003ebranches\u003c/b\u003e entry. For instance, one can choose \u003cb\u003eon: push\u003c/b\u003e to run the actions whenever a new implementation \n  is pushed on any \u003cb\u003ebranches\u003c/b\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"justify\"\u003e\n  In order to deploy the documentation, the GITHUB_SECRETS must be replaced by your own \u003cb\u003esecrets\u003c/b\u003e,\n\u003c/p\u003e \n\n```yaml\n    - name: Deploy 🚀\n      ...\n        ACCESS_TOKEN: ${{ secrets.GITHUB_SECRETS }}\n```\n\n\u003cp align=\"justify\"\u003e\n  Check this \u003ca href=\"https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token\"\u003edocumentation\u003c/a\u003e to learn how \n  to generate github-tokens, and the \u003ca href=\"https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets\"\u003e\n  following\u003c/a\u003e on how to add tokens to \u003cb\u003esecrets\u003c/b\u003e. The \u003cb\u003ePyPI token\u003c/b\u003e has to be generated from \n  \u003ca href=\"https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/\"\u003ehere\u003c/a\u003e by creating and\n  account and added to the repository in the same way as for the documentation. Similarly, the \u003cb\u003eCodecov token\u003c/b\u003e can be generated from \n  \u003ca href=\"https://codecov.io/gh\"\u003ehere\u003c/a\u003e for a specific repository.\n\u003c/p\u003e\n\n\n## Useful links\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e Awesome python \u003c/td\u003e\n    \u003ctd\u003e \u003ca href=\"https://github.com/vinta/awesome-python\"\u003egithub\u003c/a\u003e | \u003ca href=\"https://awesome-python.com/)\"\u003ewebpage\u003c/a\u003e \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e All algorithms implemented in python \u003c/td\u003e\n    \u003ctd\u003e \u003ca href=\"https://github.com/TheAlgorithms/Python\"\u003egithub\u003c/a\u003e \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e PyGithub: Typed interactions with the GitHub API v3 \u003c/td\u003e\n    \u003ctd\u003e \u003ca href=\"https://github.com/PyGithub/PyGithub\"\u003egithub\u003c/a\u003e | \u003ca href=\"https://pygithub.readthedocs.io/\"\u003ewebpage\u003c/a\u003e \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n## Projects using this template\n\nWith **v.0.0.1** (as a proof of concept):\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e \u003cb\u003ePackage\u003c/b\u003e \u003c/td\u003e\n    \u003ctd\u003e \u003cb\u003eDescription\u003c/b\u003e  \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e \u003ca href=\"https://github.com/Radonirinaunimi/Style-Transfer\"\u003eTimst\u003c/b\u003e \u003c/td\u003e\n    \u003ctd\u003e Image style transfer using pyTorch. \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e \u003ca href=\"https://github.com/Radonirinaunimi/pwnd-check\"\u003eCheckPwd\u003c/b\u003e \u003c/td\u003e\n    \u003ctd\u003e Python package that checks if your credentials have been leaked to the web. \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradonirinaunimi%2Fpython-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradonirinaunimi%2Fpython-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradonirinaunimi%2Fpython-template/lists"}