Configuration Class Reference

Public Member Functions
None	__init__ (self, bool isolated, Optional[Kind] load_only=None)
None	load (self)
Optional[str]	get_file_to_edit (self)
Iterable[Tuple[str, Any]]	items (self)
Any	get_value (self, str key)
None	set_value (self, str key, Any value)
None	unset_value (self, str key)
None	save (self)
Iterable[Tuple[str, str]]	get_environ_vars (self)
Iterable[Tuple[Kind, List[str]]]	iter_config_files (self)
Dict[str, Any]	get_values_in_config (self, Kind variant)
str	__repr__ (self)

Data Fields
	isolated
	load_only

Protected Member Functions
None	_ensure_have_load_only (self)
Dict[str, Any]	_dictionary (self)
None	_load_config_files (self)
RawConfigParser	_load_file (self, Kind variant, str fname)
RawConfigParser	_construct_parser (self, str fname)
None	_load_environment_vars (self)
Dict[str, Any]	_normalized_keys (self, str section, Iterable[Tuple[str, Any]] items)
Tuple[str, RawConfigParser]	_get_parser_to_modify (self)
None	_mark_as_modified (self, str fname, RawConfigParser parser)

Detailed Description

Handles management of configuration.

Provides an interface to accessing and managing configuration files.

This class converts provides an API that takes "section.key-name" style
keys and stores the value associated with it as "key-name" under the
section "section".

This allows for a clean interface wherein the both the section and the
key-name are preserved in an easy to manage form in the configuration files
and the data stored is also nice.

Definition at line 87 of file configuration.py.

Constructor & Destructor Documentation

__init__()

None __init__	(		self,
		bool	isolated,
		Optional[Kind]	load_only = None
	)

Definition at line 101 of file configuration.py.

    def __init__(self, isolated: bool, load_only: Optional[Kind] = None) -> None:
        super().__init__()
 
        if load_only is not None and load_only not in VALID_LOAD_ONLY:
            raise ConfigurationError(
                "Got invalid value for load_only - should be one of {}".format(
                    ", ".join(map(repr, VALID_LOAD_ONLY))
                )
            )
        self.isolated = isolated
        self.load_only = load_only
 
        # Because we keep track of where we got the data from
        self._parsers: Dict[Kind, List[Tuple[str, RawConfigParser]]] = {
            variant: [] for variant in OVERRIDE_ORDER
        }
        self._config: Dict[Kind, Dict[str, Any]] = {
            variant: {} for variant in OVERRIDE_ORDER
        }
        self._modified_parsers: List[Tuple[str, RawConfigParser]] = []
 

References Configuration.__init__(), and i.

Referenced by Configuration.__init__(), and Protocol.__init_subclass__().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

__repr__()

str __repr__

(

self

)

Definition at line 380 of file configuration.py.

    def __repr__(self) -> str:
        return f"{self.__class__.__name__}({self._dictionary!r})"

_construct_parser()

RawConfigParser _construct_parser (   self, str  fname  )

protected

Definition at line 277 of file configuration.py.

    def _construct_parser(self, fname: str) -> RawConfigParser:
        parser = configparser.RawConfigParser()
        # If there is no such file, don't bother reading it but create the
        # parser anyway, to hold the data.
        # Doing this is useful when modifying and saving files, where we don't
        # need to construct a parser.
        if os.path.exists(fname):
            locale_encoding = locale.getpreferredencoding(False)
            try:
                parser.read(fname, encoding=locale_encoding)
            except UnicodeDecodeError:
                # See https://github.com/pypa/pip/issues/4963
                raise ConfigurationFileCouldNotBeLoaded(
                    reason=f"contains invalid {locale_encoding} characters",
                    fname=fname,
                )
            except configparser.Error as error:
                # See https://github.com/pypa/pip/issues/4893
                raise ConfigurationFileCouldNotBeLoaded(error=error)
        return parser
 

References i.

Referenced by Configuration._load_file().

Here is the caller graph for this function:

_dictionary()

Dict[str, Any] _dictionary (   self )

protected

A dictionary representing the loaded configuration.

Definition at line 233 of file configuration.py.

    def _dictionary(self) -> Dict[str, Any]:
        """A dictionary representing the loaded configuration."""
        # NOTE: Dictionaries are not populated if not loaded. So, conditionals
        #       are not needed here.
        retval = {}
 
        for variant in OVERRIDE_ORDER:
            retval.update(self._config[variant])
 
        return retval
 

References i.

Referenced by Configuration.get_value(), and Configuration.items().

Here is the caller graph for this function:

_ensure_have_load_only()

None _ensure_have_load_only (   self )

protected

Definition at line 227 of file configuration.py.

    def _ensure_have_load_only(self) -> None:
        if self.load_only is None:
            raise ConfigurationError("Needed a specific file to be modifying.")
        logger.debug("Will be working with %s variant only", self.load_only)
 

References i, and Configuration.load_only.

Referenced by Configuration.save(), Configuration.set_value(), and Configuration.unset_value().

Here is the caller graph for this function:

_get_parser_to_modify()

Tuple[str, RawConfigParser] _get_parser_to_modify (   self )

protected

Definition at line 361 of file configuration.py.

    def _get_parser_to_modify(self) -> Tuple[str, RawConfigParser]:
        # Determine which parser to modify
        assert self.load_only
        parsers = self._parsers[self.load_only]
        if not parsers:
            # This should not happen if everything works correctly.
            raise ConfigurationError(
                "Fatal Internal error [id=2]. Please report as a bug."
            )
 
        # Use the highest priority parser.
        return parsers[-1]
 

References Configuration.load_only.

Referenced by Configuration.get_file_to_edit(), Configuration.set_value(), and Configuration.unset_value().

Here is the caller graph for this function:

_load_config_files()

None _load_config_files (   self )

protected

Loads configuration from configuration files

Definition at line 244 of file configuration.py.

    def _load_config_files(self) -> None:
        """Loads configuration from configuration files"""
        config_files = dict(self.iter_config_files())
        if config_files[kinds.ENV][0:1] == [os.devnull]:
            logger.debug(
                "Skipping loading configuration files due to "
                "environment's PIP_CONFIG_FILE being os.devnull"
            )
            return
 
        for variant, files in config_files.items():
            for fname in files:
                # If there's specific variant set in `load_only`, load only
                # that variant, not the others.
                if self.load_only is not None and variant != self.load_only:
                    logger.debug("Skipping file '%s' (variant: %s)", fname, variant)
                    continue
 
                parser = self._load_file(variant, fname)
 
                # Keeping track of the parsers used
                self._parsers[variant].append((fname, parser))
 

References Configuration._load_file(), i, Configuration.iter_config_files(), and Configuration.load_only.

Referenced by Configuration.load().

Here is the call graph for this function:

Here is the caller graph for this function:

_load_environment_vars()

None _load_environment_vars (   self )

protected

Loads configuration from environment variables

Definition at line 298 of file configuration.py.

    def _load_environment_vars(self) -> None:
        """Loads configuration from environment variables"""
        self._config[kinds.ENV_VAR].update(
            self._normalized_keys(":env:", self.get_environ_vars())
        )
 

References Configuration._normalized_keys(), Configuration.get_environ_vars(), and i.

Referenced by Configuration.load().

Here is the call graph for this function:

Here is the caller graph for this function:

_load_file()

RawConfigParser _load_file (   self, Kind  variant, str  fname  )

protected

Definition at line 267 of file configuration.py.

    def _load_file(self, variant: Kind, fname: str) -> RawConfigParser:
        logger.verbose("For variant '%s', will try loading '%s'", variant, fname)
        parser = self._construct_parser(fname)
 
        for section in parser.sections():
            items = parser.items(section)
            self._config[variant].update(self._normalized_keys(section, items))
 
        return parser
 

References Configuration._construct_parser(), Configuration._normalized_keys(), and i.

Referenced by Configuration._load_config_files().

Here is the call graph for this function:

Here is the caller graph for this function:

_mark_as_modified()

None _mark_as_modified (   self, str  fname, RawConfigParser  parser  )

protected

Definition at line 375 of file configuration.py.

    def _mark_as_modified(self, fname: str, parser: RawConfigParser) -> None:
        file_parser_tuple = (fname, parser)
        if file_parser_tuple not in self._modified_parsers:
            self._modified_parsers.append(file_parser_tuple)
 

Referenced by Configuration.set_value(), and Configuration.unset_value().

Here is the caller graph for this function:

_normalized_keys()

Dict[str, Any] _normalized_keys (   self, str  section, Iterable[Tuple[str, Any]]   items  )

protected

Normalizes items to construct a dictionary with normalized keys.

This routine is where the names become keys and are made the same
regardless of source - configuration files or environment.

Definition at line 304 of file configuration.py.

    ) -> Dict[str, Any]:
        """Normalizes items to construct a dictionary with normalized keys.
 
        This routine is where the names become keys and are made the same
        regardless of source - configuration files or environment.
        """
        normalized = {}
        for name, val in items:
            key = section + "." + _normalize_name(name)
            normalized[key] = val
        return normalized
 

References pip._internal.configuration._normalize_name().

Referenced by Configuration._load_environment_vars(), and Configuration._load_file().

Here is the call graph for this function:

Here is the caller graph for this function:

get_environ_vars()

Iterable[Tuple[str, str]] get_environ_vars

(

self

)

Returns a generator with all environmental vars with prefix PIP_

Definition at line 318 of file configuration.py.

    def get_environ_vars(self) -> Iterable[Tuple[str, str]]:
        """Returns a generator with all environmental vars with prefix PIP_"""
        for key, val in os.environ.items():
            if key.startswith("PIP_"):
                name = key[4:].lower()
                if name not in ENV_NAMES_IGNORED:
                    yield name, val
 

References i.

Referenced by Configuration._load_environment_vars().

Here is the caller graph for this function:

get_file_to_edit()

Optional[str] get_file_to_edit

(

self

)

Returns the file with highest priority in configuration

Definition at line 128 of file configuration.py.

    def get_file_to_edit(self) -> Optional[str]:
        """Returns the file with highest priority in configuration"""
        assert self.load_only is not None, "Need to be specified a file to be editing"
 
        try:
            return self._get_parser_to_modify()[0]
        except IndexError:
            return None
 

References Configuration._get_parser_to_modify(), and Configuration.load_only.

Here is the call graph for this function:

get_value()

Any get_value	(		self,
		str	key
	)

Get a value from the configuration.

Definition at line 143 of file configuration.py.

    def get_value(self, key: str) -> Any:
        """Get a value from the configuration."""
        orig_key = key
        key = _normalize_name(key)
        try:
            return self._dictionary[key]
        except KeyError:
            # disassembling triggers a more useful error message than simply
            # "No such key" in the case that the key isn't in the form command.option
            _disassemble_key(key)
            raise ConfigurationError(f"No such key - {orig_key}")
 

References Configuration._dictionary(), pip._internal.configuration._disassemble_key(), and pip._internal.configuration._normalize_name().

Here is the call graph for this function:

get_values_in_config()

Dict[str, Any] get_values_in_config	(		self,
		Kind	variant
	)

Get values present in a config file

Definition at line 357 of file configuration.py.

    def get_values_in_config(self, variant: Kind) -> Dict[str, Any]:
        """Get values present in a config file"""
        return self._config[variant]
 

items()

Iterable[Tuple[str, Any]] items

(

self

)

Returns key-value pairs like dict.items() representing the loaded
configuration

Definition at line 137 of file configuration.py.

    def items(self) -> Iterable[Tuple[str, Any]]:
        """Returns key-value pairs like dict.items() representing the loaded
        configuration
        """
        return self._dictionary.items()
 

References Configuration._dictionary(), and Configuration.items().

Referenced by OrderedDict.__eq__(), CaseInsensitiveDict.__repr__(), OrderedDict.__repr__(), ParseResults.as_dict(), ParseResults.dump(), and Configuration.items().

Here is the call graph for this function:

Here is the caller graph for this function:

iter_config_files()

Iterable[Tuple[Kind, List[str]]] iter_config_files

(

self

)

Yields variant and configuration files associated with it.

This should be treated like items of a dictionary.

Definition at line 327 of file configuration.py.

    def iter_config_files(self) -> Iterable[Tuple[Kind, List[str]]]:
        """Yields variant and configuration files associated with it.
 
        This should be treated like items of a dictionary.
        """
        # SMELL: Move the conditions out of this function
 
        # environment variables have the lowest priority
        config_file = os.environ.get("PIP_CONFIG_FILE", None)
        if config_file is not None:
            yield kinds.ENV, [config_file]
        else:
            yield kinds.ENV, []
 
        config_files = get_configuration_files()
 
        # at the base we have any global configuration
        yield kinds.GLOBAL, config_files[kinds.GLOBAL]
 
        # per-user configuration next
        should_load_user_config = not self.isolated and not (
            config_file and os.path.exists(config_file)
        )
        if should_load_user_config:
            # The legacy config file is overridden by the new config file
            yield kinds.USER, config_files[kinds.USER]
 
        # finally virtualenv configuration first trumping others
        yield kinds.SITE, config_files[kinds.SITE]
 

