Refactor bitwise and dict_union for readability

Author: huangsam

ultimatepython/engineering/bitwise.py

@@ -1,54 +1,102 @@
 """
-Bitwise operators perform calculations on the binary representation of integers.
+Bitwise operators manipulate integers at the individual bit level, serving as
+essential tools in systems engineering, low-level protocols, and optimization.
 
-They operate on integers at the bit level, manipulating individual bits (0s and 1s)
-directly. Bitwise operations include AND (`&`), OR (`|`), XOR (`^`), NOT (`~`),
-and bit shifts (`<<`, `>>`). In Python, integers have arbitrary precision, but
-negative numbers are represented conceptually as having an infinite prefix of
-1-bits in a two's complement binary system.
+While high-level Python code often abstracts away binary representations, bit-level
+manipulation remains fundamental in production software engineering for:
+- Permission & Flag Sets: Storing multiple boolean states (e.g., Read/Write/Execute,
+  feature flags) compactly within a single integer.
+- Binary Protocol & Hardware Interfacing: Packing and unpacking binary payloads,
+  network headers, and device control registers.
+- High-Performance Operations: Leveraging bit shifts (`<<`, `>>`) for fast power-of-two
+  scaling and constant-time bitwise operations.
+- State Masking & Toggling: Testing specific bit fields with AND (`&`), setting flags
+  with OR (`|`), toggling states with XOR (`^`), and clearing bits with NOT (`~`).
 """
 
+# Permission flags defined as distinct powers of two (individual bits)
+PERM_READ = 1 << 0  # 0001 (1)
+PERM_WRITE = 1 << 1  # 0010 (2)
+PERM_EXECUTE = 1 << 2  # 0100 (4)
+
+
+def has_permission(user_perms: int, perm: int) -> bool:
+    """Check if a specific permission flag is enabled using bitwise AND."""
+    return (user_perms & perm) != 0
+
+
+def add_permission(user_perms: int, perm: int) -> int:
+    """Add a permission flag using bitwise OR."""
+    return user_perms | perm
+
+
+def remove_permission(user_perms: int, perm: int) -> int:
+    """Clear a permission flag using bitwise AND with NOT."""
+    return user_perms & ~perm
+
+
+def toggle_permission(user_perms: int, perm: int) -> int:
+    """Toggle a permission flag using bitwise XOR."""
+    return user_perms ^ perm
+
 
 def main() -> None:
-    # Define some integer values for demonstration
+    # 1. Fundamental bitwise arithmetic
     a = 5  # Binary: 0101
     b = 3  # Binary: 0011
 
-    # Bitwise AND (&) operator compares each bit of two integers and returns 1
-    # if both bits are 1, otherwise returns 0
+    # Bitwise AND (&) returns 1 only where both bits are 1
     result_and = a & b  # Binary: 0001 (Decimal: 1)
     assert result_and == 1
 
-    # Bitwise OR (|) operator compares each bit of two integers and returns 1
-    # if at least one bit is 1, otherwise returns 0
+    # Bitwise OR (|) returns 1 if at least one bit is 1
     result_or = a | b  # Binary: 0111 (Decimal: 7)
     assert result_or == 7
 
-    # Bitwise XOR (^) operator compares each bit of two integers and returns 1
-    # if the bits are different (one is 1 and the other is 0), otherwise returns 0
+    # Bitwise XOR (^) returns 1 where bits differ (one is 1, one is 0)
     result_xor = a ^ b  # Binary: 0110 (Decimal: 6)
     assert result_xor == 6
 
-    # Bitwise NOT (~) operator inverts all bits of an integer
-    # It returns the one's complement of the integer
+    # Bitwise NOT (~) inverts all bits, producing two's complement: -(x + 1)
     result_not_a = ~a  # Binary: 11111010 (Decimal: -6)
     assert result_not_a == -6
 
-    # Bitwise left shift (<<) operator shifts the bits of an integer to the left by
-    # a specified number of positions, filling with zeros
+    # Bitwise left shift (<<) multiplies by powers of two (a * 2^2)
     result_left_shift = a << 2  # Binary: 010100 (Decimal: 20)
     assert result_left_shift == 20
 
-    # Bitwise right shift (>>) operator shifts the bits of an integer to the right
-    # by a specified number of positions, filling with zeros for positive numbers
-    # and with ones for negative numbers
+    # Bitwise right shift (>>) performs integer division by powers of two (a // 2^1)
     result_right_shift = a >> 1  # Binary: 0010 (Decimal: 2)
     assert result_right_shift == 2
 
-    # Note that bitwise shifts have lower precedence than arithmetic operations
+    # Operator precedence: arithmetic operations bind tighter than shifts
     # https://docs.python.org/3/reference/expressions.html
-    result_right_shift_with_addition = a >> 1 + 1  # Equivalent to a >> (1 + 1)
-    assert result_right_shift_with_addition == 1  # Binary: 0001 (Decimal: 1)
+    result_shift_precedence = a >> 1 + 1  # Evaluates as a >> (1 + 1)
+    assert result_shift_precedence == 1  # 5 >> 2 -> 1
+
+    # 2. Practical engineering: Permission bitmask management
+    user_perms = 0
+    assert has_permission(user_perms, PERM_READ) is False
+
+    # Grant read and write permissions
+    user_perms = add_permission(user_perms, PERM_READ)
+    user_perms = add_permission(user_perms, PERM_WRITE)
+    assert user_perms == 3  # Binary: 0011
+    assert has_permission(user_perms, PERM_READ) is True
+    assert has_permission(user_perms, PERM_WRITE) is True
+    assert has_permission(user_perms, PERM_EXECUTE) is False
+
+    # Toggle write permission off
+    user_perms = toggle_permission(user_perms, PERM_WRITE)
+    assert has_permission(user_perms, PERM_WRITE) is False
+    assert user_perms == PERM_READ
+
+    # Add execute and remove read permissions
+    user_perms = add_permission(user_perms, PERM_EXECUTE)
+    user_perms = remove_permission(user_perms, PERM_READ)
+    assert user_perms == PERM_EXECUTE
+    assert has_permission(user_perms, PERM_EXECUTE) is True
+    assert has_permission(user_perms, PERM_READ) is False
 
 
 if __name__ == "__main__":

ultimatepython/engineering/dict_union.py

@@ -1,173 +1,123 @@
 """
-Dictionary union operators allow you to merge dictionaries using
-the | (union) and |= (in-place union) operators. These operators
-provide a clean and intuitive syntax for combining dictionaries.
-
-This feature was introduced in Python 3.9 through PEP 584. Before
-this, you had to use methods like dict.update() or {**dict1, **dict2}
-syntax to merge dictionaries.
+Dictionary union operators (`|` and `|=`) provide clean, side-effect-free dictionary
+merging, solving a fundamental software engineering challenge in state management.
+
+In production engineering, managing application state and configuration pipelines
+often requires combining multiple data sources (such as default settings, environment
+variables, and user overrides). Prior to Python 3.9 (PEP 584), merging required
+destructive in-place mutations via `dict.update()` or verbose `{**d1, **d2}` unpacking,
+which often introduced subtle shared-state bugs across layers.
+
+Key software engineering benefits:
+- Immutability & Safety: `|` produces a new dictionary without mutating either operand,
+  preventing side-effects across components and concurrent execution paths.
+- Deterministic Precedence: Subsequent dictionaries cleanly override earlier ones,
+  making layered configuration cascades explicit and predictable.
+- Expressive In-Place Updates: `|=` clearly signals intentional local mutation
+  without sacrificing readability.
 """
 
+from typing import Any
+
+
+def cascade_config(base: dict[str, Any], *overrides: dict[str, Any]) -> dict[str, Any]:
+    """Cascade configuration layers without mutating input dictionaries.
+
+    Later layers override earlier ones, returning a freshly merged dictionary.
+    """
+    merged = base.copy()
+    for override in overrides:
+        merged |= override
+    return merged
+
+
+def apply_patch(record: dict[str, Any], patch: dict[str, Any]) -> None:
+    """Apply a partial update in-place to an existing record using |=."""
+    record |= patch
+
 
 def main() -> None:
-    # Traditional dictionary merging before Python 3.9
-    # Method 1: Using dict.update() (modifies the original)
-    dict1_old = {"a": 1, "b": 2}
-    dict2_old = {"c": 3, "d": 4}
-    dict1_old.update(dict2_old)
-    assert dict1_old == {"a": 1, "b": 2, "c": 3, "d": 4}
-
-    # Method 2: Using dictionary unpacking (creates a new dict)
-    dict3_old = {"a": 1, "b": 2}
-    dict4_old = {"c": 3, "d": 4}
-    merged_old = {**dict3_old, **dict4_old}
-    assert merged_old == {"a": 1, "b": 2, "c": 3, "d": 4}
-
-    # With Python 3.9+, we can use the | operator for union
-    # This creates a new dictionary without modifying the originals
+    # 1. Non-mutating dictionary union (|)
     dict1 = {"a": 1, "b": 2}
     dict2 = {"c": 3, "d": 4}
     merged = dict1 | dict2
     assert merged == {"a": 1, "b": 2, "c": 3, "d": 4}
