Bracex

https://facelessuser.github.io/bracex/
Admin
Bracex is a brace expanding library (à la Bash) for Python used to generate arbitrary strings,...
Tokens:3,641
Snippets:71
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Bracex Package

Source: https://facelessuser.github.io/bracex

Command to install the bracex library using pip.

```bash
$ pip install bracex
```

--------------------------------

### Bash Brace Expansion Example

Source: https://facelessuser.github.io/bracex

Demonstrates basic brace expansion in Bash.

```bash
$ echo {{a,b},c}d
ad bd cd
```

--------------------------------

### Bracex Command Line Usage

Source: https://facelessuser.github.io/bracex

Example of using Bracex from the command line to create directories.

```bash
$ python3 -m bracex -0 "base/{a,b}/{1..2}" | xargs -0 mkdir -p
$ tree base/
base/
├── a
│   ├── 1
│   └── 2
└── b
    ├── 1
    └── 2
```

--------------------------------

### Bracex Empty Expansion Example

Source: https://facelessuser.github.io/bracex

Illustrates handling of empty expansions with bracex.expand().

```python
>>> bracex.expand(r'-v{,,}')
['-v', '-v', '-v']
```

--------------------------------

### Build Documentation with Zensical

Source: https://facelessuser.github.io/bracex/about/development

Clean and build project documentation before spell checking. Requires Aspell to be installed and in the system path.

```bash
zensical build --clean -f zensical.yml

```

--------------------------------

### Install Tox

Source: https://facelessuser.github.io/bracex/about/development

Install the Tox automation tool, which is used for running validation tests, spelling checks, and linting in isolated virtual environments.

```bash
pip install tox

```

--------------------------------

### Serve Documentation with Zensical

Source: https://facelessuser.github.io/bracex/about/development

Build and preview documentation locally. The browser will update live as documents are changed.

```bash
zensical serve -f zensical.yml

```

--------------------------------

### Run Document Building with Tox

Source: https://facelessuser.github.io/bracex/about/development

Execute the document building and spell checking environment using Tox.

```bash
tox -e documents

```

--------------------------------

### Python Bracex Basic Expansion

Source: https://facelessuser.github.io/bracex

Shows how to use the bracex.expand() function for basic brace expansion in Python.

```python
>>> bracex.expand(r'file-{1,2,3}.txt')
['file-1.txt', 'file-2.txt', 'file-3.txt']
```

--------------------------------

### Bracex Command Line Help

Source: https://facelessuser.github.io/bracex

Displays the help message for the Bracex command-line interface.

```bash
$ python3 -m bracex --help
usage: python -mbracex [-h] [--terminator STR | -0] [--version] expression

Expands a bash-style brace expression, and outputs each expansion.

positional arguments:
  expression            Brace expression to expand

optional arguments:
  -h, --help            show this help message and exit
  --terminator STR, -t STR
                        Terminate each expansion with string STR (default: \n)
  -0                    Terminate each expansion with a NUL character
  --version             show program's version number and exit
```

--------------------------------

### Bracex Numerical Sequence with Step

Source: https://facelessuser.github.io/bracex

Demonstrates expanding a numerical sequence with a step using bracex.expand().

```python
>>> bracex.expand(r'file{0..6..2}.txt')
['file0.txt', 'file2.txt', 'file4.txt', 'file6.txt']
```

--------------------------------

### Run Linting with Tox

Source: https://facelessuser.github.io/bracex/about/development

Execute the linting environment using Tox to check code for style and quality issues.

```bash
tox -e lint

```

--------------------------------

### Bracex Alphabetic Sequence with Step

Source: https://facelessuser.github.io/bracex

Demonstrates expanding an alphabetical sequence with a step using bracex.expand().

```python
>>> bracex.expand(r'file{A..G..2}.txt')
['fileA.txt', 'fileC.txt', 'fileE.txt', 'fileG.txt']
```

--------------------------------

### Bracex Nested Brace Expansion

Source: https://facelessuser.github.io/bracex

Demonstrates expanding nested braces using bracex.expand().

```python
>>> bracex.expand(r'file-{{a,b},c}d.txt')
['file-ad.txt', 'file-bd.txt', 'file-cd.txt']
```

--------------------------------

### Bracex Zero-Padded Numerical Sequence

Source: https://facelessuser.github.io/bracex

Illustrates expanding zero-padded numerical sequences with bracex.expand().

```python
>>> bracex.expand(r'file{00..10..5}.jpg')
['file00.jpg', 'file05.jpg', 'file10.jpg']
```

--------------------------------

### iexpand()

Source: https://facelessuser.github.io/bracex

Similar to `expand()`, but returns a generator instead of a list. This is useful for handling very large numbers of expansions efficiently.

```APIDOC
## iexpand()

### Description
Returns a generator that yields expanded strings one by one. This is memory-efficient for large expansion sets. It accepts the same parameters as `expand()`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **string** (string) - Required - The string containing brace expressions to expand.
- **keep_escapes** (bool) - Optional - If True, escape characters are preserved in the output strings. Defaults to False.
- **limit** (int) - Optional - The maximum number of expansions to generate. Set to 0 to remove the limit. Defaults to 1000.

### Request Example
```python
import bracex

