Release v0.8.0

Author: Prodesire

CHANGELOG.md

@@ -1,3 +1,13 @@
+v0.8.0 (2026-06-16)
+-------------------
+
+**Enhancements**
+
+* Add ``dict.get_path`` and ``dict.set_path`` helpers for nested mapping access.
+* Add ``dict.deep_merge`` for recursive mapping merges.
+* Align public documentation with the current Python 3.9+ support policy.
+
+
 v0.7.4 (2026-06-15)
 -------------------
 

README.md

@@ -9,7 +9,7 @@
 [![pydu](https://img.shields.io/github/contributors/flaggo/pydu.svg)](https://github.com/flaggo/pydu/graphs/contributors)
 
 **pydu** is a library of useful **d**ata structures and **u**tils
-for Python 2 and 3, which collected from open source projects and created by contributors.
+for Python 3.9+, which collected from open source projects and created by contributors.
 
 
 ## Installation

docs/README.md

@@ -1,7 +1,7 @@
 ## pydu
 
 > **pydu(Python Data structures and Utils)** is a library of useful data structures and utils
-for Python 2 and 3, which collected from open source projects and created by contributors.
+for Python 3.9+, which collected from open source projects and created by contributors.
 
 
 ## Installation

docs/dict.md

@@ -152,3 +152,58 @@ Return a new dict without selected keys from `mapping`. Missing keys are ignored
 >>> omit(data, 'private')
 {'name': 'pydu', 'version': '0.7.3'}
 ```
+
+
+## dict.get_path
+```python
+get_path(mapping, path, default=None, separator='.')
+```
+
+Return a nested value from `mapping`. If any path segment is missing, return
+`default`. `path` can be a dotted string or an iterable of path segments.
+
+```python
+>>> from pydu.dict import get_path
+>>> data = {'user': {'profile': {'name': 'pydu'}}}
+>>> get_path(data, 'user.profile.name')
+'pydu'
+>>> get_path(data, ('user', 'profile', 'missing'), default='unknown')
+'unknown'
+```
+
+
+## dict.set_path
+```python
+set_path(mapping, path, value, separator='.')
+```
+
+Set a nested value on `mapping`, creating intermediate dictionaries as needed.
+The original mapping is updated and returned.
+
+```python
+>>> from pydu.dict import set_path
+>>> data = {}
+>>> set_path(data, 'user.profile.name', 'pydu')
+{'user': {'profile': {'name': 'pydu'}}}
+>>> data
+{'user': {'profile': {'name': 'pydu'}}}
+```
+
+
+## dict.deep_merge
+```python
+deep_merge(*mappings)
+```
+
+Return a new dict by recursively merging mappings from left to right. Later
+values override earlier values. Nested mappings are merged; other values are
+replaced.
+
+```python
+>>> from pydu.dict import deep_merge
+>>> deep_merge(
+...     {'user': {'name': 'pydu', 'active': True}},
+...     {'user': {'active': False, 'role': 'admin'}},
+... )
+{'user': {'name': 'pydu', 'active': False, 'role': 'admin'}}
+```

docs/zh-cn/README.md

@@ -1,6 +1,6 @@
 ## pydu
 
-> **pydu(Python Data structures and Utils)** 是面向Python 2 和 3 的实用数据结构和工具库。
+> **pydu(Python Data structures and Utils)** 是面向 Python 3.9+ 的实用数据结构和工具库。
 它收集自开源项目，也有来自开发者贡献。
 
 

docs/zh-cn/dict.md

@@ -144,3 +144,56 @@ omit(mapping, keys)
 >>> omit(data, 'private')
 {'name': 'pydu', 'version': '0.7.3'}
 ```
+
+
+## dict.get_path
+```python
+get_path(mapping, path, default=None, separator='.')
+```
+
+从 `mapping` 中读取嵌套值。如果任意路径片段不存在，返回 `default`。
+`path` 可以是点分隔字符串，也可以是路径片段的可迭代对象。
+
+```python
+>>> from pydu.dict import get_path
+>>> data = {'user': {'profile': {'name': 'pydu'}}}
+>>> get_path(data, 'user.profile.name')
+'pydu'
+>>> get_path(data, ('user', 'profile', 'missing'), default='unknown')
+'unknown'
+```
+
+
+## dict.set_path
+```python
+set_path(mapping, path, value, separator='.')
+```
+
+在 `mapping` 中设置嵌套值，并按需创建中间字典。原 mapping 会被更新并返回。
+
+```python
+>>> from pydu.dict import set_path
+>>> data = {}
+>>> set_path(data, 'user.profile.name', 'pydu')
+{'user': {'profile': {'name': 'pydu'}}}
+>>> data
+{'user': {'profile': {'name': 'pydu'}}}
+```
+
+
+## dict.deep_merge
+```python
+deep_merge(*mappings)
+```
+
+返回一个从左到右递归合并 mappings 后的新字典。后面的值覆盖前面的值。
+嵌套 mapping 会被递归合并，其他值会被替换。
+
+```python
+>>> from pydu.dict import deep_merge
+>>> deep_merge(
+...     {'user': {'name': 'pydu', 'active': True}},
+...     {'user': {'active': False, 'role': 'admin'}},
+... )
+{'user': {'name': 'pydu', 'active': False, 'role': 'admin'}}
+```

pydu/__init__.py

@@ -3,7 +3,7 @@
 """
 from __future__ import absolute_import
 
-__version__ = '0.7.4'
+__version__ = '0.8.0'
 
 
 # Set logging handler to avoid "No handler found" warnings.

pydu/dict.py

@@ -226,6 +226,20 @@ def _normalize_keys(keys):
     return keys
 
 
+def _normalize_path(path, separator='.'):
+    if isinstance(path, string_types):
+        if path == '':
+            return tuple()
+        if separator is None:
+            return (path,)
+        return tuple(path.split(separator))
+    try:
+        iter(path)
+    except TypeError:
+        return (path,)
+    return tuple(path)
+
+
 def pick(mapping, keys):
     """
     Return a new dict with selected keys from mapping.
@@ -243,3 +257,54 @@ def omit(mapping, keys):
     keys = set(_normalize_keys(keys))
     return dict((key, value) for key, value in mapping.items()
                 if key not in keys)
+
+
+def get_path(mapping, path, default=None, separator='.'):
+    """
+    Return the nested value at path, or default when any segment is missing.
+    """
+    value = mapping
+    for key in _normalize_path(path, separator=separator):
+        try:
+            value = value[key]
+        except (KeyError, IndexError, TypeError):
+            return default
+    return value
+
+
+def set_path(mapping, path, value, separator='.'):
+    """
+    Set a nested value at path, creating dictionaries as needed.
+    """
+    keys = _normalize_path(path, separator=separator)
+    if not keys:
+        raise ValueError('path must not be empty')
+
+    current = mapping
+    for key in keys[:-1]:
+        try:
+            next_value = current[key]
+        except (KeyError, TypeError):
+            next_value = {}
+            current[key] = next_value
+        if not isinstance(next_value, MutableMapping):
+            next_value = {}
+            current[key] = next_value
+        current = next_value
+    current[keys[-1]] = value
+    return mapping
+
+
+def deep_merge(*mappings):
+    """
+    Return a new dict by recursively merging mappings from left to right.
+    """
+    result = {}
+    for mapping in mappings:
+        for key, value in mapping.items():
+            existing = result.get(key)
+            if isinstance(existing, Mapping) and isinstance(value, Mapping):
+                result[key] = deep_merge(existing, value)
+            else:
+                result[key] = value
+    return result

stubs/pydu/dict.pyi

@@ -1,11 +1,14 @@
-import collections
+from collections.abc import MutableMapping
 from typing import Iterable, Tuple, Any, Mapping, Dict, Union
 
 
-class CaseInsensitiveDict(collections.MutableMapping):
+class CaseInsensitiveDict(MutableMapping):
     _store = ... # type: dict
     def __init__(self, data: dict=None, **kwargs) -> None: ...
     def lower_items(self) -> Iterable[Tuple[str, Any]]: ...
 
 def pick(mapping: Mapping[Any, Any], keys: Union[Any, Iterable[Any]]) -> Dict[Any, Any]: ...
 def omit(mapping: Mapping[Any, Any], keys: Union[Any, Iterable[Any]]) -> Dict[Any, Any]: ...
+def get_path(mapping: Any, path: Union[Any, Iterable[Any]], default: Any=None, separator: str='.') -> Any: ...
+def set_path(mapping: MutableMapping[Any, Any], path: Union[Any, Iterable[Any]], value: Any, separator: str='.') -> MutableMapping[Any, Any]: ...
+def deep_merge(*mappings: Mapping[Any, Any]) -> Dict[Any, Any]: ...

tests/test_dict.py

@@ -2,7 +2,8 @@
 import unittest
 
 from pydu.dict import (AttrDict, LookupDict, CaseInsensitiveDict,
-                       OrderedDefaultDict, attrify, pick, omit)
+                       OrderedDefaultDict, attrify, pick, omit,
+                       get_path, set_path, deep_merge)
 
 
 class TestAttrDict:
@@ -151,3 +152,48 @@ def test_omit_accepts_single_string_key():
     data = {'name': 'pydu', 'private': True}
 
     assert omit(data, 'private') == {'name': 'pydu'}
+
+
+def test_get_path_reads_dotted_and_iterable_paths():
+    data = {'user': {'profile': {'name': 'pydu'}}}
+
+    assert get_path(data, 'user.profile.name') == 'pydu'
+    assert get_path(data, ('user', 'profile', 'name')) == 'pydu'
+
+
+def test_get_path_returns_default_when_missing():
+    data = {'user': {'profile': {}}}
+
+    assert get_path(data, 'user.profile.name', default='unknown') == 'unknown'
+    assert get_path(data, 'user.profile.name') is None
+
+
+def test_set_path_creates_nested_dicts_and_returns_mapping():
+    data = {}
+
+    result = set_path(data, 'user.profile.name', 'pydu')
+
+    assert result is data
+    assert data == {'user': {'profile': {'name': 'pydu'}}}
+
+
+def test_set_path_replaces_non_mapping_intermediate_values():
+    data = {'user': 'legacy'}
+
+    set_path(data, ('user', 'profile', 'name'), 'pydu')
+
+    assert data == {'user': {'profile': {'name': 'pydu'}}}
+
+
+def test_deep_merge_recursively_combines_mappings_without_mutating_inputs():
+    base = {'user': {'name': 'pydu', 'active': True}, 'tags': ['old']}
+    override = {'user': {'active': False, 'role': 'admin'}, 'tags': ['new']}
+
+    result = deep_merge(base, override)
+
+    assert result == {
+        'user': {'name': 'pydu', 'active': False, 'role': 'admin'},
+        'tags': ['new'],
+    }
+    assert base == {'user': {'name': 'pydu', 'active': True}, 'tags': ['old']}
+    assert override == {'user': {'active': False, 'role': 'admin'}, 'tags': ['new']}