EDN Format Reader and Writer

Warnings

• gotcha The library, following EDN's rationale, aims to yield immutable Python data structures (e.g., tuples for lists, frozensets for sets, ImmutableDict for maps) where possible. This can be unexpected for Python developers accustomed to mutable lists and dictionaries.
  Fix: Be aware that modifying returned collections might not be possible directly. Convert to mutable types (e.g., `list(immutable_list)`) if mutation is required.
• gotcha When serializing Python dictionaries, string keys will be dumped as EDN strings, not EDN keywords. To output EDN keywords for dictionary keys, you must explicitly use `edn_format.Keyword('your-key')` as the Python dictionary key.
  Fix: Use `edn_format.Keyword()` for dictionary keys if EDN keyword output is desired. Example: `edn_format.dumps({edn_format.Keyword('my-key'): 'value'})` will output `:my-key "value"`.
• gotcha EDN is a human-readable data format, and implementations like `edn-format` may not offer the same performance characteristics (speed and memory usage) as highly optimized binary serialization formats or even standard JSON libraries for high-throughput data transfer scenarios. For wire protocols, alternatives like Cognitect Transit might be more suitable.
  Fix: Evaluate performance requirements. For high-performance serialization, consider formats and libraries designed for that purpose. For durable storage or human-readable configurations, `edn-format` is generally suitable.
• gotcha While `edn-format` supports custom tagged literals, correctly implementing and registering reader/writer handlers for them can be complex and requires a good understanding of both the EDN specification and the library's extension mechanisms.
  Fix: Refer to the library's documentation or source for examples on how to register custom tag handlers (`edn_format.add_tag`). Ensure consistency between reading and writing implementations of custom types.

Install

• pip install edn-format Install with pip

Imports

• edn_format.loads

  import edn_format
  edn_format.loads("[1 2 3]")

• edn_format.dumps

  import edn_format
  edn_format.dumps([1, 2, 3])

• edn_format.loads_all

  import edn_format
  edn_format.loads_all("1 2 3")

• edn_format.Keyword

  import edn_format
  edn_format.Keyword("my-key")

  To explicitly create an EDN keyword in Python for dumping, use edn_format.Keyword.
• edn_format.Char

  import edn_format
  edn_format.Char("\n")

  Use edn_format.Char to represent EDN character literals. It subclasses Python's `str`.

Quickstart

This quickstart demonstrates how to serialize Python dictionaries containing various EDN types (keywords, sets, booleans, character literals) into an EDN string using `edn_format.dumps`, and then deserialize an EDN string back into Python data using `edn_format.loads`. It highlights the use of `edn_format.Keyword` and `edn_format.Char` for explicit EDN type representation.

import edn_format

# Define some Python data
python_data = {
    edn_format.Keyword('name'): 'Alice',
    edn_format.Keyword('age'): 30,
    edn_format.Keyword('tags'): {'python', 'edn'},
    edn_format.Keyword('active?'): True,
    edn_format.Keyword('notes'): edn_format.Char('\n') # Example of EDN char literal
}

# Dump Python data to EDN string
edn_string = edn_format.dumps(python_data, sort_keys=True, indent=2)
print("--- EDN Output ---")
print(edn_string)
# Expected output might look like:
# {
#   :active? true,
#   :age 30,
#   :name "Alice",
#   :notes \newline,
#   :tags #{"edn" "python"}
# }

# Load EDN string back to Python data
edn_input = "{ :id 123 :items [\"apple\" \"banana\"] :metadata #myapp/custom {\"version\" \"1.0\"} }"
loaded_data = edn_format.loads(edn_input)
print("\n--- Loaded Python Data ---")
print(loaded_data)
# Example of accessing loaded data
# print(loaded_data[edn_format.Keyword('id')]) # 123
# print(loaded_data[edn_format.Keyword('items')]) # ['apple', 'banana']