[Grok-dev] Re: Salt & z3c.autoinclude

[Martin Aspeli]

Ethan Jucovy wrote:
> Hey,
> 
> I've incorporated many of the recommendations in this thread into the 
> adding-salt branch of z3c.autoinclude and cleaned up the code a bit.  
> Three specific points follow, in increasing level of code detail.  :)

You rock ;-)

> First, in response to Martin's understandable confusion about 
> autoinclusion (z3c.autoinclude's original functionality: dependency 
> loading) vs plugin inclusion, I've extracted a common base into 
> z3c.autoinclude.utils and tried to distinguish more clearly between the 
> two functions in the README.  I also added a brief introductory section 
> to the README which lays out how to use the package from a user's 
> perspective (ZCML directives, entry points) without going into any of 
> the details of the code or tests.  I hope this makes it all a bit more 
> clear.

Cool!

> On Sat, Mar 22, 2008 at 6:56 PM, Martijn Faassen <faassen at startifact.com 
> <mailto:faassen at startifact.com>> wrote:
>  > We need to distinguish auto-inclusion from loading up plugins.
>  > Auto-inclusion means automatically also loading the ZCML of that
>  > dependency.
> 
> I think this terminology is contributing to the confusion.  From a new 
> user's perspective I think "auto-inclusion" would seem to describe both 
> functions of the package: whether it is loading ZCML from dependencies 
> or plugins, the package is performing the same task of automatically 
> including packages without any explicit per-package <include> 
> statement.  Perhaps we should disambiguate these and refer explicitly to 
> "including dependencies" and "including plugins" throughout?  (Rename 
> include.py to dependency.py, IncludeFinder to DependencyFinder, etc.)  
> Martijn, I'm sure you have a strong opinion here -- how would you feel 
> about renaming the ``<autoinclude>`` directive to something less 
> ambiguous like ``<includeDependencies>``, symmetric to 
> ``<includePlugins>``?  (I'd love to think of a shorter word than 
> "dependency" for the directive but I'm drawing a blank...)

+1 for this, though I'm not sure if we have live users of this thing 
that need to be migrated?

Perhaps <autoinclude /> could be a convenience directive that does 
*both* <autoincludeDependencies /> and <autoincludePlugins />?

I don't mind longish names if they are descriptive and accurate, personally.

> Second, I've changed the entry point syntax per Martijn's preference; it 
> now looks like (using Products.CMFPlone as the example platform to plug 
> in to) ::
> 
> """
> [z3c.autoinclude.plugin]
> target = Products.CMFPlone
> """
> 
> There is an implicit, enforced assumption that the right-hand side of 
> the entry point (that is, the platform) is a valid dotted module name.

Can we make it an explicit assumption (i.e. documented) if it isn't 
already? :)

> On Sat, Mar 22, 2008 at 7:32 PM, Martin Aspeli <optilude at gmx.net 
> <mailto:optilude at gmx.net>> wrote:
>  > So long as we don't design the syntax or framework so that it's
>  > impossible to cleanly support multiple targets in the future, I'm happy
>  > with that stance.
> 
> I'm pretty sure that this syntax will work quite well for multiple 
> targets (platforms) actually so you needn't worry.  The left-hand side 
> of the entry point ("target") is completely extraneous so multiple entry 
> points can be defined for a single plugin package already; I haven't 
> written any tests to prove this but I think that something like the 
> following would Just Work (assuming the <includePlugins> directives were 
> specified somewhere, and assuming the package magically worked on two 
> frameworks with the same configuration) ::
> 
> """
> [z3c.autoinclude.plugin]
> target = Products.CMFPlone
> smash = grok
> """
> 
> More importantly though, the fact that the left-hand side is ignored 
> entirely leaves plenty of room for a future syntax extension there which 
> specifies a ZCML starting point, which would make the above example 
> rather more useful.  But it seems we're all in agreement to leave this 
> alone for now and wait for a real-world use case to (potentially) come up.

Sounds good.

> Anyway, that's about it for the update.  If anyone's really interested 
> in the inner workings, I refactored out a common base class 
> ``DistributionManager`` which the ``IncludeFinder`` and ``PluginFinder`` 
> both extend.  There's some highly questionable makeshift adaptation of 
> distribution objects and strings going on there which I'm half-tempted 
> to formalize with zope.component and zope.interface but that may be 
> overkill, I'm not really sure.  As always, comments and criticism much 
> appreciated.

Thanks so much for doing this!

Martin


-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book