[z3-five] Restructuring

[Martijn Faassen]

Philipp von Weitershausen wrote:
> as I've mentioned a couple of times, I've been planning to
> restructure some Five code. The reason is that we will want to add
> more Zope 3 features to Five (for example, for the mid-term I want to
> add i18n and l10n capabilities) and the code structure (especially
> the test structure) is getting out of hand.

I agree the test structure is getting out of hand, but I don't agree
that the package structure in general is getting out of hand.

> In Zope 3, there's a package hierarchy convention that is not too
> flat to provide no structure whatsoever and not too deep to find
> yourself lost in. Most importantly, tests are included along with
> every package and can therefore be much more easily be associated
> with the module or class they actually test. Right now, with a big
> blobbish FiveTest product, this is almost never the case in Five.

Since we're testing integration with Zope 2, I suspect our tests will
always be rather functionally oriented and somewhat big/blobbish. I
imagine they can be factored out a bit more, but I'm not sure how far we
can sensibly go.

> Also, Zope 3 has embraced doctests enourmously in recent times and I
> think they add a lot to the implicit code documentation because they
> almost force one to tell a story along the test. Also, doctests as
> inline docstring are probably the closest you can get in
> test-to-implementation association...
> 
> So, the objective can be summed up:
> 
> * restructure Five into a more Zope3-like package hierarchy (this
> will most likely result in 'browser' and 'skin' subpackages, possibly
> also 'traversing'; these names correspond to Zope 3 naming
> conventions).

I would hold off on this for now. Over time I've become very wary of
introducing hierarchy where it's not obvious. It's not obvious to me
what would be in browser, skin and traversing... Flat is better than
nested. I know you can say namespaces are good, but since I don't see
the namespaces you'll have to convince me with a bit more detail...

Heh, it's not even obvious what the names are for in Zope 3 all the
time, witness the whole zope.app.publisher, zope.app.publication and
then one of them, which I always forget, has a 'browser' subdirectory
which then defines lots of ZCML directives...

> * restructure tests to be more atomic and more doctest-like, thus
> easier to read, understand and modify.

Restructuring the tests is fine with me.

> I'll obviously be creating a branch for this. I don't believe in 
> branches that live too long, though, so I'd like to come to the point
>  where a certain state of satisfactory restructuring is reached and 
> everbody is ok with it pretty soon.

We're currently working on Five 0.4, which is really a fairly minor
tweak-version that we'd like to have integrated into Zope 2.8. After
that we could merge the work.

Can you please focus on the test work first and separately, and not do 
the package restructuring yet? I'm really dubious whether a package 
restructuring is needed at this stage, and at least the test work 
wouldn't be thrown away in that case.

Regards,

Martijn