for expansion in bracex.iexpand(r'item-{a,b,c}'):
    print(expansion)
# Output:
# item-a
# item-b
# item-c
```

### Response
#### Success Response (200)
- **generator** (generator) - A generator yielding expanded strings.

#### Response Example
(Output is yielded iteratively, not a single JSON response)
```

--------------------------------

### Run All Tox Environments

Source: https://facelessuser.github.io/bracex/about/development

Execute all defined test environments using Tox. This will create and run tests in virtual environments for specified Python versions.

```bash
tox

```

--------------------------------

### Bracex Numerical Sequence Expansion

Source: https://facelessuser.github.io/bracex

Shows expanding a simple numerical sequence with bracex.expand().

```python
>>> bracex.expand(r'file{0..3}.txt')
['file0.txt', 'file1.txt', 'file2.txt', 'file3.txt']
```

--------------------------------

### Perform Spell Check

Source: https://facelessuser.github.io/bracex/about/development

Initiate spell checking for project documents after building them. Misspelled words will be reported.

```bash
pyspelling

```

--------------------------------

### Bracex Escaped Brace Expansion with keep_escapes

Source: https://facelessuser.github.io/bracex

Demonstrates using `keep_escapes=True` to retain backslashes during expansion.

```python
>>> bracex.expand(r'file\{00..10..5}.jpg', keep_escapes=True)
['file\\{00..10..5}.jpg']
```

--------------------------------

### expand()

Source: https://facelessuser.github.io/bracex

Expands a given string with brace expressions into a list of strings. It supports various expansion types like sequences, nested braces, and alphabetic ranges. Escapes can be optionally kept, and the expansion size can be limited.

```APIDOC
## expand()

### Description
Accepts a string and returns a list of expanded strings. If all expansions are empty, an empty list is returned by default. The `keep_escapes` parameter controls whether escape characters are processed or preserved. An optional `limit` parameter restricts the number of generated expansions.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **string** (string) - Required - The string containing brace expressions to expand.
- **keep_escapes** (bool) - Optional - If True, escape characters are preserved in the output strings. Defaults to False.
- **limit** (int) - Optional - The maximum number of expansions to generate. Set to 0 to remove the limit. Defaults to 1000.

### Request Example
```python
import bracex

result = bracex.expand(r'file-{1,2,3}.txt')
print(result)
# Output: ['file-1.txt', 'file-2.txt', 'file-3.txt']

result_escaped = bracex.expand(r'file\{a,b}.txt', keep_escapes=True)
print(result_escaped)
# Output: ['file\\{a,b}.txt']
```

### Response
#### Success Response (200)
- **list** (list[string]) - A list of strings, where each string is an expansion of the input.

#### Response Example
```json
["file-1.txt", "file-2.txt", "file-3.txt"]
```
```

--------------------------------

### Bracex Unsupported Expansion Type

Source: https://facelessuser.github.io/bracex

Illustrates that Bracex does not expand `${...}` syntax.

```python
>>> bracex.expand(r'file${a,b,c}.jpg')
['file${a,b,c}.jpg']
```

--------------------------------

### Bracex Alphabetic Sequence Expansion

Source: https://facelessuser.github.io/bracex

Shows expanding an alphabetical sequence using bracex.expand().

```python
>>> bracex.expand(r'file{A..D}.txt')
['fileA.txt', 'fileB.txt', 'fileC.txt', 'fileD.txt']
```

--------------------------------

### Bracex Escaped Brace Expansion

Source: https://facelessuser.github.io/bracex

Shows how Bracex handles escaped braces, preventing expansion.

```python
>>> bracex.expand(r'file\{00..10..5}.jpg')
['file{00..10..5}.jpg']
```

--------------------------------

### Run Specific Tox Environment

Source: https://facelessuser.github.io/bracex/about/development

Target a specific Python version environment for testing with Tox, e.g., Python 3.7.

```bash
tox -e py37

```

--------------------------------

### Bracex expand() Function Signature

Source: https://facelessuser.github.io/bracex

Defines the signature of the `expand` function in Bracex.

```python
def expand(string, keep_escapes=False, limit=1000):
```

--------------------------------

### Run Validation Tests

Source: https://facelessuser.github.io/bracex/about/development

Execute the project's test suite using Pytest to ensure code health.

```bash
py.test

```

--------------------------------

### Bracex iexpand() Function Signature

Source: https://facelessuser.github.io/bracex

Defines the signature of the `iexpand` function in Bracex, which returns a generator.

```python
def iexpand(string, keep_escapes=False, limit=1000):
```

--------------------------------

### Erase Coverage Data

Source: https://facelessuser.github.io/bracex/about/development

Clear existing code coverage data before running tests to generate fresh coverage reports.

```bash
coverage erase

```
Tokens:
Raw