configuration-file 2.1.0

A Python implementation of the Configuration File (CF) format - a human-readable, machine-parseable data serialization format

configuration-file

A Python implementation of the Configuration File (CF) format - a human-readable, machine-parseable data serialization format for configuration files.

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 for complete details, or the local copy included in this repository.

Installation

pip install configuration-file

For development:

pip install configuration-file[dev]

Quick Example

CF files use the .cf extension:

# 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)

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)

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:

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

2. Create a virtual environment and install dependencies:

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

Running Tests

pytest

With coverage:

pytest --cov=cf_py --cov-report=html

Code Quality

Lint and format code:

ruff check .
ruff format .

Type checking:

mypy src/cf_py

License

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

Copyright (c) 2026 Dejan Lekic.