Notes from first time use

[jack89roberts]

I played with the template for the first time today just to get an idea for what it does/how it compares to the ARC one. Just written down everything that came up when I went through it, apologies it got so long!

There are a few tweaks that could be nice to add, but otherwise most my comments are just places where I might prefer different (generally less strict) choices for the default setup of various tools, but different people will have different views on that and I can see the argument for keeping the template quite opinionated/strict. It's nice how much it sets up!

Setting up the template

• Docs for initialising the local git repo and creating/pushing to GitHub (or automate this)
• Docs for how to use the generated template (i.e. readme for how to setup a virtual env, add dependencies, use pre-commit etc. depending on the choices made), e.g. the kind of thing in here - I see some of this is in CONTRIBUTING.md actually, but I don't think people would necessarily look in there.
• Docs for what choices have been made for the default (and why), e.g. pre-commit hooks, pytest, ruff, isort etc. - a lot of them are not using a default out-the-box setup. Also as a way of pointing people to where there are things they may want to edit.
  • Edit: Comments like this one may just be a matter of linking out to the relevant docs for the parent scientific Python template.
  • .copier-answers.yml: Inclined to think I don't want this in my project, is there a strong case for including it?
  • pyproject.toml: classifiers: Includes "Programming Language :: Python :: 3.9" but requires-python is >=3.10.
  • An option not to generate anything related to pushing to PyPI, e.g. in the readme badges and GitHub actions (for projects that are not expecting to push a Python package).
  • Is it necessary to specify both test and dev groups in optional dependencies? (And personally I like to have pre-commit, linters etc. installed there too so I can run them easily locally and VS code extensions pick them up etc., though that may not be best practice since they're then defined in both pre-commit and pyproject.toml)
• Is from __future__ import annotations still necessary in the Python 3.10+ world?

Setting up Hatch/installing the package [some not really about the template]

• Docs for setting up the environment if using hatch would be nice. I spent a lot of time figuring out why hatch new --init wasn't working before running hatch env create.
• If the package name is different to the project name a [tool.hatch.build.targets.wheel], packages=["mypath"] value needs to be added to pyproject.toml. I think the template allows these names to be different but doesn't update the hatch stuff to reflect.
  • Rather than a [tool.hatch] section with envs.default.<xyz> keys I seemed to need a [tool.hatch.envs.default] section for it to pick up the values correctly.
• Is it necessary for there to be dependencies (pytest) listed in tool.hatch.envs.default when these are also specified in project.optional-dependencies? It seems optional dependencies are not installed in the hatch environment so I guess the answer is yes.
  • Edit: The Hatch docs suggest adding a features block to tool.hatch.envs to do this.
• (as an aside) it's nice that hatch seems to be able to manage python versions on its own!
• When I try to update a dependency: "ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. locomoset 0.1.0 requires wandb~=0.15.11, but you have wandb 0.17.0 which is incompatible." -> I had 0.15.11 before and I'm telling you it now should be 0.17.0?
  • If I deleted and recreated the environment it was fine after, but don't get why updating the pyproject.toml then syncing dependencies didn't work.
• If I configure Hatch to put virtual environments in .venv VS Code still doesn't use them automatically as the Hatch env is put in a sub-directory within .venv.
• Is there not an equivalent of poetry add, is it just by changing pyproject.toml manually?
  • Edit: This is mentioned as coming soon in this issue.

Using the template

• The pytest options make loads of my tests fail due to warnings from other packages. Maybe I should be better at suppressing/fixing these warnings but it feels quite aggressive as the default.
• name-tests-test in pre-commit is shouting at me for having files that don't start with test_ in my tests directory (those files don't contain tests), but wouldn't be a big deal to exclude them.
• mypy is shouting at me about a lot but unsurprising since I didn't use mypy in that project. But does the pre-commit config remove type-checking if it's not asked for in the template setup (I haven't checked but don't see anything in the pre-commit config that would remove it)?
• The default ruff config picks up on some interesting things, but not sure I'd want all of them to block commits/fail actions.
  • Edit: Actually, having gone through them the vast majority I'd be happy to have flagged, the main ones I'm not sure about are EM101, EM102, B028, which IMO sacrifice readability/ease of development for slightly better logs/tracebacks. There are also several cases of ARG001 and ARG002 I'd need to ignore (unused arguments for compatibility with other functions/classes), though I can see this helping more often than hurting.

[phinate]

This is incredible feedback. Thank you for being so thorough with documenting your experience!!

A quick note just before I go through this more methodically: I've never actually used hatch itself, just the hatchling backend (there are a couple of notes on this here: https://hatch.pypa.io/1.9/why/).

Will make some spin-off issues :)

[phinate]

Created #34, #35, #36, #37, #38 to track some of these points. I've yet to look into your hatch issues.

[jack89roberts]

It looks like hatch can do a lot in terms of Python version/environment management, I think it does everything you might use pyenv/venv/tox/nox/setuptools for in one tool (though I've never used tox/nox). I might try it on a project at some point though poetry / setuptools + venv are the current ARC favourites (& battle).

[jack89roberts]

I think the pytest defaults and the inclusion of flake8-errmsg in ruff are worth a chat at some point so I might make an issue about those too.

[phinate]

An update: I've thought about the hatch issues, and decided not to support it (or poetry) as a backend from now, mostly because you can do most of this setup with the tools directly via poetry new and hatch new. The good news is that the template is much easier to maintain as a result! Thanks for trying out hatch.