From 98d06e25caf98e9097bb338db3885ee56a8d311e Mon Sep 17 00:00:00 2001 From: David Wilson Date: Fri, 23 Nov 2018 04:01:40 +0000 Subject: [PATCH] docs: delete shame.rst to make room for new chapters. --- docs/shame.rst | 90 -------------------------------------------------- docs/toc.rst | 1 - 2 files changed, 91 deletions(-) delete mode 100644 docs/shame.rst diff --git a/docs/shame.rst b/docs/shame.rst deleted file mode 100644 index 041feb2a..00000000 --- a/docs/shame.rst +++ /dev/null @@ -1,90 +0,0 @@ - -Importer Wall Of Shame ----------------------- - -The following modules and packages violate protocol or best practice in some way: - -* 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:`sys.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 -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. - -**What could it do instead?** - -* ``pkg_resources.resource_stream()`` - -**What Mitogen is forced to do** - -When it sees ``pbr`` being loaded, it smodges the process environment with a -``PBR_VERSION`` variable to override any attempt to auto-detect the version. -This will probably break code I haven't seen yet. - - -``pkg_resources`` -================= - -Anything that imports ``pkg_resources`` will eventually cause ``pkg_resources`` -to try and import and scan ``__main__`` for its ``__requires__`` attribute -(``pkg_resources/__init__.py::_build_master()``). This breaks any app that is -not expecting its ``__main__`` to suddenly be sucked over a network and -injected into a remote process, like py.test. - -A future version of Mitogen might have a more general hack that doesn't import -the master's ``__main__`` as ``__main__`` in the slave, avoiding all kinds of -issues like these. - -**What could it do instead?** - -* Explicit is better than implicit: wait until the magical behaviour is - explicitly requested (i.e. an API call). - -* Use ``get("__main__")`` on :py:data:`sys.modules` rather than ``import``, but - this method isn't general enough, it only really helps tools like Mitogen. - -**What Mitogen is forced to do** - -Examine the stack during every attempt to import ``__main__`` and check if the -requestee module is named ``pkg_resources``, if so then refuse the import. - - -``six`` -======= - -The ``six`` module makes some effort to conform to PEP-302, but it is missing -several critical pieces, e.g. the ``__loader__`` attribute. This not only -breaks the Python standard library tooling (such as the :py:mod:`inspect` -module), but also Mitogen. Newer versions of ``six`` improve things somewhat, -but there are still outstanding issues preventing Mitogen from working with -``six``. - -This package is sufficiently popular that it must eventually be supported. See -`here for an example issue`_. - -.. _here for an example issue: https://github.com/dw/mitogen/issues/31 - -**What could it do instead?** - -* Any custom hacks installed into :py:data:`sys.modules` should support the - protocols laid out in PEP-302. - -**What Mitogen is forced to do** - -Vendored versions of ``six`` currently don't work at all. diff --git a/docs/toc.rst b/docs/toc.rst index 7b3274a9..abd52a1f 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -14,7 +14,6 @@ Table Of Contents api examples internals - shame .. toctree:: :hidden: