New to Python packaging? Avoid hatch (danpassaro.dev)

submitted 2 days ago by dan_p_the_dev@lemmy.world to c/python@programming.dev

26 comments fedilink hide all child comments

you are viewing a single comment's thread
view the rest of the comments

[-] eager_eagle@lemmy.world 6 points 2 days ago

hatch has hardcoded awareness of Git and Mercurial and specifically searches for project-level .gitignore and .hgignore to read those files directly. But it doesn’t handle user-level or system-level config, so anything you have ignored from config outside of your project, like .env in my example, will not be ignored by hatch, and will wind up in your sdist.

ah that probably explains why I didn't have this problem, same reason why I don't like global gitignores

[-] esc@piefed.social 3 points 2 days ago

[tool.hatch.build.targets.sdist]
include = [
  "pkg/*.py",
  "/tests",
]
exclude = [
  "*.json",
  "pkg/_compat.py",
]

It takes about 30 seconds of reading the documentation to find this.

[-] dan_p_the_dev@lemmy.world 2 points 2 days ago* (last edited 2 days ago)

Actually working out the right configuration for your project is likely going to take you more than 30 seconds. And finding the documentation for how to do this is only quick if you know exactly where to look and what to look for. When you invoke pyproject-build it's not clear that hatch is the piece of the puzzle that's causing unexpected files to wind up in your sdist.

And this is still more config and overhead than simply choosing a build backend with more sensible default behavior like uv_build.

[-] esc@piefed.social 2 points 1 day ago

Please, you've wasted a lot of time writing the article without bothering to read documentation (it's mentioned in both python guide and on the hatchling page), which takes one click and like three paragraphs down, and uv_build requires to use uv and not everyone likes it or wants to use it. Anyway reading documentation is far more important for beginners than automagical tools that supposedly solve all the problems in the world.

[-] dan_p_the_dev@lemmy.world 1 points 1 day ago* (last edited 1 day ago)

Please, you’ve wasted a lot of time writing the article without bothering to read documentation

? I linked directly to the documentation I read, and that's how I wound up using hatch in the first place. Did you read my article...? Reading the official Python documentation is what led to me uploading my .jj folder and a gitignored .env file to PyPI and writing this post. And writing the post was not a waste of time.

uv_build requires to use uv and not everyone likes it or wants to use it

That's fine. I'm sure there are other build backends that work similarly to uv_build and only grab what's needed to distribute your library. The point isn't that everyone needs to use uv_build, the point is that hatch has surprising and imo dangerous default behavior.

[-] esc@piefed.social 0 points 1 day ago

You see, I've actually read your article, you even linked to the hatchling site yourself. It takes little effort. Demonstration

[-] dan_p_the_dev@lemmy.world 1 points 1 day ago

This doesn't explain that hatch will package everything in the project directory by default. As a new user making a package, why would you think to look for hatch configuration options?

I mentioned in the article (maybe you don't read that carefully?) that hatch can be configured to do what you need, but if you're just following the packaging guide, which doesn't mention this behavior or provide any kind of heads up to new users, you won't be aware that it is going to even try to look at a directory like .jj. And why would it? I wouldn't expect a compiler or a tool like Maven to look at files that aren't needed to build the project. Why does hatch?

Your demonstration just shows if you're already aware of the problem and you know the cause of the problem, you can find a solution. I say as much in the article and agree with the point. The point of my article is this is surprising default behavior and it's better to just use a tool that has sensible defaults.

[-] esc@piefed.social 0 points 1 day ago* (last edited 1 day ago)

I wouldn't try to follow hunches on how tool that has extensive and accessible documentation works, your novice is a strawman that has expectations but unable to do anything for some reason. So he should completely change the workflow.

Nothing personal, I liked your article in general, but pretending that default is all there is isn't great way to frame it, you could have linked relevant documentation and provided a snippet on how it should be done instead of dismissing it entirely, because default doesn't meet your expectations

[-] dan_p_the_dev@lemmy.world 3 points 2 days ago

Even if you're using git or hg for version control you'll probably wind up with more in your sdist than you need: things like uv.lock, Justfile, or the contents of your tests/ dir might not be harmful, but they bloat your sdist and don't really belong there, and hatch will package them up with your source code unless you explicitly configure it not to.

[-] eager_eagle@lemmy.world 7 points 2 days ago* (last edited 2 days ago)

you just need only-include

https://hatch.pypa.io/1.13/config/build/#explicit-selection

it's easier than changing build backends

and a lot of times tests/ (and docs/) are included with source code in an sdist format - https://discuss.python.org/t/should-sdists-include-docs-and-tests/14578

[-] dan_p_the_dev@lemmy.world 2 points 2 days ago* (last edited 2 days ago)

Interesting discussion, thanks for the link! I side with pf_moore there; when I think of distributing a library I think of shipping only the library code itself and none of the supporting files, although I can understand the argument to include things like tests/ and docs/.

That said, if you haven't already tailored your project for hatch, configuring only-include is more work than switching to a build backend that just bundles source modules by default. With the right config hatch can do what you like, and I can understand existing users sticking with it, but for newbies I think it's really risky to suggest a build backend that grabs everything it finds in the working directory and packages it up for PyPI. It's just surprising and dangerous default behavior imo.