Documentation

(Filing as a documentation issue, since I suspect the behavior is intentional and has its valid use cases.)

In Gentoo, we install packages into a temporary directory whose contents resemble the actual filesystem prefix. For some packages that don't use PEP517 build systems, we invoke python -m compileall to byte-compile the installed modules.

Today I wanted to switch our code to start using the -s option, and I've noticed that in addition to the path specified, it also strips the path separator following it.

For example, consider the following example:

$ mkdir -p /tmp/destdir/usr/lib/python3.13/site-packages
$ > /tmp/destdir/usr/lib/python3.13/site-packages/foo.py
$ python3.13 -m compileall -s /tmp/destdir /tmp/destdir/usr/lib/python3.13/site-packages/foo.py
Compiling '/tmp/destdir/usr/lib/python3.13/site-packages/foo.py'...
$ strings /tmp/destdir/usr/lib/python3.13/site-packages/__pycache__/foo.cpython-313.pyc 
'usr/lib/python3.13/site-packages/foo.py
<module>r

Note that while I expeced it to strip /tmp/destdir, leaving /usr/lib/python3.13/site-packages/foo.py, it also stripped the following slash, making the path relative.

Now, I can achieve the desired behavior by adding -p /:

$ rm /tmp/destdir/usr/lib/python3.13/site-packages/__pycache__/foo.cpython-313.pyc
$ python3.13 -m compileall -s /tmp/destdir -p / /tmp/destdir/usr/lib/python3.13/site-packages/foo.py
Compiling '/tmp/destdir/usr/lib/python3.13/site-packages/foo.py'...
$ strings /tmp/destdir/usr/lib/python3.13/site-packages/__pycache__/foo.cpython-313.pyc 
(/usr/lib/python3.13/site-packages/foo.py
<module>r

However, I found that behavior surprising and I think it should be documented better. Particularly, the current documentation states:

which to me sounds like it would remove the specified string, rather than making the path relative. Perhaps it would make sense to specify explicitly that:

1. Removing the prefix makes paths relative to it.
2. -s and -p can be used simultaneously.
3. -p / can be used to make the path absolute.

Linked PRs

• gh-133503: Update compileall.rst's documentation of -s and -p for clarity,  #134756
• [3.13] gh-133503: clarify compileall -s/-p docs (GH-134756) #134996
• [3.14] gh-133503: clarify compileall -s/-p docs (GH-134756) #134997