python-poetry / python-poetry/poetry

Add support for app/library type to `poetry new` and `poetry init`

Open
#9,668 12 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

kind/feature status/triage
Dominant language
Python
Stars
34.3k
Forks
2.5k
Avg merge
2d 19h
Merged PRs (30d)
30

Description

Issue Kind

Brand new capability

Description

Currently if I use poetry new or poetry init, I end up with a pyproject.toml configuration that is more oriented towards a library than an app, with no way to tell the new / init commands otherwise (beyond --python, but that's only one of several things that would need overriding).

For example they generate:

[tool.poetry]
name = "example"
version = "0.1.0"
description = ""
authors = ["..."]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

...whereas for an app:

  • it's rare to want to publish the app (ie: I want package-mode = false from https://github.com/python-poetry/poetry/pull/8650, and don't want the name/version/description/authors/readme fields)
  • it's rare to need to build the app (ie: I don't need the [build-system])
  • it's safer to set a specific major Python version (eg 3.12.*) rather than allowing an unsafe range (such as >=3.12) - so prod vs staging vs each developer's machine is at least using the same major Python version.

And therefore for apps, a config like the following is more appropriate:

[tool.poetry]
package-mode = false

[tool.poetry.dependencies]
python = "3.12.*"

As such, it would be helpful if the poetry new and poetry init commands accepted something like a --type argument (and corresponding question prompt when using those commands in interactive mode), that accepted options like "app" or "library", that then generated config more appropriate for the specified use-case. The interactive prompts and/or existing CLI args would still allow users to mix and match if needed (for example, the user could select "app" mode, but when prompted for the python value, could override the app mode's suggested default of "3.N.*" to a wider range if they prefer.

Such a type option would be similar to:

Possible arg/option names:

  • --type {app,lib} (or --type {app,library}
  • --app / --lib (or --app / --library)

Note: I intentionally didn't include --package-mode {true,false} in the list, since this feature request is about more than just package-mode = false and about several other defaults that make less sense when using Poetry with an app.

Impact
  • Means users can more easily generate a config that contains best practices for app use-cases, rather than them having to discover additional config/best practices via the docs and change it retrospectively
  • Likely means fewer support tickets about things like "why is Poetry saying I have to have a README" etc, since not all users read the docs properly
  • Encourages projects which are apps to not use unsafe unbounded Python version ranges (which can cause breakage in CI/CD environments when new Python versions are released, or cause user confusion when production works differently from locally when they happen to be using different Python versions that are permitted by the wide range)
Workarounds

Users either:

  • avoid using poetry new / poetry init at all, and create their pyproject.toml from scratch using the docs
  • use poetry new / poetry init and fill out questions that aren't relevant, but then have to change the defaults afterwards

...but both of these rely upon the user knowing that the default configs generated by new/init are not ideal for app use-cases, and what they should change to make them more suitable.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the CLI entry points for poetry new and poetry init, then inspect how their interactive prompts and generated pyproject.toml configuration are defined. Done means both commands support an app/library choice, apply appropriate defaults, and still allow existing options and prompts to override those defaults.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.