xmlrpc.client tells Fails and ProtocolError are returned, while the code raises them

[JulienPalard]

Documentation

In https://docs.python.org/3/library/xmlrpc.client.html I read:

The RPC finishes by returning a value, which may be either returned data in a conformant type or a Fault or ProtocolError object indicating an error.

Which I interpret like this: the method either returns an object or returns a Fault (or a ProtocolError) instance.

By looking at the implementation I only see raise Fault(..., never return Fault, so it seems like the doc should be:

The RPC finishes either by returning data in a conformant type or by raising a Fault or ProtocolError exception indicating an error.

I have no working code with xmlrpc.client to test it, I'm just translating the doc in french.

Linked PRs

• gh-140458: Clarify xmlrpc.client behavior #140759

[JulienPalard]

Reproduced with the is_even example from the doc:

Normal expected behavior, it returns a value:

>>> with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
...     print("3 is even: %s" % str(proxy.is_even(3)))
...     print("100 is even: %s" % str(proxy.is_even(100)))
...     
3 is even: False
100 is even: True

Bad behavior, doc tells it returns Fault while it raises Fault:

>>> with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
...     proxy.test()
...     
Traceback (most recent call last):
  File "<python-input-3>", line 4, in <module>
    proxy.test()
    ~~~~~~~~~~^^
  File "/usr/lib/python3.13/xmlrpc/client.py", line 1096, in __call__
    return self.__send(self.__name, args)
           ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/xmlrpc/client.py", line 1435, in __request
    response = self.__transport.request(
        self.__host,
    ...<2 lines>...
        verbose=self.__verbose
        )
  File "/usr/lib/python3.13/xmlrpc/client.py", line 1140, in request
    return self.single_request(host, handler, request_body, verbose)
           ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/xmlrpc/client.py", line 1156, in single_request
    return self.parse_response(resp)
           ~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/usr/lib/python3.13/xmlrpc/client.py", line 1325, in parse_response
    return u.close()
           ~~~~~~~^^
  File "/usr/lib/python3.13/xmlrpc/client.py", line 642, in close
    raise Fault(**self._stack[0])
xmlrpc.client.Fault: <Fault 1: '<class \'Exception\'>:method "test" is not supported'>

[JulienPalard]

Ohhh there's even an example later in the doc:

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
try:
    proxy.add(2, 5)
except xmlrpc.client.Fault as err:

Flagging as easy if someone want to make a PR of this :)