Fix: update hatch install instructions to use the hatch installers rather than pipx in our tutorial

[lwasser]

We have experienced significant problems with installing hatch using pipx. mostly because pipx is really hard to install. but for scientists i do think a global installation is ideal.

As such as should update this lesson to do two things

1. at the beginning of the lesson it should tell the user to insall hatch using the installers. following the instructions on the hatch page linked here.
2. REMOVE any mention of pipx!! phew.
3. then the lesson can proceed as it is

it might also be helpful to add a small requirements box.

it can say something like this:

:::{note}
You need to have python installed in order to create a python package. If you don't already have python installed, then hatch will install it for you. If you do already have hatch installed, then you are good to go!
:::

this is the section you'd be editing on that intro lesson called get to know hatch.

When you open the issue, you can add to the top

closes #260 #278

there might be another issue related to pipx that can also be closed once a pr for this issue is merged. This is a beginner friendly issue!

[lwasser]

pulling together a few more comments in an open pr #278

1. @ucodery mentioned that the hatch installers might lead us down a slippery slope given
   • they don't cover linux installation (we need to figure that out if we go this route)
   • they are DIFFERENT in terms of - how would we install mypy, black, etc globally - still using pipx likely
2. however @ofek pointed out that indeed hatch will have a pipx like thing in the near future. so if it covers that pipx usecase as well. then we won't need to teach any additional tool.

NOTE: we still have the environment management issue to tackle but we can't do everything at once. and it's ok if we have to adjust things over time. Let's have a discussion here on a final landing place for how to install hatch

✅ build consensus on a good way to do things that ✅ works on linux, mac and windows (we have windows and mac covered right now)

thoughts??

[ucodery]

