python-package-guide HATCH tutorials update: Provide CLI example commands for Windows users

          Ok, 1st and 3rd todos are removed.  A note about converting setup.py is already in the Hatch tutorial.

About command line stuff... I was hesitating to bring this up, but... There are a fair number of folks using Windows. The commands may look a bit different if executed in cmd...but not always. A fair number of tools that come in from the *x world will use forward slashes in paths, or not understand a drive letter, or require their own special syntax for that. Others will take back slashes, but need them quoted. The best ones know what OS they're running on, and do "when in Rome...".

Windows users could install Git Bash. Or Windows Subsystem for Linux (WSL; which allows having an entire Linux distro under Windows). Or the classic Cygwin. Or adapt the commands for running directly on Windows. The easiest option is likely Git Bash. It's not entirely friction-free, however, as Git Bash's executable path may differ from the Windows path.

I've mostly ended up modifying commands so they work on cmd, except when the documentation strongly encourages use of Git Bash. Or when there's a canned development environment that can be run on a virtual machine. That's what we used to do for an open-source emergency management tool I used to work on, when we participated in hackathons. It could take the entire day to set up our environment, so instead, we prepared pre-configured virtual machine images.

The following has a good list of the options, one could just drop in a reference to this at the outset, wherever it says "we don't support Windows". :D :D :D

https://itsfoss.com/run-linux-commands-in-windows/

Originally posted by @ptressel in https://github.com/pyOpenSci/python-package-guide/pull/224#discussion_r1560142709

Apr 11 '24 19:04 ucodery

It would be great if we could provide examples for native Windows users, as we do for POSIX users. We very occasionally reference command differences between command examples for those on Windows, but we don't every provide them as alternative top-level sample code.

We do IME try to craft commands in such a way they they will work unaltered on the most systems possible, but it is not always possible. The bash examples, at least, need close scrutiny.

As a possible solution, we could adopt tabbed code callouts, using a library like https://sphinx-tabs.readthedocs.io/en/latest/ or https://pypi.org/project/sphinx-code-tabs/ (although using an extension directive could limit our ability to do other more advanced code examples like #239).

One thing to decide is which environment to target as the native Windows environment. I would say that all of WLS(2), git-bash, cygwin, mingw, msys2 can be skipped as our POSIX examples should already generally work there. That leaves either a cmd or powershell environment. Unfortunately, these two environments are not really interchangeable, and whichever one we support will leave the other in the cold.

Apr 11 '24 19:04 ucodery

Also, this is strongly related to #134

Apr 11 '24 20:04 ucodery

All excellent points! And good eye on noting the other issue re. general unfamiliarity with command line use.

Sounds like it is time for me to install hatch under Windows, and try out the various options. I had better not offer to do this until after Tax Day, though. 😁

Apr 12 '24 20:04 ptressel

Just FYI, I have not forgotten...just got swamped with other things.

May 06 '24 20:05 ptressel

oh no worries @ptressel i just spent some time today trying to wrap up issues and pr's and am behind as well ✨ i think the windows tabs idea is a great one. the challenge that i have personally is that i don't have a windows computer / vm here right now to test things on.

i have considered making a vm on my mac to test all things windows. i also don't have a good sense of what shells windows users prefer.

When i taught Python and bash we used to suggest that all windows users use gitbash as it was the most straight forward tool to download, install and use. however most of my students were new to shell / bash so they didn't have a preference. i don't know what to suggest here in terms of which shell to add a tab for.

@ptressel @ucodery do you have any suggestions? we literally ran into this in our workshop the other week. i agree 💯 that it's important!!

May 06 '24 23:05 lwasser

There are at least five options...listed here in likely preference order.

Commands adapted to run on the Windows command line (cmd) -- this is what's available with no work.
Git Bash -- the main issue is the path -- are bash commands masking items with the same name in the Windows path? -- and the home directory -- Git Bash defaults to the user's directory rather than Documents, which is probably the right choice, but may be a surprise.
PowerShell -- also available by default, but less commonly used than cmd.
Windows Subsystem for Linux (WSL) -- an installable tool from Microsoft that allows running a Linux distro on Windows. It's an impressive piece of work, as (if I understand correctly) it translates operations into native Windows calls -- it's not a VM.
Cygwin bash -- I don't know what the maintenance status is these days.

