mirror of https://github.com/pypa/pip
WIP: Add initial draft of configuration deep dive
This commit is contained in:
parent
98b3221fd4
commit
a83ea610d2
|
@ -0,0 +1,89 @@
|
|||
===========================
|
||||
Configuration File Handling
|
||||
===========================
|
||||
|
||||
The ``pip._internal.configuration`` module is responsible for handling
|
||||
configuration files (eg. loading from and saving values to) that are used by
|
||||
pip. The module's functionality is largely exposed through and coordinated by
|
||||
the module's ``Configuration`` class.
|
||||
|
||||
.. note::
|
||||
|
||||
This section of the documentation is currently being written. pip
|
||||
developers welcome your help to complete this documentation. If you're
|
||||
interested in helping out, please let us know in the
|
||||
`tracking issue <https://github.com/pypa/pip/issues/6831>`_.
|
||||
|
||||
|
||||
.. _configuration-overview:
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
TODO: Figure out how to structure the initial part of this document.
|
||||
|
||||
Loading
|
||||
-------
|
||||
|
||||
#. Determine configuration files to be used (built on top of :pypi:`appdirs`).
|
||||
#. Load from all the configuration files.
|
||||
#. For each file, construct a ``RawConfigParser`` instance and read the
|
||||
file with it. Store the filename and parser for accessing / manipulating
|
||||
the file's contents later.
|
||||
#. Load values stored in ``PIP_*`` environment variables.
|
||||
|
||||
The precedence of the various "configuration sources" is determined by
|
||||
``Configuration._override_order``, and the precedence-respecting values are
|
||||
lazily computed when values are accessed by a callee.
|
||||
|
||||
Saving
|
||||
------
|
||||
|
||||
Once the configuration is loaded, it is saved by iterating through all the
|
||||
"modified parser" pairs (filename and associated parser, that were modified
|
||||
in-memory after the initial load), and writing the state of the parser to file.
|
||||
|
||||
-----
|
||||
|
||||
The remainder of this section is organized by documenting some of the
|
||||
implementation details of the ``configuration`` module, in the following order:
|
||||
|
||||
* the :ref:`kinds <config-kinds>` enum,
|
||||
* the :ref:`Configuration <configuration-class>` class,
|
||||
|
||||
|
||||
.. _config-kinds:
|
||||
|
||||
kinds
|
||||
=====
|
||||
|
||||
- used to represent "where" a configuration value comes from
|
||||
(eg. environment variables, site-specific configuration file,
|
||||
global configuration file)
|
||||
|
||||
.. _configuration-class:
|
||||
|
||||
Configuration
|
||||
============
|
||||
|
||||
- TODO: API & usage - ``Command``, when processing CLI options.
|
||||
- __init__()
|
||||
- load()
|
||||
- items()
|
||||
- TODO: API & usage - ``pip config``, when loading / manipulating config files.
|
||||
- __init__()
|
||||
- get_file_to_edit()
|
||||
- get_value()
|
||||
- set_value()
|
||||
- unset_value()
|
||||
- save()
|
||||
- TODO: nuances of ``load_only`` and ``get_file_to_edit``
|
||||
- TODO: nuances of ``isolated``
|
||||
|
||||
Future Refactoring Ideas
|
||||
========================
|
||||
|
||||
* Break up the ``Configuration`` class into 2 smaller classes, by use case
|
||||
* ``Command`` use-case (read only) -- ``ConfigurationReader``
|
||||
* ``pip config`` use-case (read / write) -- ``ConfigurationModifier`` (inherit from ``ConfigurationReader``)
|
||||
* Eagerly populate ``Configuration._dictionary`` on load.
|
|
@ -20,6 +20,7 @@ Architecture of pip's internals
|
|||
|
||||
overview
|
||||
anatomy
|
||||
configuration-files
|
||||
package-finding
|
||||
upgrade-options
|
||||
|
||||
|
|
Loading…
Reference in New Issue