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

[docs] Add shebang section for scripts #11553

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[docs] Add shebang section for scripts #11553

wants to merge 5 commits into from

Conversation

sa-
Copy link

@sa- sa- commented Feb 16, 2025

Summary

Documentation only. Adds a section in scripts.md about running uv scripts with a shebang line

Test Plan

n/a

@sa- sa- changed the title [docs] Add shebang sectiong for scripts [docs] Add shebang section for scripts Feb 16, 2025
@zanieb zanieb self-assigned this Feb 16, 2025
@sa-
Copy link
Author

sa- commented Feb 17, 2025

CI now passes :)

@c14n
Copy link

c14n commented Feb 19, 2025

While these changes are now formally correct, they are unfortunately factually incorrect.

The proper shebang line should be

#!/usr/bin/env -S uv run --script

The use of the -S flag for env is required due to the way spaces are handled in shebang lines. The example given in the patch will simply not work. For details, refer to

  1. https://www.gnu.org/software/coreutils/env
  2. «Use in shell-scripts» on https://man.freebsd.org/cgi/man.cgi?env

The use of the --script flag for uv is required to prevent infinite recursion, as seen in #11220.

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 .py.

@sa-
Copy link
Author

sa- commented Feb 20, 2025

@c14n Thanks for taking the time, I've incorporated your feedback

@c14n
Copy link

c14n commented Feb 20, 2025

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:

This is an brief introductory paragraph that explains what you can expect
to accomplish by following the advice in this section. After the colon 
terminating this sentence, we give you example code:

```python title="example.py"
# Here is the code that is absolutely necessary to illustrate the point, 
# and no more. 
```

```console
$ command-to-run-the-example-must-have-dollar-sign-before
Output. Does not start with a dollar sign.
```

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.
Copy link

@c14n c14n Feb 20, 2025

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
Copy link

@c14n c14n Feb 20, 2025

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
```
Copy link

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.

Copy link

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!")
```

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

Successfully merging this pull request may close these issues.

3 participants