[Python-Dev] Warnings (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Thu Dec 1 08:55:19 CET 2011

On Thu, Dec 1, 2011 at 5:36 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:

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.

I created http://bugs.python.org/issue13515 to propose a specific documentation style guide adopt along these lines (expanded a bit to cover other cross-cutting concerns like the pipe buffer blocking I/O problem in subprocess).

Cheers, Nick.

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

More information about the Python-Dev mailing list