[Python-Dev] Warnings

[Nick Coghlan]

On Thu, Dec 1, 2011 at 5:15 PM, Glyph <glyph at twistedmatrix.com> wrote:
> I think both of these documents point to a need for a recommended idiom for
> discussing security, or at least common antipatterns, within the Python
> documentation.  I like the IETF's "security considerations" section, because
> it separates things off into a section that can be referred to later, once
> the developer has had an opportunity to grasp the basics.  Any section with
> security implications can easily say "please refer to the 'security
> considerations' section for important information on how to avoid common
> mistakes" without turning into a big security digression on its own.

I like that approach - one of the problems with online docs is the
fact people don't read them in order, hence the proliferation of
warnings for the subprocess module. A clear "Security Considerations"
section with appropriate cross links would allow us to be clear and
explicit about common problems without littering the docs with red
warning boxes for security issues that are inherent in a particular
task rather than being a Python-specific problem.

Cheers,
Nick.

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