References pip._internal.configuration.get_configuration_files(), i, Configuration.isolated, and InstallRequirement.isolated.

Referenced by Configuration._load_config_files().

Here is the call graph for this function:

Here is the caller graph for this function:

load()

None load

(

self

)

Loads configuration from configuration files and environment

Definition at line 122 of file configuration.py.

    def load(self) -> None:
        """Loads configuration from configuration files and environment"""
        self._load_config_files()
        if not self.isolated:
            self._load_environment_vars()
 

References Configuration._load_config_files(), Configuration._load_environment_vars(), Configuration.isolated, and InstallRequirement.isolated.

Here is the call graph for this function:

save()

None save

(

self

)

Save the current in-memory state.

Definition at line 203 of file configuration.py.

    def save(self) -> None:
        """Save the current in-memory state."""
        self._ensure_have_load_only()
 
        for fname, parser in self._modified_parsers:
            logger.info("Writing to %s", fname)
 
            # Ensure directory exists.
            ensure_dir(os.path.dirname(fname))
 
            # Ensure directory's permission(need to be writeable)
            try:
                with open(fname, "w") as f:
                    parser.write(f)
            except OSError as error:
                raise ConfigurationError(
                    f"An error occurred while writing to the configuration file "
                    f"{fname}: {error}"
                )
 

References Configuration._ensure_have_load_only(), and i.

Referenced by pyparsing_test.reset_pyparsing_context.__enter__().

Here is the call graph for this function:

Here is the caller graph for this function:

set_value()

None set_value	(		self,
		str	key,
		Any	value
	)

Modify a value in the configuration.

Definition at line 155 of file configuration.py.

    def set_value(self, key: str, value: Any) -> None:
        """Modify a value in the configuration."""
        key = _normalize_name(key)
        self._ensure_have_load_only()
 
        assert self.load_only
        fname, parser = self._get_parser_to_modify()
 
        if parser is not None:
            section, name = _disassemble_key(key)
 
            # Modify the parser and the configuration
            if not parser.has_section(section):
                parser.add_section(section)
            parser.set(section, name, value)
 
        self._config[self.load_only][key] = value
        self._mark_as_modified(fname, parser)
 

References pip._internal.configuration._disassemble_key(), Configuration._ensure_have_load_only(), Configuration._get_parser_to_modify(), Configuration._mark_as_modified(), pip._internal.configuration._normalize_name(), i, and Configuration.load_only.

Here is the call graph for this function:

unset_value()

None unset_value	(		self,
		str	key
	)

Unset a value in the configuration.

Definition at line 174 of file configuration.py.

    def unset_value(self, key: str) -> None:
        """Unset a value in the configuration."""
        orig_key = key
        key = _normalize_name(key)
        self._ensure_have_load_only()
 
        assert self.load_only
        if key not in self._config[self.load_only]:
            raise ConfigurationError(f"No such key - {orig_key}")
 
        fname, parser = self._get_parser_to_modify()
 
        if parser is not None:
            section, name = _disassemble_key(key)
            if not (
                parser.has_section(section) and parser.remove_option(section, name)
            ):
                # The option was not removed.
                raise ConfigurationError(
                    "Fatal Internal error [id=1]. Please report as a bug."
                )
 
            # The section may be empty after the option was removed.
            if not parser.items(section):
                parser.remove_section(section)
            self._mark_as_modified(fname, parser)
 
        del self._config[self.load_only][key]
 

References pip._internal.configuration._disassemble_key(), Configuration._ensure_have_load_only(), Configuration._get_parser_to_modify(), Configuration._mark_as_modified(), pip._internal.configuration._normalize_name(), i, and Configuration.load_only.

Here is the call graph for this function:

Field Documentation

isolated

isolated

Definition at line 110 of file configuration.py.

Referenced by InstallRequirement.install(), Configuration.iter_config_files(), and Configuration.load().

load_only

load_only

Definition at line 111 of file configuration.py.

Referenced by Configuration._ensure_have_load_only(), Configuration._get_parser_to_modify(), Configuration._load_config_files(), Configuration.get_file_to_edit(), Configuration.set_value(), and Configuration.unset_value().

---

The documentation for this class was generated from the following file:

• /home/liwuen/projects_dev/pqc-engineering-ssec-23/venv/lib/python3.12/site-packages/pip/_internal/configuration.py