Metadata-Version: 2.4
Name: philiprehberger-dotenv-cast
Version: 0.1.2
Summary: Type-safe environment variable loading with casting and defaults.
Project-URL: Homepage, https://github.com/philiprehberger/py-dotenv-cast#readme
Project-URL: Repository, https://github.com/philiprehberger/py-dotenv-cast
Project-URL: Issues, https://github.com/philiprehberger/py-dotenv-cast/issues
Project-URL: Changelog, https://github.com/philiprehberger/py-dotenv-cast/blob/main/CHANGELOG.md
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: cast,config,dotenv,env,environment
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-dotenv-cast

[![Tests](https://github.com/philiprehberger/py-dotenv-cast/actions/workflows/publish.yml/badge.svg)](https://github.com/philiprehberger/py-dotenv-cast/actions/workflows/publish.yml)
[![PyPI version](https://img.shields.io/pypi/v/philiprehberger-dotenv-cast.svg)](https://pypi.org/project/philiprehberger-dotenv-cast/)
[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/py-dotenv-cast)](https://github.com/philiprehberger/py-dotenv-cast/commits/main)

Type-safe environment variable loading with casting and defaults.

## Installation

```bash
pip install philiprehberger-dotenv-cast
```

## Usage

```python
from philiprehberger_dotenv_cast import env, load_dotenv

# Load a .env file into os.environ
load_dotenv()

# Read variables with type casting
host = env.str("HOST", "localhost")
port = env.int("PORT", 8080)
debug = env.bool("DEBUG", False)
tags = env.list("TAGS")  # "a,b,c" -> ["a", "b", "c"]
```

### Boolean Casting

Boolean values are case-insensitive:

- Truthy: `"true"`, `"1"`, `"yes"`, `"on"`
- Falsy: `"false"`, `"0"`, `"no"`, `"off"`

### List Splitting

```python
# Default separator is ","
tags = env.list("TAGS")  # "a, b, c" -> ["a", "b", "c"]

# Custom separator
paths = env.list("PATHS", separator=":")
```

### JSON Parsing

```python
config = env.json("CONFIG")  # '{"key": "value"}' -> {"key": "value"}
```

### Missing Variables

Variables without a default raise `MissingEnvError`:

```python
from philiprehberger_dotenv_cast import env, MissingEnvError

try:
    secret = env.str("SECRET_KEY")  # raises if not set
except MissingEnvError:
    print("SECRET_KEY is required")
```

### Loading .env Files

```python
from philiprehberger_dotenv_cast import load_dotenv

# Load default .env
load_dotenv()

# Load a specific file
load_dotenv("config/.env.production")
```

## API

| Method / Function | Description |
|-------------------|-------------|
| `env.str(key, default?)` | Get variable as string |
| `env.int(key, default?)` | Get variable cast to int |
| `env.float(key, default?)` | Get variable cast to float |
| `env.bool(key, default?)` | Get variable cast to bool |
| `env.list(key, separator?, default?)` | Get variable split into a list |
| `env.json(key, default?)` | Get variable parsed as JSON |
| `load_dotenv(path?)` | Load a .env file into `os.environ` |
| `Env` | Class for creating custom instances |
| `MissingEnvError` | Raised when a required variable is missing |

## Development

```bash
pip install -e .
python -m pytest tests/ -v
```

## Support

If you find this project useful:

⭐ [Star the repo](https://github.com/philiprehberger/py-dotenv-cast)

🐛 [Report issues](https://github.com/philiprehberger/py-dotenv-cast/issues?q=is%3Aissue+is%3Aopen+label%3Abug)

💡 [Suggest features](https://github.com/philiprehberger/py-dotenv-cast/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)

❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)

🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)

💻 [GitHub Profile](https://github.com/philiprehberger)

🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)

## License

[MIT](LICENSE)
