Pad out shame.rst.

This commit is contained in:
David Wilson 2017-09-17 18:22:15 +05:30
parent bc49bccac6
commit 6ff2a49f10
1 changed files with 38 additions and 11 deletions

View File

@ -2,14 +2,38 @@
Importer Wall Of Shame Importer Wall Of Shame
---------------------- ----------------------
The following modules and packages run magic during ``__init.py__`` that makes The following modules and packages violate protocol or best practice in some way:
life hard for Mitogen. Executing code during module import is always bad, and
Mitogen is a concrete benchmark for why it's bad. * They run magic during ``__init.py__`` that makes life hard for Mitogen.
Executing code during module import is always bad, and Mitogen is a concrete
benchmark for why it's bad.
* They install crap in :py:data:`py.modules` that completely ignore or
partially implement the protocols laid out in PEP-302.
* They "vendor" a third party package, either incompletely, using hacks visible
through the runtime's standard interfaces, or with ancient versions of code
that in turn mess with :py:data:`sys.modules` in some horrible way.
Bugs will probably be filed for these in time, but it does not address the huge Bugs will probably be filed for these in time, but it does not address the huge
installed base of existing old software versions, so hacks are needed anyway. installed base of existing old software versions, so hacks are needed anyway.
``pbr``
=======
It claims to use ``pkg_resources`` to read version information
(``_get_version_from_pkg_metadata()``), which would result in PEP-302 being
reused and everything just working wonderfully, but instead it actually does
direct filesystem access. So we smodge the environment with a ``PBR_VERSION``
environment variable to override any version that was defined. This will
probably break code I haven't seen yet.
**What could it do instead?**
* ``pkg_resources.get_resource_stream()``
``pkg_resources`` ``pkg_resources``
================= =================
@ -32,16 +56,19 @@ issues like these.
this method isn't general enough, it only really helps tools like Mitogen. this method isn't general enough, it only really helps tools like Mitogen.
``pbr`` ``six``
======= =======
It claims to use ``pkg_resources`` to read version information The ``six`` module makes some effort to conform to PEP-302, but it is missing
(``_get_version_from_pkg_metadata()``), which would result in PEP-302 being several critical pieces, e.g. the ``__loader__`` attribute. This not only
reused and everything just working wonderfully, but instead it actually does breaks the Python standard library tooling (such as the :py:mod:`inspect`
direct filesystem access. So we smodge the environment with a ``PBR_VERSION`` module), but also Mitogen. Newer versions of ``six`` improve things somewhat,
environment variable to override any version that was defined. This will but there are still outstanding issues preventing Mitogen from working with
probably break code I haven't seen yet. ``six``.
This package is sufficiently popular that it must eventually be supported.
**What could it do instead?** **What could it do instead?**
* ``pkg_resources.get_resource_stream()`` * Any custom hacks installed into :py:data:`sys.modules` should support the
protocols laid out in PEP-302.