New submission from Nick Coghlan <ncogh...@gmail.com>:

This issue proposes that we adopt and apply some standard practices when 
documenting modules that have potential security implications and other 
cross-cutting errors that may affect multiple interfaces within the module.

Accordingly, the main target is the "Documenting Python" meta-docs, proposing 
the addition of a new subsection to the Style Guide, with an update to the 
subprocess module documentation serving as the exemplar of a new recommended 
style:

======================
2.6 Security Considerations (and Other Concerns)
------------------------------------------------

Some modules provided with Python are inherently exposed to security issues 
(e.g. shell injection vulnerabilities) due to the purpose of the module (e.g. 
subprocess invocation). Littering the documentation of these modules with red 
warning boxes for problems that are due to the task at hand, rather than 
specifically to Python's support for that task, doesn't make for a good reading 
experience.

Instead, these security concerns should be gathered into a dedicated "Security 
Considerations" section within the module's documentation, and cross-referenced 
from the documentation of affected interfaces with in-line text similar to 
"Please refer to the :ref:`security-considerations` section for important 
information on how to avoid common mistakes".

Similarly, if there is a common error that affects many interfaces in a module 
(e.g. OS level pipe buffers filling up and stalling child processes), these can 
be documented in a "Common Errors" section and cross-referenced rather than 
repeated for every affected interface.
======================


(based on the thread at 
http://mail.python.org/pipermail/python-dev/2011-December/114717.html)

----------
assignee: docs@python
components: Documentation
messages: 148710
nosy: docs@python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Consistent documentation practices for security concerns and 
considerations

_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue13515>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to