# pipes-compat

[![CI](https://github.com/Grochocinski/pipes-compat/actions/workflows/ci.yml/badge.svg)](https://github.com/Grochocinski/pipes-compat/actions/workflows/ci.yml)

Compatibility shim for Python's removed `pipes` module (Python 3.13+)

## Overview

The `pipes` module was deprecated in Python 3.11 and removed in Python 3.13 (PEP 594). This package provides a compatibility layer for code that still depends on the `pipes` module.

## Installation

```bash
pip install pipes-compat
```

## Usage

### Basic Usage

The most common use case is the `quote()` function for shell escaping:

```python
import pipes

# Shell-escape a string
escaped = pipes.quote("hello world")
print(escaped)  # 'hello world'
```

### Template Class

The `Template` class allows you to build and execute shell pipelines:

```python
import pipes

# Create a pipeline template
t = pipes.Template()

# Add commands to the pipeline
t.append('grep "error"', 'f')
t.append('sort', 'f')
t.append('uniq', 'f')

# Execute the pipeline
t.copy('input.txt', 'output.txt')

# Or use with stdin/stdout
t.copy('-', '-')  # stdin to stdout
t.copy('input.txt', '-')  # file to stdout
```

### Advanced Usage

```python
import pipes

t = pipes.Template()
t.append('tr "[:lower:]" "[:upper:]"', 'f')
t.append('head -n 10', 'f')

# Open a file through the pipeline
with t.open('input.txt', 'r') as f:
    content = f.read()

# Enable debugging
t.debug(True)
t.copy('input.txt', 'output.txt')  # Prints command to stderr
```

## API Reference

### `pipes.quote(s: str) -> str`

Return a shell-escaped version of the string `s`. This is a compatibility shim for `pipes.quote()`, using `shlex.quote()` internally.

### `pipes.Template`

A class for creating and executing shell pipelines.

#### Methods

- `append(cmd: str, kind: str) -> None`: Append a command to the end of the pipeline
- `prepend(cmd: str, kind: str) -> None`: Prepend a command to the beginning of the pipeline
- `reset() -> None`: Reset the template to its initial state
- `clone() -> Template`: Return a copy of the template
- `debug(flag: bool) -> None`: Enable or disable debugging output
- `open(file: str, mode: str) -> IO`: Open a file through the pipeline
- `copy(infile: str, outfile: str) -> None`: Copy a file through the pipeline

## Compatibility Notes

- This shim uses `subprocess` internally, which is the recommended replacement for `pipes`
- The implementation prioritizes compatibility over performance
- For new code, consider using `subprocess` directly instead of this compatibility shim
- Some edge cases in the original `pipes` module may behave slightly differently

## Requirements

- Python 3.13 or later

## Development

To set up the development environment:

```bash
# Install the package in development mode with dev dependencies
pip install -e ".[dev]"
```

To run the test suite:

```bash
pytest
```

To run tests with coverage:

```bash
pytest --cov=pipes --cov-report=html
```

To run linting with Ruff:

```bash
ruff check .
ruff format --check .
```

To auto-fix linting issues:

```bash
ruff check --fix .
ruff format .
```

## License

Apache-2.0

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.
