0
# ConfigParser
1

2
Updated configparser from stdlib for earlier Pythons with enhanced configuration file parsing capabilities. This backport provides the same interface as Python's standard library configparser module while offering enhanced features and maintaining compatibility across Python versions.
3

4
## Package Information
5

6
- **Package Name**: configparser
7
- **Language**: Python
8
- **Installation**: `pip install configparser`
9

10
## Core Imports
11

12
```python
13
from backports import configparser
14
```
15

16
Access specific classes:
17

18
```python
19
# All classes are accessed through the configparser module
20
config = configparser.ConfigParser()
21
raw_config = configparser.RawConfigParser()
22
```
23

24
## Basic Usage
25

26
```python
27
from backports import configparser
28

29
# Create a parser instance
30
config = configparser.ConfigParser()
31

32
# Read configuration from file
33
config.read('config.ini')
34

35
# Access sections and options
36
sections = config.sections()
37
options = config.options('section_name')
38

39
# Get values with type conversion
40
value = config.get('section_name', 'option_name')
41
number = config.getint('section_name', 'numeric_option')
42
flag = config.getboolean('section_name', 'boolean_option')
43

44
# Set values
45
config.add_section('new_section')
46
config.set('new_section', 'new_option', 'value')
47

48
# Write configuration to file
49
with open('output.ini', 'w') as f:
50
    config.write(f)
51

52
# Dictionary-style access
53
config['section']['option'] = 'new_value'
54
value = config['section']['option']
55
```
56

57
## Architecture
58

59
ConfigParser follows a hierarchical design:
60

61
- **ConfigParser**: Main parser class with interpolation support for %(name)s style substitutions
62
- **RawConfigParser**: Base parser without interpolation, suitable for configuration files with literal % symbols
63
- **SectionProxy**: Dictionary-like interface for accessing individual sections
64
- **Interpolation Classes**: Handle value substitution (BasicInterpolation, ExtendedInterpolation)
65

66
This design enables flexible configuration file handling with support for various formats, interpolation styles, and access patterns while maintaining backward compatibility with the standard library.
67

68
## Capabilities
69

70
### Parser Classes
71

72
Core configuration parser classes providing the main functionality for reading, writing, and manipulating configuration files.
73

74
```python { .api }
75
class ConfigParser(RawConfigParser): ...
76
class RawConfigParser(MutableMapping): ...
77
class SectionProxy(MutableMapping): ...
78
class ConverterMapping(MutableMapping): ...
79
```
80

81
[Parser Classes](./parser-classes.md)
82

83
### File Operations
84

85
Methods for reading configuration data from various sources (files, strings, dictionaries) and writing configuration data to files.
86

87
```python { .api }
88
def read(filenames, encoding=None): ...
89
def read_file(f, source=None): ...
90
def read_string(string, source='<string>'): ...
91
def read_dict(dictionary, source='<dict>'): ...
92
def write(fp, space_around_delimiters=True): ...
93
```
94

95
[File Operations](./file-operations.md)
96

97
### Section Management
98

99
Operations for managing configuration sections including creation, removal, and validation of sections.
100

101
```python { .api }
102
def sections(): ...
103
def add_section(section): ...
104
def remove_section(section): ...
105
def has_section(section): ...
106
```
107

108
[Section Management](./section-management.md)
109

110
### Option Access
111

112
Methods for accessing, setting, and managing configuration options with type conversion support.
113

114
```python { .api }
115
def get(section, option, *, raw=False, vars=None, fallback=_UNSET): ...
116
def getint(section, option, *, raw=False, vars=None, fallback=_UNSET, **kwargs): ...
117
def getfloat(section, option, *, raw=False, vars=None, fallback=_UNSET, **kwargs): ...
118
def getboolean(section, option, *, raw=False, vars=None, fallback=_UNSET, **kwargs): ...
119
def set(section, option, value=None): ...
120
def has_option(section, option): ...
121
```
122

123
[Option Access](./option-access.md)
124

125
### Interpolation
126

127
Value substitution capabilities allowing dynamic configuration values that reference other options within the same configuration.
128

129
```python { .api }
130
class Interpolation: ...
131
class BasicInterpolation(Interpolation): ...
132
class ExtendedInterpolation(Interpolation): ...
133
```
134

135
[Interpolation](./interpolation.md)
136

137
### Exception Handling
138

139
Complete exception hierarchy for handling various configuration parsing and access errors.
140

141
```python { .api }
142
class Error(Exception): ...
143
class NoSectionError(Error): ...
144
class DuplicateSectionError(Error): ...
145
class NoOptionError(Error): ...
146
class InterpolationError(Error): ...
147
class ParsingError(Error): ...
148
```
149

150
[Exception Handling](./exception-handling.md)
151

152
### Constants
153

154
Module-level constants used throughout the configparser library.
155

156
```python { .api }
157
DEFAULTSECT = "DEFAULT"
158
MAX_INTERPOLATION_DEPTH = 10
159
UNNAMED_SECTION = _UnnamedSection()
160
```
161

162
- **DEFAULTSECT**: Name of the default section that applies to all other sections
163
- **MAX_INTERPOLATION_DEPTH**: Maximum recursion depth for value interpolation  
164
- **UNNAMED_SECTION**: Special object representing the unnamed section when allow_unnamed_section=True