Metadata-Version: 2.5
Name: ej
Version: 0.0.5
Summary: String generation
Project-URL: Homepage, https://github.com/t-c-w/ej
Project-URL: Repository, https://github.com/t-c-w/ej
Author: t-c-w
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: formatting,parsing,string,string-generation,templates
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# ej
String generation

To install:	```pip install ej```

## Overview
The `ej` package provides advanced string formatting capabilities that extend Python's built-in string formatting methods. It includes functionality for partial and incremental formatting, transforming format strings, and applying transformation pipelines directly within format specifications.

## Features
- **Partial Formatting**: Allows string templates to be formatted even when not all placeholders are provided values. Unprovided fields remain as placeholders in the output.
- **Incremental Formatting**: Supports formatting strings in multiple passes, which is useful for configurations or templates where some values depend on others.
- **Format String Transformation**: Functions to transform format strings by auto-generating field names or converting them to use automatic field numbering.
- **Pipeline Formatting**: A powerful feature where values can be processed through a series of functions directly specified in the format string.

## Usage Examples

### Partial Formatting
You can use `PartialFormatter` to handle cases where not all template fields are provided. It's useful for building strings step-by-step in applications such as configuration files or complex outputs where some values are optional:

```python
from ej import partial_formatter

template = "Hello, {name}! Your balance is {balance}."
formatted = partial_formatter.format(template, name="Alice")
print(formatted)  # Output: "Hello, Alice! Your balance is {balance}."
```

### Incremental Formatting
This feature allows for strings to be formatted in stages, which is useful when some values depend on others:

```python
from ej import format_str_vals_of_dict

data = {
    'path': '{base_path}/images/{image_id}.jpg',
    'base_path': '/user/data',
    'image_id': '12345'
}
formatted_data = format_str_vals_of_dict(data)
print(formatted_data['path'])  # Output: '/user/data/images/12345.jpg'
```

### Transforming Format Strings
Convert a format string to use automatic field numbering or name fields explicitly:

```python
from ej import auto_field_format_str, name_fields_in_format_str

format_str = "User: {0}, ID: {1}"
auto_format = auto_field_format_str(format_str)
print(auto_format)  # Output: "User: {}, ID: {}"

named_format = name_fields_in_format_str("Hello, {0}!", ["name"])
print(named_format)  # Output: "Hello, {name}!"
```

### Pipeline Formatting
Apply a series of transformations to a value directly within the format string:

```python
from ej import PipelineTemplate

pipeline = PipelineTemplate(
    double=lambda x: x * 2,
    increment=lambda x: x + 1
)
result = pipeline.format("{value:double|increment}", value=3)
print(result)  # Output: '7'
```

## Documentation

### Classes and Functions

- **`PartialFormatter`**: A formatter that allows partial formatting of strings.
- **`format_str_vals_of_dict`**: Formats the string values of a dictionary, handling nested formatting needs.
- **`compile_str_from_parsed`**: Reconstructs a format string from parsed components.
- **`transform_format_str`**: Transforms a format string using a specified transformation function.
- **`match_format_string`**: Matches a string against a format string and extracts values.
- **`PipelineTemplate`**: A formatter that applies a sequence of transformations to format string fields.

These utilities make the `ej` package a robust tool for handling complex string formatting scenarios in Python applications.