{"id":20766229,"url":"https://github.com/datapuzzler/python_package_starter","last_synced_at":"2026-04-19T22:32:40.593Z","repository":{"id":136869819,"uuid":"363694182","full_name":"dataPuzzler/python_package_starter","owner":"dataPuzzler","description":"A boilerplate repository for python package development","archived":false,"fork":false,"pushed_at":"2021-08-08T12:02:28.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-26T10:47:59.401Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dataPuzzler.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-02T16:14:41.000Z","updated_at":"2021-08-08T12:02:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"7037d770-6b17-4b6d-b930-dcb28cef0199","html_url":"https://github.com/dataPuzzler/python_package_starter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dataPuzzler/python_package_starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataPuzzler%2Fpython_package_starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataPuzzler%2Fpython_package_starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataPuzzler%2Fpython_package_starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataPuzzler%2Fpython_package_starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dataPuzzler","download_url":"https://codeload.github.com/dataPuzzler/python_package_starter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dataPuzzler%2Fpython_package_starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32025702,"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":[],"created_at":"2024-11-17T11:22:07.732Z","updated_at":"2026-04-19T22:32:40.575Z","avatar_url":"https://github.com/dataPuzzler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Run unittests](https://github.com/dataPuzzler/python_package_starter/actions/workflows/unit-tests.yml/badge.svg?branch=master\u0026event=push)](https://github.com/dataPuzzler/python_package_starter/actions/workflows/unit-tests.yml)\n# Python Package Starter\n\nThe python_package_starter can be used as starting point for the development of a python package, that can be deployed to PyPi or installed locally via pip.\nIt includes the following features:\n\n- [Python inside a virtual environment](#virtual-env)\n- [A (sample) python package](#sample-package)\n- [Automatic Loading of Environment Variables](#env-var-loading)\n- [Unit-testing via pytest](#unit-testing)\n- [Automated Testing via Github Workflows](#ci)\n- [Code linting via flake8](#code-linting)\n- [Static Type-checking via mypy](#type-check)\n- [Documentation generation via Sphinx with auto-doc setup](#code-docu)\n\n\nInstructions how to work with each of this components is provided in more detail in the following sections.\n\nThe project should be understood as **opinionated**. It is primarily based on my own experience in developing python packages.\nFurthermore, I relied on the advice given by the [Python Packaging Authority (PyPA)](https://packaging.python.org/guides/distributing-packages-using-setuptools/) and used the excellent [Flask](https://github.com/pallets/flask) project as primary reference for established 'best practices'. The structure and content of this document was also inspired by [py-package-template](https://github.com/AlexIoannides/py-package-template).\n\n\n## Project Setup\n\n### Prerequisites \u003ca name=\"prereq\"\u003e\u003c/a\u003e\n- It is assumed that Python 3.9.x is 'globally' installed on your system and available on your cmd search path.\n- It is assumed that git 2.x.x is installed on your system and available on your cmd search path.\n\n\n### Installing pipenv globally\n[Pipenv](https://docs.pipenv.org) is used as the tool of choice to manage virtual environments and project package dependencies. You can install \nit globally on your system with:\n\n```bash\npip3 install pipenv\n```\nFor more information, including advanced configuration options, see the [official pipenv documentation](https://docs.pipenv.org).\n\n### Clone the project  \n\nClone this repository into a directory of your choice via\n```bash\ngit clone https://github.com/dataPuzzler/python_package_starter.git \u003cYour_Project_Name\u003e\ncd \u003cYour_Project_Name\u003e\n```\n\n### Install project dependencies into a virtual environment\nInside `\u003cYour_Project_Name\u003e`, run the following command:\n\n```bash\npipenv install --dev\n```\n\nThis will create a virtual python environment into `\u003cYour_Project_Name\u003e/.venv` and install all project dependencies (incl. dev dependencies) into it.\n\nAll of the direct packages dependencies required to run the project's code (e.g. multilevel_py), as well as all the packages used during development (e.g. flake8 for code linting and IPython for interactive console sessions), are described in the `Pipfile`. Their precise downstream dependencies are fixed in `Pipfile.lock`, which is used to guarentee repeatable (i.e. deterministic) builds.\n\n\n## Application of project and related tools\n\n### Running Python and IPython from the Project's Virtual Environment\u003ca name=\"virtual-env\"\u003e\u003c/a\u003e\n\nIn order to open a Python REPL using within an environment that precisely mimics projects virtual environment, use Pipenv from the command line as follows,\n\n```bash\npipenv run python3\n```\n\nFor use of an interactive python session, run the previous command with `ipython3` instead of `python3`.\n\n### Pipenv Shells\n\nPrepending `pipenv` to every command you want to run within the context of your Pipenv-managed virtual environment is tedious. This can be avoided by entering a Pipenv-managed shell.\n\n```bash\npipenv shell\n```\n\nWhich is equivalent to 'activating' the virtual environment. Any command will now be executed within the virtual environment. That means instead of `pipenv run \u003cANY_CMD\u003e` it suffices to run `\u003cANY_CMD\u003e` inside an active shell session.\n\nUse `exit` to leave the shell session.\n\n\n\n### Automatic Loading of Environment Variables \u003ca name=\"env-var-loading\"\u003e\u003c/a\u003e\n\nPipenv will automatically pick-up and load any environment variables declared in the `.env` file, located in the package's root directory. For example, adding,\n\n```bash\nPCK_ENV=prd\n```\n\nwill enable access to this variable within any Python program, via a call to `os.environ['PCK_ENV']`. \n\n\n\n### A (sample) python package \u003ca name=\"sample-package\"\u003e\u003c/a\u003e\n\nThe sample python package shipped with this boilerplate is located in the `src` directory consists of the two main files:\n\n- `animals.py`\n- `entry_points.py`\n\nThe code in `animals.py` depends on [multilevel_py](https://github.com/dataPuzzler/multilevel_py) and illustrates its core features by constructing a \nsimple classification hierarchy, resulting in a description of the well known cartoon characters tom and jerry.\nThis code depicts an example of a simple python package and is meant to be replaced by the code of the python package to be developed.\n\nEntry points enable that the invocation of certain package functions from the command line. For example, the `entry_points.py` module is referenced in the `setup.cfg` file in the `options.entry_points` section:\n\n```python\nconsole_scripts =\n    sample_pck = sample_pck.entry_points:main\n```\nThis enables the declared entry point - `sample_pck.entry_points.main` -  to be invoked when `pipenv run sample_pck` is called from the command line.\n\n\n### Running Unit Tests \u003ca name=\"unit-testing\"\u003e\u003c/a\u003e\n\nAll tests have been written using the [PyTest](https://docs.pytest.org/en/latest/) package. Tests are kept in the `tests` folder and can be run from the command line by invoking,\n\n```bash\npipenv run pytest\n```\n\nThe test suite is structured as an independent Python package as follows:\n\n```bash\ntests/\n |-- test_data/\n |   __init__.py\n |   conftest.py\n |   test_animals.py\n```\n\nThe `conftest.py` module is used by pytest to build testing-utilities used by several testing modules. These are referred to as 'fixtures' in PyTest - more details can be found [here](https://docs.pytest.org/en/latest/fixture.html).\n\n### Automated Testing using Github workflows \u003ca name=\"ci\"\u003e\u003c/a\u003e\nThis package starter also defines a Continous Integration workflow that resides in the `.github/workflows/unit-tests.yml` directory.\nThis workflow runs all unit-tests via `pytest` on each push to the master branch. \nIf you don't use Githubs CI Pipelines, delete the `.github` directory and its subdirectories. \n\n\n### Linting Code \u003ca name=\"code-linting\"\u003e\u003c/a\u003e\n\n[Flake8](http://flake8.pycqa.org/en/latest/) is used to enforce recommended code style guides. The precise linting rules are configured in the `[flake8]` section of `setup.cfg`.\n\nTo start code linting, execute the following command:\n\n```bash\npipenv run flake8 src/sample_pck\n```\n\n\n### Static Type Checking \u003ca name=\"type-check\"\u003e\u003c/a\u003e\n\nThe [MyPy package](http://mypy-lang.org) can be used to perform static type checks on your codebase. The tool is configured in the `[mypy]` section of \n`setup.cfg` and can be executed via the following command.\n\n```bash\npipenv run python -m mypy\n```\n\n\n### Code Documentation \u003ca name=\"code-docu\"\u003e\n\nThe documentation is located `docs` folder and has been built using [Sphinx](http://www.sphinx-doc.org). Sqhinx's default 'quickstart' was run in order to create the initial `conf.py`. It was customized with respect to the docstring format and the documentation theme as explained below.\n\n\n#### Usage of Google-style docstrings\nTo support Docstrings according to the [Google Styleguide](https://google.github.io/styleguide/pyguide.html), the `sphinx.ext.napoleon` shipped by Sphinx is used.\n\n\n#### Usage of Read the Docs Documentation Theme\nThe third party theme from [Read the Docs](https://readthedocs.org) has also been used, by installing the `sphinx_rtd_theme` as a development dependency and modifying `docs/source/config.py` as follows:\n\n```python\nimport sphinx_rtd_theme\nhtml_theme = \"sphinx_rtd_theme\"\nhtml_theme_path = [sphinx_rtd_theme.get_html_theme_path()]\n```\n\n\n#### Creating a HTML Version\n\nFrom the repository directory:\n\n```bash\n\npipenv run sphinx-build -b html docs/ docs/_build/html\n```\n\nAlternatively, you can use the `make` utility located in the `docs` dir:\n```bash\ncd docs\nmake html\n```\n\nThe resulting HTML documentation can be accessed by opening `docs/_built/html/index.html` in a web browser.\n\n\n\n#### Creating a PDF Version Using LaTeX\n\nIf a LaTex distribution is present on your system, it is possible to create a PDF version of the documentation as well. \nNavigate to `docs/` and run,\n\n```bash\nmake latexpdf\n```\n\nBoth LaTeX and PDF versions can then be found in `docs/_build/latex`.\n\n\n### Building a deployable Package Distribution\n\nThe recommended approach to deploy this package is to build a Python [wheel](https://wheel.readthedocs.io/en/stable/) and to install it in a fresh virtual environment on the target system. The exact build configuration is determined by the provided metadata in `setup.py` and `setup.cfg`. Note, that this requires that all package dependencies are also specified in the `install_requires` declaration in `setup.py`, **regardless** of their entry in `Pipfile`. For more information on Python packaging refer to the [Python Packaging User Guide](https://packaging.python.org) and the accompanying [sample project](https://github.com/pypa/sampleproject). To create the Python wheel run,\n\n```bash\npipenv run python setup.py bdist_wheel\n```\n\nThis will create `build` and `dist` directories - the wheel can be found in the latter. This needs to be copied to the target system (which is assumed to fulfill the requirements as defined in ['Prerequisites']('#prereq')). There it can be installed into a new virtual environment, together with all downstream dependencies, by running\n\n```bash\npipenv install path/to/your-package.whl\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatapuzzler%2Fpython_package_starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatapuzzler%2Fpython_package_starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatapuzzler%2Fpython_package_starter/lists"}