Metadata-Version: 2.4
Name: envsub
Version: 0.2.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Typing :: Typed
Requires-Dist: furo>=2024.5.6 ; extra == 'docs'
Requires-Dist: linkify-it-py>=2.0.3,<3 ; extra == 'docs'
Requires-Dist: myst-parser>=3.0.0,<4 ; python_full_version < '3.10' and extra == 'docs'
Requires-Dist: myst-parser>=4.0.0,<5 ; python_full_version >= '3.10' and extra == 'docs'
Requires-Dist: sphinx>=7.0.1,<8 ; extra == 'docs'
Requires-Dist: sphinx-autodoc2>=0.5.0,<1 ; extra == 'docs'
Provides-Extra: docs
License-File: LICENSE
Summary: A text preprocessing tool with environment variable substitution.
Keywords: environment,substitution,variables
Author: Guillaume Gauvrit <guillaume@gauvr.it>
Author-email: Guillaume Gauvrit <guillaume@gauvr.it>
License: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://mardiros.github.io/envsub/
Project-URL: Documentation, https://mardiros.github.io/mardiros/envsub
Project-URL: Repository, https://github.com/mardiros/envsub.git
Project-URL: Issues, https://github.com/mardiros/envsub/issues
Project-URL: Changelog, https://mardiros.github.io/mardiros/envsub/changelog.html

# envsub

[![Documentation](https://github.com/mardiros/envsub/actions/workflows/publish-doc.yml/badge.svg)](https://mardiros.github.io/envsub/)
[![Continuous Integration](https://github.com/mardiros/envsub/actions/workflows/tests.yml/badge.svg)](https://github.com/mardiros/envsub/actions/workflows/tests.yml)
[![Maintainability](https://api.codeclimate.com/v1/badges/a63ad49239e41de4f6b7/maintainability)](https://codeclimate.com/github/mardiros/envsub/maintainability)

**envsub** is a text preprocessing tool that performs environment variable
substitution in files, with support for default values. Written in Rust and
callable from Python, it provides a fast and reliable way to inject environment
variables into text files during runtime.

## Features

- Environment variable substitution in any text file.
- Support for default values when environment variables are missing.
- Fast performance with Rust under the hood, accessible from Python.

## Installation

```bash
pip install envsub
```


## Usage


### envsub api

envsub comes with a `sub` method that text a `io.TextIO` and return
a `io.TextIO` containing the replaced variable.

Basic usage:

```python
from envsub import sub


with open("/path/to/file", "r") as downstream:
    with sub(downstream) as upstream:
        upstream.read()

```


When it is usefull.

``envsub`` is made for replacing a set of variable inside a configuration
file from envisonment variable, its feet well with confifuration file format.

Example with json:


```python
import json
from envsub import sub

with open("/path/to/file.json", "r") as downstream:
    with sub(downstream) as upstream:
        data = json.load(upstream)

```


### Substitution format

envsubst subsitute variable format that are curly-braced, like in bash.

```json
{"hello": "${NAME}"}
```

> ⚠️ **Warning:**
>
> The variable stay in the same line, no `\n` are permitted.**
>
> This will **not** work:
> {"hello": "${
>      NAME
>    }"
> }
>


#### Default value:

If the environment variable is not present, no substitution will be made,
it means than in the previous example, `${NAME}` will stay in the read value.

Alternatively, a default value can be set in the variable, using a `-` value.


```json
{"hello": "${NAME-world}"}
```

In this case the final result will be `{"hello": "world"}`.



## Alternatives

Similar tools exists, but did not find any good one in python.

The envsub lib has been created to replace non existing tool like
[a8m/envsubst](https://github.com/a8m/envsubst) a Go binary that
update the GNU envsubst that do not support default values.

