Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editable install instructions on contributing page could be clearer #505

Open
andypbarrett opened this issue Feb 2, 2024 · 7 comments
Open

Comments

@andypbarrett
Copy link

It looks like there is a typo on the contributing page.

I think

pip install -e.

should be

pip install -e .
@JessicaS11
Copy link
Member

Thanks, @andypbarrett! I can't remember where or when I learned it (and of course am not finding it documented anywhere), but the two are equivalent. I use pip install -e. all the time (yay for not having to type that extra character!). Have you encountered use cases where that doesn't work? If so, we should definitely update the docs. Otherwise, do you think it's worth a note that either works?

@weiji14
Copy link
Member

weiji14 commented Feb 6, 2024

I tried to add a space in 2ec4e6f, but Jessica said the same thing in #187 (comment) and reverted it back 😆

@andypbarrett
Copy link
Author

Mmmm I just tried it again and pip install -e. worked. Weird! I thought spaces mattered in linux.

I suggest closing the issue because it is a red hering.

@andypbarrett
Copy link
Author

Alternatively add that pip install -e. and pip install -e . both work. Now I want to understand why they both work.

@JessicaS11
Copy link
Member

Alternatively add that pip install -e. and pip install -e . both work.

probably a good idea given it seems to be a recurring theme... 😆

Now I want to understand why they both work.

Curious to know if you figure it out. I think I learned it in a youtube video of a "how to make Python software" workshop that Lindsey Heagey recommended for me when we started icepyx. It was one of those narrative "you can do this without the space instead and it works" things. 🤷‍♀️

@mfisher87
Copy link
Member

mfisher87 commented Aug 12, 2024

This is a confusing aspect of POSIX shortform argument behavior. Often, for example, one wants to quickly specify shortform arguments and their values:

du -hd1

This passes the --human-readable flag and the --depth option with the value 1 to du. It's short, but it's not readable. There are additional problems. Order matters. What about du -d1h?

$ du -d1h
du: invalid maximum depth ‘1h’
Try 'du --help' for more information.

Only one specific way of glomming the arguments into a single incantation gives us the 🪄 magic 🎩 🐇 we're looking for! However, du --depth 1 --human-readable is clear and can be broken down and re-written in different order.

IMO, for educational content, we should strictly avoid short-form arguments and go for --editable instead of -e to avoid any confusion. There is no option to omit the space after the long-form argument:

$ pip install --editable.

Usage:   
  pip install [options] <requirement specifier> [package-index-options] ...
  pip install [options] -r <requirements file> [package-index-options] ...
  pip install [options] [-e] <vcs project url> ...
  pip install [options] [-e] <local project path> ...
  pip install [options] <archive url/path> ...

no such option: --editable.

@mfisher87 mfisher87 changed the title Typo in pip install -e instructions on contributing page Editable install instructions on contributing page could be clearer Aug 12, 2024
@mfisher87
Copy link
Member

https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html

An option and its argument may or may not appear as separate tokens. (In other words, the whitespace separating them is optional.) Thus, -o foo and -ofoo are equivalent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants