Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

2.0.1

Changed

  • Redesigned Interactive Playground with improved UI/UX:
  • New top/bottom layout replacing the previous section-based design
  • Tab-based navigation for all 7 API functions (get_at, set_at, exists_at, delete_at, get_depth, count_leaves, get_all_paths)
  • Live stats bar showing data metrics (Depth, Leaves, Paths) in real-time
  • Live Python code preview with copy-to-clipboard functionality
  • Improved example selector with quick-switch buttons
  • Dark-themed JSON editor with syntax validation
  • Better responsive design for mobile devices

2.0.0

Breaking Changes

  • get_at now raises PathError by default for missing paths instead of returning None silently. Use the default parameter for optional/nullable access: get_at(data, "path", default=None)
  • get_at and set_at parameters are now keyword-only - The default and create parameters must be passed as keyword arguments (e.g., get_at(data, "path", default=None), not get_at(data, "path", None))
  • set_at parameter change - The fill_strategy parameter has been replaced with a simpler create boolean parameter. Replace fill_strategy=FillStrategy.AUTO with create=True
  • No more sparse lists - set_at no longer allows creating lists with gaps. Lists must be built sequentially (index 0, then 1, then 2, etc.). Attempting to set at index > len(list) raises PathError
  • Removed FillStrategy enum - Use create=True/False instead
  • Implicit None returns from get_at - Now raises PathError by default instead of returning None silently

Added

  • Introspection module with new functions for analyzing nested structures:
  • get_depth(data) - Returns maximum nesting depth
  • count_leaves(data) - Counts total leaf values
  • get_all_paths(data) - Returns all paths to leaf values
  • default parameter for get_at - Explicit way to handle missing paths: get_at(data, "path", default="fallback")
  • create parameter for set_at - Simple boolean to control auto-creation of intermediate containers
  • New error codes:
  • OPERATION_DISABLED - For operations blocked by configuration (e.g., list deletion without allow_list_mutation=True)
  • NON_NAVIGABLE_TYPE - For attempts to navigate into non-container types (e.g., int, str, set)

Changed

  • Improved error messages with more context about what went wrong and how to fix it
  • Refactored internal helpers for better maintainability and testability
  • Enhanced path validation with clearer error codes

For detailed migration instructions, see the Migration Guide.

1.1.7

Added

  • JSON textarea editor in demo page replacing read-only data display
  • Radio button selection for three example datasets (User Profile, E-commerce Data, API Response) and custom JSON input
  • Consolidated path validation tests into test_normalize_path.py with new test cases for complex keys and None value handling

Fixed

  • Fixed normalize_path() converting all list path keys to strings, now preserves integer and other key types.

1.1.6

Added

  • Interactive demo page powered by Pyodide - try nestedutils directly in your browser without installation
  • Demo page includes examples for all core functions (get_at, set_at, exists_at, delete_at) with real-time JSON editing
  • Added interactive demo badge and link to README

1.1.5

Changed

  • Enhanced docstrings across all modules (access.py, constants.py, enums.py, exceptions.py) with improved examples and detailed parameter descriptions
  • Improved API reference page structure to better organize documentation sections
  • Comprehensive examples in enum docstrings for PathErrorCode and FillStrategy

1.1.4

Added

  • Custom MkDocs theme overrides for enhanced SEO and social media integration
  • Comprehensive meta tags including Open Graph and Twitter Card support for better link previews
  • Structured data (JSON-LD) with SoftwareApplication schema for improved search engine visibility
  • Dynamic keywords meta tag support that combines page-specific and global keywords

Changed

  • Fixed Open Graph image URL in documentation to use correct repository path
  • Synchronized keywords between pyproject.toml and mkdocs.yml for consistent SEO across PyPI and documentation
  • Configured MkDocs to use custom theme directory for template customization

1.1.3

Fixed

  • Fixed CONTRIBUTING link in README to use absolute GitHub URL instead of relative path

1.1.2

Fixed

  • Corrected package image link in README

1.1.1

Changed

  • Updated documentation badge in README to include /nestedutils path

1.1.0

Added

  • exists_at() function to check if a path exists in nested data structures
  • Safety limits: Maximum path depth (100 levels) and maximum list index (10,000) to prevent resource exhaustion
  • Comprehensive MkDocs documentation with Material theme
  • CONTRIBUTING.md guide for contributors
  • GitHub Actions workflow for automated documentation deployment

Changed

  • BREAKING: Renamed API functions for consistency:
  • get_path() → get_at()
  • set_path() → set_at()
  • del_path() → delete_at()
  • Improved docstrings across all functions with detailed examples and parameter descriptions
  • Enhanced path validation with better error messages for edge cases
  • Refactored fill strategy handling using enums for better type safety
  • Updated README with improved documentation and examples

Fixed

  • Fixed bugs with negative index handling in get_at(), set_at(), and delete_at() methods
  • Improved validation in path normalization function
  • Fixed edge cases with empty paths and empty keys

1.0.1

Added

  • GitHub Actions workflow enhancement to automatically create releases on publish

Changed

  • Updated package description for better clarity and discoverability
  • Expanded keywords in pyproject.toml for improved PyPI searchability
  • Updated README with enhanced description and OG image

1.0.0

Added

  • Initial release of nestedutils
  • get_path() function for accessing nested values in dictionaries, lists
  • set_path() function for setting nested values with automatic container creation
  • del_path() function for deleting nested values
  • Support for dot-notation string paths ("a.b.c") and list paths (["a", "b", "c"])
  • List index support with positive and negative indices
  • Multiple fill strategies for set_path():
  • "auto": Intelligently creates containers based on next key type
  • "none": Fills missing list items with None
  • "dict": Always creates dictionaries
  • "list": Always creates lists
  • Comprehensive error handling with PathError exception and PathErrorCode enum
  • Support for navigating through None values (replaces with appropriate containers)
  • Sparse list creation when setting values at high indices
  • Full test coverage with comprehensive test suite

Features

  • Zero external dependencies
  • Python 3.8+ compatibility
  • Immutable container protection (tuples cannot be modified)
  • Safe list deletion (requires explicit allow_list_mutation=True flag)