Siva | prepare for v2.0.0 release

Author: ysskrishna

CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2025-02-06
+
+### 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](https://ysskrishna.github.io/nestedutils/migration-v1-to-v2/).
+
 ## [1.1.7]
 
 ### Added
@@ -13,7 +44,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
@@ -133,6 +163,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Immutable container protection (tuples cannot be modified)
 - Safe list deletion (requires explicit `allow_list_mutation=True` flag)
 
+[2.0.0]: https://github.com/ysskrishna/nestedutils/compare/v1.1.7...v2.0.0
 [1.1.7]: https://github.com/ysskrishna/nestedutils/compare/v1.1.6...v1.1.7
 [1.1.6]: https://github.com/ysskrishna/nestedutils/compare/v1.1.5...v1.1.6
 [1.1.5]: https://github.com/ysskrishna/nestedutils/compare/v1.1.4...v1.1.5

README.md

@@ -375,6 +375,10 @@ The library includes built-in safety limits to prevent excessive resource usage:
 These limits help protect against accidental memory exhaustion or performance issues. If you hit these limits, you'll receive a `PathError` with a clear message.
 
 
+## Migration from v1.x to v2.0
+
+Version 2.0 introduces breaking changes to make the library safer and more predictable. If you're upgrading from v1.x, please see the [Migration Guide](https://ysskrishna.github.io/nestedutils/migration-v1-to-v2/) for detailed upgrade instructions.
+
 ## Contributing
 
 Contributions are welcome! Please read our [Contributing Guide](https://github.com/ysskrishna/nestedutils/blob/main/CONTRIBUTING.md) for details on our code of conduct, development setup, and the process for submitting pull requests.

docs/migration-v1-to-v2.md

@@ -0,0 +1,12 @@
+---
+title: Migration Guide - v1 to v2
+description: "Guide for migrating from nestedutils v1.x to v2.0. Covers breaking changes, API updates, and code migration examples."
+keywords:
+  - nestedutils
+  - migration
+  - upgrade guide
+  - v2
+  - breaking changes
+---
+
+--8<-- "migration-v1-to-v2.md"

migration-v1-to-v2.md

@@ -0,0 +1,243 @@
+# Migration Guide: v1.x to v2.0
+
+This guide helps you upgrade your code from nestedutils v1.x to v2.0. Version 2.0 introduces breaking changes that make the library safer and more predictable.
+
+## Quick Summary of Breaking Changes
+
+| Change | v1.x Behavior | v2.0 Behavior |
+|--------|---------------|---------------|
+| `get_at` missing path | Returns `None` silently | Raises `PathError` |
+| `get_at` default parameter | Could be positional | Must be keyword-only (`default=...`) |
+| `set_at` auto-create | `fill_strategy` parameter | `create=False` parameter |
+| `set_at` create parameter | N/A (didn't exist) | Must be keyword-only (`create=...`) |
+| Sparse lists | Allowed with `None` fill | Not allowed (strict sequential) |
+| `FillStrategy` enum | Available | Removed |
+
+---
+
+## 1. `get_at` Now Raises by Default
+
+### The Change
+
+In v1.x, `get_at` silently returned `None` when a path didn't exist. In v2.0, it raises `PathError` by default, making missing data explicit rather than hidden.
+
+### v1.x Code
+
+```python
+from nestedutils import get_at
+
+data = {"user": {"name": "Alice"}}
+
+# v1.x: Returns None silently - bugs can hide here!
+email = get_at(data, "user.email")  # None
+age = get_at(data, "user.profile.age")  # None
+
+# v1.x: default could be passed positionally
+value = get_at(data, "missing.path", None)  # None (positional argument)
+```
+
+### v2.0 Migration
+
+**Option A: Use `default` parameter for optional values**
+
+```python
+from nestedutils import get_at
+
+data = {"user": {"name": "Alice"}}
+
+# Explicit default - clear intent
+email = get_at(data, "user.email", default=None)  # None
+email = get_at(data, "user.email", default="unknown@example.com")  # fallback value
+```
+
+**Option B: Use `exists_at` to check first**
+
+```python
+from nestedutils import get_at, exists_at
+
+if exists_at(data, "user.email"):
+    email = get_at(data, "user.email")
+else:
+    email = "default@example.com"
+```
+
+**Option C: Use try/except for error handling**
+
+```python
+from nestedutils import get_at, PathError
+
+try:
+    email = get_at(data, "user.email")
+except PathError:
+    email = "default@example.com"
+```
+
+### Why This Change?
+
+Silent `None` returns masked bugs. Consider:
+
+```python
+# v1.x - Bug hidden: typo in path returns None, not an error
+user_name = get_at(data, "usr.name")  # None (typo: "usr" vs "user")
+
+# v2.0 - Bug exposed immediately
+user_name = get_at(data, "usr.name")  # Raises PathError!
+```
+
+---
+
+## 2. `set_at` Parameter Changes
+
+### The Change
+
+The `fill_strategy` parameter has been replaced with a simpler `create` boolean parameter. Sparse list creation is no longer supported. **Important**: Both `get_at`'s `default` and `set_at`'s `create` are now keyword-only parameters (must use `default=...` and `create=...`, not positional arguments).
+
+### v1.x Code
+
+```python
+from nestedutils import set_at, FillStrategy
+
+data = {}
+
+# v1.x: Various fill strategies
+set_at(data, "user.name", "Alice", fill_strategy=FillStrategy.AUTO)
+set_at(data, "items.0", "first", fill_strategy=FillStrategy.AUTO)
+set_at(data, "items.5", "sixth", fill_strategy=FillStrategy.NONE)  # Sparse list!
+
+# v1.x: fill_strategy could be passed as string positionally
+set_at(data, "user.name", "Alice", "auto")  # Positional argument
+```
+
+### v2.0 Migration
+
+```python
+from nestedutils import set_at
+
+data = {}
+
+# v2.0: Simple create=True for auto-creation
+set_at(data, "user.name", "Alice", create=True)
+set_at(data, "items.0", "first", create=True)
+
+# Sparse lists are NO LONGER ALLOWED
+# set_at(data, "items.5", "sixth", create=True)  # Raises PathError!
+
+# Must build sequentially
+set_at(data, "items.1", "second", create=True)  # OK - appends
+```
+
+### FillStrategy Migration Table
+
+| v1.x `fill_strategy` | v2.0 Equivalent |
+|----------------------|-----------------|
+| `FillStrategy.AUTO` | `create=True` |
+| `FillStrategy.NONE` | Not supported (no sparse lists) |
+| `FillStrategy.DICT` | `create=True` (inferred from key type) |
+| `FillStrategy.LIST` | `create=True` (inferred from key type) |
+| Not specified | `create=False` (default, raises on missing) |
+
+### Why This Change?
+
+- Sparse lists (`[None, None, None, "value"]`) caused confusion and bugs
+- The `FillStrategy` enum added complexity without proportional benefit
+- `create=True/False` is more intuitive and covers most use cases
+
+---
+
+## 3. No More Sparse Lists
+
+### The Change
+
+v1.x allowed creating lists with gaps filled by `None`. v2.0 enforces sequential list building only.
+
+### v1.x Code
+
+```python
+from nestedutils import set_at
+
+data = {}
+set_at(data, "items.5", "value", fill_strategy=FillStrategy.NONE)
+# Result: {"items": [None, None, None, None, None, "value"]}
+```
+
+### v2.0 Migration
+
+```python
+from nestedutils import set_at
+
+data = {}
+
+# Build lists sequentially
+set_at(data, "items.0", "first", create=True)
+set_at(data, "items.1", "second", create=True)
+set_at(data, "items.2", "third", create=True)
+# Result: {"items": ["first", "second", "third"]}
+
+# Or use plain Python for sparse/pre-sized lists
+data = {"items": [None] * 6}
+set_at(data, "items.5", "value")  # OK - index exists
+```
+
+### Why This Change?
+
+Sparse lists often indicate logic errors. If you truly need sparse data, a dict with integer keys is more appropriate:
+
+```python
+# Instead of sparse list
+data = {"items": {5: "value", 10: "another"}}
+```
+
+---
+
+## 4. FillStrategy Enum Removed
+
+### The Change
+
+The `FillStrategy` enum has been removed from the public API.
+
+### v1.x Code
+
+```python
+from nestedutils import FillStrategy
+
+strategy = FillStrategy.AUTO
+```
+
+### v2.0 Migration
+
+Remove all `FillStrategy` imports and usages. Use `create=True/False` instead.
+
+```python
+# v2.0: No FillStrategy import needed
+from nestedutils import set_at
+
+set_at(data, "path", value, create=True)
+```
+
+---
+
+## 5. New Introspection Functions
+
+v2.0 adds new introspection functions that don't exist in v1.x:
+
+```python
+from nestedutils import get_depth, count_leaves, get_all_paths
+
+data = {"a": {"b": 1, "c": 2}, "d": [3, 4]}
+
+get_depth(data)       # 2
+count_leaves(data)    # 4
+get_all_paths(data)   # [["a", "b"], ["a", "c"], ["d", 0], ["d", 1]]
+```
+
+---
+
+## Migration Checklist
+
+- [ ] **Search for `get_at` calls without `default`** - Add `default=None` if silent failure is intended
+- [ ] **Update positional `default` arguments** - Change `get_at(data, "path", None)` to `get_at(data, "path", default=None)`
+- [ ] **Remove `FillStrategy` imports** - Replace with `create=True/False`
+- [ ] **Remove `fill_strategy` parameters** - Replace with `create=True`
+- [ ] **Update positional `fill_strategy` arguments** - Change `set_at(data, "path", value, "auto")` to `set_at(data, "path", value, create=True)`
+- [ ] **Check for sparse list creation** - Refactor to sequential building or use dicts
+- [ ] **Run your test suite** - v2.0's stricter behavior will expose hidden bugs

mkdocs.yml

@@ -13,6 +13,7 @@ nav:
   - Home: index.md
   - Interactive Demo: demo.md
   - API Reference: api-reference.md
+  - Migration Guide (v1 → v2): migration-v1-to-v2.md
   - Contributing: CONTRIBUTING.md
   - Changelog: CHANGELOG.md
   - License: LICENSE.md

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nestedutils"
-version = "1.1.7"
+version = "2.0.0"
 description = "The lightweight Python library for safe, simple, dot-notation access to nested dicts and lists. Effortlessly get, set, and delete values deep in your complex JSON, API responses, and config files without verbose error-checking or handling KeyError exceptions."
 readme = "README.md"
 requires-python = ">=3.8"