Code Cleanup

[ysskrishna]

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.