{"id":18295869,"url":"https://github.com/astropenguin/demo-python-package","last_synced_at":"2025-04-09T08:41:49.801Z","repository":{"id":37222535,"uuid":"203070693","full_name":"astropenguin/demo-python-package","owner":"astropenguin","description":":gift: A repository to demonstrate the development of a Python package","archived":false,"fork":false,"pushed_at":"2022-12-08T03:15:31.000Z","size":6369,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-15T02:44:20.646Z","etag":null,"topics":["black","codecov","demo","flake8","python","sphinx","travis-ci"],"latest_commit_sha":null,"homepage":"https://astropenguin.github.io/demo-python-package","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/astropenguin.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":"2019-08-19T00:23:39.000Z","updated_at":"2021-11-11T10:33:25.000Z","dependencies_parsed_at":"2023-01-25T03:45:11.046Z","dependency_job_id":null,"html_url":"https://github.com/astropenguin/demo-python-package","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fdemo-python-package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fdemo-python-package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fdemo-python-package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fdemo-python-package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astropenguin","download_url":"https://codeload.github.com/astropenguin/demo-python-package/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008198,"owners_count":21032549,"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":["black","codecov","demo","flake8","python","sphinx","travis-ci"],"created_at":"2024-11-05T14:38:36.802Z","updated_at":"2025-04-09T08:41:49.784Z","avatar_url":"https://github.com/astropenguin.png","language":"Python","readme":"# demo-python-package\n\n[![Travis CI](https://img.shields.io/travis/astropenguin/demo-python-package/master.svg?label=Travis%20CI\u0026style=flat-square)](https://travis-ci.org/astropenguin/demo-python-package)\n[![Codecov](https://img.shields.io/codecov/c/github/astropenguin/demo-python-package?label=Codecov\u0026style=flat-square)](https://codecov.io/gh/astropenguin/demo-python-package)\n[![linting](https://img.shields.io/badge/Linting-Flake8-orange?style=flat-square)](http://flake8.pycqa.org/en/latest)\n[![Formatting](https://img.shields.io/badge/Formatting-Black-333?style=flat-square)](https://black.readthedocs.io/en/stable)\n[![Testing](https://img.shields.io/badge/Testing-pytest-yellow?style=flat-square)](https://docs.pytest.org/en/latest)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?label=License\u0026style=flat-square)](LICENSE)\n\n:gift: A repository to demonstrate the development of a Python package\n\n## Overview\n\nThis repository demonstrates a way to develop a well-formatted and well-tested Python package using CI/CD.\nWith a simple `demo` Python package, the following essential (but laborious) processes are automatically run by [Travis CI] in the cloud, which enables developers to keep focusing on the development of the package itself.\n\n- code linting (by [Flake8])\n- code formatting (by [Black])\n- code testing (by [pytest])\n- code coverage (by [Codecov])\n- documentation building (by [Sphinx])\n- documentation hosting (by [GitHub Pages])\n\n## Local Python environment\n\nThis repository has [Pipenv] files (`Pipfile` and `Pipfile.lock`) which describe a specific Python version and dependent packages.\nAfter cloning the repository to local, you can initialize a Python environment as follows:\n\n```bash\n$ git clone https://github.com/astropenguin/demo-python-package.git\n$ cd demo-python-package\n$ pipenv install --dev\n```\n\nNote that the following examples are assumed to be run in a virtual environment created by Pipenv:\n\n```bash\n$ pipenv shell # enter a virtual environment\n(demo-python-package) $\n```\n\n## Code linting by Flake8\n\n[Flake8] is a linter which checks that the source code follows the Python style guide.\nThe following command checks all the code in the `demo` package:\n\n```bash\n$ flake8 demo\n$ # nothing is output if no errors\n```\n\n## Code formatting by Black\n\n[Black] is a formatter which (forcibly) reformats the source code according to [the Black code style](https://black.readthedocs.io/en/stable/the_black_code_style.html).\nThe following command reformats all the code in the `demo` package **in place**:\n\n```bash\n$ black demo\nAll done! ✨ 🍰 ✨\n1 file would be left unchanged.\n$\n```\n\nIf you want to just check them, run with `--check` option:\n\n```bash\n$ black --check demo\nAll done! ✨ 🍰 ✨\n1 file would be left unchanged.\n$\n```\n\n## Code testing by pytest\n\n[pytest] runs all test scripts in the `tests` directory.\nBefore using it, you need to install the `demo` package by pip so that the scripts can find the path of the package:\n\n```bash\n$ pip install -e .\n$ pytest\n========================= test session starts =========================\nplatform darwin -- Python 3.7.3, pytest-5.1.1, py-1.8.0, pluggy-0.12.0\nrootdir: /path/to/demo-python-package\nplugins: cov-2.7.1\ncollected 2 items\n\ntests/test_version.py ..                                        [100%]\n\n========================== 2 passed in 0.02s ==========================\n$\n```\n\n## Code coverage by Codecov\n\n[Codecov] calculates the fraction of the code that are tested to the whole code (often called code coverage), which is a useful indicator that the package is well-tested or not.\nThe code coverage is calculated by pytest with `--cov` option:\n\n```bash\n$ pytest --cov demo\n========================= test session starts =========================\nplatform darwin -- Python 3.7.3, pytest-5.1.1, py-1.8.0, pluggy-0.12.0\nrootdir: /path/to/demo-python-package\nplugins: cov-2.7.1\ncollected 2 items\n\ntests/test_version.py ..                                        [100%]\n\n---------- coverage: platform darwin, python 3.7.3-final-0 -----------\nName               Stmts   Miss  Cover\n--------------------------------------\ndemo/__init__.py       3      0   100%\n\n========================== 2 passed in 0.05s ==========================\n$\n```\n\n## Documentation building by Sphinx\n\n[Sphinx] is a document builder written in Python.\nIn this repository, it generates an HTML document that describes the usage of the package functions, classes, etc based on the docstrings of them.\nIn the local environment, you can generate the document by the following commands:\n\n```bash\n$ sphinx-apidoc -f -o docs/_apidoc demo\n$ sphinx-build docs docs/_build\n$ sphinx-build docs docs/_build\n```\n\n## Documentation hosting by GitHub Pages\n\nOnce the document is created, it is hosted by [GitHub Pages].\nThe document is then pushed to the `gh-pages` branch by [Travis CI].\nSee `.travis.yml` for more details.\n\n## Useful tips\n\n### VS Code settings\n\nIf you use VS Code, the following settings (to be written in `.vscode/settings.json`) enables the editor integration of Black and Flake8.\nThis would be useful to check linting and do formatting of the package on the spot.\nNote that you need to install [the Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) to VS Code.\n\n```jsonc\n{\n    // auto formatting by Black\n    \"editor.formatOnType\": true,\n    \"python.formatting.provider\": \"black\",\n    // auto linting by Flake8\n    \"python.linting.enabled\": true,\n    \"python.linting.lintOnSave\": true,\n    \"python.linting.flake8Enabled\": true,\n    \"python.linting.pylintEnabled\": false,\n}\n```\n\n### Linting and formatting before commit\n\nIf you want to make sure that the code follows Flake8 and Black before you commit, [pre-commit] and the following settings (to be written in `.pre-commit-config.yaml`) is useful.\nThis will check linting and formatting of the code you stage before you commit and the commit will be passed only when Black and Flake8 finish with the status code 0.\n\n```yaml\nrepos:\n  - repo: https://github.com/ambv/black\n    rev: stable\n    hooks:\n      - id: black\n        language_version: python3.7\n  - repo: https://gitlab.com/pycqa/flake8\n    rev: 3.7.8\n    hooks:\n      - id: flake8\n```\n\nNote that you need to run the following command before you use the feature.\n\n```bash\n$ pre-commit install\n```\n\n## References\n\n- [Travis CI]\n    - [Build Stages \\- Travis CI](https://docs.travis-ci.com/user/build-stages)\n    - [Job Lifecycle \\- Travis CI](https://docs.travis-ci.com/user/job-lifecycle)\n- [Flake8]\n    - [Using Version Control Hooks — flake8 3\\.7\\.8 documentation](http://flake8.pycqa.org/en/latest/user/using-hooks.html)\n    - [black/\\.flake8 at master · psf/black](https://github.com/psf/black/blob/master/.flake8)\n- [Black]\n    - [Version control integration — Black 19\\.3b0 documentation](https://black.readthedocs.io/en/stable/version_control_integration.html)\n    - [Editor integration — Black 19\\.3b0 documentation](https://black.readthedocs.io/en/stable/editor_integration.html)\n- [Sphinx]\n    - [Getting Started — Sphinx 2\\.3\\.0 documentation](https://www.sphinx-doc.org/en/2.0/usage/quickstart.html)\n    - [Support for NumPy and Google style docstrings — Sphinx 2\\.3\\.0 documentation](https://www.sphinx-doc.org/en/2.0/usage/extensions/napoleon.html)\n- [Codecov]\n    - [codecov/example\\-python: Python coverage example](https://github.com/codecov/example-python)\n- [GitHub Pages]\n    - [GitHub Pages Deployment \\- Travis CI](https://docs.travis-ci.com/user/deployment/pages/)\n- [pytest]\n    - [Installing and Using plugins — pytest documentation](https://docs.pytest.org/en/latest/plugins.html)\n- [pre-commit]\n    - [pre\\-commit](https://pre-commit.com/hooks.html)\n- [Pipenv]\n\n[Travis CI]: https://travis-ci.org\n[Flake8]: http://flake8.pycqa.org/en/latest\n[Black]: https://black.readthedocs.io/en/stable\n[pytest]: https://docs.pytest.org/en/latest\n[Codecov]: https://codecov.io\n[Sphinx]: http://www.sphinx-doc.org/en/master\n[GitHub Pages]: https://pages.github.com\n[Pipenv]: https://pipenv.readthedocs.io/en/latest\n[pre-commit]: https://pre-commit.com/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropenguin%2Fdemo-python-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastropenguin%2Fdemo-python-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropenguin%2Fdemo-python-package/lists"}