[Python-Dev] Warnings

[Nick Coghlan]

On Thu, Dec 1, 2011 at 4:10 PM, Raymond Hettinger
<raymond.hettinger at gmail.com> wrote:
> When updating the documentation, please don't go overboard with warnings.
> The docs need to be worded affirmatively -- say what a tool does and show
> how to use it correctly.
> See http://docs.python.org/documenting/style.html#affirmative-tone
>
> The docs for the subprocess module currently have SEVEN warning boxes on one
> page:
> http://docs.python.org/library/subprocess.html#module-subprocess
> The implicit message is that our tools are hazardous and should be avoided.

I have no problem with eliminating a lot of those specific warnings -
I kept them there in the last rewrite (and added a couple of new ones)
because avoiding shell injection vulnerabilities is such a driving
theme behind the subprocess module design. Since I was already
changing a lot of other things, messing with that aspect really wasn't
high on my priority list.

Now that we have the "frequently used arguments" section, though, the
rest of the warnings could fairly readily be downgraded to notes or
inline references to that section.

> Please show some restraint and aim for clean looking, high-quality technical
> writing without the FUD.

I do object to you calling genuine attempts to educate programmers
about security issues FUD, though. It's not FUD - novice programmers
inflict shell injection, script injection and SQL injection
vulnerabilities on the world every day. The multiple warnings are
there in the subprocess docs because people often only look at the
documentation for the specific function they're interested in, not at
the broader context of the page it is part of.

"Overkill" is a legitimate complaint, but calling attempts to
highlight genuinely insecure practices FUD is the kind of attitude
that has given the world so many years of persistent vulnerability to
buffer overflow attacks :P

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia