On 3 Aug 2013 06:01, "PJ Eby" <pje@telecommunity.com> wrote:

On Fri, Aug 2, 2013 at 11:27 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:

...

I pushed a version of PEP 426 with an initial sketch of an entry points replacement design: http://hg.python.org/peps/rev/ea3d93e40e02

To give it a sensible home in the PEP, I ended up defining "modules" and "namespaces" fields in addition to "commands" and "exports". The overall section is called "Installed interfaces".

I initially tried it with the unpacked multi-field mapping for export specifiers, but ended up reverting to something closer to the setuptools notation for readability purposes. For the moment, "requires_extra" is included since it isn't that hard to explain.

Thanks again for all the hard work in putting this together!

Btw, under setuptools, entry point *group* names are restricted to valid Python module names, so this is a subset of valid distribution names. Conversely, entry *point* names are intentionally arbitrary and may contain anything that isn't an '=', as long as they don't start with a '#'.

The reason for these choices is that entry point groups are used to ensure global uniqueness, but need a standard way for subdividing namespaces. (Notice that setuptools has groups like distutils.setup_arguments and distutils.setup_commands.)

Conversely, individual entry point names have a free-form syntax so that they can carry additional structured information, like a converter specifying what it converts from and to, with a quality metric. The idea is to allow tools to build plugin registries from this kind of information without needing to import the modules. Basically, if you can fit it on one line, before the '=', in a reasonably human-readable way, and it saves you from having to import the module in order to figure out whether you wanted to import it in the first place, you can put it in the name.

You might wish to make names a bit more restrictive than this, I suppose, but I'm not sure that all of the limitations of distribution names are actually appropriate here. In particular, restricting to alphanumerics, dots, and dashes is *way* too restrictive. Entry point names are sometimes used for human-readable command descriptions, e.g. this is a perfectly valid entry point definition in setuptools:

wikiup: Upload documents to one or more wiki pages = some.module:entrypoint [extra1, extra2]

Anyway, entry point group names are definitely *not* recommended to follow distribution names, as that makes them rather useless. Things that consume entry points will generally have more than one group, eventually, so at least one of those groups will then have to *not* be named after a distribution, unless you arbitrarily break up the project into multiple distributions so the group names match, which is kind of silly. ;-)

This makes sense - I was trying to cut down on the number of different naming schemes we had, but may not have divided things up well. How about we go with: Valid dotted names for: - modules - namespaces - module & name portions of export specifiers - export group names - extension names Valid distribution names for: - script wrappers Arbitrary strings for export group entries.

Finally, it might be good to point out once again that extras are not so much "a set of dependencies that will be checked for at runtime" as a set of dependencies that are *needed* at runtime. This need may or may not be checked, and may or may not be satisfied dynamically at runtime; it depends on the API in use, and how/whether it is invoked.

An unconditional import of an optional dependency counts as a runtime check in my view :) Agreed that could be clarified in the PEP, though. Cheers, Nick.

Nick Coghlan <ncoghlan <at> gmail.com> writes:

Just pushed these changes. I'm happy to leave the PEP alone for a while now,

Thanks for doing these updates. Can I suggest the following corrections? 1. In the section "Exports", there is a dangling sentence which needs to be completed: "The interpretation of the individual export keys is defined by the distribution that i" 2. In the same section, it says "Export group names SHOULD correspond to module names ..." and also "It is suggested that export groups be named after distributions to help avoid name conflicts." It should be one of these (I presume the former). Regards, Vinay Sajip

PJ Eby <pje <at> telecommunity.com> writes:

And not quite the former, either; the same arguments about not splitting a distribution apply to modules as well. i.e., a single module might consume exports from more than one group, so saying they should correspond is too strong; I would say instead that export group names are dotted names that should be *prefixed* with the name of a package or module provided by the relevant distribution.

You're right - I was being a little sloppy, but that was my understanding (i.e. the emphasis on prefixes).

(Of course, it's also perfectly fine for one to use a domain name or other similarly-unique prefix; the real point is just that top-level names should be reserved for groups defined by the stdlib and/or PEPs, and everybody else should be using unique prefixes that give some indication where one would look for a spec.)

Right, though it's probably enough to just use a module name which is "unique" to the distribution. Of course, nothing prevents two completely unrelated distributions having a top-level module "foo", but in that case any ambiguity in export names is probably the least of the worries of someone who installs two such conflicting distributions. Regards, Vinay Sajip

On 4 August 2013 05:14, Vinay Sajip <vinay_sajip@yahoo.co.uk> wrote:

Nick Coghlan <ncoghlan <at> gmail.com> writes:

...

Just pushed these changes.

One more problem: the updated pydist-schema.json is not a valid schema file (it's not valid JSON either- I think there are trailing commas and a mismatched brace somewhere.

It's at least valid JSON now. I make no promises about the current draft being a valid jsonschema :) It turned out I had missed a few other naming related updates, so I did another pass over all the interface and extension related sections. Some points of note: 1. I adopted the PEP 3155 "qualified name" terminology for dotted names. This applies to both module names (where their name and their qualified name are the same thing) *and* to the names of other objects within modules. 2. I adopted the term "fully qualified name" for the "module:name" notation used by export specifiers (amongst other things). For modules, the qualified name and the fully qualified name are the same. 3. I explicitly recommend the one distribution <-> one module/package equivalence. There are valid reasons for deviating from that recommendation, but it's still a good default. 4. I expand further on the intended usage of export groups (focusing on plugin systems) 5. Both export group names and metadata extension names are now required to use the qualified name format, with a recommendation that they use a prefix that matches a module published by the defining distribution 6. Qualified names are currently restricted to Python 2 compatible identifiers. Even though it isn't as scary as the idea of Unicode metadata names, I believe Unicode identifier support in export metadata is still a can of worms that we don't want to open yet. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On 10 August 2013 13:12, Vinay Sajip <vinay_sajip@yahoo.co.uk> wrote:

Nick Coghlan <ncoghlan <at> gmail.com> writes:

...

6. Qualified names are currently restricted to Python 2 compatible identifiers.

This constraint causes some problems in practice, some of which might be more problematic than others:

1. Some existing distributions have group names which violate the constraint. For example, nose uses group names such as "nose.plugins.0.10". Around a hundred other distributions advertise plugins under group names like this.

2. Some distributions have package names which aren't actual packages but which nevertheless contain source files. For example, Django lists "django.utils.2to3_fixers" in its list of packages, though this is just a directory containing fixers and not an actual package. This, of course, also violates the constraint.

It seems like it might be worth relaxing the restriction so that a qualified name starts with a Python 2 compatible segment, but can have subsequent components matching the [A-Za-z0-9]+ pattern.

Done. Cheers, Nick.