#479 scripts install with broken shebang

[Jason R. Coombs]

The way docutils presents its executable scripts is broken on macOS.

Today, I installed docutils using pipx.

 @ pipx install docutils
  installed package docutils 0.20.1, installed using Python 3.12.2
  These apps are now globally available
    - docutils
    - rst2html.py
    - rst2html4.py
    - rst2html5.py
    - rst2latex.py
    - rst2man.py
    - rst2odt.py
    - rst2odt_prepstyles.py
    - rst2pseudoxml.py
    - rst2s5.py
    - rst2xetex.py
    - rst2xml.py
    - rstpep2html.py
done! ✨ 🌟 ✨

Quick aside, it would be nice if these executables didn't have the .py extension.

After installing, the scripts failed with this error:

 @ rst2html.py docs/*
xonsh: subprocess mode: command not found: '/Users/jaraco/Library/Application'

The problem is that pipx, by default, installs its data into the "Application Support" directory:

 @ pipx environment | grep HOME
PIPX_HOME=
PIPX_HOME=/Users/jaraco/Library/Application Support/pipx

And when it does, the scripts get installed with an invalid shebang because Unix doesn't support spaces in shebangs:

 @ head -n 1 $(which rst2html.py)
#!/Users/jaraco/Library/Application Support/pipx/venvs/docutils/bin/python

[Günter Milde]

Thank you for reporting a problem with Docutils.

The problem seems caused by the installer pipx rather than Docutils:

In the repository and source tarball, the front end tools start with the line

#!/usr/bin/env python3

In the "wheel", the line is shortened to

#!python

The upcoming release 0.21 will provide rst2* "console_scripts" entry points instead of installing the rst2*.py front end tools.
This change will provide the rst2* cli commands ("apps") also under Windows and solve the quick aside.

The Generic Command Line Front End docutils already uses the new standard.
You may try, e.g,

docutils --help

to see, if this works on your system. If yes, the "rst2*" commands should work with Docutils 0.21, too.

Attention

The current usage is

<toolname> [options] [<source> [<destination>]]

In a directory with files a.rst and b.rst, the command

rst2html.py docs/*

will happily overwrite b.rst with the output of converting a.rst without warning.
This is a known problem and will change in future releases.

[Günter Milde]

This is a known issue with pipx under MacOS. See
https://pipx.pypa.io/stable/troubleshooting/#macos-issues
for a workaround.
(It would still be interesting to know, whether the problem persists with "console entry points", i.e. with the docutils app.

[Jason R. Coombs]

Yes, using the docutils app does work, so rst.* should also work once converted to console entry points. Thanks!

I agree the "macOS workaround" could work around the issue, but it's not a very robust workaround, as it requires repairing every shebang on every installation, and moreover, the bug doesn't exist just in macOS or just with pipx. Here's the same bug manifest in Ubuntu using just pip:

docker run -it jaraco/multipy-tox bash
root@6b1625414874:/# mkdir /foo\ bar
root@6b1625414874:/# py -m venv /foo\ bar/env
root@6b1625414874:/# /foo\ bar/env/bin/pip install -q docutils

[notice] A new release of pip is available: 23.2.1 -> 24.0
[notice] To update, run: python3.12 -m pip install --upgrade pip
root@6b1625414874:/# /foo\ bar/env/bin/rst2html.py
bash: /foo bar/env/bin/rst2html.py: /foo: bad interpreter: No such file or directory

The root problem is that Unix doesn't support paths with spaces in a shebang.

[Jason R. Coombs]

The upstream pipx issue is https://github.com/pypa/pipx/issues/1198.