[Python-checkins] peps: Try to clean up PEP 426 naming rules
nick.coghlan
python-checkins at python.org
Sun Aug 4 08:29:33 CEST 2013
http://hg.python.org/peps/rev/e4e32122be07
changeset: 5030:e4e32122be07
user: Nick Coghlan <ncoghlan at gmail.com>
date: Sun Aug 04 16:29:14 2013 +1000
summary:
Try to clean up PEP 426 naming rules
files:
pep-0426.txt | 123 +++++++++++++++++------
pep-0426/pydist-schema.json | 15 +-
2 files changed, 100 insertions(+), 38 deletions(-)
diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -247,10 +247,17 @@
"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 @@
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 @@
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 @@
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 @@
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 @@
.. 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 @@
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 @@
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.
-
-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
-
-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.
-
-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.
+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.
+
+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.
+
+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.
+
+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 @@
===================
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
diff --git a/pep-0426/pydist-schema.json b/pep-0426/pydist-schema.json
--- a/pep-0426/pydist-schema.json
+++ b/pep-0426/pydist-schema.json
@@ -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]*)*$"
}
}
}
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list