-
-    # The original dictionaries remain unchanged
+    # Original dictionaries remain untouched
     assert dict1 == {"a": 1, "b": 2}
     assert dict2 == {"c": 3, "d": 4}
 
-    # When there are overlapping keys, the right operand's values take precedence
-    # This is the same behavior as dict.update() and {**d1, **d2}
+    # 2. Overlapping key precedence: right operand overrides left operand
     dict3 = {"a": 1, "b": 2, "c": 3}
     dict4 = {"b": 20, "c": 30, "d": 4}
     merged2 = dict3 | dict4
-    # Keys 'b' and 'c' from dict4 override those from dict3
     assert merged2 == {"a": 1, "b": 20, "c": 30, "d": 4}
 
-    # The order matters! Left operand is the base, right operand overwrites
+    # Order matters: left is the base, right is the override
     merged3 = dict4 | dict3
-    # Now keys 'b' and 'c' from dict3 override those from dict4
     assert merged3 == {"b": 2, "c": 3, "d": 4, "a": 1}
 
-    # The |= operator performs in-place union (augmented assignment)
-    # This is equivalent to dict.update() but with cleaner syntax
+    # 3. In-place dictionary union (|=)
+    # Mutates the left operand in place, leaving the right operand unchanged
     dict5 = {"a": 1, "b": 2}
-    dict6 = {"c": 3, "d": 4}
+    dict6 = {"b": 20, "c": 3}
     dict5 |= dict6
-    # dict5 is modified in place
-    assert dict5 == {"a": 1, "b": 2, "c": 3, "d": 4}
-    # dict6 remains unchanged
-    assert dict6 == {"c": 3, "d": 4}
-
-    # The |= operator also handles overlapping keys
-    dict7 = {"a": 1, "b": 2, "c": 3}
-    dict8 = {"b": 20, "d": 4}
-    dict7 |= dict8
-    # 'b' from dict8 overwrites 'b' in dict7
-    assert dict7 == {"a": 1, "b": 20, "c": 3, "d": 4}
-
-    # You can chain multiple | operations
-    dict9 = {"a": 1}
-    dict10 = {"b": 2}
-    dict11 = {"c": 3}
-    dict12 = {"d": 4}
-    combined = dict9 | dict10 | dict11 | dict12
-    assert combined == {"a": 1, "b": 2, "c": 3, "d": 4}
-
-    # When chaining with overlapping keys, rightmost values win
-    dict13 = {"a": 1, "x": 10}
-    dict14 = {"b": 2, "x": 20}
-    dict15 = {"c": 3, "x": 30}
-    combined2 = dict13 | dict14 | dict15
-    # 'x' ends up with value 30 from the rightmost dictionary
-    assert combined2 == {"a": 1, "b": 2, "c": 3, "x": 30}
-
-    # The union operator works with empty dictionaries
-    empty: dict[str, int] = {}
-    dict16 = {"a": 1, "b": 2}
-    assert empty | dict16 == {"a": 1, "b": 2}
-    assert dict16 | empty == {"a": 1, "b": 2}
-    assert empty | empty == {}
-
-    # The union operator can be used with dict() constructor results
-    dict17 = dict(a=1, b=2)
-    dict18 = dict(c=3, d=4)
-    merged4 = dict17 | dict18
-    assert merged4 == {"a": 1, "b": 2, "c": 3, "d": 4}
-
-    # You can mix different value types in merged dictionaries
-    dict19 = {"name": "Alice", "age": 30}
-    dict20 = {"city": "NYC", "scores": [85, 90, 95]}
-    dict21 = {"active": True}
-    person = dict19 | dict20 | dict21
-    assert person == {"name": "Alice", "age": 30, "city": "NYC", "scores": [85, 90, 95], "active": True}
-
-    # Practical use case: Configuration merging
-    # Start with default configuration
-    default_config = {"timeout": 30, "retries": 3, "debug": False, "log_level": "INFO"}
+    assert dict5 == {"a": 1, "b": 20, "c": 3}
+    assert dict6 == {"b": 20, "c": 3}
 
-    # User provides custom configuration (partial)
-    user_config = {"timeout": 60, "debug": True}
+    # 4. Chained unions
+    dict_a = {"x": 1}
+    dict_b = {"y": 2}
+    dict_c = {"z": 3, "x": 10}
+    combined = dict_a | dict_b | dict_c
+    assert combined == {"x": 10, "y": 2, "z": 3}
 
