pdm init --template helloworld to support template for init command

[larrycai]

Is your feature request related to a problem? Please describe.

python users normally create structures from sample or old projects, and always

• frustrated on structure ( src/<project> & tests)
• needs a working code base for simple example to start (flask sample)
• waste time for simple setup with default code rules (pyproject.toml for quality control tools, ide code rule setup ...)
• ..

It benefits

• new user to have clean & latest best python standard env
• experienced user to have quick env
• enterprise users to have standard aligned env automatically

Describe the solution you'd like

• extra parameter --template to support some community driven templates (can have basic MACRO to replace)
• templates can be inside pdm repo or url based to be easily customized.

[frostming]

This is also a function that I have been wanting to implement for a long time, but there are still some points that I am hesitant about.

1. Do we need to support variable substitution? Generating a pyproject.toml based on user input is easy to do. Do we also need to change the ${package_name}/ or src/${package_name}?
2. If so, to how much degree we allow this? Like cookiecutter and copier, the project templates are given as a set of Jinja2 templates, with variables to be substituted.
3. Are we really going to re-invent the wheel, if there are already project generators out there?

[pawamoy]

If we're still talking about using Copier templates, I definitely recommend option 3. You can store the templates in your @pdm-project org, simply prefix them with template- to keep it clean (no need for a new org). PDM would then "just" run Copier programmatically. Users would enjoy all Copier updates without any issues.

Option 2 (single template with subdirectories) is feasible as well, though the choice of template would have to be done through a Copier question (that PDM can still provide an answer for, from a PDM CLI flag).

I tried option 1 in my previous job, because our company prevented us to use git clone (??????), and I can tell you that it is extremely hard to reason about, and very much not working well.

---

Any consideration about performance can also be discussed within Copier directly.

[frostming]

I tend to avoid introducing large external dependencies in PDM, only for a specific task. So we are talking about supporting a minimal template system(only replace the ${package_name}, which can be found from the pyproject.toml). Copier integration will be likely available via a plugin.

[larrycai]

minimal templates is good enough. And leave the rest to copier

The benefit for this small template can help beginner to have a standard python working structure (do we have PEP for it) from beginning:

• if we have PEP related, then pdm init --template PEPxxx
• if flask community want to recommend one simple standard, then pdm init --template flask

[frostming]

if flask community want to recommend one simple standard, then pdm init --template flask

In npm, the templates are distributed as separate packages prefixed with create- so users can do yarn create vite or npm init vite. That's npm's style, we are not likely to go this route. So if the flask team wants to recommend a template, they have to contribute their template to pdm-project organization. I hope the org won't grow too large to hold all these templates 🐶

[larrycai]

so it could be good to have

$ pdm init  # current basic setup for new python project
$ pdm init --template helloworld   # or PEP related templates to provide good structure to start with, no updates normally.
$ pdm init --template https://github.com/pdm-project/copier-pdm # users needs to make sure the template fulfill the copier's format

[frostming]

According to the above discussion, the basic RFC for this feature is as follows:

1. Allow passing a positional arg to pdm init, as pdm init <template_name_url>¹ to create a project based on the given template.
   a. When the argument value is a name, look for templates under https://github.com/pdm-project/template-<name>
   b. It can be a path to a local template directory
   c. It can also be a full URL pointing to a Git repository, such as GitLab or BitBucket URL.
   d. Apart from Git, other VCS are not supported.
2. The template repository is just a normal repository, without any special config or variables, except for a mandatory pyproject.toml that complies with PEP 621 standard. So you can use any pyproject.toml-based project as template project. But generally, a template should be kept simple enough.
3. Here are the steps to initialize a project:
   a. Clone the template to local
   b. Get the template project name from its pyproject.toml
   c. Generate a [project] table based on the user input and update pyproject.toml
   d. Convert the project name to import name, and replace all occurrences in the project recursively with the new project name²
   e. Write the results to the current project
4. When user run pdm init, a built-in template shipped with PDM will be used, to keep the old behavior.

/cc @larrycai @pawamoy

Footnotes

1. I did not use the suggested --template option, since we haven't use the positional arg yet for pdm init. This also looks similar to npm create and yarn create. ↩

2. This means the import name should be derived from package name and we don't support otherwise. ↩

[larrycai]

to make it simple, I don't think we need to support <owner>/<repo>, if it is the case, use complete url instead

1.b for <owner>/<repo> could be used for local pdm init path/to/project, do we want to support this?

copier path/to/project/template path/to/destination

[pawamoy]

I agree with @larrycai, supporting owner/repo will bring edge cases. We can start without this feature and always add it later if needed. Passing the URL is fine to start.

I am almost sure users will want to use local paths though, as @larrycai suggests. So we already have to distinguish the argument into three categories: single name, local path, URL.

For 3.b., I'm not sure to understand why we'd need to get the project name of the template? Isn't it replaced by user input anyway?

[frostming]

For 3.b, since we are doing name replacement, we need to know the old name. We won't have any template variables here.

For git URL, I'm thinking of supporting SSH urls since it is the only available way for some developers.

[larrycai]

most of company use https instead of ssh (trends?)

[pawamoy]

For 3.b, since we are doing name replacement, we need to know the old name. We won't have any template variables here.

Ah, right! Thanks.

Yeah both git+https and git+ssh must be supported.

[larrycai]

review the implementation, so in the end copier is not used. (I am ok for it), then we need to maintain the "guideline" for template by ourselves, not something like

the template is copier based, you can reuse it and check more features there.

[frostming]

We will keep it simple and be conservative about adding new features.

We can add copier support in a plugin.

[MrTango]

I just tried the template feature with the existing django-app template.
But why do i have to provide github username to do the git clone?
And also it is not working anymore with github like this.

[frostming]

It is using git+https automatically, it will ask for credentials if you didn't setup them for http.