Documentation strategy for PEP 3151
Hello, I'd like some advice on what the best path is in cases such as: A :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`. Should I replace "socket.error" with "OSError" (knowing that the former is now an alias of the latter), or leave "socket.error" so that people have less surprises when running their code with a previous Python version? Regards Antoine.
2011/10/12 Antoine Pitrou <solipsis@pitrou.net>:
Hello,
I'd like some advice on what the best path is in cases such as:
A :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
Should I replace "socket.error" with "OSError" (knowing that the former is now an alias of the latter), or leave "socket.error" so that people have less surprises when running their code with a previous Python version?
I think you should say OSError but leave a historical note with a versionchanged on it. -- Regards, Benjamin
On Oct 12, 2011, at 10:24 AM, Benjamin Peterson wrote:
2011/10/12 Antoine Pitrou <solipsis@pitrou.net>:
I'd like some advice on what the best path is in cases such as:
A :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
Should I replace "socket.error" with "OSError" (knowing that the former is now an alias of the latter), or leave "socket.error" so that people have less surprises when running their code with a previous Python version?
I think you should say OSError but leave a historical note with a versionchanged on it.
+1 -Barry
On 10/12/2011 10:58 AM, Barry Warsaw wrote:
On Oct 12, 2011, at 10:24 AM, Benjamin Peterson wrote:
2011/10/12 Antoine Pitrou<solipsis@pitrou.net>:
I'd like some advice on what the best path is in cases such as:
A :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
Should I replace "socket.error" with "OSError" (knowing that the former is now an alias of the latter), or leave "socket.error" so that people have less surprises when running their code with a previous Python version?
I think you should say OSError but leave a historical note with a versionchanged on it.
+1
Given that tracebacks for uncaught socket errors will end with OSError, the doc should say that is what is raised. The edits and notes I have seen so far today look fine. I also liked the What's New example. The new version looks *much* better, and not just because of the deleted import, but because the changes allow a much clearer structure that is more pleasant to read. So my thanks also for carrying out this project. -- Terry Jan Reedy
On Wed, Oct 12, 2011 at 09:17, Antoine Pitrou <solipsis@pitrou.net> wrote:
Hello,
I'd like some advice on what the best path is in cases such as:
A :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
Should I replace "socket.error" with "OSError" (knowing that the former is now an alias of the latter), or leave "socket.error" so that people have less surprises when running their code with a previous Python version?
I would expect the 3.3 documentation shows the best way to write 3.3 code, so I'd prefer to see OSError there. A good "What's New" entry as well as explanation/example of how the hierarchy has changed in library/exceptions.rst should cover anyone questioning the departure from socket.error.
participants (5)
-
Antoine Pitrou -
Barry Warsaw -
Benjamin Peterson -
Brian Curtin -
Terry Reedy