annotate Lib/packaging/errors.py @ 73323:dad02a080bbc

Improve byte-compilation in packaging to be independent of -O or -B. The code I fixed to comply with PEP 3147 still had one bug: When run under python -O, some paths for pyc files would be pyo, because I called imp.cache_from_source without explicit debug_override argument in some places, and under -O that would return .pyo (this is well explained in the imp docs). Now all code (util.byte_compile, build_py, install_lib) can create .pyo files according to options given by users, without interference from the calling Python’s own optimize mode. On a related topic, I also removed the code that prevented byte compilation under python -B. The rationale is that packaging gives control over the creation of pyc files to the user with its own explicit option, and the behavior should not be changed if the calling Python happens to run with -B for whatever reason. I will argue that this is a bug fix and ask to be allowed to backport this change to distutils. Finally, I moved one nugget of information about the --compile and --optimize options from the source into the doc. It clears up a misunderstanding that I (and maybe other people) had.
author Éric Araujo <merwok@netwok.org>
date Thu, 03 Nov 2011 05:08:28 +0100
parents 1a31c3be88b1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
70194
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
1 """Exceptions used throughout the package.
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
2
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
3 Submodules of packaging may raise exceptions defined in this module as
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
4 well as standard exceptions; in particular, SystemExit is usually raised
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
5 for errors that are obviously the end-user's fault (e.g. bad
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
6 command-line arguments).
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
7 """
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
8
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
9
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
10 class PackagingError(Exception):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
11 """The root of all Packaging evil."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
12
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
13
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
14 class PackagingModuleError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
15 """Unable to load an expected module, or to find an expected class
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
16 within some module (in particular, command modules and classes)."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
17
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
18
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
19 class PackagingClassError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
20 """Some command class (or possibly distribution class, if anyone
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
21 feels a need to subclass Distribution) is found not to be holding
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
22 up its end of the bargain, ie. implementing some part of the
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
23 "command "interface."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
24
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
25
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
26 class PackagingGetoptError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
27 """The option table provided to 'fancy_getopt()' is bogus."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
28
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
29
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
30 class PackagingArgError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
31 """Raised by fancy_getopt in response to getopt.error -- ie. an
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
32 error in the command line usage."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
33
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
34
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
35 class PackagingFileError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
36 """Any problems in the filesystem: expected file not found, etc.
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
37 Typically this is for problems that we detect before IOError or
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
38 OSError could be raised."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
39
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
40
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
41 class PackagingOptionError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
42 """Syntactic/semantic errors in command options, such as use of
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
43 mutually conflicting options, or inconsistent options,
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
44 badly-spelled values, etc. No distinction is made between option
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
45 values originating in the setup script, the command line, config
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
46 files, or what-have-you -- but if we *know* something originated in
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
47 the setup script, we'll raise PackagingSetupError instead."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
48
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
49
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
50 class PackagingSetupError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
51 """For errors that can be definitely blamed on the setup script,
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
52 such as invalid keyword arguments to 'setup()'."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
53
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
54
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
55 class PackagingPlatformError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
56 """We don't know how to do something on the current platform (but
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
57 we do know how to do it on some platform) -- eg. trying to compile
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
58 C files on a platform not supported by a CCompiler subclass."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
59
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
60
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
61 class PackagingExecError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
62 """Any problems executing an external program (such as the C
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
63 compiler, when compiling C files)."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
64
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
65
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
66 class PackagingInternalError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
67 """Internal inconsistencies or impossibilities (obviously, this
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
68 should never be seen if the code is working!)."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
69
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
70
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
71 class PackagingTemplateError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
72 """Syntax error in a file list template."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
73
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
74
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
75 class PackagingPyPIError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
76 """Any problem occuring during using the indexes."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
77
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
78
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
79 # Exception classes used by the CCompiler implementation classes
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
80 class CCompilerError(Exception):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
81 """Some compile/link operation failed."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
82
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
83
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
84 class PreprocessError(CCompilerError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
85 """Failure to preprocess one or more C/C++ files."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
86
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
87
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
88 class CompileError(CCompilerError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
89 """Failure to compile one or more C/C++ source files."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
90
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
91
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
92 class LibError(CCompilerError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
93 """Failure to create a static library from one or more C/C++ object
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
94 files."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
95
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
96
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
97 class LinkError(CCompilerError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
98 """Failure to link one or more C/C++ object files into an executable
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
99 or shared library file."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
100
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
101
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
102 class UnknownFileError(CCompilerError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
103 """Attempt to process an unknown file type."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
104
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
105
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
106 class MetadataMissingError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
107 """A required metadata is missing"""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
108
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
109
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
110 class MetadataConflictError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
111 """Attempt to read or write metadata fields that are conflictual."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
112
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
113
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
114 class MetadataUnrecognizedVersionError(PackagingError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
115 """Unknown metadata version number."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
116
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
117
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
118 class IrrationalVersionError(Exception):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
119 """This is an irrational version."""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
120 pass
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
121
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
122
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
123 class HugeMajorVersionNumError(IrrationalVersionError):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
124 """An irrational version because the major version number is huge
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
125 (often because a year or date was used).
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
126
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
127 See `error_on_huge_major_num` option in `NormalizedVersion` for details.
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
128 This guard can be disabled by setting that option False.
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
129 """
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
130 pass
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
131
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
132
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
133 class InstallationException(Exception):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
134 """Base exception for installation scripts"""
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
135
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
136
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
137 class InstallationConflict(InstallationException):
1a31c3be88b1 initial import of the packaging package in the standard library
Tarek Ziade <tarek@ziade.org>
parents:
diff changeset
138 """Raised when a conflict is detected"""