[Python-Dev] Warnings
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