-    # Merge configurations, user settings override defaults
-    final_config = default_config | user_config
-    assert final_config == {
-        "timeout": 60,  # Overridden by user
-        "retries": 3,  # From default
-        "debug": True,  # Overridden by user
-        "log_level": "INFO",  # From default
-    }
-
-    # Practical use case: Building objects incrementally
-    # Start with base attributes
-    base = {"id": 1, "type": "user"}
-
-    # Add authentication info
-    with_auth = base | {"username": "john", "email": "john@example.com"}
-
-    # Add profile info
-    with_profile = with_auth | {"bio": "Developer", "location": "USA"}
+    # 5. Empty dictionaries and dict() constructors
+    empty: dict[str, int] = {}
+    assert empty | {"a": 1} == {"a": 1}
+    assert dict(a=1, b=2) | dict(c=3) == {"a": 1, "b": 2, "c": 3}
 
-    assert with_profile == {"id": 1, "type": "user", "username": "john", "email": "john@example.com", "bio": "Developer", "location": "USA"}
+    # 6. Practical engineering: Cascading configuration layers
+    default_config = {"timeout": 30, "retries": 3, "debug": False, "log_level": "INFO"}
+    env_config = {"debug": True}
+    cli_config = {"timeout": 60, "log_level": "DEBUG"}
+
+    active_config = cascade_config(default_config, env_config, cli_config)
+    assert active_config == {
+        "timeout": 60,  # Overridden by CLI
+        "retries": 3,  # Retained from defaults
+        "debug": True,  # Overridden by environment
+        "log_level": "DEBUG",  # Overridden by CLI
+    }
+    # Verified: default_config was never mutated
+    assert default_config["timeout"] == 30
+    assert default_config["debug"] is False
 
-    # Practical use case: Updating records with |=
+    # 7. Practical engineering: Applying in-place record patches
     user_record = {"id": 100, "name": "Jane", "status": "active", "login_count": 5}
+    patch_data = {"status": "inactive", "login_count": 6}
+    apply_patch(user_record, patch_data)
+    assert user_record == {"id": 100, "name": "Jane", "status": "inactive", "login_count": 6}
 
-    # Apply update from an external source
-    update = {"status": "inactive", "login_count": 6, "last_login": "2024-01-15"}
-    user_record |= update
-
-    assert user_record == {"id": 100, "name": "Jane", "status": "inactive", "login_count": 6, "last_login": "2024-01-15"}
-
-    # The union operators only work with dictionaries
-    # Attempting to use them with non-dict types raises TypeError
-    dict22 = {"a": 1}
+    # 8. Type safety: Unions require both operands to be dict instances
     error_raised = False
     try:
-        # This will fail because list is not a dict
-        dict22 | [("b", 2)]  # type: ignore [operator]
+        dict1 | [("c", 3)]  # type: ignore [operator]
     except TypeError:
         error_raised = True
     assert error_raised is True
 
-    # However, you can use dict() to convert compatible types first
-    dict23 = {"a": 1}
-    dict24 = dict([("b", 2), ("c", 3)])  # Convert list of tuples to dict
-    merged5 = dict23 | dict24
-    assert merged5 == {"a": 1, "b": 2, "c": 3}
-
-    # Comparison with the older approaches shows the clarity improvement:
-
-    # OLD: Using update() - modifies original, no expression result
-    old1 = {"a": 1}
-    old1.update({"b": 2})
-    assert old1 == {"a": 1, "b": 2}
+    # Non-dict compatible mappings must be converted explicitly
+    assert dict1 | dict([("c", 3)]) == {"a": 1, "b": 2, "c": 3}
 
-    # OLD: Using unpacking - verbose for multiple merges
-    old2 = {**{"a": 1}, **{"b": 2}, **{"c": 3}}
-    assert old2 == {"a": 1, "b": 2, "c": 3}
+    # 9. Comparison with pre-3.9 approaches
+    # Traditional update() mutated in place and returned None (no chaining):
+    legacy_dict = {"a": 1}
+    legacy_dict.update({"b": 2})
+    assert legacy_dict == {"a": 1, "b": 2}
 
-    # NEW: Using union operator - clean and chainable
-    new1 = {"a": 1} | {"b": 2} | {"c": 3}
-    assert new1 == {"a": 1, "b": 2, "c": 3}
+    # Traditional unpacking syntax was verbose:
+    legacy_unpacking = {**{"a": 1}, **{"b": 2}}
+    assert legacy_unpacking == {"a": 1, "b": 2}
 
 
 if __name__ == "__main__":