This is a follow up to issue #8855. Currently the security warning is completely invisible from Python 2 docs http://docs.python.org/2/library/shelve.html and is located under screen border on Python 3 docs.

The proposal is to move warning out of the description of open() function to paragraph following module description, the same way is it is done for pickle http://docs.python.org/3.3/library/pickle.html

tag:easy

Using the "warning" directive can be backported from the 3.x docs.

For 3.x, it's already prominent enough. Your "screen border" is not everyone's screen border.

The scope of warning is wrong. It is not a warning for open() call, and that's why it is easy to miss.

Oh, please. It's big and red and directly below the open() description, how could you miss it?

New changeset 1d850260a356 by Georg Brandl in branch '2.7':
Closes #19061: make shelve security warning consistent between 2.x and 3.x.
http://hg.python.org/cpython/rev/1d850260a356

On Sun, Sep 22, 2013 at 12:42 PM, Georg Brandl <report@bugs.python.org>wrote:

> Oh, please. It's big and red and directly below the open() description,
> how could you miss it?
>

I believe that it is pretty easy with mobile browser due to screen
constraints. Can you test this on your mobile devices?

As for your argument about my border not being everyone's border, I believe
that my border accounts for 18%+ of browser market share.
http://gs.statcounter.com/#mobile_vs_desktop-ww-monthly-201308-201308-bar I
would be even more interested to see docs.python.org stats, which may be
more, because reading docs from tablet is more convenient, or less, because
there tables are not good development platforms for Python.

> I believe that it is pretty easy with mobile browser due to screen
> constraints. Can you test this on your mobile devices?

Sorry, but we don't adapt the docs *content* to any specific device.  You should never only read just a screenful in any case.  This is technical documentation, not a news article!

If you believe that you can improve the docs *design* (the CSS, mainly) to work better on mobile devices, be my guest!  There are certainly optimization opportunities, but that never relieves you of making sure you read the whole content that's relevant to you.

On Sun, Sep 22, 2013 at 2:11 PM, Georg Brandl <report@bugs.python.org>wrote:

>
> Georg Brandl added the comment:
>
> > I believe that it is pretty easy with mobile browser due to screen
> > constraints. Can you test this on your mobile devices?
>
> Sorry, but we don't adapt the docs *content* to any specific device.  You
> should never only read just a screenful in any case.  This is technical
> documentation, not a news article!
>

I am sorry, but you're misplacing arguments. It looks like this:

me[1]> open() function description is a wrong place for warning that is
related to a whole module
you[2]> common, it is visible, that's the point anyway
me[3]> it is not visible on mobile
you[4]> we do not support mobile

[3] makes your point [2] invalid. And your point [4] doesn't apply as an
answer to [1].

 Now my arguments are:
1. Warning is located in the wrong place (bug is trivial, not important)
2. Wrong place causes problems with mobiles (trivial, somewhat matters)

And you argument that users (or is it for me personally?) should never read
only screenful for a module description is rather strange for the most of
us.

   "Why are things always in the last place you look for them?
    Because you stop looking when you find them."

I highly recommend you to read this book -
http://www.sensible.com/chapter.html - it's awesome.
And just for amusement -
http://uxmyths.com/post/647473628/myth-people-read-on-the-web

> If you believe that you can improve the docs *design* (the CSS, mainly) to
> work better on mobile devices, be my guest!  There are certainly
> optimization opportunities, but that never relieves you of making sure you
> read the whole content that's relevant to you.
>

There is nothing wrong with CSS or mobile design. There is an issue with
the placement of this specific piece of information, which comes detached
from the place (module description) where it belongs. Although the effect
of this bug is partially with background workaround, the cause is still
there.

To make it more real scenario for you. In corporate environment somebody
who issues a recommendation, is not necessarily the person who implements
it. If you're implementing everything yourself, of course you won't miss
the details.

> me[1]> open() function description is a wrong place for warning that is
related to a whole module
> you[2]> common, it is visible, that's the point anyway
> me[3]> it is not visible on mobile
> you[4]> we do not support mobile

Your complaint was that it is "located under screen border".  My reply is that what the "screen border" is is highly device specific and that  we don't cater to specific devices, therefore rejecting your complaint.  I never said "we don't support mobile".  That's it for me and this issue.

On Sun, Sep 22, 2013 at 2:57 PM, Georg Brandl <report@bugs.python.org>wrote:

>
> Georg Brandl added the comment:
>
> > me[1]> open() function description is a wrong place for warning that is
> related to a whole module
> > you[2]> common, it is visible, that's the point anyway
> > me[3]> it is not visible on mobile
> > you[4]> we do not support mobile
>
> Your complaint was that it is "located under screen border".  My reply is
> that what the "screen border" is is highly device specific and that  we
> don't cater to specific devices, therefore rejecting your complaint.  I
> never said "we don't support mobile".  That's it for me and this issue.
>

Well, at least now you know how I read the replies. Glad we settled this
down. Now it would be nice if somebody with CLA for docs could just move
this block upper.