This page documents the changes in the Python implementation of NestedText. Changes to the NestedText language are shown in Language changes.

Latest development version

Version: 3.4.0
Released: 2022-06-15

v3.4 (2022-06-15)


Be aware that the new version of the on_dup parameter are not compatible with previous versions.

v3.3 (2022-06-07)

v3.2 (2022-01-17)

  • add circular reference detection and reporting.

v3.1 (2021-07-23)

  • change error reporting for dumps() and dump() functions; culprit is now the keys rather than the value.

v3.0 (2021-07-17)

  • Deprecate trailing commas in inline lists and dictionaries.

  • Adds keymap argument to load() and loads().

  • Adds inline_level argument to dump() and dumps().

  • Implement on_dup argument to load() and loads() in inline dictionaries.

  • Apply convert and default arguments of dump() and dumps() to dictionary keys.


Be aware that aspects of this version are not backward compatible. Specifically, trailing commas are no longer supported in inline dictionaries and lists. In addition, [ ] now represents a list that contains an empty string, whereas previously it represented an empty list.

v2.0 (2021-05-28)

  • Deprecate quoted keys.

  • Add multiline keys to replace quoted keys.

  • Add inline lists and dictionaries.

  • Move from renderers to converters in dump() and dumps(). Both allow you to support arbitrary data types. With renderers you provide functions that are responsible for directly creating the text to be inserted in the NestedText output. This can be complicated and error prone. With converters you instead convert the object to a known NestedText data type (dict, list, string, …) and the dump function automatically formats it appropriately.

  • Restructure documentation.


Be aware that aspects of this version are not backward compatible.

  1. It no longer supports quoted dictionary keys.

  2. The renderers argument to dump() and dumps() has been replaced by converters.

  3. It no longer allows one to specify level in dump() and dumps().

v1.3 (2021-01-02)

  • Move the test cases to a submodule.


When cloning the NestedText repository you should use the –recursive flag to get the official_tests submodule:

git clone --recursive

When updating an existing repository, you need to initialize the submodule after doing a pull:

git submodule update --init --remote tests/official_tests

This only need be done once.

v1.2 (2020-10-31)

  • Treat CR LF, CR, or LF as a line break.

  • Always quote keys that start with a quote.

v1.1 (2020-10-13)

  • Add ability to specify return type of load() and loads().

  • Quoted keys are now less restricted.

  • Empty dictionaries and lists are rejected by dump() and dumps() except as top-level object if default argument is specified as ‘strict’.


Be aware that this version is not fully backward compatible. Unlike previous versions, this version allows you to restrict the type of the return value of the load() and loads() functions, and the default is ‘dict’. The previous behavior is still supported, but you must explicitly specify top=’any’ as an argument.

This change results in a simpler return value from load() and loads() in most cases. This substantially reduces the chance of coding errors. It was noticed that it was common to simply assume that the top-level was a dictionary when writing code that used these functions, which could result in unexpected errors when users hand-create the input data. Specifying the return value eliminates this type of error.

There is another small change that is not backward compatible. The source argument to these functions is now a keyword only argument.

v1.0 (2020-10-03)

  • Production release.