[Zope-dev] shipping with standard docutils

[Philipp von Weitershausen]

At the PIKTipi sprint this past weekend, Andi Zeidler, Andreas Jung and 
I worked on integrating ZODB 3.8 and Zope 3.4 into the Zope 2 trunk. 
Zope 3.4 has actually "exploded" into many eggs that are now 
independently managed and released. I therefore looked into a way to 
make Zope 2 dependent on these eggs instead of shipping with its own 
copies of the packages. There are clear benefits to that:

* as newer versions of specific zope.* or ZODB packages are released, 
you can individually install those or not. There'll be no need to wait 
for another Zope 2 release.

* many third-party packages that we had to ship with Zope 2 were 
actually dependencies of the included Zope 3 (pytz, ClientForm, etc.). 
The Zope 3 eggs now simply depend on them via the egg dependency 
mechanism, which means we no longer have to track those projects through 
vendor imports.

* I actually went a bit further and eggified Zope 2 (it seemed the 
logical conclusion). I didn't really explode Zope 2, it's one big egg 
(except for a few things that are completely independent, such as 
ExtensionClass, Acquisition, DateTime, zLOG). Though currently not very 
comfortable to use, the Zope2 egg seems fully functional and I see it as 
a (if not *the*) way to distribute Zope 2 in the future.


Coming to the actual problem: docutils is one third-party dependency of 
Zope that we track as a vendor import. Due to certain security problems 
that can arise when rendering reStructuredText, the docutils code was 
patched. Therefore, when shipping Zope with the standard docutils 
distribution (which can be conveniently pulled down as an egg), tests 
that assert the security of reStructuredText obviously fail.

Andi converted the patch that was done to docutils to a monkey patch. 
It's available on the 'witsch-zope2.11-with-standard-docutils' branch. 
Not only am I not a big fan of monkey patches, I also think the 
behaviour of failing with an exception instead of presenting a warning 
is not very friendly.

Tres explained the reason for patching docutils to raise a 
NotImplementedError in an email message on 8 July 2006:

> In Zope2 land, the module is still available, and can be used by other
> code (which may not know of that issue).  I'm *not* in favor of shipping
> an un-patched docutils until we work this out.  For instance, perhaps we
> should be patching docutils to make the *default* settings disable file
> inclusion and 'raw';  then the trusted code which wanted to render reST
> which legitimately needed those features could enable them explicitly.

In my 'philikon-zope2.11-with-standard-docutils' branch, I have done 
that "working out": making all reStructuredText rendering from Zope 
immune to 'include' and 'raw' directives. Instead of raising a 
NotImplementedError, however, I simply changed the default settings in 
docutils (via monkey patch that's much less intrusive than swapping out 
methods).


I propose to merge my branch to the trunk, therefore effectively 
changing the way we deal with the forbidden 'include' and 'raw' 
directives (presenting warning, not raising NotImplementedError), and 
allowing us to work with a standard docutils distribution.

If wanted, I'd also be willing to backport this to older Zopes, though 
that might change their behaviour regarding reStructuredText in an 
unwanted way within a bugfix release.


-- 
http://worldcookery.com -- Professional Zope documentation and training