Windows users will have cmd, and may have used it. If they install git from git-scm.com, then they'll have Git Bash (IIRC). Those are likely the two best options. If we find out that the commands for use with Git Bash are identical to those for Linux, then asking folks to install git gets a big boost in preference, as there would be no need for separate Windows commands beyond some setup.

(I predate the command line -- started with FORTRAN coding sheets and punched cards. :D )

May 07 '24 04:05 ptressel

Just to add to what @ptressel already said

cmd is probably the most "obvious" choice. It's the oldest and most consistently-available option. It's the sh of Windows - always there, but full of old and strange conventions and not preferred (IME) by those with more technical knowledge. But then those technical users know what you are trying to convey and are likely to be able to translate to their preferred workflow.
git bash certainly was the preferred shell for dev examples in the past, but IME at least with software engineers WLS is much preferred these days. However, both use a true bash and the commands we already have should work. If not, they should be changed to work on a Linux bash and WLS bash.
powershell is the only other native choice besides cmd. It's new and fancy and has it superfans. If cmd is Windows' sh then powershell is its fish. As someone who helps maintain terminal installation commands for Windows software I can tell you that whichever you pick there will be users that copy the provided command and paste it into their preferred (or only know) terminal and get confused why the docs have a command that errors out. Not matter what warnings you place there.
See above - WSL is great, very popular, but we don't need separate commands for it. Also IIRC some Windows editions won't support WSL.
Cygwin is still maintained and works just fine. I would avoid it for new users though. And once again, it is POSIX so no new commands if we did recommend it.

May 07 '24 17:05 ucodery

my first pick would be WSL, for some reasons:

if windows user don't know cmd/power shell commands, so the learning curve would be the same to learn linux commands.
in my experience, sometimes even with anaconda some students are not able to have a funcional environment.
some packages don't support windows (maybe it is not a extensive list of the most popular ones, but sometimes it could be a restriction)
provide support in a community for windows users sometimes is really hard

of course, mainly of my points are based on my experience, and of course, my point here is not about to use it as a preferred tool, but at least it would be nice to not ignore it. and additionally, it is really easy to configure and easy to use it.

May 07 '24 18:05 xmnlab

I've found myself in the need of a python development environment for a beginner on Windows just some days ago. I feel like I can really recommend miniforge:

it comes with a graphical installer for Windows
it provides conda and mamba resolvers
it comes with a nice miniforge prompt with linux like commands
it comes with a code command launching vs code in the related conda/mamba environment, so one can use git extensions in vs code, rather than "bother" with command lines.

May 07 '24 18:05 cmarmo

@cmarmo i am a HUGE fan of miniforge but i never knew about the prompt that it offers. how do you invoke a miniforge prompt?

my quick read on WSL (i could be wrong y'all) is that it might be more involved to install / setup. can anyone confirm and or tell me my read is wrong!?

What if we consider a few options:

If they don't yet have python installed, and they want to use conda - miniforge is the way to go OR mamba forge for faster resolving (if that has the prompt @cmarmo mentioned). Then tell people about the prompt that is available with this python install
If they are on windows and only have the cmd prompt, suggest they use gitbash - i do have this setup bash lesson here. but i haven't tested it on windows in a year or two
tell people about WSL in case they might be interested in a more robust solution? this one just sounds a bit more complex to me (again i could be wrong!)

@ptressel and @ucodery both have the cmd prompt first for windows users. we could include commands for that prompt (if they will consistently work) i'm just nervous about things consistently working across various versions of windows. btw i do remember using windows ages ago and the DOS prompt.

May 07 '24 20:05 lwasser

how do you invoke a miniforge prompt?

At least in the last version I've installed, the installer put it in the Windows Start menu, I looked for it with the search bar.... sorry I can't provide a screenshot, I don't have a Windows system on hand right now.

May 07 '24 21:05 cmarmo

no worries - please do not apologize! that is helpful to know!!

May 07 '24 21:05 lwasser

I want to circle back on this issue. i think right now there still isn't enough information for an external contributor to work on this. i'm going to keep it open but remove it from the help-wanted board for the time being!

Jul 12 '24 17:07 lwasser