{"id":24091238,"url":"https://github.com/bateman/python_pyenv_poetry_template","last_synced_at":"2025-09-10T04:43:18.279Z","repository":{"id":225155609,"uuid":"765218224","full_name":"bateman/python_pyenv_poetry_template","owner":"bateman","description":"A template repository for Python projects using Pyenv and Poetry","archived":false,"fork":false,"pushed_at":"2025-05-05T20:42:11.000Z","size":1239,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T23:30:02.022Z","etag":null,"topics":["poetry","pyenv","python","template"],"latest_commit_sha":null,"homepage":"https://bateman.github.io/python_pyenv_poetry_template/","language":"Makefile","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/bateman.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,"zenodo":null}},"created_at":"2024-02-29T13:59:35.000Z","updated_at":"2025-03-08T15:23:46.000Z","dependencies_parsed_at":"2024-04-02T10:47:31.905Z","dependency_job_id":"75f7ca3c-db0a-4eb9-a28f-f8b155d51e5b","html_url":"https://github.com/bateman/python_pyenv_poetry_template","commit_stats":null,"previous_names":["bateman/python-pyenv-poetry-template","bateman/python_pyenv_poetry_template"],"tags_count":35,"template":true,"template_full_name":null,"purl":"pkg:github/bateman/python_pyenv_poetry_template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bateman%2Fpython_pyenv_poetry_template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bateman%2Fpython_pyenv_poetry_template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bateman%2Fpython_pyenv_poetry_template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bateman%2Fpython_pyenv_poetry_template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bateman","download_url":"https://codeload.github.com/bateman/python_pyenv_poetry_template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bateman%2Fpython_pyenv_poetry_template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274412862,"owners_count":25280199,"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","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"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":["poetry","pyenv","python","template"],"created_at":"2025-01-10T07:13:09.782Z","updated_at":"2025-09-10T04:43:18.261Z","avatar_url":"https://github.com/bateman.png","language":"Makefile","readme":"\u003cdiv align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/bateman/python_pyenv_poetry_template/main/images/logo/logo-p3t-transparent-bg.png\" width=\"110\"\u003e\u003c/div\u003e\n\n# Python Pyenv Poetry Template\n\n![PyPI - Version](https://img.shields.io/pypi/v/python_pyenv_poetry_template?style=flat-square\u0026color=%23007EC6)\n![GitHub Release](https://img.shields.io/github/v/release/bateman/python_pyenv_poetry_template?style=flat-square)\n![GitHub top language](https://img.shields.io/github/languages/top/bateman/python_pyenv_poetry_template?style=flat-square)\n![Codecov](https://img.shields.io/codecov/c/github/bateman/python_pyenv_poetry_template?style=flat-square)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bateman/python_pyenv_poetry_template/release.yml?style=flat-square)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bateman/python_pyenv_poetry_template/docker.yml?style=flat-square\u0026label=docker)\n![GitHub Pages Status](https://img.shields.io/badge/docs-passing-46cc14?style=flat-square)\n![GitHub License](https://img.shields.io/github/license/bateman/python_pyenv_poetry_template?style=flat-square)\n\nA template repository for Python projects using Pyenv and Poetry.\n\n## Makefile\n\nThe project relies heavily on `make`, which is used to run *all* commands. It has been tested on macOS and Ubuntu 22.04. Windows users are strongly encouraged to install [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).\n\nRun `make` to see the list of the available targets.\n\n```console\n$ make\n\nUsage:\n  make [target] [ARGS=\"...\"]\n\nInfo\n  help                  Show this help message\n  info                  Show development environment info\nSystem\n  python                Check if Python is installed\n  virtualenv            Check if virtualenv exists and activate it - create it if not\n  poetry                Check if Poetry is installed\n  poetry-update         Update Poetry\nProject\n  project/install       Install the project for development\n  project/production    Install the project for production\n  project/update        Update the project\n  project/clean         Clean the project - removes all cache dirs and stamp files\n  project/reset         Cleans plus removes the virtual environment (use ARGS=\"hard\" to re-initialize the project)\n  project/run           Run the project\n  project/tests         Run the tests\n  project/build         Build the project as a package\n  project/buildall      Build the project package and generate the documentation\n  project/publish       Publish the project to PyPI\n  project/publishall    Publish the project package to PyPI and the documentation to GitHub Pages\n  project/deps-export   Export the project's dependencies to requirements*.txt files\nCheck\n  check/format          Format the code\n  check/lint            Lint the code\n  check/precommit       Run all pre-commit checks\nRelease\n  release/version       Tag a new release version\n  release/publish       Push the tagged version to origin - triggers the release and docker actions\nDocker\n  docker/build          Build the Docker image\n  docker/run            Run the Docker container\n  docker/all            Build and run the Docker container\n  docker/stop           Stop the Docker container\n  docker/remove         Remove the Docker image, container, and volumes\nDocumentation\n  docs/build            Generate the project documentation\n  docs/serve            Serve the project documentation locally\n  docs/publish          Publish the project documentation to GitHub Pages (use ARGS=\"--force\" to force the deployment)\n```\n\n## Installation\n\nThis is a template repository, so first things first, you create a new GitHub repository and choose this as its template. After that, follow the installation steps below.\n\n1. Clone the repository: `git clone https://github.com/\u003cyour-github-name\u003e/\u003cyour-project-name\u003e.git `\n2. Navigate to the project directory: `cd \u003cyour-project-name\u003e`\n3. Check the status of the dev environment: `make info` will list the tools currently installed and the default value of project vars, as in the example below:\n\n        System:\n          OS: Darwin\n          Shell: /bin/bash - GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)\n          Make: GNU Make 3.81\n          Git: git version 2.39.3 (Apple Git-146)\n        Project:\n          Project name: python_pyenv_poetry_template\n          Project description: 'A GitHub template for Python projects using Pyenv and Poetry'\n          Project author: Fabio Calefato (bateman \u003cfcalefato@gmail.com\u003e)\n          Project version: 0.9.0\n          Project license: MIT\n          Project repository: https://github.com/bateman/python_pyenv_poetry_template\n          Project directory: /Users/fabio/Dev/git/python_pyenv_poetry_template\n        Python:\n          Python version: 3.12.1\n          Pyenv version: pyenv 2.3.36\n          Pyenv root: /Users/fabio/.pyenv\n          Pyenv virtualenv name: venvp3t\n          Poetry version: Poetry (version 1.8.2)\n        Docker:\n          Docker: Docker version 25.0.3, build 4debf41\n          Docker Compose: Docker Compose version v2.24.6-desktop.1\n          Docker image name: p3t\n          Docker container name: p3t\n\n4. If any of the needed tools are missing, it will be marked as '*not installed*'. Install them and re-run `make info` to ensure the tools are now correctly installed and in your PATH.\n5. Update the project variables values by editing `pyproject.toml`. In addition, you can add any of the variables in the list below to a `Makefile.env` file to override the default values used in the  `Makefile`. You can check the variables configuration using `make info`.\n\n        PYTHON_VERSION=3.12.1\n        PYENV_VIRTUALENV_NAME=venvp3t\n        DOCKER_CONTAINER_NAME=p3t\n        DOCKER_IMAGE_NAME=p3t\n\n6. To create the virtual environment, run `make virtualenv`. Note that this will also check for the requested Python version; if not available, it will ask you to use `pyenv` to install it.\n7. To complete the installation for development purposes, run `make project/install` -- this will install all development dependencies. Otherwise, for production purposes only, run `make project/production`.\n\n\u003e [!TIP]\n\u003e The installation step will install some 'default' dependencies, such as `rich` and `pretty-errors`, but also dev-dependecies, such as `ruff` and `pytest`.\n\u003e Edit the `pyproject.toml` to add/remove dependencies before running `make project/install`. Otherwise, you can add and remove dependencies later using `poetry add` and `poetry remove` commands.\n\n\u003e [!NOTE]\n\u003e The `PROJECT_NAME` var will be converted to lowercase and whitespaces will be replaced by `_`. This value will be the name of your project module.\n\n\u003e [!CAUTION]\n\u003e The `Makefile.env` should specify at least the `PYTHON_VERSION=...`. Otherwise, the GitHub Actions will fail. Also, make sure that the Python version specified in `Makefile.env` (e.g., 3.12.1) satisfies the requirements in `pyproject.toml` file (e.g., python = \"^3.12\").\n\n## Development\n\nThe project uses the following development libraries:\n\n* `ruff`: for code linting, formatting, and security analysis.\n* `mypy`: for static type-checking.\n* `pre-commit`: for automating all the checks above before committing.\n\n\u003e [!TIP]\n\u003e To manually run code formatting and linting, run `make check/format` and `make check/lint`, respectively.\n\u003e To execute all the checks, stage your changes, then run `make check/precommit`.\n\n## Execution\n\n* To run the project: `make project/run`\n\n\u003e [!TIP]\n\u003e Pass parameters using the ARGS variable (e.g., `make project/run ARGS=\"--text Ciao --color red\"`).\n\n## Testing\n\n* To run the tests: `make project/tests`\n\n\u003e [!TIP]\n\u003e Pass parameters using the ARGS variable (e.g., `make project/tests ARGS=\"--cov-report=xml\"`).\n\n\u003e [!NOTE]\n\u003e Tests are executed using `pytest`. Test coverage is calculated using the plugin `pytest-cov`.\n\n\u003e [!WARNING]\n\u003e Pushing new commits to GitHub, will trigger the GitHub Action defined in `tests.yml`, which will upload the coverage report to [Codecov](https://about.codecov.io/). To ensure correct execution, first log in to Codecov and enable the coverage report for your repository; this will generate a `CODECOV_TOKEN`. Then, add the `CODECOV_TOKEN` to your repository's 'Actions secrets and variables' settings page.\n\n## Update\n\nRun `make project/update` to update all the dependencies using `poetry`.\n\n## Build\n\nRun `make project/build` to build the project as a Python package.\nThe `*.tar.gz` and `*.whl` will be placed in the `BUILD` directory (by default `dist/`).\n\n\u003e [!TIP]\n\u003e Run `make project/buildall` to build both the project's wheel and tarball, as well as the documentation site.\n\n## Release\n\n* Run `make release/version ARGS=\"\u003csemvertag\u003e\"` to bump the version of the project and write the new version back to `pyproject.toml`, where `\u003csemvertag\u003e` is one of the following rules: `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`.\n\n  The table below illustrates the effect of these rules with concrete examples.\n\n  | **Rule**     | **Before** | **After** |\n  |--------------|-----------:|----------:|\n  | `major`      |    1.3.0   |   2.0.0   |\n  | `minor`      |    2.1.4   |   2.2.0   |\n  | `patch`      |    4.1.1   |   4.1.2   |\n  | `premajor`   |    1.0.2   |  2.0.0a0  |\n  | `preminor`   |    1.0.2   |  1.1.0a0  |\n  | `prepatch`   |    1.0.2   |  1.0.3a0  |\n  | `prerelease` |    1.0.2   |  1.0.3a0  |\n  | `prerelease` |   1.0.3a0  |  1.0.3a1  |\n  | `prerelease` |   1.0.3b0  |  1.0.3b1  |\n\n* Run `make release/publish` to trigger, respectively, the upload of a new release to GitHub and a Docker image to DockerHub by executing the GitHub Actions `release.yml` and `docker.yml`, as detailed next.\n\n## GitHub Actions\n\nAs shown in the table below, there are four GitHub Actions workflow. Take note on the event triggering the run and the Secrets needed for a succesfull execution.\n\n| **Action name** | **Purpose**                                 | **Runs on**                                            | **Secrets**                             |\n|:---------------:|---------------------------------------------|--------------------------------------------------------|-----------------------------------------|\n|  `release.yml`  | Release package to PyPI and GitHub 📦       | tag push                                               | -                                       |\n|   `docker.yml`  | Push image to DockerHub 🚀                  | tag push                                               | `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` |\n|   `tests.yml`   | Run tests and upload coverage to Codecov 📊 | commit push on branches != `main`, manual              | `CODECOV_TOKEN`                         |\n|    `docs.yml`   | Upload documentation to GitHub Pages 📓     | commit push on `docs/**` path of `main` branch, manual | `RELEASE_TOKEN`                         |\n\n\u003e [!CAUTION]\n\u003e Follow this [guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#configuring-trusted-publishing) and configure PyPI’s trusted publishing implementation to connect to GitHub Actions CI/CD. Otherwise, the release workflow will fail.\n\n## Publish to PyPI\n\nTo manually publish your package to PyPI, run `make project/publish`. If necessary, this will build the project as a Python package and upload the generated `*.tar.gz` and `*.whl` files to PyPI.\n\n\u003e [!TIP]\n\u003e Run `make project/publishall` to manually publish the package to PyPI and the documentation site to GitHub Pages.\n\n\u003e [!WARNING]\n\u003e Before trying manually publish your package to PyPI, make sure you have a valid API token. Then, you need manually configure `poetry` running the following command: `poetry config pypi-token.pypi \u003cyour-api-token\u003e`.\n\n## Documentation\n\n* Run `make docs/build` to build the project documentation using `mkdocs`. The documentation will be generated from your project files' comments in docstring format, thanks to the `mkdocstrings` plugin.\nThe documentation files will be stored in the `DOCS_SITE` directory (by default `site/`).\n* Run `make docs/serve` to browse the built site locally, at http://127.0.0.1:8000/your-github-name/your-project-name/\n* Run `make docs/publish` to publish the documentation site as GitHub pages. The content will be published to a separate branch, named `gh-pages`. Access the documentation online at https://your-github-name.github.io/your-project-name/\n\n\u003e [!TIP]\n\u003e You can edit the `mkdocs.yml` file to adapt it to your project's specifics. For example, you can change the `material` theme or adjust the logo and colors. Refer to this [guide](https://squidfunk.github.io/mkdocs-material/setup/) for more.\n\n\u003e [!NOTE]\n\u003e After the first deployment to your GitHub repository, your repository Pages settings (Settings \u003e Pages) will be automatically updated to point to the documentation site content stored in the `gh-pages` branch.\n\n\u003e [!WARNING]\n\u003e Before being able to succesfully publishing the project documentation to GitHub Pages, you need to add a `RELEASE_TOKEN` to your repository's 'Actions secrets and variables' settings page. The `RELEASE_TOKEN` is generated from your GitHub 'Developer Settings' page. Make sure to select the full `repo` scope when generating it.\n\n## Docker\n\n* To build the Docker container: `make docker/build`\n* To start the Docker container and run the application: `make docker/run`\n* To build and run: `make docker/all`\n\n\u003e [!NOTE]\n\u003e Before building the container, you can edit `Makefile.env` and change the name of the image and or container (by default they will match the name of your project).\n\n\u003e [!WARNING]\n\u003e Pushing a new tag to GitHub will trigger the GitHub Action defined in `docker.yml`. To ensure correct execution, you first need to add the `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets to your repository's 'Actions secrets and variables' settings page.\n\n## Contributing\n\nContributions are welcome! Follow these steps:\n\n1. Fork the repository.\n2. Create a new branch: `git checkout -b feature-name`\n3. Make your changes and commit: `git commit -m 'Add feature'`\n4. Push to the branch: `git push origin feature-name`\n5. Submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbateman%2Fpython_pyenv_poetry_template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbateman%2Fpython_pyenv_poetry_template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbateman%2Fpython_pyenv_poetry_template/lists"}