{"id":26163502,"url":"https://github.com/jlevy/simple-modern-poetry","last_synced_at":"2025-07-14T20:34:06.589Z","repository":{"id":276402842,"uuid":"929152778","full_name":"jlevy/simple-modern-poetry","owner":"jlevy","description":"A minimal, modern Python project template using Poetry. Also available as a GitHub template:","archived":false,"fork":false,"pushed_at":"2025-03-10T19:15:14.000Z","size":52,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T14:34:07.635Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/jlevy/simple-modern-poetry-template","language":"Jinja","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/jlevy.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":"2025-02-07T22:46:53.000Z","updated_at":"2025-03-10T19:15:18.000Z","dependencies_parsed_at":"2025-03-04T02:26:50.848Z","dependency_job_id":"2c694492-3ff6-4f5c-83f4-109f314078fc","html_url":"https://github.com/jlevy/simple-modern-poetry","commit_stats":null,"previous_names":["jlevy/clean-poetry-template","jlevy/simple-modern-poetry"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jlevy/simple-modern-poetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fsimple-modern-poetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fsimple-modern-poetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fsimple-modern-poetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fsimple-modern-poetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/simple-modern-poetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fsimple-modern-poetry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265344844,"owners_count":23750566,"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":[],"created_at":"2025-03-11T14:27:22.885Z","updated_at":"2025-07-14T20:34:06.576Z","avatar_url":"https://github.com/jlevy.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simple-modern-poetry\n\n## What is This?\n\n**simple-modern-poetry** is a minimal, modern **Python project template** for new\nprojects (Python 3.10–3.13) that uses\n[**Poetry 2.0**](https://github.com/python-poetry/poetry).\nThis template aims to be a good base for serious work but also simple so it's an easy\noption for any small project.\n\n\u003e [!NOTE]\n\u003e \n\u003e See [simple-modern-uv](https://github.com/jlevy/simple-modern-uv) for a similar but\n\u003e template for **uv**, which is newer and may be best for new projects.\n\nIt is still surprisingly hard to learn modern best practices for setting up Python\ninstallations and tools without reading many pages of docs on\n[pyenv](https://github.com/pyenv/pyenv),\n[Poetry](https://python-poetry.org/docs/basic-usage/) (and its\n[2.0 update](https://python-poetry.org/blog/announcing-poetry-2.0.0/)),\n[pipx](https://github.com/pypa/pipx),\n[GitHub Actions](https://github.com/actions/setup-python) etc.\n\nSo I'm sharing a template that I now use myself and that I can point friends to.\n\nIt aims to be \"done right\" with modern tools but still absolutely as simple as possible:\n\n- Modern [**Poetry**](https://github.com/python-poetry/poetry) setup with\n  [dynamic versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) to make\n  releases easier along with the\n  [shell](https://github.com/python-poetry/poetry-plugin-shell) and\n  [up](https://github.com/MousaZeidBaker/poetry-plugin-up) plugins.\n  (Why use Poetry? See [below](#alternatives).)\n\n- Simple **GitHub Actions CI workflow** including (optional) **publishing to PyPI**. To\n  publish a release, just create a release on GitHub.\n\n- Standard, modern linting, formatting, and testing with\n  [**black**](https://github.com/psf/black),\n  [**ruff**](https://github.com/charliermarsh/ruff),\n  [**usort**](https://github.com/facebook/usort),\n  [**mypy**](https://github.com/python/mypy),\n  [**codespell**](https://github.com/codespell-project/codespell), and\n  [**pytest**](https://github.com/pytest-dev/pytest).\n\n- A **starter readme** with handy reminders on Python and Poetry setup/installation and\n  basic dev workflows using to save time for you and users or collaborators.\n\n- The whole template is **only ~300 lines of code** so you can read it and change what\n  you want.\n\nIt doesn't have lots of options or try to use every bell and whistle.\nIt just adds the above essential things that should be in place for any new Python\nproject.\n\n## When to Use This Template\n\nIt should work whenever you want to use modern Python and Poetry and have a build\nworkflow in GitHub. It does not handle:\n\n- Using Docker (but you could add this later)\n\n- Using [Conda](https://github.com/conda/conda) for dependencies (but note many deep\n  learning libraries like PyTorch now support pip so this isn't as necessary as often as\n  it used to be)\n\n- Using a code repo or build system that isn't GitHub and GitHub Actions\n\n(See [below](#alternatives) for other options.)\n\n## How to Use This Template\n\n\u003e [!NOTE]\n\u003e \n\u003e By default this template uses MIT license.\n\u003e If you want a different license or are not publishing your project as open source,\n\u003e update `license` in pyproject.yaml and the LICENSE file.\n\u003e If desired, you may delete the `.github/workflows/publish.yml` file if you are not\n\u003e publishing to PyPI.\n\nThe template can be used in two ways.\nOption 1 is quickest.\nFor more flexibility, consider Option 2.\n\n### Option 1: GitHub Template\n\nJust use\n[**this template repository**](https://github.com/jlevy/simple-modern-poetry-template),\nwhich is the output of this template.\n\nGo there and hit the \"Use this template\" button.\nOnce you have the code, search for **`_changeme_`** for all field names like project\nname, author, etc. You may also want to change the license/copyright.\n\n### Option 2: Use Copier\n\nThis template uses [**copier**](https://github.com/copier-org/copier), which seems like\nthe best tool nowadays for project templates.\nUsing copier is the recommended approach since it then lets you instantiate the template\nvariables, but it requires a few more commands.\n\nNote that copier also has the cool feature to [update your project\ntemplate](#updating-your-project-template) as this template improves in the future.\n\nTo create a new project repo with `copier`:\n\n```shell\n# Ensure you have Python 3.11+ and pipx installed. (If not, see below.)\n\n# Install copier:\npipx install copier\n\n# Clone this template:\ncopier copy gh:jlevy/simple-modern-poetry your-project-name\n# Then follow the instructions.\n```\n\nYou can enter names for the project, description, etc., or just press enter and later\nlook for `_changeme_` in the code.\n\nOnce you have the template set up, you will need to check the code into Git for Poetry\nto work. [Create a new GitHub\nrepo](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository)\nand add your initial code:\n\n```shell\ncd PROJECT\ngit init\n# Make license or other initial adjustments if needed.\ngit add .\ngit commit -m \"Initial commit from simple-modern-poetry.\"\n# Create repo on GitHub.\ngit remote add origin git@github.com:OWNER/PROJECT.git  # or https://github.com/...\ngit branch -M main\ngit push -u origin main\n```\n\n## Getting Started on Your Project\n\nThe\n[**default template readme**](https://github.com/jlevy/simple-modern-poetry-template)\ncovers the install and build workflows.\nIt's just Poetry and a tiny Makefile with shortcuts.\nIt also has concise documentation on installing Python and Poetry.\n\n## Updating Your Project Template\n\nIf you use Option 2 or if you pick Option 1 and correctly fill in your\n`.copier-answers.yml` file, you have the option to update your project with any future\nupdates to this template at any time.\n\nIf this file is updated with your project name etc., then you can\n[update your project](https://copier.readthedocs.io/en/latest/updating/) to reflect any\nchanges to this template by running `copier update`.\n\n## Alternatives\n\n**Poetry** is one of the best package managers for modern Python projects.\nThose who love the latest tools may want to consider\n[**uv**](https://github.com/astral-sh/uv) instead of Poetry.\n\nOr for [**Conda**](https://github.com/conda/conda) dependencies, also consider the newer\n[**pixi**](https://github.com/prefix-dev/pixi/) package manager.\n\nCurrently (early 2025) Poetry is one of the most mature, straightforward options,\nespecially since tool support, such as GitHub workflows and dependabot, still seem\nbetter for Poetry.\n\nAssuming you want to use Poetry, there are several other good templates, such as\n[cookiecutter-poetry](https://github.com/fpgmaas/cookiecutter-poetry) and\n[poetry-copier](https://github.com/lukin0110/poetry-copier) you may wish to consider.\n\nThis template takes a different philosophy.\nI found existing ones to be out of date or have lots of options and scaffolding for\ndifferent frameworks.\nThat's hard to maintain in the template repo and overwhelming to read at first.\nThis is intended instead to be a very simple base.\nYou can add to it if you want.\n\n## Contributing\n\nPRs welcome on [this repository](https://github.com/jlevy/simple-modern-poetry) (not on\nthe GitHub template repo, which mirrors this one).\nPlease use the Discussions tab with your feedback, questions, or suggestions!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fsimple-modern-poetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Fsimple-modern-poetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fsimple-modern-poetry/lists"}