Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Configuration management setup
3Some terminology:
4- name
5 As written in config files.
6- value
7 Value associated with a name
8- key
9 Name combined with it's section (section.name)
10- variant
11 A single word describing where the configuration key-value pair came from
12"""
14from __future__ import annotations
16import configparser
17import locale
18import os
19import sys
20from collections.abc import Iterable
21from typing import Any, NewType
23from pip._internal.exceptions import (
24 ConfigurationError,
25 ConfigurationFileCouldNotBeLoaded,
26)
27from pip._internal.utils import appdirs
28from pip._internal.utils.compat import WINDOWS
29from pip._internal.utils.logging import getLogger
30from pip._internal.utils.misc import ensure_dir, enum
32RawConfigParser = configparser.RawConfigParser # Shorthand
33Kind = NewType("Kind", str)
35CONFIG_BASENAME = "pip.ini" if WINDOWS else "pip.conf"
36ENV_NAMES_IGNORED = "version", "help"
38# The kinds of configurations there are.
39kinds = enum(
40 USER="user", # User Specific
41 GLOBAL="global", # System Wide
42 SITE="site", # [Virtual] Environment Specific
43 ENV="env", # from PIP_CONFIG_FILE
44 ENV_VAR="env-var", # from Environment Variables
45)
46OVERRIDE_ORDER = kinds.GLOBAL, kinds.USER, kinds.SITE, kinds.ENV, kinds.ENV_VAR
47VALID_LOAD_ONLY = kinds.USER, kinds.GLOBAL, kinds.SITE
49logger = getLogger(__name__)
52# NOTE: Maybe use the optionx attribute to normalize keynames.
53def _normalize_name(name: str) -> str:
54 """Make a name consistent regardless of source (environment or file)"""
55 name = name.lower().replace("_", "-")
56 name = name.removeprefix("--") # only prefer long opts
57 return name
60def _disassemble_key(name: str) -> list[str]:
61 if "." not in name:
62 error_message = (
63 "Key does not contain dot separated section and key. "
64 f"Perhaps you wanted to use 'global.{name}' instead?"
65 )
66 raise ConfigurationError(error_message)
67 return name.split(".", 1)
70def get_configuration_files() -> dict[Kind, list[str]]:
71 global_config_files = [
72 os.path.join(path, CONFIG_BASENAME) for path in appdirs.site_config_dirs("pip")
73 ]
75 site_config_file = os.path.join(sys.prefix, CONFIG_BASENAME)
76 legacy_config_file = os.path.join(
77 os.path.expanduser("~"),
78 "pip" if WINDOWS else ".pip",
79 CONFIG_BASENAME,
80 )
81 new_config_file = os.path.join(appdirs.user_config_dir("pip"), CONFIG_BASENAME)
82 return {
83 kinds.GLOBAL: global_config_files,
84 kinds.SITE: [site_config_file],
85 kinds.USER: [legacy_config_file, new_config_file],
86 }
89class Configuration:
90 """Handles management of configuration.
92 Provides an interface to accessing and managing configuration files.
94 This class converts provides an API that takes "section.key-name" style
95 keys and stores the value associated with it as "key-name" under the
96 section "section".
98 This allows for a clean interface wherein the both the section and the
99 key-name are preserved in an easy to manage form in the configuration files
100 and the data stored is also nice.
101 """
103 def __init__(self, isolated: bool, load_only: Kind | None = None) -> None:
104 super().__init__()
106 if load_only is not None and load_only not in VALID_LOAD_ONLY:
107 raise ConfigurationError(
108 "Got invalid value for load_only - should be one of {}".format(
109 ", ".join(map(repr, VALID_LOAD_ONLY))
110 )
111 )
112 self.isolated = isolated
113 self.load_only = load_only
115 # Because we keep track of where we got the data from
116 self._parsers: dict[Kind, list[tuple[str, RawConfigParser]]] = {
117 variant: [] for variant in OVERRIDE_ORDER
118 }
119 self._config: dict[Kind, dict[str, dict[str, Any]]] = {
120 variant: {} for variant in OVERRIDE_ORDER
121 }
122 self._modified_parsers: list[tuple[str, RawConfigParser]] = []
124 def load(self) -> None:
125 """Loads configuration from configuration files and environment"""
126 self._load_config_files()
127 if not self.isolated:
128 self._load_environment_vars()
130 def get_file_to_edit(self) -> str | None:
131 """Returns the file with highest priority in configuration"""
132 assert self.load_only is not None, "Need to be specified a file to be editing"
134 try:
135 return self._get_parser_to_modify()[0]
136 except IndexError:
137 return None
139 def items(self) -> Iterable[tuple[str, Any]]:
140 """Returns key-value pairs like dict.items() representing the loaded
141 configuration
142 """
143 return self._dictionary.items()
145 def get_value(self, key: str) -> Any:
146 """Get a value from the configuration."""
147 orig_key = key
148 key = _normalize_name(key)
149 try:
150 clean_config: dict[str, Any] = {}
151 for file_values in self._dictionary.values():
152 clean_config.update(file_values)
153 return clean_config[key]
154 except KeyError:
155 # disassembling triggers a more useful error message than simply
156 # "No such key" in the case that the key isn't in the form command.option
157 _disassemble_key(key)
158 raise ConfigurationError(f"No such key - {orig_key}")
160 def set_value(self, key: str, value: Any) -> None:
161 """Modify a value in the configuration."""
162 key = _normalize_name(key)
163 self._ensure_have_load_only()
165 assert self.load_only
166 fname, parser = self._get_parser_to_modify()
168 if parser is not None:
169 section, name = _disassemble_key(key)
171 # Modify the parser and the configuration
172 if not parser.has_section(section):
173 parser.add_section(section)
174 parser.set(section, name, value)
176 self._config[self.load_only].setdefault(fname, {})
177 self._config[self.load_only][fname][key] = value
178 self._mark_as_modified(fname, parser)
180 def unset_value(self, key: str) -> None:
181 """Unset a value in the configuration."""
182 orig_key = key
183 key = _normalize_name(key)
184 self._ensure_have_load_only()
186 assert self.load_only
187 fname, parser = self._get_parser_to_modify()
189 if (
190 key not in self._config[self.load_only][fname]
191 and key not in self._config[self.load_only]
192 ):
193 raise ConfigurationError(f"No such key - {orig_key}")
195 if parser is not None:
196 section, name = _disassemble_key(key)
197 if not (
198 parser.has_section(section) and parser.remove_option(section, name)
199 ):
200 # The option was not removed.
201 raise ConfigurationError(
202 "Fatal Internal error [id=1]. Please report as a bug."
203 )
205 # The section may be empty after the option was removed.
206 if not parser.items(section):
207 parser.remove_section(section)
208 self._mark_as_modified(fname, parser)
209 try:
210 del self._config[self.load_only][fname][key]
211 except KeyError:
212 del self._config[self.load_only][key]
214 def save(self) -> None:
215 """Save the current in-memory state."""
216 self._ensure_have_load_only()
218 for fname, parser in self._modified_parsers:
219 logger.info("Writing to %s", fname)
221 # Ensure directory exists.
222 ensure_dir(os.path.dirname(fname))
224 # Ensure directory's permission(need to be writeable)
225 try:
226 with open(fname, "w") as f:
227 parser.write(f)
228 except OSError as error:
229 raise ConfigurationError(
230 f"An error occurred while writing to the configuration file "
231 f"{fname}: {error}"
232 )
234 #
235 # Private routines
236 #
238 def _ensure_have_load_only(self) -> None:
239 if self.load_only is None:
240 raise ConfigurationError("Needed a specific file to be modifying.")
241 logger.debug("Will be working with %s variant only", self.load_only)
243 @property
244 def _dictionary(self) -> dict[str, dict[str, Any]]:
245 """A dictionary representing the loaded configuration."""
246 # NOTE: Dictionaries are not populated if not loaded. So, conditionals
247 # are not needed here.
248 retval = {}
250 for variant in OVERRIDE_ORDER:
251 retval.update(self._config[variant])
253 return retval
255 def _load_config_files(self) -> None:
256 """Loads configuration from configuration files"""
257 config_files = dict(self.iter_config_files())
258 if config_files[kinds.ENV][0:1] == [os.devnull]:
259 logger.debug(
260 "Skipping loading configuration files due to "
261 "environment's PIP_CONFIG_FILE being os.devnull"
262 )
263 return
265 for variant, files in config_files.items():
266 for fname in files:
267 # If there's specific variant set in `load_only`, load only
268 # that variant, not the others.
269 if self.load_only is not None and variant != self.load_only:
270 logger.debug("Skipping file '%s' (variant: %s)", fname, variant)
271 continue
273 parser = self._load_file(variant, fname)
275 # Keeping track of the parsers used
276 self._parsers[variant].append((fname, parser))
278 def _load_file(self, variant: Kind, fname: str) -> RawConfigParser:
279 logger.verbose("For variant '%s', will try loading '%s'", variant, fname)
280 parser = self._construct_parser(fname)
282 for section in parser.sections():
283 items = parser.items(section)
284 self._config[variant].setdefault(fname, {})
285 self._config[variant][fname].update(self._normalized_keys(section, items))
287 return parser
289 def _construct_parser(self, fname: str) -> RawConfigParser:
290 parser = configparser.RawConfigParser()
291 # If there is no such file, don't bother reading it but create the
292 # parser anyway, to hold the data.
293 # Doing this is useful when modifying and saving files, where we don't
294 # need to construct a parser.
295 if os.path.exists(fname):
296 locale_encoding = locale.getpreferredencoding(False)
297 try:
298 parser.read(fname, encoding=locale_encoding)
299 except UnicodeDecodeError:
300 # See https://github.com/pypa/pip/issues/4963
301 raise ConfigurationFileCouldNotBeLoaded(
302 reason=f"contains invalid {locale_encoding} characters",
303 fname=fname,
304 )
305 except configparser.Error as error:
306 # See https://github.com/pypa/pip/issues/4893
307 raise ConfigurationFileCouldNotBeLoaded(error=error)
308 return parser
310 def _load_environment_vars(self) -> None:
311 """Loads configuration from environment variables"""
312 self._config[kinds.ENV_VAR].setdefault(":env:", {})
313 self._config[kinds.ENV_VAR][":env:"].update(
314 self._normalized_keys(":env:", self.get_environ_vars())
315 )
317 def _normalized_keys(
318 self, section: str, items: Iterable[tuple[str, Any]]
319 ) -> dict[str, Any]:
320 """Normalizes items to construct a dictionary with normalized keys.
322 This routine is where the names become keys and are made the same
323 regardless of source - configuration files or environment.
324 """
325 normalized = {}
326 for name, val in items:
327 key = section + "." + _normalize_name(name)
328 normalized[key] = val
329 return normalized
331 def get_environ_vars(self) -> Iterable[tuple[str, str]]:
332 """Returns a generator with all environmental vars with prefix PIP_"""
333 for key, val in os.environ.items():
334 if key.startswith("PIP_"):
335 name = key[4:].lower()
336 if name not in ENV_NAMES_IGNORED:
337 yield name, val
339 # XXX: This is patched in the tests.
340 def iter_config_files(self) -> Iterable[tuple[Kind, list[str]]]:
341 """Yields variant and configuration files associated with it.
343 This should be treated like items of a dictionary. The order
344 here doesn't affect what gets overridden. That is controlled
345 by OVERRIDE_ORDER. However this does control the order they are
346 displayed to the user. It's probably most ergonomic to display
347 things in the same order as OVERRIDE_ORDER
348 """
349 # SMELL: Move the conditions out of this function
351 env_config_file = os.environ.get("PIP_CONFIG_FILE", None)
352 config_files = get_configuration_files()
354 yield kinds.GLOBAL, config_files[kinds.GLOBAL]
356 # per-user config is not loaded when env_config_file exists
357 should_load_user_config = not self.isolated and not (
358 env_config_file and os.path.exists(env_config_file)
359 )
360 if should_load_user_config:
361 # The legacy config file is overridden by the new config file
362 yield kinds.USER, config_files[kinds.USER]
364 # virtualenv config
365 yield kinds.SITE, config_files[kinds.SITE]
367 if env_config_file is not None:
368 yield kinds.ENV, [env_config_file]
369 else:
370 yield kinds.ENV, []
372 def get_values_in_config(self, variant: Kind) -> dict[str, Any]:
373 """Get values present in a config file"""
374 return self._config[variant]
376 def _get_parser_to_modify(self) -> tuple[str, RawConfigParser]:
377 # Determine which parser to modify
378 assert self.load_only
379 parsers = self._parsers[self.load_only]
380 if not parsers:
381 # This should not happen if everything works correctly.
382 raise ConfigurationError(
383 "Fatal Internal error [id=2]. Please report as a bug."
384 )
386 # Use the highest priority parser.
387 return parsers[-1]
389 # XXX: This is patched in the tests.
390 def _mark_as_modified(self, fname: str, parser: RawConfigParser) -> None:
391 file_parser_tuple = (fname, parser)
392 if file_parser_tuple not in self._modified_parsers:
393 self._modified_parsers.append(file_parser_tuple)
395 def __repr__(self) -> str:
396 return f"{self.__class__.__name__}({self._dictionary!r})"