Frequently Asked Questions (FAQ)

  1. What is the difference between flatdict, flatdict2, and cj365-flatdict packages?

    flatdict is the original package written for Python 2.7 by Gavin M. Roy in 2012, which provides the basic functionality for flattening nested dictionaries and lists. Improvements and maintenance of this package stopped in 2020 at v4.0.1, until the v4.1.0 was released in 2026, which resolved the problem with installation by pip >=25.3 with the latest build standard PEP 517.

    flatdict2 is a fork created by Dennis Henry in 2020 of the original flatdict package to publish a wheel on PyPI instead of just a source distribution but it did not modernize the codebase. The source dist is not installable by pip 25.3 due to the old build standard but the wheel is installable by pip 25.3 and provides the same functionality as flatdict.

    cj365-flatdict is a complete rewrite of the original flatdict package by @codejedi365 in 2026, which modernized the v4.0.4 codebase to Python3 expectations, enhanced the flexibility of updating nested values, and modernized the build infrastructure to support the latest build standards and tools. Performance optimizations and testing rigor were also added to ensure the package is robust, performant, and memory efficient. The default delimiter was also changed from a colon (:) to a period (.) to align with common conventions for representing nested keys in Python and other programming languages.

  2. Why does FlatterDict exist when FlatDict already exists?

    FlatDict is designed to enable updating of nested dictionaries only while FlatterDict is designed to enable updating of nested dictionaries and sequences (lists and tuples). If you only desire to extract or update lists, tuples, or sets wholesale as values, then FlatDict will be sufficient for your needs. However, if you need to extract or update individual items within lists, tuples, or sets, then FlatterDict would be the appropriate choice.

    Integers, floats, strings, booleans, None, and other non-dict and non-sequence types are treated as simple values in both classes and cannot be updated with delimited keys.

  3. How does FlatterDict differ from FlatDict?

    FlatterDict is able to take a delimited key that includes an offset integer for a list, tuple, or set and update the value at that offset within the sequence. For example, if you have a list my_list = [1, 2, 3] and you want to update the value at index 1 to be 42, you could use FlatterDict to do this with a delimited key like my_list.1. This would update the list to be my_list = [1, 42, 3].

    In contrast, FlatDict would treat my_list.1 as an invalid key since it does not support updating of individual items within sequences. Instead, you would need to update the entire list at once with a key like my_list and provide the new list value.

  4. Why can’t I use customized classes as values in FlatDict or FlatterDict?

    FlatDict will be able to handle customized classes as values unless they specifically extend the built-in dict class. These classes will be treated as simple values and cannot be updated with delimited keys. However, if a customized class extends the built-in dict class, the behavior of FlatDict can be unpredictable since it is designed to work with standard Python data types and may not be compatible with the internal structure and behavior of customized classes that extend dict.

    FlatterDict will not be able to handle customized sequence classes because under the hood we convert sequences to index-keyed dictionaries to provide the delimited key updating functionality. In the inflate() method, we attempt to convert these index-keyed dictionaries back to their original sequence types but if the original sequence type is a customized class, we will not be able to convert it back and it will be inflated as a memory-efficient tuple instead.