[Distutils] entry points PEP

[Vinay Sajip]

Daniel Holth <dholth <at> gmail.com> writes:

> On Thu, Jul 18, 2013 at 9:27 AM, Paul Moore <p.f.moore <at> gmail.com> 
wrote:
 
> It is an extension so it can be a separate PEP, since there's enough
> to talk about in the main PEP. The document tries to write down what
> setuptools does in a straightforward json way.

If the JSON we're talking about goes in the main metadata dictionary, 
perhaps
it should go into PEP 426, so that everything is in one place. As we're 
talking
about special handling of script generation by installers, it may make sense 
to
not consider them as extensions but as core metadata.

> > 2. distlib calls these "exports" and I think that's a better name. But 
if
> > names are all that we argue over, I'm happy 

The reason for picking "exports" is that you can export data, not just code,
and "entry point" has a connotation of being code. PJE suggested "exports" 
and
I think it fits the bill better than "entry_points".

> > 3. Someone (I think it was PJE) pointed out that having entry points in 
a
> > separate metadata file was good because it allowed a fast check of "does
> > this distribution expose entry points?" Note that this isn't a useful 
thing
> > to check for script wrappers, which again argues that those should be
> > handled separately.

That seems generally true, except that there might be applications out there
that want to walk over the scripts associated with different installed
distributions. That seems a legitimate, though uncommon, use case.

In any case, I think the script metadata should be structured as 

"scripts": {
  "console": [spec1, spec2]
  "gui": [spec1, spec2]
}

Because that allows a sensible place for e.g. script generation options, as 
in

"scripts": {
  "console": [spec1, spec2]
  "gui": [spec1, spec2]
  "options": { ... }
}


> I am more interested in seeing the installer update some kind of index
> like a sqlite database. I don't know if it would be faster since I
> haven't tried it.

That (a SQLite installation database) is probably some way off, and would
require more significant changes elsewhere. The big advantage of the current
setup with text files is that every thing is human readable - very handy 
when
things go wrong. I don't know whether this area is a performance bottleneck,
but we will be able to deal with it using a separate exports.json file in 
the
short term.

> For one thing you can have more than one mysql = in the same
> sqlalchemy.dialects. I think in this instance the string parsing is

Don't you say in the PEP about the key that "It must be locally unique 
within
this distribution’s group."?

> probably simpler than defining a more JSONy version.

I think Paul's point is that if it was JSON, you wouldn't need to parse
anything. The current format of entries is

name = module:attrs [flag1,flag2]

which could be { "name": name, "module": module, "attrs": attrs, "flags":
["flag1", "flag2"] } which is obviously more verbose.

Note that I don't see necessarily a connection between extras and flags, 
though
you've mentioned that they're extras. Does setuptools store, against an
installed distribution, the extras it was installed with? AFAIK it doesn't.
(Even if it did, it would need to keep that updated if one of the extras'
dependencies were later uninstalled.) And if not, how would having extras in
the specification help, since  you can't test the "must be installed" part? 
On
the other hand, you might want to use generalised flags that provide control
over how the exported entry is processed.

One reason for keeping the format as-is might be in case any migration 
issues
come up (i.e. people depending on this specific format in some way), but I'm
not sure whether there are any such issues or what they might be.

> FWIW the PEP 426 metadata is also full of structured strings.

True - the dependency specifier, if nothing else.

One other thing is that the PEP needs to state that the exports metadata 
must
be written to exports.json in the .dist-info folder by an installer - that
isn't mentioned anywhere. Also, whether it should contain the scripts part, 
or
just the other exports (but see my comment above as to why scripts might be
considered exports worth iterating over, like any other).

Regards,

Vinay Sajip