Enhance the tutorial on how to set up a project.

[tobiasraabe]

Changes

Follow-up to pytask-dev/cookiecutter-pytask-project#8 (comment)

• Remove conda develop.
• Replace setup.py by setup.cfg and pyproject.toml.

[tobiasraabe]

@hmgaudecker, I mention only the old setup.py approach since I documenting setuptools-scm feels like taking a big detour. What do you think? Is it fine although it is then not fully alinged with the template?

https://pytask-dev.readthedocs.io/en/latest/tutorials/how_to_set_up_a_project.html?highlight=setup.py#setup-py

[codecov]

Codecov Report

Merging #217 (bb971a1) into main (0641f39) will not change coverage.
The diff coverage is n/a.

❗ Current head bb971a1 differs from pull request most recent head 917fc20. Consider uploading reports for the commit 917fc20 to get more accurate results

@@           Coverage Diff           @@
##             main     #217   +/-   ##
=======================================
  Coverage   93.97%   93.97%           
=======================================
  Files          75       75           
  Lines        6671     6671           
=======================================
  Hits         6269     6269           
  Misses        402      402           

Flag	Coverage Δ
end_to_end	79.56% <ø> (ø)
integration	41.65% <ø> (ø)
unit	70.24% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0641f39...917fc20. Read the comment docs.

[hmgaudecker]

TBH, it sounds a bit like this will end up in documentation hell, leaving users confused.

IIUC, the same should be possible replacing setup.py with pyproject.toml. Then referring to setuptools_scm would be just a matter of changing the entries of that file?

[tobiasraabe]

What you need to set up to achieve the same behavior is

• add a pyproject.toml file with some info
• store the metadata in setup.cfg as long as https://github.com/pypa/setuptools/issues/2671 is not yet implemented which enables us to store everything in the toml
• add setuptools-scm and toml to the dependencies.
• Add an almost empty setup.py (https://github.com/pytest-dev/pytest/blob/main/setup.py)

Although, it makes the tutorial longer, at least it is consistent.

[hmgaudecker]

What do you mean by "the same behavior"? Finding the stuff in src ? Or using the git tags etc.? I thought the latter was what setuptools-scm does, that you could leave out. No idea about the setup.py.

[tobiasraabe]

With the same behavior I mean: finding stuff in src, adding metadata to the package, setting a version (dynamically via setuptools-scm or static via the version keyword in setup.py).

This can be done all in setup.py. Simple but inconsistent.

Or you need to do the four points from the post above. Consistent, but more documentation.

pyproject toml is used by setuptools-scm to store information on how to build the package.

[hmgaudecker]

Great, thanks! I still don't quite understand why all four steps are needed. A little research, maybe too shallow...

• I could set the version directly in setup.cfg, it seems -- why setuptools-scm except for the extra comfort?
• Looks like with recent-enough pip, setup.py can go? Are you fine with requiring that?

In case I am not mistaken, it would just be pyproject.toml + setup.cfg instead of setup.py?

[tobiasraabe]

Exactly for the extra comfort :). Releasing a new version just becomes writing a new release on Github with a tag.

This pip version is from last April. I guess I am fine with that. I dont know why someone runs on an older version.

[hmgaudecker]

Exactly for the extra comfort :). Releasing a new version just becomes writing a new release on Github with a tag.

Yeah, that's why I would keep that in the templates, but I agree with you ^^^^^ that documenting it here would be a bit of a detour.

This pip version is from last April. I guess I am fine with that. I dont know why someone runs on an older version.

Cool. So pyproject.toml + setup.cfg it is, ditching setup.py.

While you are at it: I would change

every time you recreate your Python environment

to

should you recreate your Python environment

Most people will not do that very often.

[tobiasraabe]

Hi @hmgaudecker, it is done. If you'd like, you can have a final look and then we merge it. Thanks for the discussion!

[hmgaudecker]

Great, thank you!