Documentation strategy for PEP 3151

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation strategy for PEP 3151

Antoine Pitrou

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.


_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strategy for PEP 3151

Benjamin Peterson-3
2011/10/12 Antoine Pitrou <[hidden email]>:

>
> 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
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strategy for PEP 3151

briancurtin
In reply to this post by Antoine Pitrou
On Wed, Oct 12, 2011 at 09:17, Antoine Pitrou <[hidden email]> 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.
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strategy for PEP 3151

Barry Warsaw
In reply to this post by Benjamin Peterson-3
On Oct 12, 2011, at 10:24 AM, Benjamin Peterson wrote:

>2011/10/12 Antoine Pitrou <[hidden email]>:
>> 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
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strategy for PEP 3151

Terry Reedy
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<[hidden email]>:
>>> 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

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com