Python template v3

[albireox]

I have done some updating of both the template and the style guide, which were over three years old.

This new template (v3) uses copier because cookiecutter seems to have become abandonware. I have remove most of the configuration options and settled for using uv, Ruff, and furo for Sphinx theming since I think that's what we all are using these days and it simplifies the template and the documentation.

The new version of the documentation can be previewed here and the style guide here.

This probably deserves a synchronous code-review.

Closes #25

[johndonor3]

I don't have any strong opinions here. It seems simpler than the previous template though so that's good!

[havok2063]

I'll take a look at this soon. Maybe by next week's coding time. Regarding copier, is cookiecutter deprecated? it's last commit was 5 days ago. And I know folks are using cruft now to manage project templates. I'm not familiar with copier but I'll take a look.

[albireox]

Yes, it seems people still commit to coockiecutter but there hasn't been a release in over a year. I checked the issues at the time and it seemed the main maintainers where MIA, but maybe not. I didn't know cruft but I'm not super attached to copier either. I think any of them are probably good enough for our needs ... including an old version of cookiecutter.

[havok2063]

I'm testing this out. When I run uvx copier copy --trust gh:sdss/python_template /Users/brian/Work/git/sdss/test_project I get an error. I get the same thing pointing to my local checkout of the branch. This shouldn't depend on cookiecutter, right?

  File "<template>", line 1, in top-level template code
  File "/Users/brian/.local/share/uv/tools/copier/lib/python3.10/site-packages/jinja2/sandbox.py", line 319, in getattr
    value = getattr(obj, attribute)
jinja2.exceptions.UndefinedError: 'cookiecutter' is undefined

[albireox]

I think that's because it's defaulting to the main branch which still has references to cookiecutter since this is not yet merged. Can you try uvx copier copy --trust --vcs-ref python-template-v3 gh:sdss/python_template /Users/brian/Work/git/sdss/test_project?

[havok2063]

That worked. I'm surprised it didn't work when it was pointed to the local branch checkout.

One quick question on the uv venv setup: What determines which python version it creates the venv for? It defaults to 12, whether I created it from a different env or not. Are we able to have a question asking which python version to use?

I'll keep playing around with this.

[albireox]

I think to run it from a local checkout you need to do something like copier copy --trust -r HEAD . ~/Downloads/test_project The -r HEAD was necessary if you have uncommitted changes.

Yes, we could ask a question about the uv Python version to use. Right now it defaults to whatever uv would use if you do uv venv, which I think is the highest version it has access to, but there are environment variables to change that.

[albireox]

Yesterday you mentioned being able to update the template for already generated project. I think that's a good idea. copier has some features for that that I haven't explored. I think they would require keeping the answers file, which right now I'm removing in post-processing.

[havok2063]

This is looking good to me. The output project is nice and clean. One thought I had was adding a question to optionally create a minimal Dockerfile for the package.

Also, I wonder if it's worth thinking about a migration script to help packages move from v1->v2->v3, etc, or future versions. I'm not sure how feasible that is. Perhaps it's easier moving forward, after projects are made with copier.

[havok2063]

Can we add some boilerplate instructions to this readme for installation, dev installation, and how to serve the docs locally?

[albireox]

Done. Can you check the text? I mostly copied what you added for sdssdb.

[havok2063]

Yeah I think "project updates" would be good to include. Besides supporting package/project updates, it would allow people to re-answer optional questions for adding features.

We might also want a separate script/repo for pushing mass updates to multiple packages.

[albireox]

I included a question to add a Dockerfile and GitHub action. I tested it and I think it works. Can you have a look at the code and the documentation?

I like the idea of allowing to update projects generated with the template. I will probably require a bit of testing and playing around with the options.

I think an automated conversion tool from v1 and v2 may be difficult to write since those versions had some many forking paths, but maybe we can include some documentation on how to do it manually.