From 07e58c33896c382ebccd99ed8dc28e457ab96c45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 3 Jun 2011 20:43:42 +0200 Subject: =?UTF-8?q?Remove=20link=20that=E2=80=99s=20already=20present=20at?= =?UTF-8?q?=20the=20top=20of=20the=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doc/library/collections.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 79db55e..1a41a50 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1136,9 +1136,6 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin: .. seealso:: - * Latest version of the :source:`Python source code for the collections - abstract base classes ` - * `OrderedSet recipe `_ for an example built on :class:`MutableSet`. -- cgit v0.12 From 36226804fec95ac02f151087aace78945cda7168 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 3 Jun 2011 20:49:39 +0200 Subject: Point to new collections.abc module for collections ABCs --- Doc/library/abc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 3e38cb4..54f7a5f 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -20,7 +20,7 @@ regarding a type hierarchy for numbers based on ABCs.) The :mod:`collections` module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the -:mod:`collections` module has some ABCs that can be used to test whether +:mod:`collections.abc` submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, is it hashable or a mapping. -- cgit v0.12 From ba661a9c398c1d75a036e0b56bba59ab7191eaa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 02:31:14 +0200 Subject: Add missing section of doc file lost among repositories and conversions --- Doc/packaging/setupcfg.rst | 163 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 3 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index be6c8c9..68786b2 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -4,11 +4,114 @@ Specification of the :file:`setup.cfg` file ******************************************* -.. :version: 1.0 +:version: 0.9 This document describes the :file:`setup.cfg`, an ini-style configuration file -(compatible with :class:`configparser.RawConfigParser`) configuration file used -by Packaging to replace the :file:`setup.py` file. +(compatible with :class:`configparser.RawConfigParser`) used by Packaging to +replace the :file:`setup.py` file. + + +Syntax +====== + +The configuration file is an ini-based file. Variables name can be +assigned values, and grouped into sections. A line that starts with "#" is +commented out. Empty lines are also removed. + +Example:: + + [section1] + # comment + name = value + name2 = "other value" + + [section2] + foo = bar + + +Values conversion +----------------- + +Here are a set of rules for converting values: + +- If value is quoted with " chars, it's a string. This notation is useful to + include "=" characters in the value. In case the value contains a " + character, it must be escaped with a "\" character. +- If the value is "true" or "false" --no matter what the case is--, it's + converted to a boolean, or 0 and 1 when the language does not have a + boolean type. +- A value can contains multiple lines. When read, lines are converted into a + sequence of values. Each new line for a multiple lines value must start with + a least one space or tab character. These indentation characters will be + stripped. +- all other values are considered as strings + +Examples:: + + [section] + foo = one + two + three + + bar = false + baz = 1.3 + boo = "ok" + beee = "wqdqw pojpj w\"ddq" + + +Extending files +--------------- + +An INI file can extend another file. For this, a "DEFAULT" section must contain +an "extends" variable that can point to one or several INI files which will be +merged to the current file by adding new sections and values. + +If the file pointed in "extends" contains section/variable names that already +exist in the original file, they will not override existing ones. + +file_one.ini:: + + [section1] + name2 = "other value" + + [section2] + foo = baz + bas = bar + +file_two.ini:: + + [DEFAULT] + extends = file_one.ini + + [section2] + foo = bar + +Result:: + + [section1] + name2 = "other value" + + [section2] + foo = bar + bas = bar + +To point several files, the multi-line notation can be used:: + + [DEFAULT] + extends = file_one.ini + file_two.ini + +When several files are provided, they are processed sequentially. So if the +first one has a value that is also present in the second, the second one will +be ignored. This means that the configuration goes from the most specialized to +the most common. + +**Tools will need to provide a way to produce a canonical version of the +file**. This will be useful to publish a single file. + + +Description of sections and fields +================================== Each section contains a description of its options. @@ -646,3 +749,57 @@ section named after the command. Example:: Option values given in the configuration file can be overriden on the command line. See :ref:`packaging-setup-config` for more information. + + +Extensibility +============= + +Every section can define new variables that are not part of the specification. +They are called **extensions**. + +An extension field starts with *X-*. + +Example:: + + [metadata] + ... + X-Debian-Name = python-distribute + + +Changes in the specification +============================ + +The version scheme for this specification is **MAJOR.MINOR**. +Changes in the specification will increment the version. + +- minor version changes (1.x): backwards compatible + + - new fields and sections (both optional and mandatory) can be added + - optional fields can be removed + +- major channges (2.X): backwards-incompatible + + - mandatory fields/sections are removed + - fields change their meaning + +As a consequence, a tool written to consume 1.X (say, X=5) has these +properties: + +- reading 1.Y, YX is also possible. The tool will just ignore the new + fields (even if they are mandatory in that version) + If optional fields were removed, the tool will just consider them absent. +- reading 2.X is not possible; the tool should refuse to interpret + the file. + +A tool written to produce 1.X should have these properties: + +- it will write all mandatory fields +- it may write optional fields + + +Acks +==== + +XXX -- cgit v0.12 From fa088dbd0cf20abdab011285d7f5d950ca61fb4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 18:42:38 +0200 Subject: Improve glossary entry for ABCs. - Rename reST target name for collections ABCs to avoid collisions - Add link to importlib ABCs (collections, numbers and io ABCs were already linked) - Link to glossary entry from numbers module doc (other modules already do it) --- Doc/glossary.rst | 14 ++++++++------ Doc/library/abc.rst | 2 +- Doc/library/collections.rst | 7 ++++--- Doc/library/numbers.rst | 6 +++--- 4 files changed, 16 insertions(+), 13 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index d14455b..fa34f29 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -27,12 +27,14 @@ Glossary :ref:`2to3-reference`. abstract base class - :ref:`abstract-base-classes` complement :term:`duck-typing` by + Abstract base classes complement :term:`duck-typing` by providing a way to define interfaces when other techniques like - :func:`hasattr` would be clumsy. Python comes with many built-in ABCs for + :func:`hasattr` would be clumsy or subtly wrong (for example with + :ref:`magic methods `). Python comes with many built-in ABCs for data structures (in the :mod:`collections` module), numbers (in the - :mod:`numbers` module), and streams (in the :mod:`io` module). You can - create your own ABC with the :mod:`abc` module. + :mod:`numbers` module), streams (in the :mod:`io` module), import finders + and loaders (in the :mod:`importlib.abc` module). You can create your own + ABCs with the :mod:`abc` module. argument A value passed to a function or method, assigned to a named local @@ -430,8 +432,8 @@ Glossary mapping A container object that supports arbitrary key lookups and implements the methods specified in the :class:`Mapping` or :class:`MutableMapping` - :ref:`abstract base classes `. Examples include - :class:`dict`, :class:`collections.defaultdict`, + :ref:`abstract base classes `. Examples + include :class:`dict`, :class:`collections.defaultdict`, :class:`collections.OrderedDict` and :class:`collections.Counter`. metaclass diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 9fadbd2..fa34a6f 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -12,7 +12,7 @@ -------------- This module provides the infrastructure for defining an :term:`abstract base -class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this +class` (ABC) in Python, as outlined in :pep:`3119`; see the PEP for why this was added to Python. (See also :pep:`3141` and the :mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 1a41a50..0b45fe1 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -33,8 +33,9 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`, ===================== ==================================================================== In addition to the concrete container classes, the collections module provides -:ref:`abstract-base-classes` that can be used to test whether a class provides a -particular interface, for example, whether it is hashable or a mapping. +:ref:`abstract base classes ` that can be +used to test whether a class provides a particular interface, for example, +whether it is hashable or a mapping. :class:`Counter` objects @@ -984,7 +985,7 @@ attribute. subclass) or an arbitrary sequence which can be converted into a string using the built-in :func:`str` function. -.. _abstract-base-classes: +.. _collections-abstract-base-classes: ABCs - abstract base classes ---------------------------- diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst index df8d521..ad33396 100644 --- a/Doc/library/numbers.rst +++ b/Doc/library/numbers.rst @@ -5,9 +5,9 @@ :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.). -The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract -base classes which progressively define more operations. None of the types -defined in this module can be instantiated. +The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric +:term:`abstract base classes ` which progressively define +more operations. None of the types defined in this module can be instantiated. .. class:: Number -- cgit v0.12 From 088025fc5bb10711db53d16788c202e3852e3777 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 18:45:40 +0200 Subject: Use list constructor or built-in method instead of copy module --- Lib/packaging/compiler/cygwinccompiler.py | 7 +++---- Lib/packaging/run.py | 3 +-- Lib/packaging/util.py | 3 +-- 3 files changed, 5 insertions(+), 8 deletions(-) diff --git a/Lib/packaging/compiler/cygwinccompiler.py b/Lib/packaging/compiler/cygwinccompiler.py index 7bfa611..348dbe7 100644 --- a/Lib/packaging/compiler/cygwinccompiler.py +++ b/Lib/packaging/compiler/cygwinccompiler.py @@ -48,7 +48,6 @@ of GCC (same as cygwin in no-cygwin mode). import os import sys -import copy from packaging import logger from packaging.compiler.unixccompiler import UnixCCompiler @@ -172,9 +171,9 @@ class CygwinCCompiler(UnixCCompiler): extra_postargs=None, build_temp=None, target_lang=None): """Link the objects.""" # use separate copies, so we can modify the lists - extra_preargs = copy.copy(extra_preargs or []) - libraries = copy.copy(libraries or []) - objects = copy.copy(objects or []) + extra_preargs = list(extra_preargs or []) + libraries = list(libraries or []) + objects = list(objects or []) # Additional libraries libraries.extend(self.dll_libraries) diff --git a/Lib/packaging/run.py b/Lib/packaging/run.py index de9dd13..1895dde 100644 --- a/Lib/packaging/run.py +++ b/Lib/packaging/run.py @@ -5,7 +5,6 @@ import re import sys import getopt import logging -from copy import copy from packaging import logger from packaging.dist import Distribution @@ -673,7 +672,7 @@ class Dispatcher: def main(args=None): old_level = logger.level - old_handlers = copy(logger.handlers) + old_handlers = list(logger.handlers) try: dispatcher = Dispatcher(args) if dispatcher.action is None: diff --git a/Lib/packaging/util.py b/Lib/packaging/util.py index 4e5bd2c..748686d 100644 --- a/Lib/packaging/util.py +++ b/Lib/packaging/util.py @@ -14,7 +14,6 @@ import zipfile import posixpath import sysconfig import subprocess -from copy import copy from glob import iglob as std_iglob from fnmatch import fnmatchcase from inspect import getsource @@ -384,7 +383,7 @@ byte_compile(files, optimize=%r, force=%r, elif optimize == 2: cmd.insert(1, "-OO") - env = copy(os.environ) + env = os.environ.copy() env['PYTHONPATH'] = os.path.pathsep.join(sys.path) try: spawn(cmd, env=env) -- cgit v0.12 From 823759e7672b95ced55b9d5a757faab47bdb5c2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 18:46:25 +0200 Subject: Add reST target for Doc/packaging/setupcfg --- Doc/packaging/commandhooks.rst | 5 +++++ Doc/packaging/setupcfg.rst | 2 ++ 2 files changed, 7 insertions(+) diff --git a/Doc/packaging/commandhooks.rst b/Doc/packaging/commandhooks.rst index 8dc233b..fd33357 100644 --- a/Doc/packaging/commandhooks.rst +++ b/Doc/packaging/commandhooks.rst @@ -1,3 +1,5 @@ +.. TODO integrate this in commandref and configfile + ============= Command hooks ============= @@ -9,6 +11,9 @@ The pre-hooks are run after the command is finalized (its options are processed), but before it is run. The post-hooks are run after the command itself. Both types of hooks receive an instance of the command object. +See also global setup hooks in :ref:`packaging-setupcfg`. + + Sample usage of hooks ===================== diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index 68786b2..9af8b63 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -1,5 +1,7 @@ .. highlightlang:: cfg +.. _packaging-setupcfg: + ******************************************* Specification of the :file:`setup.cfg` file ******************************************* -- cgit v0.12 From 70798be6f65029f5a37b34db83512460aa88813c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 20:47:26 +0200 Subject: Remove unneeded executable bit on two distutils files --- Lib/distutils/tests/Setup.sample | 0 Lib/distutils/tests/test_extension.py | 0 2 files changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 Lib/distutils/tests/Setup.sample mode change 100755 => 100644 Lib/distutils/tests/test_extension.py diff --git a/Lib/distutils/tests/Setup.sample b/Lib/distutils/tests/Setup.sample old mode 100755 new mode 100644 diff --git a/Lib/distutils/tests/test_extension.py b/Lib/distutils/tests/test_extension.py old mode 100755 new mode 100644 -- cgit v0.12 From 35a4d01a927a9ad0a774eec6a9ee1b728279c5b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 22:24:59 +0200 Subject: Improve a few docstrings in packaging. Also beautify import lists. Having them grouped by lenght makes it slightly easier to look for a module. --- Lib/packaging/create.py | 17 +++++------------ Lib/packaging/util.py | 15 +++++++-------- 2 files changed, 12 insertions(+), 20 deletions(-) diff --git a/Lib/packaging/create.py b/Lib/packaging/create.py index b96aef0..5a2eabd 100644 --- a/Lib/packaging/create.py +++ b/Lib/packaging/create.py @@ -1,15 +1,8 @@ -#!/usr/bin/env python """Interactive helper used to create a setup.cfg file. This script will generate a packaging configuration file by looking at the current directory and asking the user questions. It is intended to -be called as - - pysetup create - -or - - python3.3 -m packaging.create +be called as *pysetup create*. """ # Original code by Sean Reifschneider @@ -26,17 +19,17 @@ or # Detect scripts (not sure how. #! outside of package?) import os +import re import imp import sys import glob -import re import shutil import sysconfig import tokenize -from configparser import RawConfigParser -from textwrap import dedent from hashlib import md5 +from textwrap import dedent from functools import cmp_to_key +from configparser import RawConfigParser # importing this with an underscore as it should be replaced by the # dict form or another structures for all purposes from packaging._trove import all_classifiers as _CLASSIFIERS_LIST @@ -230,7 +223,7 @@ class MainProgram: self._write_cfg() def has_setup_py(self): - """Test for the existance of a setup.py file.""" + """Test for the existence of a setup.py file.""" return os.path.exists('setup.py') def define_cfg_values(self): diff --git a/Lib/packaging/util.py b/Lib/packaging/util.py index 748686d..ddb8ed9 100644 --- a/Lib/packaging/util.py +++ b/Lib/packaging/util.py @@ -1,19 +1,18 @@ -"""packaging.util -Miscellaneous utility functions. -""" -import errno -import csv -import hashlib +"""Miscellaneous utility functions.""" + import os -import sys import re +import csv +import sys +import errno import shutil import string +import hashlib import tarfile import zipfile import posixpath -import sysconfig import subprocess +import sysconfig from glob import iglob as std_iglob from fnmatch import fnmatchcase from inspect import getsource -- cgit v0.12 From 2ef747cb778a45ec7eb96f5ba5f725bbf53e970c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 22:33:16 +0200 Subject: =?UTF-8?q?Cleanup=20in=20packaging:=20don=E2=80=99t=20unnecessari?= =?UTF-8?q?ly=20instantiate=20exceptions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Lib/packaging/pypi/dist.py | 2 +- Lib/packaging/pypi/simple.py | 2 +- Lib/packaging/run.py | 2 +- Lib/packaging/tests/test_uninstall.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Lib/packaging/pypi/dist.py b/Lib/packaging/pypi/dist.py index 16510df..db04cda 100644 --- a/Lib/packaging/pypi/dist.py +++ b/Lib/packaging/pypi/dist.py @@ -135,7 +135,7 @@ class ReleaseInfo(IndexReference): not return one existing distribution. """ if len(self.dists) == 0: - raise LookupError() + raise LookupError if dist_type: return self[dist_type] if prefer_source: diff --git a/Lib/packaging/pypi/simple.py b/Lib/packaging/pypi/simple.py index c492179..c372c6f 100644 --- a/Lib/packaging/pypi/simple.py +++ b/Lib/packaging/pypi/simple.py @@ -189,7 +189,7 @@ class Crawler(BaseClient): self._process_index_page(predicate.name) if predicate.name.lower() not in self._projects: - raise ProjectNotFound() + raise ProjectNotFound releases = self._projects.get(predicate.name.lower()) releases.sort_releases(prefer_final=prefer_final) diff --git a/Lib/packaging/run.py b/Lib/packaging/run.py index 1895dde..7e791a4 100644 --- a/Lib/packaging/run.py +++ b/Lib/packaging/run.py @@ -383,7 +383,7 @@ def _search(dispatcher, args, **kw): """ #opts = _parse_args(args[1:], '', ['simple', 'xmlrpc']) # 1. what kind of index is requested ? (xmlrpc / simple) - raise NotImplementedError() + raise NotImplementedError actions = [ diff --git a/Lib/packaging/tests/test_uninstall.py b/Lib/packaging/tests/test_uninstall.py index 4b37286..00e97e4 100644 --- a/Lib/packaging/tests/test_uninstall.py +++ b/Lib/packaging/tests/test_uninstall.py @@ -111,7 +111,7 @@ class UninstallTestCase(support.TempdirManager, old = os.rename def _rename(source, target): - raise OSError() + raise OSError os.rename = _rename try: -- cgit v0.12 From 18efecf30afce7d2e4da718ae02397834233ed43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 22:33:59 +0200 Subject: Make help messages in packaging.run more consistent --- Lib/packaging/run.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Lib/packaging/run.py b/Lib/packaging/run.py index 7e791a4..c17ccfd 100644 --- a/Lib/packaging/run.py +++ b/Lib/packaging/run.py @@ -34,14 +34,14 @@ create_usage = """\ Usage: pysetup create or: pysetup create --help -Create a new Python package. +Create a new Python project. """ generate_usage = """\ Usage: pysetup generate-setup or: pysetup generate-setup --help -Generates a setup.py script for backward-compatibility purposes. +Generate a setup.py script for backward-compatibility purposes. """ @@ -95,7 +95,7 @@ positional arguments: dist installed distribution name optional arguments: - -y auto confirm package removal + -y auto confirm distribution removal """ run_usage = """\ @@ -217,7 +217,6 @@ def _generate(distpatcher, args, **kw): print('The setup.py was generated') - @action_help(graph_usage) def _graph(dispatcher, args, **kw): name = args[1] @@ -392,10 +391,10 @@ actions = [ ('install', 'Install a project', _install), ('remove', 'Remove a project', _remove), ('search', 'Search for a project in the indexes', _search), - ('list', 'Search for local projects', _list), + ('list', 'List installed releases', _list), ('graph', 'Display a graph', _graph), - ('create', 'Create a Project', _create), - ('generate-setup', 'Generates a backward-comptatible setup.py', _generate) + ('create', 'Create a project', _create), + ('generate-setup', 'Generate a backward-comptatible setup.py', _generate), ] -- cgit v0.12 From 8f66f61e55fc51945bc406a6f9408c1bc131bb3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 22:36:40 +0200 Subject: Clean up packaging.create and add TODO notes for future cleanups --- Lib/packaging/create.py | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Lib/packaging/create.py b/Lib/packaging/create.py index 5a2eabd..d591fb9 100644 --- a/Lib/packaging/create.py +++ b/Lib/packaging/create.py @@ -274,9 +274,13 @@ class MainProgram: with open(_FILENAME, 'w', encoding='utf-8') as fp: fp.write('[metadata]\n') + # TODO use metadata module instead of hard-coding field-specific + # behavior here + # simple string entries for name in ('name', 'version', 'summary', 'download_url'): fp.write('%s = %s\n' % (name, self.data.get(name, 'UNKNOWN'))) + # optional string entries if 'keywords' in self.data and self.data['keywords']: fp.write('keywords = %s\n' % ' '.join(self.data['keywords'])) @@ -288,6 +292,7 @@ class MainProgram: fp.write( 'description = %s\n' % '\n |'.join(self.data['description'].split('\n'))) + # multiple use string entries for name in ('platform', 'supported-platform', 'classifier', 'requires-dist', 'provides-dist', 'obsoletes-dist', @@ -322,8 +327,8 @@ class MainProgram: def setup_mock(**attrs): """Mock the setup(**attrs) in order to retrieve metadata.""" - # use the distutils v1 processings to correctly parse metadata. - #XXX we could also use the setuptools distibution ??? + + # TODO use config and metadata instead of Distribution from distutils.dist import Distribution dist = Distribution(attrs) dist.parse_config_files() @@ -355,13 +360,14 @@ class MainProgram: data['modules'].extend(dist.py_modules or []) # 2.1 data_files -> resources if dist.data_files: - if len(dist.data_files) < 2 or \ - isinstance(dist.data_files[1], str): + if (len(dist.data_files) < 2 or + isinstance(dist.data_files[1], str)): dist.data_files = [('', dist.data_files)] # add tokens in the destination paths vars = {'distribution.name': data['name']} path_tokens = list(sysconfig.get_paths(vars=vars).items()) + # TODO replace this with a key function def length_comparison(x, y): len_x = len(x[1]) len_y = len(y[1]) @@ -384,12 +390,12 @@ class MainProgram: dest = ('{%s}' % tok) + dest[len(path):] files = [('/ '.join(src.rsplit('/', 1)), dest) - for src in srcs] + for src in srcs] data['resources'].extend(files) # 2.2 package_data -> extra_files package_dirs = dist.package_dir or {} - for package, extras in iter(dist.package_data.items()) or []: + for package, extras in dist.package_data.items() or []: package_dir = package_dirs.get(package, package) for file_ in extras: if package_dir: @@ -451,10 +457,10 @@ class MainProgram: if match: self.data['name'] = match.group(1) self.data['version'] = match.group(2) - # TODO Needs tested! + # TODO needs testing! if not is_valid_version(self.data['version']): msg = "Invalid version discovered: %s" % self.data['version'] - raise RuntimeError(msg) + raise ValueError(msg) def query_user(self): self.data['name'] = ask('Project name', self.data['name'], -- cgit v0.12 From 45593836647f6d7426f883dc3ed6847aeaea69ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 4 Jun 2011 22:37:57 +0200 Subject: Improve consistency in questions asked by packaging.create. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I reworded “wizard” because it is a Windows-specific term. --- Lib/packaging/create.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Lib/packaging/create.py b/Lib/packaging/create.py index d591fb9..c18d42f 100644 --- a/Lib/packaging/create.py +++ b/Lib/packaging/create.py @@ -61,7 +61,7 @@ E-mail address of the project author (typically you). 'do_classifier': ''' Trove classifiers are optional identifiers that allow you to specify the intended audience by saying things like "Beta software with a text UI -for Linux under the PSF license. However, this can be a somewhat involved +for Linux under the PSF license". However, this can be a somewhat involved process. ''', 'packages': ''' @@ -88,7 +88,7 @@ human language, programming language, user interface, etc... ''', 'setup.py found': ''' The setup.py script will be executed to retrieve the metadata. -A wizard will be run if you answer "n", +An interactive helper will be run if you answer "n", ''', } @@ -475,25 +475,25 @@ class MainProgram: self.data.get('author'), _helptext['author']) self.data['author_email'] = ask('Author e-mail address', self.data.get('author_email'), _helptext['author_email']) - self.data['home_page'] = ask('Project Home Page', + self.data['home_page'] = ask('Project home page', self.data.get('home_page'), _helptext['home_page'], required=False) if ask_yn('Do you want me to automatically build the file list ' - 'with everything I can find in the current directory ? ' + 'with everything I can find in the current directory? ' 'If you say no, you will have to define them manually.') == 'y': self._find_files() else: - while ask_yn('Do you want to add a single module ?' + while ask_yn('Do you want to add a single module?' ' (you will be able to add full packages next)', helptext=_helptext['modules']) == 'y': self._set_multi('Module name', 'modules') - while ask_yn('Do you want to add a package ?', + while ask_yn('Do you want to add a package?', helptext=_helptext['packages']) == 'y': self._set_multi('Package name', 'packages') - while ask_yn('Do you want to add an extra file ?', + while ask_yn('Do you want to add an extra file?', helptext=_helptext['extra_files']) == 'y': self._set_multi('Extra file/dir name', 'extra_files') @@ -581,7 +581,7 @@ class MainProgram: self.set_other_classifier(self.classifiers) def set_other_classifier(self, classifiers): - if ask_yn('Do you want to set other trove identifiers', 'n', + if ask_yn('Do you want to set other trove identifiers?', 'n', _helptext['trove_generic']) != 'y': return self.walk_classifiers(classifiers, [CLASSIFIERS], '') @@ -598,7 +598,7 @@ class MainProgram: classifiers.add(desc[4:] + ' :: ' + key) continue - if ask_yn('Do you want to set items under\n "%s" (%d sub-items)' + if ask_yn('Do you want to set items under\n "%s" (%d sub-items)?' % (key, len(trove[key])), 'n', _helptext['trove_generic']) == 'y': self.walk_classifiers(classifiers, trovepath + [trove[key]], @@ -606,7 +606,7 @@ class MainProgram: def set_license(self, classifiers): while True: - license = ask('What license do you use', + license = ask('What license do you use?', helptext=_helptext['trove_license'], required=False) if not license: return -- cgit v0.12 From d5d831b74d249acfda2927bfcd6addd4bab003a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 01:13:48 +0200 Subject: Update doctring now that Python has real booleans --- Lib/packaging/util.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/packaging/util.py b/Lib/packaging/util.py index ddb8ed9..d4aae41 100644 --- a/Lib/packaging/util.py +++ b/Lib/packaging/util.py @@ -271,7 +271,7 @@ def execute(func, args, msg=None, verbose=0, dry_run=False): def strtobool(val): - """Convert a string representation of truth to true (1) or false (0). + """Convert a string representation of truth to a boolean. True values are 'y', 'yes', 't', 'true', 'on', and '1'; false values are 'n', 'no', 'f', 'false', 'off', and '0'. Raises ValueError if -- cgit v0.12 From f0f9b22459f8d07d04875e31a63287e19c85e243 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 01:52:37 +0200 Subject: Add a short table of contents to the setup.cfg spec. I tried shortening the sidebar ToC with the tocdepth option instead, but it has a bug which caused all headings with a level deeper than the tocdepth value to all have the same section number, which was a usability regression rather than in improvement. --- Doc/packaging/setupcfg.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index 9af8b63..a195d5a 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -12,6 +12,10 @@ This document describes the :file:`setup.cfg`, an ini-style configuration file (compatible with :class:`configparser.RawConfigParser`) used by Packaging to replace the :file:`setup.py` file. +.. contents:: + :depth: 3 + :local: + Syntax ====== -- cgit v0.12 From 0300b5c9e6dc84b5dd6d2ba26a99832d9397cca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 01:54:54 +0200 Subject: Change reST targets in setup.cfg spec. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I chose “setupcfg” as prefix instead of “packaging-setupcfg” because the scope of the spec is not limited to packaging: it’s intended as a language-agnostic document for packaging tools developers as well as Python authors. --- Doc/packaging/commandhooks.rst | 2 +- Doc/packaging/setupcfg.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/packaging/commandhooks.rst b/Doc/packaging/commandhooks.rst index fd33357..0a3d044 100644 --- a/Doc/packaging/commandhooks.rst +++ b/Doc/packaging/commandhooks.rst @@ -11,7 +11,7 @@ The pre-hooks are run after the command is finalized (its options are processed), but before it is run. The post-hooks are run after the command itself. Both types of hooks receive an instance of the command object. -See also global setup hooks in :ref:`packaging-setupcfg`. +See also global setup hooks in :ref:`setupcfg-spec`. Sample usage of hooks diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index a195d5a..af90304 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -1,6 +1,6 @@ .. highlightlang:: cfg -.. _packaging-setupcfg: +.. _setupcfg-spec: ******************************************* Specification of the :file:`setup.cfg` file @@ -387,7 +387,7 @@ The final paths where files will be placed are composed by : **source** + **destination**. In the previous example, **doc/doc.man** will be placed in **destination_doc/doc/doc.man** and **scripts/foo.sh** will be placed in **destination_scripts/scripts/foo.sh**. (If you want more control on the final -path, take a look at base_prefix_). +path, take a look at :ref:`setupcfg-resources-base-prefix`). The **destination** part of resources declaration are paths with categories. Indeed, it's generally a bad idea to give absolute path as it will be cross @@ -511,7 +511,7 @@ Your **files** section will be:: More control on destination part ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _base_prefix: +.. _setupcfg-resources-base-prefix: Defining a base prefix """""""""""""""""""""" -- cgit v0.12 From ed4fd704aa41b7b233a963f91690a33e698a9d87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 02:07:24 +0200 Subject: Rephrase and update intro and syntax sections of setupcfg --- Doc/packaging/setupcfg.rst | 66 ++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index af90304..0d820d9 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -9,8 +9,10 @@ Specification of the :file:`setup.cfg` file :version: 0.9 This document describes the :file:`setup.cfg`, an ini-style configuration file -(compatible with :class:`configparser.RawConfigParser`) used by Packaging to -replace the :file:`setup.py` file. +used by Packaging to replace the :file:`setup.py` file used by Distutils. +This specification is language-agnostic, and will therefore repeat some +information that's already documented for Python in the +:class:`configparser.RawConfigParser` documentation. .. contents:: :depth: 3 @@ -20,11 +22,10 @@ replace the :file:`setup.py` file. Syntax ====== -The configuration file is an ini-based file. Variables name can be -assigned values, and grouped into sections. A line that starts with "#" is -commented out. Empty lines are also removed. - -Example:: +The ini-style format used in the configuration file is a simple collection of +sections that group sets of key-value fields separated by ``=`` or ``:`` and +optional whitespace. Lines starting with ``#`` or ``;`` are comments and will +be ignored. Empty lines are also ignored. Example:: [section1] # comment @@ -35,22 +36,24 @@ Example:: foo = bar -Values conversion ------------------ +Parsing values +--------------- + +Here are a set of rules to parse values: + +- If a value is quoted with ``"`` chars, it's a string. If a quote character is + present in the quoted value, it can be escaped as ``\"`` or left as-is. + +- If the value is ``true``, ``t``, ``yes``, ``y`` (case-insensitive) or ``1``, + it's converted to the language equivalent of a ``True`` value; if it's + ``false``, ``f``, ``no``, ``n`` (case-insensitive) or ``0``, it's converted to + the equivalent of ``False``. -Here are a set of rules for converting values: +- A value can contain multiple lines. When read, lines are converted into a + sequence of values. Each line after the first must start with a least one + space or tab character; this leading indentation will be stripped. -- If value is quoted with " chars, it's a string. This notation is useful to - include "=" characters in the value. In case the value contains a " - character, it must be escaped with a "\" character. -- If the value is "true" or "false" --no matter what the case is--, it's - converted to a boolean, or 0 and 1 when the language does not have a - boolean type. -- A value can contains multiple lines. When read, lines are converted into a - sequence of values. Each new line for a multiple lines value must start with - a least one space or tab character. These indentation characters will be - stripped. -- all other values are considered as strings +- All other values are considered strings. Examples:: @@ -68,12 +71,12 @@ Examples:: Extending files --------------- -An INI file can extend another file. For this, a "DEFAULT" section must contain -an "extends" variable that can point to one or several INI files which will be -merged to the current file by adding new sections and values. +A configuration file can be extended (i.e. included) by other files. For this, +a ``DEFAULT`` section must contain an ``extends`` key which value points to one +or more files which will be merged into the current files by adding new sections +and fields. If a file loaded by ``extends`` contains sections or keys that +already exist in the original file, they will not override the previous values. -If the file pointed in "extends" contains section/variable names that already -exist in the original file, they will not override existing ones. file_one.ini:: @@ -107,13 +110,12 @@ To point several files, the multi-line notation can be used:: extends = file_one.ini file_two.ini -When several files are provided, they are processed sequentially. So if the -first one has a value that is also present in the second, the second one will -be ignored. This means that the configuration goes from the most specialized to -the most common. +When several files are provided, they are processed sequentially, following the +precedence rules explained above. This means that the list of files should go +from most specialized to most common. -**Tools will need to provide a way to produce a canonical version of the -file**. This will be useful to publish a single file. +**Tools will need to provide a way to produce a merged version of the +file**. This will be useful to let users publish a single file. Description of sections and fields -- cgit v0.12 From 138900802239f39ad1940098f023475524ed242e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 01:58:25 +0200 Subject: Make example of file inclusion in setupcfg more obvious --- Doc/packaging/setupcfg.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index 0d820d9..1999f18 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -77,38 +77,37 @@ or more files which will be merged into the current files by adding new sections and fields. If a file loaded by ``extends`` contains sections or keys that already exist in the original file, they will not override the previous values. - -file_one.ini:: +Contents of :file:`one.cfg`:: [section1] - name2 = "other value" + name = value [section2] - foo = baz - bas = bar + foo = foo from one.cfg -file_two.ini:: +Contents of :file:`two.cfg`:: [DEFAULT] - extends = file_one.ini + extends = one.cfg [section2] - foo = bar + foo = foo from two.cfg + baz = baz from two.cfg -Result:: +The result of parsing :file:`two.cfg` is equivalent to this file:: [section1] - name2 = "other value" + name = value [section2] - foo = bar - bas = bar + foo = foo from one.cfg + baz = baz from two.cfg -To point several files, the multi-line notation can be used:: +Example use of multi-line notation to include more than one file:: [DEFAULT] - extends = file_one.ini - file_two.ini + extends = one.cfg + two.cfg When several files are provided, they are processed sequentially, following the precedence rules explained above. This means that the list of files should go -- cgit v0.12 From 8a4e7a9e2c1e1a6b305397de735e43f779c499e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 01:58:54 +0200 Subject: Move a non-PEP 345 field at the end of the metadata fields list --- Doc/packaging/setupcfg.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index 1999f18..baafe4e 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -218,10 +218,6 @@ description in Distutils1.) A file can be provided in the *description-file* field. *optional* -description-file - path to a text file that will be used for the - **description** field. *optional* - keywords A list of additional keywords to be used to assist searching for the distribution in a larger catalog. Comma or space-separated. @@ -282,6 +278,13 @@ project-url A label, followed by a browsable URL for the project. "label, url". The label is limited to 32 signs. *optional*, *multi* +One extra field not present in PEP 345 is supported: + +description-file + Path to a text file that will be used to fill the ``description`` field. + ``description-file`` and ``description`` are mutually exclusive. *optional* + + Example:: -- cgit v0.12 From 1cf8a3203d7e7bccaea0ec5fe81e08fce3b25c33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 02:00:03 +0200 Subject: Minor rework of the extensibility and acks sections --- Doc/packaging/setupcfg.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index baafe4e..231436c 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -764,15 +764,13 @@ line. See :ref:`packaging-setup-config` for more information. Extensibility ============= -Every section can define new variables that are not part of the specification. -They are called **extensions**. +Every section can have fields that are not part of this specification. They are +called **extensions**. -An extension field starts with *X-*. - -Example:: +An extension field starts with ``X-``. Example:: [metadata] - ... + name = Distribute X-Debian-Name = python-distribute @@ -809,7 +807,17 @@ A tool written to produce 1.X should have these properties: - it may write optional fields -Acks -==== -XXX + + +Acknowledgments +=============== + +This specification includes work and feedback from these people: + +- Tarek Ziadé +- Julien Jehannet +- Boris Feld +- Éric Araujo + +(If your name is missing, please :ref:`let us know `.) -- cgit v0.12 From 60533e03e9970988b0b0fbf9811db4a948e6ffe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 02:00:54 +0200 Subject: Fix a few typos --- Doc/packaging/setupcfg.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index 231436c..a67c1fb 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -521,7 +521,7 @@ Defining a base prefix """""""""""""""""""""" When you define your resources, you can have more control of how the final path -is compute. +is computed. By default, the final path is:: @@ -548,7 +548,7 @@ The **prefix** is "docs/" and the **suffix** is "doc.html". .. note:: - Glob syntax is working the same way with standard source and splitted source. + Glob syntax is working the same way with standard source and split source. So these rules:: docs/* @@ -557,7 +557,7 @@ The **prefix** is "docs/" and the **suffix** is "doc.html". Will match all the files in the docs directory. -When you use splitted source, the final path is compute in this way:: +When you use split source, the final path is computed this way:: destination + prefix -- cgit v0.12 From a69ade81be00270bd613f7e5e4f999f5d7bc304b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 6 Jun 2011 02:02:34 +0200 Subject: Rephrase the section about spec versioning --- Doc/packaging/setupcfg.rst | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst index a67c1fb..92ddb8b 100644 --- a/Doc/packaging/setupcfg.rst +++ b/Doc/packaging/setupcfg.rst @@ -777,37 +777,36 @@ An extension field starts with ``X-``. Example:: Changes in the specification ============================ -The version scheme for this specification is **MAJOR.MINOR**. -Changes in the specification will increment the version. +The versioning scheme for this specification is **MAJOR.MINOR**. Changes in the +specification will cause the version number to be updated. -- minor version changes (1.x): backwards compatible +Changes to the minor number reflect backwards-compatible changes: - - new fields and sections (both optional and mandatory) can be added - - optional fields can be removed +- New fields and sections (optional or mandatory) can be added. +- Optional fields can be removed. -- major channges (2.X): backwards-incompatible +The major number will be incremented for backwards-incompatible changes: - - mandatory fields/sections are removed - - fields change their meaning +- Mandatory fields or sections are removed. +- Fields change their meaning. -As a consequence, a tool written to consume 1.X (say, X=5) has these -properties: +As a consequence, a tool written to consume 1.5 has these properties: -- reading 1.Y, YX is also possible. The tool will just ignore the new - fields (even if they are mandatory in that version) - If optional fields were removed, the tool will just consider them absent. -- reading 2.X is not possible; the tool should refuse to interpret - the file. +- Can read 1.1, 1.2 and all versions < 1.5, since the tool knows what + optional fields weren't there. -A tool written to produce 1.X should have these properties: + .. XXX clarify -- it will write all mandatory fields -- it may write optional fields +- Can also read 1.6 and other 1.x versions: The tool will just ignore fields it + doesn't know about, even if they are mandatory in the new version. If + optional fields were removed, the tool will just consider them absent. +- Cannot read 2.x and should refuse to interpret such files. +A tool written to produce 1.x should have these properties: +- Writes all mandatory fields. +- May write optional fields. Acknowledgments -- cgit v0.12