(Just FYI there is one other place we already recommend pipx, and that's for grayskull)

[lwasser]

oooh you're right!! atleast it's in a small breakout box there. it seems like we might want to think about the bigger picture of environments and environment management. global installs vs project based workflows.

there could be use cases for say a specific scientific project that wants to use black to format code (or ruff) where it would be easier to have linting dependencies that get installed into a project environment vs an outside user installing things separately. this topic is actually fairly complex the more i think about it! it could be worth sitting down and thikning about various times when a pipx-like installation vs a project / single environment or set of project environments if we are using hatch / nox make sense.

yikes!

[ucodery]

I'll let @ofek speak to Hatch's Linux install story as I have only used it by doing a python -m pip install hatch. But as a user, going through the docs, it appears that there are two ways to install Hatch on Linux: pip like I did above, and a tarball binary distribution. The second is the only way to get Hatch if Python is not yet available.

The application-as-a-.tar.gz is not uncommon and some Linux users just know what to do with such a distribution, but it is not IMHO a beginner friendly install journey. The user will have to download the tarball, un-tar it, usually with a command line tool, and then place the unpacked executable on PATH. Its a lot to explain to users that aren't familiar with the terminal.

[lwasser]

@ucodery i hear you (but please know i'm not a linux user and have only played with it when i had to on a vm). it seems like to use linux, you need to be fairly well versed with terminal things. this is not a reason to go this route at all - but would you agree (or disagree) that linux users generally are more comfortable with the terminal? or is that a misconception in my brain.

i'm going to sign off here in just a few but let's see what ofek says! i'll check back in here on monday. i really love the thought that you're putting into this. it's exactly the thinking that we need. we also can test this out in our scipy workshop in july too! if you can't make it isabel and i can just tell you how it goes!!

[ucodery]

I would say yes, in my experience Linux users are more likely to be familiar with the terminal to some degree. I don't want to say they all are, and most of my interactions on computers are with coders who are generally more familiar with the terminal in any system. One area I think it might be less true is Windows users using WSL. They must install Hatch the Linux way, the Windows installer will not help them.

Besides tarballs there are generally two other forms of Linux distribution: support all native OS package formats, like ripgrep,or host a web-addressable POSIX compliant installer, like pyenv. Neither is a perfect solution for Linux, and either can be a lot more than the already significant effort to provide prebuilt binaries. But these are both common, and I would say more user friendly, ways of distributing. I wonder if Hatch has considered either.

[ofek]

This might be a stupid question but why can't Linux users just install from their distribution's package manager? My assumption was that doing so is the expectation of that community and there is no standard installer format but there have been different attempts like Snap (which I think failed?), Flatpak, etc. I've also seen software distribute their own .deb and .rpm but Hatch will never do so because that seems like a lot of work when users can just use what comes with the system.

I'm not opposed to an installer script for Linux although I don't have the time for that in the foreseeable future, but would welcome contributions!

[ofek]

Upon further research I don't want to do an installer script but rather I would prefer distributing a Flatpak or AppImage. The latter impresses me technically while the former seems like the future.

[ucodery]

Not a stupid question, distribution's package managers are definitely the preferred and many users will be using these channels. I'm not quite clear if you mean installing Python from the distro and then installing Hatch with that Python or if you mean installing hatch directly from the distro. If the latter, it hadn't occurred to me that it would be available; a quick search shows a version on pacman but none in debian.

[ofek]

Hmm, true https://repology.org/project/hatch/versions

I don't know why it's not on Debian cc @stefanor

[stefanor]

I don't know why it's not on Debian

I only packaged hatchling, not the full hatch, because that was all I needed at the time, to get a hatch-using package into Debian. I assumed that most hatch users wouldn't be using distro-provided hatch (probably a little old, on a stable release).

But taking a quick look at what it would take to package it, I think all the dependencies are in place so it should be pretty straight-forward. Edit: No, we need to package uv first

Filed https://bugs.debian.org/1072818 to request a Debian package

[ofek]

Thanks Stefano! While you're here, what are your thoughts on this issue? Basically, there is a desire to recommend the platform-specific Hatch installers on Windows and macOS but on Linux there is uncertainty. What is the usual way users install command line, single binary applications? Also, these users might not be as experienced in system things like modifying PATH.

[stefanor]

I think using their native package manage is always going to be the most user-friendly option. The difficulty is when they're running an older stable OS. The version they get may not be something upstream wants to support any more.

In that case, pipx is a good tool for Python. We package pipx in Debian, so it's only an apt install away.

There are also other tools like snap that could be useful here. (Flatpak isn't great for CLI) It allows delivering the latest versions of applications, complete with newer execution environments to a wide range of Linux distributions.

[WeepingClown13]

Following Stefano's bug I tried packaging hatch, built it and built the apache airflow package with it. Tried some other things and seems to be working fine, but indeed as mentioned above, uv is not in debian at least. I managed to get most of the tests passing simply by substituting the uv command with pip in tests (still have ~85 failures to work with, with some of them still calling uv). So at the moment it all depends on how necessary uv is to have, as packaging it will be quite some effort in all probability (the dependency tree looks huge and from rust packaging experince it is typically even bigger once you get into it).

[ofek]

@WeepingClown13 Thanks for trying! Can you use 1.9.7 which is the last release that didn't require UV?

---

@stefanor I didn't realize that but yeah after reading it looks like Flatpak is a no-go, thanks for the heads up! I'm open to feedback but I would prefer to not build Snap because I'm reading that it requires the user to have admin permissions and apparently startup time may be slow?

You have an interesting idea though, until Hatch is shipped the recommendation could just be to get pipx from the distribution and then simply pipx install hatch.

[ucodery]

I feel like this conversation has gone full circle. PyOpenSci already recommends using pix to install Hatch. It has so far worked great on Linux, using pipx's official installation documentation. But we've been having some issues with our Windows users going this route. Since Hatch provides a native Windows installer, we started looking into removing pipx from the guide. We don't really need a new way to get pipx on Linux but rather a consistent install story for all three main platforms.

[ofek]

Can you find out if your Linux users are familiar with Snap? I don't mind doing that if it's what folks are used to nowadays.

[stefanor]

We don't really need a new way to get pipx on Linux but rather a consistent install story for all three main platforms.

There is a bit of a fundamental difference there. Windows users are used to having to use installers for everything. Linux users are used to never using upstream installers, but rather going to their package manager first.

[lwasser]

hey @ofek @stefanor i'm happy to follow up with linux users in our community! let's see what a user-friendly story might look like on linux. in my mind it is the case that people using linux are likely used to doing things via command line, packaging managers, etc rather than installers. more coming soon on this!!

[lwasser]

@all-contributors please add @stefanor for review

[allcontributors[bot]]

@lwasser

I've put up a pull request to add @stefanor! :tada:

[JacksonBurns]

I have a number of packages installed through apt, but there are some notable exceptions. Many of my peers in science install conda via their CLI installation script. Many of us also install VSCode via snap.

Broadly agree that something via the CLI is more common, though any installer that works on the first try is a good installer IMO

[ofek]

Hatch is also available on conda-forge https://anaconda.org/conda-forge/hatch

[tomalrussell]

Just commenting as a PyOpenSci linux (Ubuntu) user - this works fine for my own machine and is within comfort zone:

apt install pipx
pipx install hatch

And if I needed it on a shared server, first route would be to install to a conda environment in my user directory, second would be via asking sysadmins nicely to add to a base image or module load system.

[lwasser]

ok friends - i'm following up on this conversation now because we are actually TEACHING hatch in 2 weeks at SCIPY!! 2 weeks exactly from today. and we @kierisi and I are going to pull together instructions for users to install things prior to the workshop.

This is where i think we are landing now - and what i can update our tutorial with if it sounds reasonable for now

1. We will obviously link to your installation instructions @ofek in the hatch docs but users will want (single way to do things) directions too
2. For those users we will tell them

windows: use the hatch installers - done. mac: user the hatch installers - done. Linux: use pipx (but also refer to the docs if you have other preferred ways to install things)

apt install pipx
pipx install hatch

as that seems to work for @tomalrussell

Can y'all confirm that this is a reasonable solution for the time being. Honestly it was the windows users that had the most "pain" in our last sprint installing hatch from our tutorials. But it seems like these three approaches might be best for the time being.

[lwasser]

@all-contributors please add @tomalrussell for review

[allcontributors[bot]]

@lwasser

@tomalrussell already contributed before to review

[lwasser]

@all-contributors please add @WeepingClown13 for review

[allcontributors[bot]]

@lwasser

I've put up a pull request to add @WeepingClown13! :tada:

[lwasser]

ok friends - i've opened this pr to address installation issues. review is welcome. we will merge it next tuesday 2 July 2024. i feel good about where we are with these instructions!