# envdot
Enhanced environment variable management for Python with multi-format support and automatic type detection.
## Features
- 🔧 **Multiple Format Support**: `.env`, `.json`, `.yaml`, `.yml`, and `.ini` files
- 🎯 **Automatic Type Detection**: Automatically converts strings to `bool`, `int`, `float`, or keeps as `string`
- 💾 **Read and Write**: Load from and save to configuration files
- 🔄 **Method Chaining**: Fluent API for cleaner code
- 🌍 **OS Environment Integration**: Seamlessly works with `os.environ`
- 📦 **Zero Dependencies**: Core functionality works without external packages (YAML support requires PyYAML)
## Installation
```bash
pip install envdot
# With YAML support
pip install envdot[yaml]
# With all extras
pip install envdot[all]
```
## Quick Start
### Basic Usage
```python
from envdot import DotEnv
# Auto-detect and load from common config files (.env, config.json, etc.)
env = DotEnv()
# Or specify a file
env = DotEnv('.env')
# Get values with automatic type detection
db_host = env.get('DB_HOST') # Returns string
db_port = env.get('DB_PORT') # Returns int (auto-detected)
debug_mode = env.get('DEBUG') # Returns bool (auto-detected)
api_timeout = env.get('API_TIMEOUT') # Returns float (auto-detected)
# Set values
env.set('NEW_KEY', 'value')
env.set('FEATURE_ENABLED', True)
# Save to file
env.save('.env')
```
### Convenience Functions
```python
from envdot import load_env, get_env, set_env, save_env
# Load configuration
load_env('.env')
# Get values
database_url = get_env('DATABASE_URL')
max_connections = get_env('MAX_CONNECTIONS', default=100)
# Set values
set_env('NEW_FEATURE', True)
# Save changes
save_env('.env')
```
### Working with Different File Formats
#### .env File
```python
env = DotEnv('.env')
env.load()
```
#### JSON File
```python
env = DotEnv('config.json')
env.load()
```
#### YAML File
```python
env = DotEnv('config.yaml')
env.load() # Requires PyYAML
```
#### INI File
```python
env = DotEnv('config.ini')
env.load()
```
### Type Detection Examples
The package automatically detects and converts types:
```python
# Given this .env file:
# DEBUG=true
# PORT=8080
# TIMEOUT=30.5
# APP_NAME=MyApp
# EMPTY_VALUE=
env = DotEnv('.env')
env.get('DEBUG') # Returns: True (bool)
env.get('PORT') # Returns: 8080 (int)
env.get('TIMEOUT') # Returns: 30.5 (float)
env.get('APP_NAME') # Returns: 'MyApp' (str)
env.get('EMPTY_VALUE') # Returns: None
```
### Explicit Type Casting
```python
# Force a specific type
version = env.get('VERSION', cast_type=str)
port = env.get('PORT', cast_type=int)
enabled = env.get('ENABLED', cast_type=bool)
```
### Method Chaining
```python
env = DotEnv('.env') \
.load() \
.set('NEW_KEY', 'value') \
.set('ANOTHER_KEY', 123) \
.save()
```
### Dictionary-Style Access
```python
env = DotEnv('.env')
# Get values
value = env['KEY_NAME']
# Set values
env['NEW_KEY'] = 'new value'
# Check existence
if 'API_KEY' in env:
print("API key is configured")
# Get all variables
all_vars = env.all()
```
### Advanced Features
#### Load Without Overriding
```python
env.load(override=False) # Keep existing values
```
#### Load Without Applying to OS Environment
```python
env.load(apply_to_os=False) # Don't set in os.environ
```
#### Save to Different Format
```python
env = DotEnv('.env')
env.load()
env.save('config.json') # Convert .env to JSON
```
#### Clear Variables
```python
env.clear() # Clear internal storage only
env.clear(clear_os=True) # Also clear from os.environ
```
#### Delete Specific Keys
```python
env.delete('OLD_KEY')
env.delete('TEMP_KEY', remove_from_os=True)
```
## Type Detection Rules
The package uses the following rules for automatic type detection:
- **Boolean**: `true`, `yes`, `on`, `1` → `True` | `false`, `no`, `off`, `0` → `False`
- **None**: `none`, `null`, empty string → `None`
- **Integer**: Numbers without decimal point → `int`
- **Float**: Numbers with decimal point → `float`
- **String**: Everything else → `str`
## File Format Examples
### .env
```env
DEBUG=true
PORT=8080
DATABASE_URL=postgresql://localhost/mydb
```
### .json
```json
{
"DEBUG": true,
"PORT": 8080,
"DATABASE_URL": "postgresql://localhost/mydb"
}
```
### .yaml
```yaml
DEBUG: true
PORT: 8080
DATABASE_URL: postgresql://localhost/mydb
```
### .ini
```ini
[DEFAULT]
DEBUG = true
PORT = 8080
DATABASE_URL = postgresql://localhost/mydb
```
## API Reference
### DotEnv Class
#### `__init__(filepath=None, auto_load=True)`
Initialize DotEnv instance.
#### `load(filepath=None, override=True, apply_to_os=True)`
Load environment variables from file.
#### `get(key, default=None, cast_type=None)`
Get environment variable with automatic type detection.
#### `set(key, value, apply_to_os=True)`
Set environment variable.
#### `save(filepath=None, format=None)`
Save environment variables to file.
#### `delete(key, remove_from_os=True)`
Delete environment variable.
#### `all()`
Get all environment variables as dictionary.
#### `keys()`
Get all variable names.
#### `clear(clear_os=False)`
Clear all stored variables.
### Convenience Functions
- `load_env(filepath=None, **kwargs)` - Load environment variables
- `get_env(key, default=None, cast_type=None)` - Get environment variable
- `set_env(key, value, **kwargs)` - Set environment variable
- `save_env(filepath=None, **kwargs)` - Save environment variables
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Author
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
[](https://www.buymeacoffee.com/cumulus13)
[](https://ko-fi.com/cumulus13)
[Support me on Patreon](https://www.patreon.com/cumulus13)
Raw data
{
"_id": null,
"home_page": "https://github.com/cumulus13/envdot",
"name": "envdot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "environment, variables, config, envdot, configuration",
"author": "Hadi Cahyadi",
"author_email": "Hadi Cahyadi <cumulus13@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/c1/f29eef264fd3da009be67e300394c99d29f58110693a50cdb0a2825980bb/envdot-1.0.0.tar.gz",
"platform": null,
"description": "# envdot\r\n\r\nEnhanced environment variable management for Python with multi-format support and automatic type detection.\r\n\r\n## Features\r\n\r\n- \ud83d\udd27 **Multiple Format Support**: `.env`, `.json`, `.yaml`, `.yml`, and `.ini` files\r\n- \ud83c\udfaf **Automatic Type Detection**: Automatically converts strings to `bool`, `int`, `float`, or keeps as `string`\r\n- \ud83d\udcbe **Read and Write**: Load from and save to configuration files\r\n- \ud83d\udd04 **Method Chaining**: Fluent API for cleaner code\r\n- \ud83c\udf0d **OS Environment Integration**: Seamlessly works with `os.environ`\r\n- \ud83d\udce6 **Zero Dependencies**: Core functionality works without external packages (YAML support requires PyYAML)\r\n\r\n## Installation\r\n\r\n```bash\r\npip install envdot\r\n\r\n# With YAML support\r\npip install envdot[yaml]\r\n\r\n# With all extras\r\npip install envdot[all]\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom envdot import DotEnv\r\n\r\n# Auto-detect and load from common config files (.env, config.json, etc.)\r\nenv = DotEnv()\r\n\r\n# Or specify a file\r\nenv = DotEnv('.env')\r\n\r\n# Get values with automatic type detection\r\ndb_host = env.get('DB_HOST') # Returns string\r\ndb_port = env.get('DB_PORT') # Returns int (auto-detected)\r\ndebug_mode = env.get('DEBUG') # Returns bool (auto-detected)\r\napi_timeout = env.get('API_TIMEOUT') # Returns float (auto-detected)\r\n\r\n# Set values\r\nenv.set('NEW_KEY', 'value')\r\nenv.set('FEATURE_ENABLED', True)\r\n\r\n# Save to file\r\nenv.save('.env')\r\n```\r\n\r\n### Convenience Functions\r\n\r\n```python\r\nfrom envdot import load_env, get_env, set_env, save_env\r\n\r\n# Load configuration\r\nload_env('.env')\r\n\r\n# Get values\r\ndatabase_url = get_env('DATABASE_URL')\r\nmax_connections = get_env('MAX_CONNECTIONS', default=100)\r\n\r\n# Set values\r\nset_env('NEW_FEATURE', True)\r\n\r\n# Save changes\r\nsave_env('.env')\r\n```\r\n\r\n### Working with Different File Formats\r\n\r\n#### .env File\r\n```python\r\nenv = DotEnv('.env')\r\nenv.load()\r\n```\r\n\r\n#### JSON File\r\n```python\r\nenv = DotEnv('config.json')\r\nenv.load()\r\n```\r\n\r\n#### YAML File\r\n```python\r\nenv = DotEnv('config.yaml')\r\nenv.load() # Requires PyYAML\r\n```\r\n\r\n#### INI File\r\n```python\r\nenv = DotEnv('config.ini')\r\nenv.load()\r\n```\r\n\r\n### Type Detection Examples\r\n\r\nThe package automatically detects and converts types:\r\n\r\n```python\r\n# Given this .env file:\r\n# DEBUG=true\r\n# PORT=8080\r\n# TIMEOUT=30.5\r\n# APP_NAME=MyApp\r\n# EMPTY_VALUE=\r\n\r\nenv = DotEnv('.env')\r\n\r\nenv.get('DEBUG') # Returns: True (bool)\r\nenv.get('PORT') # Returns: 8080 (int)\r\nenv.get('TIMEOUT') # Returns: 30.5 (float)\r\nenv.get('APP_NAME') # Returns: 'MyApp' (str)\r\nenv.get('EMPTY_VALUE') # Returns: None\r\n```\r\n\r\n### Explicit Type Casting\r\n\r\n```python\r\n# Force a specific type\r\nversion = env.get('VERSION', cast_type=str)\r\nport = env.get('PORT', cast_type=int)\r\nenabled = env.get('ENABLED', cast_type=bool)\r\n```\r\n\r\n### Method Chaining\r\n\r\n```python\r\nenv = DotEnv('.env') \\\r\n .load() \\\r\n .set('NEW_KEY', 'value') \\\r\n .set('ANOTHER_KEY', 123) \\\r\n .save()\r\n```\r\n\r\n### Dictionary-Style Access\r\n\r\n```python\r\nenv = DotEnv('.env')\r\n\r\n# Get values\r\nvalue = env['KEY_NAME']\r\n\r\n# Set values\r\nenv['NEW_KEY'] = 'new value'\r\n\r\n# Check existence\r\nif 'API_KEY' in env:\r\n print(\"API key is configured\")\r\n\r\n# Get all variables\r\nall_vars = env.all()\r\n```\r\n\r\n### Advanced Features\r\n\r\n#### Load Without Overriding\r\n\r\n```python\r\nenv.load(override=False) # Keep existing values\r\n```\r\n\r\n#### Load Without Applying to OS Environment\r\n\r\n```python\r\nenv.load(apply_to_os=False) # Don't set in os.environ\r\n```\r\n\r\n#### Save to Different Format\r\n\r\n```python\r\nenv = DotEnv('.env')\r\nenv.load()\r\nenv.save('config.json') # Convert .env to JSON\r\n```\r\n\r\n#### Clear Variables\r\n\r\n```python\r\nenv.clear() # Clear internal storage only\r\nenv.clear(clear_os=True) # Also clear from os.environ\r\n```\r\n\r\n#### Delete Specific Keys\r\n\r\n```python\r\nenv.delete('OLD_KEY')\r\nenv.delete('TEMP_KEY', remove_from_os=True)\r\n```\r\n\r\n## Type Detection Rules\r\n\r\nThe package uses the following rules for automatic type detection:\r\n\r\n- **Boolean**: `true`, `yes`, `on`, `1` \u2192 `True` | `false`, `no`, `off`, `0` \u2192 `False`\r\n- **None**: `none`, `null`, empty string \u2192 `None`\r\n- **Integer**: Numbers without decimal point \u2192 `int`\r\n- **Float**: Numbers with decimal point \u2192 `float`\r\n- **String**: Everything else \u2192 `str`\r\n\r\n## File Format Examples\r\n\r\n### .env\r\n```env\r\nDEBUG=true\r\nPORT=8080\r\nDATABASE_URL=postgresql://localhost/mydb\r\n```\r\n\r\n### .json\r\n```json\r\n{\r\n \"DEBUG\": true,\r\n \"PORT\": 8080,\r\n \"DATABASE_URL\": \"postgresql://localhost/mydb\"\r\n}\r\n```\r\n\r\n### .yaml\r\n```yaml\r\nDEBUG: true\r\nPORT: 8080\r\nDATABASE_URL: postgresql://localhost/mydb\r\n```\r\n\r\n### .ini\r\n```ini\r\n[DEFAULT]\r\nDEBUG = true\r\nPORT = 8080\r\nDATABASE_URL = postgresql://localhost/mydb\r\n```\r\n\r\n## API Reference\r\n\r\n### DotEnv Class\r\n\r\n#### `__init__(filepath=None, auto_load=True)`\r\nInitialize DotEnv instance.\r\n\r\n#### `load(filepath=None, override=True, apply_to_os=True)`\r\nLoad environment variables from file.\r\n\r\n#### `get(key, default=None, cast_type=None)`\r\nGet environment variable with automatic type detection.\r\n\r\n#### `set(key, value, apply_to_os=True)`\r\nSet environment variable.\r\n\r\n#### `save(filepath=None, format=None)`\r\nSave environment variables to file.\r\n\r\n#### `delete(key, remove_from_os=True)`\r\nDelete environment variable.\r\n\r\n#### `all()`\r\nGet all environment variables as dictionary.\r\n\r\n#### `keys()`\r\nGet all variable names.\r\n\r\n#### `clear(clear_os=False)`\r\nClear all stored variables.\r\n\r\n### Convenience Functions\r\n\r\n- `load_env(filepath=None, **kwargs)` - Load environment variables\r\n- `get_env(key, default=None, cast_type=None)` - Get environment variable\r\n- `set_env(key, value, **kwargs)` - Set environment variable\r\n- `save_env(filepath=None, **kwargs)` - Save environment variables\r\n\r\n## License\r\n\r\nMIT License\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n\r\n## Author\r\n[Hadi Cahyadi](mailto:cumulus13@gmail.com)\r\n \r\n\r\n[](https://www.buymeacoffee.com/cumulus13)\r\n\r\n[](https://ko-fi.com/cumulus13)\r\n\r\n[Support me on Patreon](https://www.patreon.com/cumulus13)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enhanced environment variable management with multi-format support",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/cumulus13/envdot/issues",
"Documentation": "https://github.com/cumulus13/envdot#readme",
"Homepage": "https://github.com/cumulus13/envdot",
"Repository": "https://github.com/cumulus13/envdot"
},
"split_keywords": [
"environment",
" variables",
" config",
" envdot",
" configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5dd14a1b45f3d40c6fb0b616e0db41b0c6975de8039819011e65b11e720699f5",
"md5": "5843100a4bf5a3a4a996567bce8ff109",
"sha256": "5f21c2ec282b4ea110cd4f24227e21ee7880ded34e5492f17621e74e62c43970"
},
"downloads": -1,
"filename": "envdot-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5843100a4bf5a3a4a996567bce8ff109",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8751,
"upload_time": "2025-10-10T17:31:47",
"upload_time_iso_8601": "2025-10-10T17:31:47.234180Z",
"url": "https://files.pythonhosted.org/packages/5d/d1/4a1b45f3d40c6fb0b616e0db41b0c6975de8039819011e65b11e720699f5/envdot-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9c1f29eef264fd3da009be67e300394c99d29f58110693a50cdb0a2825980bb",
"md5": "7326c8a0c27d7ecd567b156b8213f4d8",
"sha256": "63b514941790d1cc5110f1bb3ded016789c0705f3394210cb4c7fcc258bba3c3"
},
"downloads": -1,
"filename": "envdot-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7326c8a0c27d7ecd567b156b8213f4d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12193,
"upload_time": "2025-10-10T17:31:50",
"upload_time_iso_8601": "2025-10-10T17:31:50.084931Z",
"url": "https://files.pythonhosted.org/packages/f9/c1/f29eef264fd3da009be67e300394c99d29f58110693a50cdb0a2825980bb/envdot-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 17:31:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cumulus13",
"github_project": "envdot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "envdot"
}
JSON
