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.

Sign up for GitHub

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

Jump to bottom

Fix direct usage of pip.pyz example #12043

Merged
merged 13 commits into from
Apr 22, 2024
Merged

Fix direct usage of pip.pyz example #12043

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
66903a3
Fix direct usage of pip.pyz example
Jackenmen May 20, 2023
5102ca4
Create 12043.doc.rst
Jackenmen May 20, 2023
881da76
Update installation.md
Jackenmen May 20, 2023
3db673f
Update installation.md
Jackenmen May 21, 2023
39431b5
Use a single tab for both commands
Jackenmen May 28, 2023
b1ea8c1
Revert "Use a single tab for both commands"
Jackenmen May 28, 2023
cebb9f1
Add a note to Windows invocation
Jackenmen May 28, 2023
b96b21d
Add newline to make it look less weird when changing tabs?
Jackenmen May 28, 2023
8fe45a1
Try fixing italics *again*
Jackenmen May 28, 2023
8901f87
Remove the code block syntax altogether
Jackenmen May 28, 2023
a3ce5aa
Try doscon
Jackenmen May 28, 2023
2d6e6be
Check one thing about the prompt
Jackenmen May 28, 2023
67f79f2
Revert "Check one thing about the prompt"
Jackenmen May 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions docs/html/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,25 @@ $ python pip.pyz --help

If run directly:

```{pip-cli}
$ pip.pyz --help
````{tab} Linux
```console
$ chmod +x ./pip.pyz
$ ./pip.pyz
```
````

````{tab} MacOS
```console
$ chmod +x ./pip.pyz
$ ./pip.pyz
```
Jackenmen marked this conversation as resolved.
Show resolved Hide resolved
````

````{tab} Windows
```console
C:\> .\pip.pyz
```
````
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On windows this needs to register the .pyz extension and associate it to some python interpreter? Does this support virtual environments?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On windows this needs to register the .pyz extension and associate it to some python interpreter?

Yeah, that's done during installation. Considering that it's based on py launcher, I'm guessing it's only done when that is installed.

Does this support virtual environments?

Yes, py launcher uses the activated virtual environment if a specific Python version isn't specified, which it isn't when running the .pyz file directly.

During my testing, I found out that zipapps don't work as great on Windows as they do on Unix since they're only based on the registered extensions and therefore aren't recognized transparently everywhere (e.g. subprocess.run(["pip.pyz"]) doesn't work, running it in PowerShell causes Command Prompt window to open instead of using the existing terminal).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

zipapps don't work as great on Windows as they do on Unix

Correct. On Windows, I would typically recommend using py C:\Path\To\pip.pyz, or using a launcher executable. Users of the scoop package manager on Windows can use something like https://github.com/pfmoore/scoop-enk/blob/master/bucket/pip.json (or just register that bucket and use it directly 🙂)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this be fixed to say py .\pip.pyz?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to make sure I understand you correctly, you want both of these invocations to use py pip.pyz?
image

Instead of being different how it's on Linux/MacOS:
image

Such change would be fine for me, I just want to make sure that's what you want. In such a case, I should probably add some text before the command on the second Windows tab to minimize the user confusion though. Or maybe keep only a single Windows tab for that whole text there and only show a single command on the Windows tab?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, that's a good point. I hadn't spotted that this was the "if run directly" section. I honestly don't know how we explain what's needed simply here. You're correct that it shouldn't use py as that's not "running it directly".

I don't think the pip documentation is the right place to get into how to set your system up to automatically run .pyz files, but I also don't think we're doing anyone any favours by giving a command that won't work for a non-trivial subset of users 🙁

Maybe we just remove the example invocation altogether, just leaving the statement "If run directly then the currently active Python interpreter will be used". It's a little cryptic, leaving the user to infer what "running directly" means, but at least it isn't flat-out incorrect.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I committed what I think would be the least cryptic option. It isn't quite what you proposed so let me know what you think about that:
https://pip--12043.org.readthedocs.build/en/12043/installation/#standalone-zip-application

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I don't like it, as the way the second example disappears when I switch from Linux to Windows is extremely disconcerting.

OK, this all sucks. I'm going to say let's just go back to using plain .\pip.pyz on Windows, and hope we don't get too many confused Windows users asking us how to register the .pyz extension. I don't like it, but all of the alternatives seem worse to me.

Maybe we just add a note - something like

If run directly:
C:> .\pip.pyz --help
then the currently active Python interpreter will be used. You may need to configure your system to recognise the .pyz extension before this will work.

that would be enough?

By the way, I just noticed that the Windows version, C:> py pip.pyz --help renders in italics, for some weird reason. It shouldn't do that. I have no idea why it happens - other console commands don't display like that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we just add a note - something like

If run directly:
C:> .\pip.pyz --help
then the currently active Python interpreter will be used. You may need to configure your system to recognise the .pyz extension before this will work.

that would be enough?

Seems fine to me, will change it to that in a moment.

By the way, I just noticed that the Windows version, C:> py pip.pyz --help renders in italics, for some weird reason. It shouldn't do that.

That's partially on me, I tried to make it consistent with the prefix used by {pip-cli} and I removed the \ from C:\> which seems to get rendered differently. C:\> is actually more correct anyway since that's how Command Prompt shows the root drive path so I'll change it back.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I think it looks good now. Turns out that the italics was caused by the console lexer being used for the code block. I changed it to the proper doscon. Btw, the same problem can also be observed in user guide document.

As for the note, I added it as a separate line in the Windows tab. To me, it looks less disconcerting when switching tabs, see:

Linux tab

chrome_h7g4UpQ64U

Windows tab with one paragraph

chrome_RcIiEbjhPw

Windows tab with two paragraphs

chrome_eWdTEZ5CzN


then the currently active Python interpreter will be used.

Expand Down
1 change: 1 addition & 0 deletions news/12043.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Fix the direct usage of zipapp showing up as ``python -m pip.pyz`` rather than ``./pip.pyz`` / ``.\pip.pyz``