Peppercorn

0.6 · maintenance · verified Fri Apr 17

Peppercorn is a Python library designed to transform flat key-value pairs (common in web form posts, e.g., from `request.form`) into structured nested dictionaries and lists, and vice-versa. It handles dot-notation and array indexing in keys to reconstitute complex data structures. The current version is 0.6, and it appears to be in maintenance mode with infrequent updates.

Common errors

```
AttributeError: module 'peppercorn' has no attribute 'Parse'
```
cause Attempting to call `peppercorn.Parse` (PascalCase) instead of `peppercorn.parse` (lowercase). Python function names are typically snake_case.

fix Use `peppercorn.parse` (lowercase) for the parsing function.
```
My parsed data is flat, but I expected a nested dictionary/list!
```
cause The input keys to `peppercorn.parse` did not strictly follow the dot-notation (`parent.child`) or array-indexing (`list.0.item`) conventions, causing `peppercorn` to treat them as literal flat keys.

fix Inspect your input dictionary keys. Ensure nested objects use dot-notation and list items use integer indices following the dot (e.g., `items.0.name`).
```
TypeError: 'dict' object is not subscriptable (when trying to access a list element)
```
cause This error often occurs when `peppercorn.parse` creates a dictionary where you expected a list, because the input keys for what should have been list elements were malformed (e.g., `items.first.name` instead of `items.0.name`).

fix Verify that your input keys for list elements use valid integer indices, like `items.0.field`, `items.1.field`, etc., ensuring `peppercorn` correctly identifies and creates a list.

Warnings

gotcha The `parse` function expects input keys to strictly follow dot-notation for nested dictionaries and integer indices for lists (e.g., `parent.child.0.grandchild`). Keys that do not conform will be treated as literal flat strings, potentially leading to unexpected non-nested output.
Fix: Ensure input keys adhere to `peppercorn`'s expected format (dot-separated for dicts, integer-indexed for lists).
gotcha Peppercorn primarily handles structure reconstitution. It does not perform type conversions (e.g., converting '123' to an integer, or 'true' to a boolean). All values in the resulting structure will remain strings.
Fix: Perform explicit type conversions on the parsed data after `peppercorn.parse` if non-string types are required for business logic.
gotcha The library appears to be in maintenance mode, with no new releases since January 2021. While stable for its niche, new feature development or active bug fixes are unlikely. Consider alternatives for projects requiring active development or support for modern web frameworks' advanced form handling.
Fix: Evaluate if the current feature set meets long-term needs. For new projects, explore modern form handling libraries if active development is a requirement.

Install

pip install peppercorn Install latest version

Imports

parse
```
from peppercorn import parse
```
flatten
```
from peppercorn import flatten
```

Quickstart

Demonstrates parsing a flat dictionary (representing form data) into a nested structure and then flattening it back.

import peppercorn

# Example form data, typically from request.form
form_data = {
    'items.0.name': 'Foo',
    'items.0.value': '123',
    'items.1.name': 'Bar',
    'items.1.value': '456',
    'user.name': 'Alice',
    'user.id': 'abc'
}

# Parse flat data into a nested structure
parsed_data = peppercorn.parse(form_data)
print("Parsed Data:", parsed_data)
# Expected: {'items': [{'name': 'Foo', 'value': '123'}, {'name': 'Bar', 'value': '456'}], 'user': {'name': 'Alice', 'id': 'abc'}}

# Flatten a nested structure back into flat form data
# (Often for use in template rendering or re-submitting)
flat_data = peppercorn.flatten(parsed_data)
print("Flattened Data:", flat_data)
# Expected: {'items.0.name': 'Foo', 'items.0.value': '123', 'items.1.name': 'Bar', 'items.1.value': '456', 'user.name': 'Alice', 'user.id': 'abc'}

view raw JSON →