Perky Configuration Format

0.9.3 · active · verified Thu Apr 16

Perky is a new, simple, and Pythonic text file format designed for configuration files, serving as an alternative to INI, TOML, and JSON. It focuses on a minimal, human-friendly syntax and explicit data type handling, supporting strings, mappings (dicts), and sequences (lists) natively, leaving other type transformations to the user. The library is lightweight, fast, written in 100% pure Python, and currently maintained with version 0.9.3, supporting Python 3.6+.

Common errors

```
ModuleNotFoundError: No module named 'perky'
```
cause The 'perky' library is not installed in the current Python environment.

fix Run `pip install perky` to install the library.
```
FileNotFoundError: [Errno 2] No such file or directory: 'your_config.perky'
```
cause The file path provided to `perky.load()` does not exist or is incorrect.

fix Verify the file path and name. Ensure the file exists at the specified location or provide the correct absolute/relative path.
```
perky.errors.PerkyError: Unexpected character '=' in line ...
```
cause A malformed Perky syntax, often due to an unquoted '=' or other structural errors within a line.

fix Review the Perky file at the indicated line number. Ensure key-value pairs are correctly formatted, strings are properly quoted (if necessary), and container structures are valid. Pragmas (lines starting with '=') must be at the beginning of the line.
```
KeyError: 'some_key'
```
cause Attempting to access a key in a Perky-parsed dictionary that does not exist.

fix Check the Perky file for the correct key name and structure. Use `dict.get()` with a default value to safely access optional keys, e.g., `config.get('optional_key', 'default_value')`.

Warnings

breaking The `encoding` argument was removed from `perky.load()` and `perky.loads()` in version 0.9.0. Perky now exclusively supports UTF-8 encoding for reading and writing files. If other encodings are required, users must handle the loading/saving to disk and use `loads`/`dumps` for string-to-object conversion.
Fix: Ensure all Perky files are UTF-8 encoded. For non-UTF-8 files, read/write them with appropriate encoding and use `perky.loads()` or `perky.dumps()` with the resulting string data.
breaking The `Parser` attribute `breadcrumbs` was renamed to `stack` in version 0.9.1. While `breadcrumbs` remains an alias for now, it is undocumented and unsupported, and will be removed before version 1.0.
Fix: Update any custom pragma handlers or code accessing parser internals to use `parser.stack` instead of `parser.breadcrumbs`.
deprecated The entire `perky.transformation` submodule, which provided functions to convert strings to native Python types, is deprecated and no longer maintained or supported. It will be removed before version 1.0.
Fix: Perky's philosophy is explicit data type handling. Implement custom conversion logic or integrate a third-party data transformation library like Marshmallow for type coercion.
gotcha Perky explicitly supports only strings, dictionaries, and lists. It does not perform automatic type inference for integers, floats, booleans, or `None`. Values like `True`, `123`, or `1.5` are parsed as strings.
Fix: After parsing, explicitly convert string values to their desired Python types in your application code, e.g., `bool(config['settings']['debug'])` or `int(config['version'])`.

Install

pip install perky Install latest version

Imports

load
```
from perky import load
```
For loading Perky configuration from a file.
loads
```
from perky import loads
```
For loading Perky configuration from a string.

Quickstart

This quickstart demonstrates how to parse a Perky formatted string using `perky.loads`. The output will show how to access the parsed dictionary's values. Perky files support strings, dictionaries (mappings), and lists (sequences). Perky does not automatically convert values like 'True' to a boolean or '1.0' to a float; these remain as strings unless explicitly transformed by the user.

import perky

config_string = """
name = ExampleApp
version = 1.0
settings = {
  debug = True
  log_level = INFO
  features = [
    feature_a
    feature_b
  ]
}
"""

config = perky.loads(config_string)

print(config['name'])
print(config['settings']['debug'])
print(config['settings']['features'][0])

# Example of loading from a file (if 'config.perky' existed)
# with open('config.perky', 'w') as f:
#     f.write(config_string)
# file_config = perky.load('config.perky')
# print(file_config)

view raw JSON →