Issue #25768: Make compileall functions return booleans and document

the return values as well as test them.

Thanks to Nicholas Chammas for the bug report and initial patch.

2 files changed, 13 insertions, 4 deletions

diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index c5736f2..679c2b4 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -103,7 +103,8 @@ Public functions
 .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1)
 
    Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
-   files along the way.
+   files along the way. Return a true value if all the files compiled successfully,
+   and a false value otherwise.
 
    The *maxlevels* parameter is used to limit the depth of the recursion; it
    defaults to ``10``.
@@ -155,7 +156,8 @@ Public functions
 
 .. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1)
 
-   Compile the file with path *fullname*.
+   Compile the file with path *fullname*. Return a true value if the file
+   compiled successfully, and a false value otherwise.
 
    If *ddir* is given, it is prepended to the path to the file being compiled
    for use in compilation time tracebacks, and is also compiled in to the
@@ -191,8 +193,10 @@ Public functions
 
 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1)
 
-   Byte-compile all the :file:`.py` files found along ``sys.path``. If
-   *skip_curdir* is true (the default), the current directory is not included
+   Byte-compile all the :file:`.py` files found along ``sys.path``. Return a
+   true value if all the files compiled successfully, and a false value otherwise.
+
+   If *skip_curdir* is true (the default), the current directory is not included
    in the search.  All other parameters are passed to the :func:`compile_dir`
    function.  Note that unlike the other compile functions, ``maxlevels``
    defaults to ``0``.
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index f97c70f..c660933 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -230,6 +230,11 @@ that may require changes to your code.
 Changes in the Python API
 -------------------------
 
+* The functions in the :mod:`compileall` module now return booleans instead
+  of ``1`` or ``0`` to represent success or failure, respectively. Thanks to
+  booleans being a subclass of integers, this should only be an issue if you
+  were doing identity checks for ``1`` or ``0``. See :issue:`25768`.
+
 * Reading the :attr:`~urllib.parse.SplitResult.port` attribute of
   :func:`urllib.parse.urlsplit` and :func:`~urllib.parse.urlparse` results
   now raises :exc:`ValueError` for out-of-range values, rather than