0
# Braceexpand
1

2
Bash-style brace expansion for Python, implementing the same brace expansion logic found in bash(1) with some limitations. This package enables pattern expansion with braces into multiple strings, supporting integer ranges, character ranges, sequences, nested patterns, and various formatting options.
3

4
## Package Information
5

6
- **Package Name**: braceexpand
7
- **Language**: Python
8
- **Installation**: `pip install braceexpand`
9
- **Version**: 0.1.7
10
- **License**: MIT
11
- **Python Compatibility**: 2.7, 3.6+
12

13
## Core Imports
14

15
```python
16
from braceexpand import braceexpand
17
```
18

19
Import the exception class for error handling:
20

21
```python
22
from braceexpand import UnbalancedBracesError
23
```
24

25
Import the alphabet constant:
26

27
```python
28
from braceexpand import alphabet
29
```
30

31
Import all public components:
32

33
```python
34
from braceexpand import braceexpand, UnbalancedBracesError, alphabet
35
```
36

37
## Basic Usage
38

39
```python
40
from braceexpand import braceexpand
41

42
# Integer range expansion
43
result = list(braceexpand('item{1..3}'))
44
# ['item1', 'item2', 'item3']
45

46
# Character range expansion
47
result = list(braceexpand('{a..c}'))
48
# ['a', 'b', 'c']
49

50
# Sequence expansion
51
result = list(braceexpand('index.html{,.backup}'))
52
# ['index.html', 'index.html.backup']
53

54
# Nested patterns
55
result = list(braceexpand('python{2.{5..7},3.{2,3}}'))
56
# ['python2.5', 'python2.6', 'python2.7', 'python3.2', 'python3.3']
57
```
58

59
## Capabilities
60

61
### Brace Expansion
62

63
Performs bash-style brace expansion on pattern strings, returning an iterator over all expanded strings.
64

65
```python { .api }
66
def braceexpand(pattern, escape=True):
67
    """
68
    Expand braces in a pattern string according to bash(1) rules.
69
    
70
    Parameters:
71
    - pattern (str): Pattern string containing braces to expand
72
    - escape (bool): Whether to interpret backslash as escape character (default: True)
73
    
74
    Returns:
75
    Iterator over strings resulting from brace expansion
76
    
77
    Raises:
78
    UnbalancedBracesError: When pattern contains unbalanced braces
79
    """
80
```
81

82
**Supported Pattern Types:**
83

84
- **Integer ranges**: `{1..3}` expands to `['1', '2', '3']`
85
- **Character ranges**: `{a..c}` expands to `['a', 'b', 'c']`
86
- **Sequences**: `{x,y,z}` expands to `['x', 'y', 'z']`
87
- **Nested patterns**: `{a,{b,c}}` expands to `['a', 'b', 'c']`
88
- **Zero-padded numbers**: `{07..10}` expands to `['07', '08', '09', '10']`
89
- **Custom increments**: `{1..7..2}` expands to `['1', '3', '5', '7']`
90
- **Bidirectional ranges**: `{4..1}` expands to `['4', '3', '2', '1']`
91
- **Negative numbers**: `{2..-1}` expands to `['2', '1', '0', '-1']`
92

93
**Escape Character Handling:**
94

95
When `escape=True` (default), backslashes can be used to escape special characters:
96

97
```python
98
# Escape braces to include them literally
99
result = list(braceexpand(r'{1\{2,3}'))
100
# ['1{2', '3']
101

102
# Double backslash for literal backslash
103
result = list(braceexpand(r'\\{1,2}'))
104
# ['\\1', '\\2']
105
```
106

107
When `escape=False`, backslashes have no special meaning:
108

109
```python
110
result = list(braceexpand(r'\{1,2}', escape=False))
111
# ['\\1', '\\2']
112
```
113

114
### Error Handling
115

116
Exception class for unbalanced brace patterns.
117

118
```python { .api }
119
class UnbalancedBracesError(ValueError):
120
    """
121
    Raised when a pattern contains unbalanced braces.
122
    
123
    This exception is raised by braceexpand() when the pattern
124
    string contains opening braces without matching closing braces,
125
    or vice versa.
126
    """
127
```
128

129
**Usage example:**
130

131
```python
132
from braceexpand import braceexpand, UnbalancedBracesError
133

134
try:
135
    result = list(braceexpand('{1{2,3}'))  # Missing closing brace
136
except UnbalancedBracesError as e:
137
    print(f"Error: {e}")
138
    # Error: Unbalanced braces: '{1{2,3}'
139
```
140

141
### Character Alphabet
142

143
Constant containing the alphabet string used for character range expansion.
144

145
```python { .api }
146
alphabet: str
147
```
148

149
The alphabet constant contains all uppercase and lowercase ASCII letters (`'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'`), used internally for character range operations like `{a..c}` or `{A..Z}`.
150

151
## Types
152

153
```python { .api }
154
from typing import Iterator
155

156
# Type definitions for the public API
157

158
UnbalancedBracesError = ValueError
159
# Exception raised for unbalanced brace patterns
160

161
alphabet: str
162
# String constant containing A-Z and a-z characters
163

164
def braceexpand(pattern: str, escape: bool = True) -> Iterator[str]:
165
    # Returns iterator over expanded strings
166
```
167

168
## Limitations
169

170
This implementation has some differences from bash brace expansion:
171

172
1. **Unbalanced braces**: Patterns with unbalanced braces raise `UnbalancedBracesError`. In bash, these are either partly expanded or ignored.
173

174
2. **Mixed-case character ranges**: Ranges like `{Z..a}` or `{a..Z}` will not include the characters `[]^_\`` that fall between `Z` and `a` in ASCII order.
175

176
## Common Use Cases
177

178
```python
179
from braceexpand import braceexpand
180

181
# Generate file paths
182
paths = list(braceexpand('/path/to/{file1,file2,file3}.txt'))
183
# ['/path/to/file1.txt', '/path/to/file2.txt', '/path/to/file3.txt']
184

185
# Generate numbered sequences
186
files = list(braceexpand('backup-{001..005}.sql'))
187
# ['backup-001.sql', 'backup-002.sql', 'backup-003.sql', 'backup-004.sql', 'backup-005.sql']
188

189
# Generate test data
190
coordinates = list(braceexpand('{x,y,z}{1..3}'))
191
# ['x1', 'x2', 'x3', 'y1', 'y2', 'y3', 'z1', 'z2', 'z3']
192

193
# Command line argument expansion
194
args = list(braceexpand('--{verbose,debug,quiet}'))
195
# ['--verbose', '--debug', '--quiet']
196
```