Try to clean up PEP 426 naming rules
This commit is contained in:
Nick Coghlan
parent
605e86dca8
commit
1019a67ffa
117
pep-0426.txt
117
pep-0426.txt
|
|
@ -247,10 +247,17 @@ avoid confusion with the Python-specific meaning of the term "distribution".
|
|||
"Dist" is the preferred abbreviation for "distributions" in the sense defined
|
||||
in this PEP.
|
||||
|
||||
"Qualified name" comes from PEP 3155, and refers to the dotted name of an
|
||||
object relative to its containing module. This is useful for referring
|
||||
to method definitions on classes, as well as any other attributes of
|
||||
top level module objects.
|
||||
"Qualified name" is a dotted Python identifier. For imported modules and
|
||||
packages, the qualified name is available as the ``__name__`` attribute,
|
||||
while for functions and classes it is available as the ``__qualname__``
|
||||
attribute.
|
||||
|
||||
A "fully qualified name" uniquely locates an object in the Python module
|
||||
namespace. For imported modules and packages, it is the same as the
|
||||
qualified name. For other Python objects, the fully qualified name consists
|
||||
of the qualified name of the containing module or package, a colon (``:``)
|
||||
and the qualified name of the object relative to the containing module or
|
||||
package.
|
||||
|
||||
|
||||
Integration and deployment of distributions
|
||||
|
|
@ -1440,19 +1447,28 @@ interfaces when installed.
|
|||
Export specifiers
|
||||
-----------------
|
||||
|
||||
An export specifier is a string using one of the following formats::
|
||||
An export specifier is a string consisting of a fully qualified name, as
|
||||
well as an optional extra name enclosed in square brackets. This gives the
|
||||
following four possible forms for an export specifier::
|
||||
|
||||
module
|
||||
module:name
|
||||
module[requires_extra]
|
||||
module:name[requires_extra]
|
||||
|
||||
.. note::
|
||||
|
||||
The jsonschema file currently restricts qualified names using the
|
||||
Python 2 ASCII identifier rules. This may need to be reconsidered
|
||||
given the more relaxed identifier rules in Python 3.
|
||||
|
||||
The meaning of the subfields is as follows:
|
||||
|
||||
* ``module``: the module providing the export
|
||||
* ``name``: if applicable, the qualified name of the export within the module
|
||||
* ``requires_extra``: indicates the export will only work correctly if the
|
||||
additional dependencies named in the given extra are available.
|
||||
additional dependencies named in the given extra are available in the
|
||||
installed environment
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -1465,12 +1481,33 @@ The meaning of the subfields is as follows:
|
|||
Modules
|
||||
-------
|
||||
|
||||
A list of module names that the distribution provides for import.
|
||||
A list of qualified names of modules and packages that the distribution
|
||||
provides for import.
|
||||
|
||||
.. note::
|
||||
|
||||
The jsonschema file currently restricts qualified names using the
|
||||
Python 2 ASCII identifier rules. This may need to be reconsidered
|
||||
given the more relaxed identifier rules in Python 3.
|
||||
|
||||
For names that contain dots, the portion of the name before the final dot
|
||||
MUST appear either in the installed module list or in the namespace package
|
||||
list.
|
||||
|
||||
To help avoid name conflicts, it is RECOMMENDED that distributions provide
|
||||
a single top level module or package that matches the distribution name
|
||||
(or a lower case equivalent). This requires that the distribution name also
|
||||
meet the requirements of a Python identifier, which are stricter than
|
||||
those for distribution names). This practice will also make it easier to
|
||||
find authoritative sources for modules.
|
||||
|
||||
Index servers SHOULD allow multiple distributions to publish the same
|
||||
modules, but MAY notify distribution authors of potential conflicts.
|
||||
|
||||
Installation tools SHOULD report an error when asked to install a
|
||||
distribution that provides a module that is also provided by a different,
|
||||
previously installed, distribution.
|
||||
|
||||
Note that attempting to import some declared modules may result in an
|
||||
exception if the appropriate extras are not installed.
|
||||
|
||||
|
|
@ -1490,7 +1527,14 @@ Example::
|
|||
Namespaces
|
||||
----------
|
||||
|
||||
A list of namespace packages that the distribution contributes modules to.
|
||||
A list of qualified names of namespace packages that the distribution
|
||||
contributes modules to.
|
||||
|
||||
.. note::
|
||||
|
||||
The jsonschema file currently restricts qualified names using the
|
||||
Python 2 ASCII identifier rules. This may need to be reconsidered
|
||||
given the more relaxed identifier rules in Python 3.
|
||||
|
||||
On versions of Python prior to Python 3.3 (which provides native namespace
|
||||
package support), installation tools SHOULD emit a suitable ``__init__.py``
|
||||
|
|
@ -1498,8 +1542,8 @@ file to properly initialise the namespace rather than using a distribution
|
|||
provided file.
|
||||
|
||||
Installation tools SHOULD emit a warning and MAY emit an error if a
|
||||
distribution declares a namespace package that conflicts the name of an
|
||||
already installed module or vice-versa.
|
||||
distribution declares a namespace package that conflicts with the name of
|
||||
an already installed module or vice-versa.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -1529,7 +1573,7 @@ installation process.
|
|||
|
||||
.. note::
|
||||
|
||||
Still needs more detail on what "appropriate wrapper" means. For now,
|
||||
Still needs more detail on what "appropriate wrappers" means. For now,
|
||||
refer to what setuptools and zc.buildout generate as wrapper scripts.
|
||||
|
||||
``prebuilt`` is a list of script paths, relative to the scripts directory in
|
||||
|
|
@ -1537,6 +1581,12 @@ a wheel file or following installation. They are provided for informational
|
|||
purpose only - installing them is handled through the normal processes for
|
||||
files created when building a distribution.
|
||||
|
||||
Index servers SHOULD allow multiple distributions to publish the same
|
||||
commands, but MAY notify distribution authors of potential conflicts.
|
||||
|
||||
Installation tools SHOULD report an error when asked to install a
|
||||
distribution that provides a command that is also provided by a different,
|
||||
previously installed, distribution.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -1551,22 +1601,28 @@ Example::
|
|||
Exports
|
||||
-------
|
||||
|
||||
The ``exports`` field is a mapping containing dotted names as keys. Each
|
||||
key defines an export group. Export group names SHOULD correspond to
|
||||
module names in the distribution responsible that defines the meaning
|
||||
of the export group.
|
||||
The ``exports`` field is a mapping containing qualified names as keys. Each
|
||||
key identifies an export group containing one or more exports published by
|
||||
the distribution.
|
||||
|
||||
Each export group is then a mapping of arbitrary non-empty string keys
|
||||
to export specifiers. The interpretation of the individual export keys is
|
||||
defined by the distribution that i
|
||||
Export group names are defined by distributions that will then make use of
|
||||
the published export information in some way. The primary use case is for
|
||||
distributions that support a plugin model: defining an export group allows
|
||||
other distributions to indicate which plugins they provide, how they
|
||||
can be imported and accessed, and which additional dependencies (if any)
|
||||
are needed for the plugin to work correctly.
|
||||
|
||||
Both export group names and export names must follow the rules for
|
||||
distribution identifiers. It is suggested that export groups be named
|
||||
after distributions to help avoid name conflicts.
|
||||
To reduce the chance of name conflicts, export group names SHOULD use a
|
||||
prefix that corresponds to a module name in the distribution that defines
|
||||
the meaning of the export group. This practice will also make it easier to
|
||||
find authoritative documentation for export groups.
|
||||
|
||||
The meaning of exports within an export group is up to the distribution
|
||||
that defines the export group. One common use case is to allow other
|
||||
distributions to advertise plugins for use by the defining distribution.
|
||||
Each individual export group is then a mapping of arbitrary non-empty string
|
||||
keys to export specifiers. The meaning of export names within an export
|
||||
group is up to the distribution that defines the export group. Creating an
|
||||
appropriate definition for the export name format can allow the importing
|
||||
distribution to determine whether or not an export is relevant without
|
||||
needing to import every exporting module.
|
||||
|
||||
|
||||
Install hooks
|
||||
|
|
@ -1682,17 +1738,20 @@ Metadata Extensions
|
|||
===================
|
||||
|
||||
Extensions to the metadata may be present in a mapping under the
|
||||
'extensions' key. The keys must meet the same restrictions as
|
||||
distribution names, while the values may be any type natively supported
|
||||
in JSON::
|
||||
'extensions' key. The keys must be valid qualified names, while
|
||||
the values may be any type natively supported in JSON::
|
||||
|
||||
"extensions" : {
|
||||
"chili" : { "type" : "Poblano", "heat" : "Mild" },
|
||||
"languages" : [ "French", "Italian", "Hebrew" ]
|
||||
}
|
||||
|
||||
To avoid name conflicts, it is RECOMMENDED that distribution names be used
|
||||
to identify metadata extensions. This practice will also make it easier to
|
||||
Extension names are defined by distributions that will then make use of
|
||||
the additional published metadata in some way.
|
||||
|
||||
To reduce the chance of name conflicts, extension names SHOULD use a
|
||||
prefix that corresponds to a module name in the distribution that defines
|
||||
the meaning of the extension. This practice will also make it easier to
|
||||
find authoritative documentation for metadata extensions.
|
||||
|
||||
Metadata extensions allow development tools to record information in the
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@
|
|||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/dotted_name"
|
||||
"$ref": "#/definitions/qualified_name"
|
||||
}
|
||||
},
|
||||
"namespaces": {
|
||||
|
|
@ -149,7 +149,7 @@
|
|||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/dotted_name"
|
||||
"$ref": "#/definitions/qualified_name"
|
||||
}
|
||||
},
|
||||
"commands": {
|
||||
|
|
@ -290,9 +290,10 @@
|
|||
"^[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?$": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/export_specifier"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
},
|
||||
"distribution_name": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?$"
|
||||
|
|
@ -310,17 +311,19 @@
|
|||
"type": "string"
|
||||
},
|
||||
"extra_name" : {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"pattern": "^[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?$"
|
||||
},
|
||||
"relative_path" : {
|
||||
"type": "string"
|
||||
},
|
||||
"export_specifier": {
|
||||
"type": "string",
|
||||
"pattern": "^([A-Za-z_][A-Za-z_0-9]*([.][A-Za-z_][A-Za-z_0-9]*)*)(:[A-Za-z_][A-Za-z_0-9]*([.][A-Za-z_][A-Za-z_0-9]*)*)?(\\[[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?\\])?$"
|
||||
},
|
||||
"dotted_name" : {
|
||||
"qualified_name" : {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z]([0-9A-Za-z_])*([.][A-Za-z]([0-9A-Za-z_])*)*$"
|
||||
"pattern": "^[A-Za-z_][A-Za-z_0-9]*([.][A-Za-z_][A-Za-z_0-9]*)*$"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue