Metadata-Version: 2.4
Name: configuration-file
Version: 2.1.0
Summary: A Python implementation of the Configuration File (CF) format - a human-readable, machine-parseable data serialization format
Project-URL: Homepage, https://codeberg.org/configuration-file/py
Project-URL: Documentation, https://codeberg.org/configuration-file/py#readme
Project-URL: Repository, https://codeberg.org/configuration-file/py.git
Project-URL: Issues, https://codeberg.org/configuration-file/py/issues
Project-URL: Specification, https://codeberg.org/configuration-file/spec
Author: Dejan Lekic
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: cf,config,configuration,configuration-file,data-format,human-readable,parser,serialization,settings
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: File Formats
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# configuration-file

A Python implementation of the [Configuration File (CF) format](https://codeberg.org/configuration-file/spec) - a human-readable, machine-parseable data serialization format for configuration files.

[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)

## What is CF?

CF (Configuration File) is a modern configuration format designed to address common shortcomings of existing formats like JSON, YAML, TOML, and INI:

- **Human-readable**: Clean, minimal syntax with comments
- **Machine-parseable**: Simple, unambiguous LL(1) grammar
- **Whitespace-independent**: Structure uses explicit delimiters (`{ }` and `[ ]`), not indentation
- **Copy-paste safe**: Configuration survives email, chat, wikis, and forums
- **Type-safe**: Explicit typing with no implicit conversions
- **Extensible**: Includes for configuration reuse across files

See the [official CF Specification](https://codeberg.org/configuration-file/spec) for complete details, or the [local copy](doc/CF-SPEC-1.0.md) included in this repository.

## Installation

```bash
pip install configuration-file
```

For development:

```bash
pip install configuration-file[dev]
```

## Quick Example

CF files use the `.cf` extension:

```cf
# Application configuration
app_name = "my-service"
version = "1.0.0"
debug = false

# Server settings
server = {
    host = "localhost"
    port = 8080
    timeout = 30.5
}

# Supported features
features = ["auth", "logging", "metrics"]

# Database connections
databases = [
    { name = "primary", url = "postgres://localhost/main" }
    { name = "replica", url = "postgres://localhost/replica", readonly = true }
]
```

## Usage

### Simple API (dict-based)

```python
import cf_py

# Parse a CF file
config = cf_py.load("config.cf")

# Parse a CF string
config = cf_py.loads('''
    app_name = "my-service"
    debug = true
''')

# Access values
print(config["app_name"])  # "my-service"
print(config["server"]["port"])  # 8080

# Serialize to CF format
cf_string = cf_py.dumps(config)

# Write to a file
cf_py.dump(config, "output.cf")
```

### Roundtrip API (preserves formatting)

```python
import cf_py

# Parse into a CFDocument that preserves comments, whitespace,
# quote styles, and separator choices
doc = cf_py.loads_document('''
    # Server configuration
    server {
        host = "localhost"
        port = 8080
    }
''')

# Read values
host = doc.get("server.host")  # "localhost"

# Modify values (only changed values are re-rendered)
doc.set("server.port", 9090)

# Serialize back with minimal diffs
output = doc.serialize()
# Comments, whitespace, and formatting are preserved

# Convert to plain dict when formatting isn't needed
config = doc.to_dict()
```

## Features

- **Full CF 1.0 specification support**
- **Comments**: Hash (`#`), double-slash (`//`), and block (`/* */`) comments
- **Data types**: Strings, integers, floats, booleans, null, dates, times, datetimes
- **Collections**: Objects and arrays with flexible syntax
- **String variants**: Double-quoted, single-quoted, triple-quoted, and raw strings
- **Environment variable substitution**: `${VAR}`, `${VAR:-default}`, `${VAR:?error}`
- **File includes**: `include "path/to/file.cf"`
- **Roundtrip preservation**: Parse, modify, and serialize with minimal diffs

## Development

### Setup

1. Clone the repository:

```bash
git clone https://codeberg.org/configuration-file/py.git
cd py
```

2. Create a virtual environment and install dependencies:

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

With coverage:

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

### Code Quality

Lint and format code:

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

Type checking:

```bash
mypy src/cf_py
```

## License

This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.

Copyright (c) 2026 Dejan Lekic.
