The log_error method in refactor.RefactoringTool raises the exception:

    def log_error(self, msg, *args, **kwds):
        """Called when an error occurs."""
        raise

but every usage of it implies that it does not, e.g:

    def refactor_string(self, data, name):
        """Refactor a given input string.
        Args:
            data: a string holding the code to be refactored.
            name: a human-readable name for use in error/log messages.
        Returns:
            An AST corresponding to the refactored input stream; None if
            there were errors during the parse.
        """
        # [..]
        try:
            tree = self.driver.parse_string(data)
        except Exception as err:
            self.log_error("Can't parse %s: %s: %s",
                           name, err.__class__.__name__, err)
            return
        finally:
        # [..]

This is the only explicit conflict I found in the documentation. From looking at the refactor_string function, it seems it should never raise on parse errors. Other uses of it are followed immediately by a return.

I'd like to see log_error only log the exception and continue.

Thanks Nick for the details. I think 2to3 uses StdoutRefactoringTool [1] which inherits from RefactoringTool in the chain and implements log_error [2] that logs the error. 

StdoutRefactoringTool inherits from MultiprocessRefactoringTool [3] which in turn inherits from RefactoringTool [4] that raises the exception on log_error. But StdoutRefactoringTool re-implemented it to log and not to raise. I couldn't see any errors on scripts that have parsing errors. I think the docstring is right from the context of StdoutRefactoringTool but they were essentially present in RefactoringTool adding to the confusion I hope. Suggestions welcome on improving this. Feel free to correct me if I am misunderstanding the issue.

Example I have used to verify : 

$ cat ../backups/bpo32750.py # parse error file should be logged and skipped
foo +- # Invalid file
$ cat ../backups/bpo32750.py # valid file
print "hello"
$ 2to3 ../backups/bpo32750.py ../backups/bpo32750_valid.py
RefactoringTool: Skipping optional fixer: buffer
RefactoringTool: Skipping optional fixer: idioms
RefactoringTool: Skipping optional fixer: set_literal
RefactoringTool: Skipping optional fixer: ws_comma
RefactoringTool: Can't parse ../backups/bpo32750.py: ParseError: bad input: type=4, value='\n', context=('', (1, 6))
RefactoringTool: Refactored ../backups/bpo32750_valid.py
--- ../backups/bpo32750_valid.py	(original)
+++ ../backups/bpo32750_valid.py	(refactored)
@@ -1 +1 @@
-print "hello"
+print("hello")
RefactoringTool: Files that need to be modified:
RefactoringTool: ../backups/bpo32750_valid.py
RefactoringTool: There was 1 error:
RefactoringTool: Can't parse ../backups/bpo32750.py: ParseError: bad input: type=4, value='\n', context=('', (1, 6))

Hope this helps.

Thanks again

[1] StdoutRefactoringTool - https://github.com/tirkarthi/cpython/blob/f6c8007a29b95b3ea3ca687a9b4924769a696328/Lib/lib2to3/main.py#L245

[2] StdoutRefactoringTool.log_error - https://github.com/tirkarthi/cpython/blob/f6c8007a29b95b3ea3ca687a9b4924769a696328/Lib/lib2to3/main.py#L65

[3] MultiprocessRefactoringTool - https://github.com/tirkarthi/cpython/blob/f6c8007a29b95b3ea3ca687a9b4924769a696328/Lib/lib2to3/refactor.py#L676

[4] RefactoringTool - https://github.com/tirkarthi/cpython/blob/f6c8007a29b95b3ea3ca687a9b4924769a696328/Lib/lib2to3/refactor.py#L155

If I understand correctly, this is not about an observed bug but about a confusion about which log_error function is being called. Can we close this or is there something to do here?