At 02:29 PM 7/2/2010 -0400, Tres Seaver wrote:

I haven't found any docs (outside the code) for the setuptools.dist.Feature,

That's because it's essentially deprecated - an experimental thing that turned out to be, well, a failed experiment. The problem is that there really needed to be better ways to store the build state with respect to features, not to mention distribution-level information about them. So, they only work correctly if you pass them to *every* setup.py command, while never changing them. To really work right, there'd need to be a "configure" command, and some sort of option storage. And, since most of the *other* use cases for the original features design were supplanted by "extras" and install_requires, it was pretty much left to optional C extensions, which might as well be handled by, well, optional C extensions. ;-) So, I haven't done anything with features in ages, and didn't document them because (AFAIK), they were only used by some ancient packages of my own, such as the original PEAK mega-distribution, PyProtocols, and RuleDispatch -- mostly to enable or disable various C extensions.

- - Feature instances represent optionally-included bits of the distribution.

- - Normally, features are disabled by default, and can be enabled by passing '--with-<featurename>' to setup.py.

- - Features declared as 'standard' are enabled by default, and can be disabled by passing '--without-<featurename>' to setup.py.

- - Features have an 'available' attribute, which can be set to False in setup.py to disable a feature based on runtime introspection (e.g., using sys.version_info or os.name).

- - It appears that it should be possible to pass an instance with a '__nonzero__' method as the 'available': the code seems only to use it in boolean tests.

- - Features may depend on (force inclusion of) other features.

- - Enabled features do their actual work by adding **kwargs to the args passed directly to setup.py

- - Distributions created via an invocation to setup.py are not labeled in any way to indicate any '--with-<featurename>' (or '--without') passed to setup.py during their creation.

- - There is no way to enable / disable a feature when installing a distribution via easy_install.

The particular use case which led me to investigate Features was easing packaging of projects with optional C extensions, such that they could be installable on Jython, IronPython, Windows, or GAE. It doesn't seem possible to figure out whether a compiler actually exists: jython's distutils lies and creates a compiler which raises exceptions, for instance.

Yeah, that's another reason why Features don't even do the optional compile thing that well. Not Jython specifically, but rather, I never decided on a good way to handle optional C extensions, that doesn't involve trapping compilation errors. (I hope distutils2 allows you to declare extensions optional; it's such a common use case.)