-
Notifications
You must be signed in to change notification settings - Fork 1.1k
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
[docs] Add shebang section for scripts #11553
base: main
Are you sure you want to change the base?
Conversation
CI now passes :) |
While these changes are now formally correct, they are unfortunately factually incorrect. The proper shebang line should be
The use of the
The use of the Moreover, if the latter flag is used, the extension of the script can be chosen arbitrarily, or even omitted; it does not have to be |
@c14n Thanks for taking the time, I've incorporated your feedback |
Notice that I am not a maintainer, so the following are just the observations of some random passer-by. There are still some issues with this pull request, chief of which being that the changes do not mesh well with the surrounding material. This is due to the fact that you do not adhere to the style guide, and do not try to match the structure of the surrounding material. Notice how every section on this page of the documentation adheres to this pattern:
Do you see how focused and concise that approach is? My advice: Read the style guide and try to match the form of the existing material. (This also applies to commit messages.) There are also some issues with the contents of the patch. I'll add inline comments to point those out. |
## Using a shebang line | ||
|
||
With a shebang line, you can run scripts that are on your `PATH` or in the current folder without | ||
specifying `uv run` before the filename. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
An executable script with a shebang can be run from anywhere, if you provide the full path to it.
For example, create a file called `do-thing` with the following contents | ||
|
||
```python title="do-thing" | ||
#!/usr/bin/env -S uv run --script |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is the important part of the example. Why do you distract from this with inline script dependencies?
A plain print()
statement should probably be enough.
|
||
``` | ||
chmod +x do-thing | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this need to be explained this explicitly? According to the style guide, guides
May assume basic knowledge of the domain.
so it should be enough to mention that a script should have its execute bit set in the introduction.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about this for an introductory paragraph:
On Unix-like systems, you can turn your script into a standalone executable by setting its execute
bit with `chmod +x standalone.py` and adding a shebang interpreter directive at the start of your
script:
```python title="standalone.py"
#!/usr/bin/env -S uv run --script
print("Hello, standalone!")
```
Summary
Documentation only. Adds a section in scripts.md about running uv scripts with a shebang line
Test Plan
n/a