memory-graph 0.3.59__tar.gz → 0.3.61__tar.gz

{memory_graph-0.3.59/memory_graph.egg-info → memory_graph-0.3.61}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory_graph
-Version: 0.3.59
+Version: 0.3.61
 Summary: Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy.
 Author-email: Bas Terwijn <bterwijn@gmail.com>
 License-Expression: BSD-2-Clause
@@ -151,6 +151,8 @@ Bas Terwijn
 ## Inspiration ##
 Inspired by [Python Tutor](https://pythontutor.com/).
 
+The main difference are that running memory_graph locally is a key design choice to support Python Tutor’s [unsupported features](https://github.com/pythontutor-dev/pythontutor/blob/master/unsupported-features.md#unsupported-features) and mirroring the data’s hierarchy improves graph readability.
+
 ## Social Media #
 * [LinkedIn](https://www.linkedin.com/groups/13244150/)
 * [Reddit](https://www.reddit.com/r/Python_memory_graph/)
@@ -169,7 +171,7 @@ Learn the right **mental model** to think about Python data. The [Python Data Mo
 
 
 ## Immutable Type ##
-In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an immutable type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
+In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an **immutable** type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
 
 ```python
 import memory_graph as mg
@@ -187,7 +189,7 @@ mg.render(locals(), 'immutable2.png')
 
 
 ## Mutable Type ##
-With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a mutable type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
+With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a **mutable** type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
 
 ```python
 import memory_graph as mg
@@ -228,6 +230,7 @@ mg.show(locals())
 
 ![copy_mutbale.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/copy_mutable.png)
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/copies.py&play).
 
 ## Custom Copy ##
 We can write our own custom copy function or method in case the three standard "copy" options don't do what we want. For example, in the code below the `custom_copy()` method of My_Class copies the `digits` but shares the `letters` between two objects.
@@ -258,7 +261,7 @@ mg.show(locals())
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/custom_copy.py&breakpoints=15&continues=1&play).
 
 ## Name Rebinding ##
-When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only rebind the name `b` to another value without effecting any other variables.
+When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only **rebind** the name `b` to another value without affecting any other variables.
 
 ```python
 import memory_graph as mg
@@ -268,13 +271,15 @@ b = a
 mg.render(locals(), 'rebinding1.png')
 
 b += [1]        # changes the value of 'b' and 'a'
-b = [100, 200]  # rebinds 'b' to another value, 'a' is uneffected
+b = [100, 200]  # rebinds 'b' to another value, 'a' is unaffected
 mg.render(locals(), 'rebinding2.png')
 ```
 | ![rebinding1.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding1.png) | ![rebinding2.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding2.png) |
 |:-----------------------------------------------------------:|:-------------------------------------------------------------:|
 | rebinding1.png | rebinding2.png |
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/rebind.py&play).
+
 ## Copying Values of Immutable Type ## 
 Because a value of immutable type will be copied automatically when it is changed, there is no need to copy it beforehand. Therefore, a shallow or deep copy of a value of immutable type will result in just an assignment to save on the time needed to make the copy and the space (=memory) needed to store the values.
 
@@ -333,7 +338,7 @@ print(f"a:{a} b:{b} c:{c}")
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/function_call.py&play).
 
-In the printed output only `a` is changed as a result of the function call:
+In the printed output we see that only `a` is changed as a result of the function call:
 ```
 a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 ```
@@ -347,7 +352,7 @@ import memory_graph as mg
 
 def add_one(a, b):
     a += 1     # change remains confined to 'a' in the add_one function
-    b[0] += 1  # change also effects 'b' outside of the add_one function
+    b[0] += 1  # change also affects 'b' outside of the add_one function
     mg.show(mg.stack())
 
 a = 10
@@ -360,11 +365,13 @@ print(f"a:{a} b:{b[0]}")
 ```
 a:10 b:11
 ```
-Calling `add_one()` does not effect the `int` value of `a` but does effect the `int` value of `b` because it's wrapped in a mutable container.
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/wrap.py&breakpoints=5&continues=1&play)
+
+The effect of calling `add_one()` is that `b[0]` increases by 1, while `a` is unaffected.
 
 ## Exercises ##
 
-Now is a good time to practice the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
+Now is a good time to practice with the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
 
 ## Block ##
 It is often helpful to temporarily block program execution to inspect the graph. For this we can use the `mg.block()` function:
@@ -457,16 +464,21 @@ print( power_set(['a', 'b', 'c']) )
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
 
+## Invocation Tree ##
+The memory_graph package visualizes data at the currect time, but to better understand recursion it can also be helpful to visualize different function calls over time. This is what the [invocation_tree](https://github.com/bterwijn/invocation_tree?tab=readme-ov-file#installation) package does.
+
+See the power_set example in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
+
 # Debugging #
 
 For the best debugging experience with memory_graph set for example expression:
 ```
 mg.render(locals(), "my_graph.pdf")
 ```
-as a *watch* in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
+as a **watch** in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
 
 ## Call Stack in Watch Context ##
-The ```mg.stack()``` doesn't work well in *watch* context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
+The ```mg.stack()``` doesn't work well in **watch** context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
 
 | debugger | function to get the call stack in 'watch' context |
 |:---|:---|
@@ -480,7 +492,7 @@ The ```mg.stack()``` doesn't work well in *watch* context in most debuggers beca
 See the [Quick Intro (3:49)](https://www.youtube.com/watch?v=23_bHcr7hqo) video for the setup.
 
 ## Other Debuggers ##
-For other debuggers, invoke this function within the *watch* context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
+For other debuggers, invoke this function within the **watch** context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
 ```
 mg.save_call_stack("call_stack.txt")
 ```
@@ -928,6 +940,53 @@ mg.config.type_to_node[List_View] = lambda data: mg.Node_Linear(data,
 ```
 ![bin_search_linear.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bin_search_linear.png)
 
+## Bitwise Operators ##
+In this configuration example we show the decimal, binary and [two's complement representation](https://www.cs.cornell.edu/~tomf/notes/cps104/twoscomp.html) representation of `int` values of dictionary subclass `Bits` to show the result of [bitwise operators](https://docs.python.org/3/library/stdtypes.html?utm_source=chatgpt.com#bitwise-operations-on-integer-types). The `~` (inverse) operator can be a bit confusing if not shown with two's complement representation.
+
+```python
+import memory_graph as mg
+
+class Bits(dict):
+   """ Dictionary subclass that we will configure to show binary representations. """
+
+def twos_complement(x: int, bits: int) -> str:
+    """Return the two's complement bit string of x in `bits` bits."""
+    mask = (1 << bits) - 1
+    return format(x & mask, f"0{bits}b")
+
+# configure memory_graph to show binary representations of values of type Bits
+mg.config.type_to_node[Bits] = lambda x : mg.Node_Table(x,
+    [ ["expression", "decimal", "bin(expression)", "16bit two's complement"] ] +
+    [ [k, f'{v:>10}', f'{bin(v):>19}', twos_complement(v,16)] for k, v in x.items()] )
+mg.config.type_to_slicer[Bits] = (mg.Slicer(), mg.Slicer())  # no slicing
+mg.config.type_to_color[Bits] = 'gold'
+mg.config.fontname = 'Courier' # monospace font
+
+bits = Bits()
+
+# now add some some variables and expressions
+bits['a'] = 1
+bits['b'] = 48
+bits['c'] = 127
+bits['a << 3'] = bits['a'] << 3         # bit shift left by 3
+bits['b >> 3'] = bits['b'] >> 3         # bit shift right by 3
+bits['a | b']  = bits['a'] | bits['b']  # bitwise or
+bits['b & c']  = bits['b'] & bits['c']  # bitwise and
+bits['b ^ c']  = bits['b'] ^ bits['c']  # bitwise exclusive or
+
+# negative numbers, inverse, and two's complement
+bits['d'] = 240
+bits['e'] = -240
+bits['f'] = -241                        # -(d+1)
+bits['~d'] = ~ bits['d']                # inverse -(x+1)
+bits['~e'] = ~ bits['e']                # inverse -(x+1)
+bits['~f'] = ~ bits['f']                # inverse -(x+1)
+
+mg.s()
+```
+![bitwise_operators.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bitwise_operators.png)
+
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bitwise_operators.py&breakpoints=22&continues=1&play)
 
 # Graph Depth #
 To limit the size of the graph the maximum depth of the graph is set by `mg.config.max_graph_depth`. Additionally for each type a depth can be set to further limit the graph, as is done for type `B` in the example below. Scissors indicate where the graph is cut short. Alternatively the `id()` of a data elements can be used to limit the graph for that specific element, as is done for the value referenced by variable `c`.

{memory_graph-0.3.59 → memory_graph-0.3.61}/README.md

@@ -131,6 +131,8 @@ Bas Terwijn
 ## Inspiration ##
 Inspired by [Python Tutor](https://pythontutor.com/).
 
+The main difference are that running memory_graph locally is a key design choice to support Python Tutor’s [unsupported features](https://github.com/pythontutor-dev/pythontutor/blob/master/unsupported-features.md#unsupported-features) and mirroring the data’s hierarchy improves graph readability.
+
 ## Social Media #
 * [LinkedIn](https://www.linkedin.com/groups/13244150/)
 * [Reddit](https://www.reddit.com/r/Python_memory_graph/)
@@ -149,7 +151,7 @@ Learn the right **mental model** to think about Python data. The [Python Data Mo
 
 
 ## Immutable Type ##
-In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an immutable type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
+In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an **immutable** type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
 
 ```python
 import memory_graph as mg
@@ -167,7 +169,7 @@ mg.render(locals(), 'immutable2.png')
 
 
 ## Mutable Type ##
-With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a mutable type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
+With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a **mutable** type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
 
 ```python
 import memory_graph as mg
@@ -208,6 +210,7 @@ mg.show(locals())
 
 ![copy_mutbale.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/copy_mutable.png)
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/copies.py&play).
 
 ## Custom Copy ##
 We can write our own custom copy function or method in case the three standard "copy" options don't do what we want. For example, in the code below the `custom_copy()` method of My_Class copies the `digits` but shares the `letters` between two objects.
@@ -238,7 +241,7 @@ mg.show(locals())
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/custom_copy.py&breakpoints=15&continues=1&play).
 
 ## Name Rebinding ##
-When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only rebind the name `b` to another value without effecting any other variables.
+When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only **rebind** the name `b` to another value without affecting any other variables.
 
 ```python
 import memory_graph as mg
@@ -248,13 +251,15 @@ b = a
 mg.render(locals(), 'rebinding1.png')
 
 b += [1]        # changes the value of 'b' and 'a'
-b = [100, 200]  # rebinds 'b' to another value, 'a' is uneffected
+b = [100, 200]  # rebinds 'b' to another value, 'a' is unaffected
 mg.render(locals(), 'rebinding2.png')
 ```
 | ![rebinding1.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding1.png) | ![rebinding2.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding2.png) |
 |:-----------------------------------------------------------:|:-------------------------------------------------------------:|
 | rebinding1.png | rebinding2.png |
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/rebind.py&play).
+
 ## Copying Values of Immutable Type ## 
 Because a value of immutable type will be copied automatically when it is changed, there is no need to copy it beforehand. Therefore, a shallow or deep copy of a value of immutable type will result in just an assignment to save on the time needed to make the copy and the space (=memory) needed to store the values.
 
@@ -313,7 +318,7 @@ print(f"a:{a} b:{b} c:{c}")
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/function_call.py&play).
 
-In the printed output only `a` is changed as a result of the function call:
+In the printed output we see that only `a` is changed as a result of the function call:
 ```
 a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 ```
@@ -327,7 +332,7 @@ import memory_graph as mg
 
 def add_one(a, b):
     a += 1     # change remains confined to 'a' in the add_one function
-    b[0] += 1  # change also effects 'b' outside of the add_one function
+    b[0] += 1  # change also affects 'b' outside of the add_one function
     mg.show(mg.stack())
 
 a = 10
@@ -340,11 +345,13 @@ print(f"a:{a} b:{b[0]}")
 ```
 a:10 b:11
 ```
-Calling `add_one()` does not effect the `int` value of `a` but does effect the `int` value of `b` because it's wrapped in a mutable container.
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/wrap.py&breakpoints=5&continues=1&play)
+
+The effect of calling `add_one()` is that `b[0]` increases by 1, while `a` is unaffected.
 
 ## Exercises ##
 
-Now is a good time to practice the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
+Now is a good time to practice with the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
 
 ## Block ##
 It is often helpful to temporarily block program execution to inspect the graph. For this we can use the `mg.block()` function:
@@ -437,16 +444,21 @@ print( power_set(['a', 'b', 'c']) )
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
 
+## Invocation Tree ##
+The memory_graph package visualizes data at the currect time, but to better understand recursion it can also be helpful to visualize different function calls over time. This is what the [invocation_tree](https://github.com/bterwijn/invocation_tree?tab=readme-ov-file#installation) package does.
+
+See the power_set example in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
+
 # Debugging #
 
 For the best debugging experience with memory_graph set for example expression:
 ```
 mg.render(locals(), "my_graph.pdf")
 ```
-as a *watch* in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
+as a **watch** in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
 
 ## Call Stack in Watch Context ##
-The ```mg.stack()``` doesn't work well in *watch* context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
+The ```mg.stack()``` doesn't work well in **watch** context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
 
 | debugger | function to get the call stack in 'watch' context |
 |:---|:---|
@@ -460,7 +472,7 @@ The ```mg.stack()``` doesn't work well in *watch* context in most debuggers beca
 See the [Quick Intro (3:49)](https://www.youtube.com/watch?v=23_bHcr7hqo) video for the setup.
 
 ## Other Debuggers ##
-For other debuggers, invoke this function within the *watch* context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
+For other debuggers, invoke this function within the **watch** context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
 ```
 mg.save_call_stack("call_stack.txt")
 ```
@@ -908,6 +920,53 @@ mg.config.type_to_node[List_View] = lambda data: mg.Node_Linear(data,
 ```
 ![bin_search_linear.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bin_search_linear.png)
 
+## Bitwise Operators ##
+In this configuration example we show the decimal, binary and [two's complement representation](https://www.cs.cornell.edu/~tomf/notes/cps104/twoscomp.html) representation of `int` values of dictionary subclass `Bits` to show the result of [bitwise operators](https://docs.python.org/3/library/stdtypes.html?utm_source=chatgpt.com#bitwise-operations-on-integer-types). The `~` (inverse) operator can be a bit confusing if not shown with two's complement representation.
+
+```python
+import memory_graph as mg
+
+class Bits(dict):
+   """ Dictionary subclass that we will configure to show binary representations. """
+
+def twos_complement(x: int, bits: int) -> str:
+    """Return the two's complement bit string of x in `bits` bits."""
+    mask = (1 << bits) - 1
+    return format(x & mask, f"0{bits}b")
+
+# configure memory_graph to show binary representations of values of type Bits
+mg.config.type_to_node[Bits] = lambda x : mg.Node_Table(x,
+    [ ["expression", "decimal", "bin(expression)", "16bit two's complement"] ] +
+    [ [k, f'{v:>10}', f'{bin(v):>19}', twos_complement(v,16)] for k, v in x.items()] )
+mg.config.type_to_slicer[Bits] = (mg.Slicer(), mg.Slicer())  # no slicing
+mg.config.type_to_color[Bits] = 'gold'
+mg.config.fontname = 'Courier' # monospace font
+
+bits = Bits()
+
+# now add some some variables and expressions
+bits['a'] = 1
+bits['b'] = 48
+bits['c'] = 127
+bits['a << 3'] = bits['a'] << 3         # bit shift left by 3
+bits['b >> 3'] = bits['b'] >> 3         # bit shift right by 3
+bits['a | b']  = bits['a'] | bits['b']  # bitwise or
+bits['b & c']  = bits['b'] & bits['c']  # bitwise and
+bits['b ^ c']  = bits['b'] ^ bits['c']  # bitwise exclusive or
+
+# negative numbers, inverse, and two's complement
+bits['d'] = 240
+bits['e'] = -240
+bits['f'] = -241                        # -(d+1)
+bits['~d'] = ~ bits['d']                # inverse -(x+1)
+bits['~e'] = ~ bits['e']                # inverse -(x+1)
+bits['~f'] = ~ bits['f']                # inverse -(x+1)
+
+mg.s()
+```
+![bitwise_operators.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bitwise_operators.png)
+
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bitwise_operators.py&breakpoints=22&continues=1&play)
 
 # Graph Depth #
 To limit the size of the graph the maximum depth of the graph is set by `mg.config.max_graph_depth`. Additionally for each type a depth can be set to further limit the graph, as is done for type `B` in the example below. Scissors indicate where the graph is cut short. Alternatively the `id()` of a data elements can be used to limit the graph for that specific element, as is done for the value referenced by variable `c`.

memory_graph-0.3.61/images/bitwise_operators.py

@@ -0,0 +1,39 @@
+import memory_graph as mg
+
+class Bits(dict):
+   """ Dictionary subclass that we will configure to show binary representations. """
+
+def twos_complement(x: int, bits: int) -> str:
+    """Return the two's complement bit string of x in `bits` bits."""
+    mask = (1 << bits) - 1
+    return format(x & mask, f"0{bits}b")
+
+# configure memory_graph to show binary representations of values of type Bits
+mg.config.type_to_node[Bits] = lambda x : mg.Node_Table(x,
+   [ ["expression", "decimal", "bin(expression)", "16bit two's complement"] ] +
+   [ [k, f'{v:>10}', f'{bin(v):>19}', twos_complement(v,16)] for k, v in x.items()] )
+mg.config.type_to_slicer[Bits] = (mg.Slicer(), mg.Slicer())  # no slicing
+mg.config.type_to_color[Bits] = 'gold'
+mg.config.fontname = 'Courier' # monospace font
+
+bits = Bits()
+
+# now add some some variables and expressions
+bits['a'] = 1
+bits['b'] = 48
+bits['c'] = 127
+bits['a << 3'] = bits['a'] << 3         # bit shift left by 3
+bits['b >> 3'] = bits['b'] >> 3         # bit shift right by 3
+bits['a | b']  = bits['a'] | bits['b']  # bitwise or
+bits['b & c']  = bits['b'] & bits['c']  # bitwise and
+bits['b ^ c']  = bits['b'] ^ bits['c']  # bitwise exclusive or
+
+# negative numbers, inverse, and two's complement
+bits['d'] = 240
+bits['e'] = -240
+bits['f'] = -241                        # -(d+1)
+bits['~d'] = ~ bits['d']                # inverse -(x+1)
+bits['~e'] = ~ bits['e']                # inverse -(x+1)
+bits['~f'] = ~ bits['f']                # inverse -(x+1)
+
+mg.render(locals(), 'bitwise_operators.png')

{memory_graph-0.3.59 → memory_graph-0.3.61}/images/create_images.sh

@@ -35,6 +35,7 @@ python not_node_types.py
 # introspection
 python avltree.py
 python bin_search.py
+python bitwise_operators.py
 python introspect_depth.py
 python hidden_edges.py
 

{memory_graph-0.3.59 → memory_graph-0.3.61}/memory_graph/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) 2023, Bas Terwijn.
 # SPDX-License-Identifier: BSD-2-Clause
 
-__version__ = "0.3.59"
+__version__ = "0.3.61"
 __author__ = 'Bas Terwijn'
 
 import memory_graph.memory_to_nodes as memory_to_nodes

{memory_graph-0.3.59 → memory_graph-0.3.61}/memory_graph/config_default.py

@@ -85,8 +85,8 @@ def reset():
         # ================= singular
         type(None) : "gray",
         bool : "pink",
-        int : "green",
-        float : "violetred1",
+        int : "darkolivegreen1",
+        float : "plum",
         complex : "yellow",
         str : "cyan",
         # ================= linear

{memory_graph-0.3.59 → memory_graph-0.3.61}/memory_graph/sequence.py

@@ -92,8 +92,13 @@ class Sequence2D(Sequence):
             slicer0, slicer1 = slicer0
         else:
             slicer1 = slicer0
-        slices0 = slicer0.get_slices( len(self.data) )
-        slices1 = slicer1.get_slices( len(self.data[0]) )
+        s0, s1 = 0, 0
+        lens1 = len(self.data[0])
+        if lens1 > 0: # has any data
+            s1 = lens1
+            s0 = len(self.data)
+        slices0 = slicer0.get_slices( s0 )
+        slices1 = slicer1.get_slices( s1 )
         return Slices2D(slices0, slices1)
 
     def indices_all(self):

{memory_graph-0.3.59 → memory_graph-0.3.61}/memory_graph/slices_table_iterator.py

@@ -60,6 +60,7 @@ class Slices_Table_Iterator2D(Slices_Table_Iterator):
                 yield (-3, -3)
             for row_i in range(row_slice[0], row_slice[1]):
                 first_col_slice = True
+                col_i = 0
                 for col_slice in col_slices:
                     if first_col_slice:
                         if len(col_slices) > 0 and col_slice[0] > 0:

{memory_graph-0.3.59 → memory_graph-0.3.61/memory_graph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory_graph
-Version: 0.3.59
+Version: 0.3.61
 Summary: Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy.
 Author-email: Bas Terwijn <bterwijn@gmail.com>
 License-Expression: BSD-2-Clause
@@ -151,6 +151,8 @@ Bas Terwijn
 ## Inspiration ##
 Inspired by [Python Tutor](https://pythontutor.com/).
 
+The main difference are that running memory_graph locally is a key design choice to support Python Tutor’s [unsupported features](https://github.com/pythontutor-dev/pythontutor/blob/master/unsupported-features.md#unsupported-features) and mirroring the data’s hierarchy improves graph readability.
+
 ## Social Media #
 * [LinkedIn](https://www.linkedin.com/groups/13244150/)
 * [Reddit](https://www.reddit.com/r/Python_memory_graph/)
@@ -169,7 +171,7 @@ Learn the right **mental model** to think about Python data. The [Python Data Mo
 
 
 ## Immutable Type ##
-In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an immutable type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
+In the code below variable `a` and `b` both reference the same tuple value (4, 3, 2). A tuple is an **immutable** type and therefore when we change variable `b` its value **cannot** be mutated in place, and thus an automatic copy is made and `a` and `b` each reference their own value afterwards.
 
 ```python
 import memory_graph as mg
@@ -187,7 +189,7 @@ mg.render(locals(), 'immutable2.png')
 
 
 ## Mutable Type ##
-With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a mutable type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
+With mutable types the result is different. In the code below variable `a` and `b` both reference the same `list` value [4, 3, 2]. A `list` is a **mutable** type and therefore when we change variable `b` its value **can** be mutated in place and thus `a` and `b` both reference the same new value afterwards. Thus changing `b` also changes `a` and vice versa. Sometimes we want this but other times we don't and then we will have to make a copy ourselfs so that `a` and `b` are independent.
 
 ```python
 import memory_graph as mg
@@ -228,6 +230,7 @@ mg.show(locals())
 
 ![copy_mutbale.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/copy_mutable.png)
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/copies.py&play).
 
 ## Custom Copy ##
 We can write our own custom copy function or method in case the three standard "copy" options don't do what we want. For example, in the code below the `custom_copy()` method of My_Class copies the `digits` but shares the `letters` between two objects.
@@ -258,7 +261,7 @@ mg.show(locals())
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/custom_copy.py&breakpoints=15&continues=1&play).
 
 ## Name Rebinding ##
-When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only rebind the name `b` to another value without effecting any other variables.
+When `a` and `b` share a mutable value, then changing the value of `b` changes the value of `a` and vice versa. However, reassigning `b` does not change `a`. When you reassign `b`, you only **rebind** the name `b` to another value without affecting any other variables.
 
 ```python
 import memory_graph as mg
@@ -268,13 +271,15 @@ b = a
 mg.render(locals(), 'rebinding1.png')
 
 b += [1]        # changes the value of 'b' and 'a'
-b = [100, 200]  # rebinds 'b' to another value, 'a' is uneffected
+b = [100, 200]  # rebinds 'b' to another value, 'a' is unaffected
 mg.render(locals(), 'rebinding2.png')
 ```
 | ![rebinding1.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding1.png) | ![rebinding2.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/rebinding2.png) |
 |:-----------------------------------------------------------:|:-------------------------------------------------------------:|
 | rebinding1.png | rebinding2.png |
 
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/rebind.py&play).
+
 ## Copying Values of Immutable Type ## 
 Because a value of immutable type will be copied automatically when it is changed, there is no need to copy it beforehand. Therefore, a shallow or deep copy of a value of immutable type will result in just an assignment to save on the time needed to make the copy and the space (=memory) needed to store the values.
 
@@ -333,7 +338,7 @@ print(f"a:{a} b:{b} c:{c}")
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/function_call.py&play).
 
-In the printed output only `a` is changed as a result of the function call:
+In the printed output we see that only `a` is changed as a result of the function call:
 ```
 a:[4, 3, 2, 1] b:(4, 3, 2) c:[4, 3, 2]
 ```
@@ -347,7 +352,7 @@ import memory_graph as mg
 
 def add_one(a, b):
     a += 1     # change remains confined to 'a' in the add_one function
-    b[0] += 1  # change also effects 'b' outside of the add_one function
+    b[0] += 1  # change also affects 'b' outside of the add_one function
     mg.show(mg.stack())
 
 a = 10
@@ -360,11 +365,13 @@ print(f"a:{a} b:{b[0]}")
 ```
 a:10 b:11
 ```
-Calling `add_one()` does not effect the `int` value of `a` but does effect the `int` value of `b` because it's wrapped in a mutable container.
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/wrap.py&breakpoints=5&continues=1&play)
+
+The effect of calling `add_one()` is that `b[0]` increases by 1, while `a` is unaffected.
 
 ## Exercises ##
 
-Now is a good time to practice the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
+Now is a good time to practice with the Python Data Model. Here are [some exercises](https://github.com/bterwijn/memory_graph_videos/blob/main/exercises/exercises.md) on references, mutability, copies, and function calls.
 
 ## Block ##
 It is often helpful to temporarily block program execution to inspect the graph. For this we can use the `mg.block()` function:
@@ -457,16 +464,21 @@ print( power_set(['a', 'b', 'c']) )
 
 Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
 
+## Invocation Tree ##
+The memory_graph package visualizes data at the currect time, but to better understand recursion it can also be helpful to visualize different function calls over time. This is what the [invocation_tree](https://github.com/bterwijn/invocation_tree?tab=readme-ov-file#installation) package does.
+
+See the power_set example in the [Invocation Tree Web Debugger](https://www.invocation-tree.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/power_set.py&timestep=1.0&play).
+
 # Debugging #
 
 For the best debugging experience with memory_graph set for example expression:
 ```
 mg.render(locals(), "my_graph.pdf")
 ```
-as a *watch* in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
+as a **watch** in a debugger tool such as the integrated debugger in Visual Studio Code. Then open the "my_graph.pdf" output file to continuously see all the local variables while debugging. This avoids having to add any memory_graph `show()` or `render()` calls to your code.
 
 ## Call Stack in Watch Context ##
-The ```mg.stack()``` doesn't work well in *watch* context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
+The ```mg.stack()``` doesn't work well in **watch** context in most debuggers because debuggers introduce additional stack frames that cause problems. Use these alternative functions for various debuggers to filter out these problematic stack frames:
 
 | debugger | function to get the call stack in 'watch' context |
 |:---|:---|
@@ -480,7 +492,7 @@ The ```mg.stack()``` doesn't work well in *watch* context in most debuggers beca
 See the [Quick Intro (3:49)](https://www.youtube.com/watch?v=23_bHcr7hqo) video for the setup.
 
 ## Other Debuggers ##
-For other debuggers, invoke this function within the *watch* context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
+For other debuggers, invoke this function within the **watch** context. Then, in the "call_stack.txt" file, identify the slice of functions you wish to include as stack frames in the call stack.
 ```
 mg.save_call_stack("call_stack.txt")
 ```
@@ -928,6 +940,53 @@ mg.config.type_to_node[List_View] = lambda data: mg.Node_Linear(data,
 ```
 ![bin_search_linear.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bin_search_linear.png)
 
+## Bitwise Operators ##
+In this configuration example we show the decimal, binary and [two's complement representation](https://www.cs.cornell.edu/~tomf/notes/cps104/twoscomp.html) representation of `int` values of dictionary subclass `Bits` to show the result of [bitwise operators](https://docs.python.org/3/library/stdtypes.html?utm_source=chatgpt.com#bitwise-operations-on-integer-types). The `~` (inverse) operator can be a bit confusing if not shown with two's complement representation.
+
+```python
+import memory_graph as mg
+
+class Bits(dict):
+   """ Dictionary subclass that we will configure to show binary representations. """
+
+def twos_complement(x: int, bits: int) -> str:
+    """Return the two's complement bit string of x in `bits` bits."""
+    mask = (1 << bits) - 1
+    return format(x & mask, f"0{bits}b")
+
+# configure memory_graph to show binary representations of values of type Bits
+mg.config.type_to_node[Bits] = lambda x : mg.Node_Table(x,
+    [ ["expression", "decimal", "bin(expression)", "16bit two's complement"] ] +
+    [ [k, f'{v:>10}', f'{bin(v):>19}', twos_complement(v,16)] for k, v in x.items()] )
+mg.config.type_to_slicer[Bits] = (mg.Slicer(), mg.Slicer())  # no slicing
+mg.config.type_to_color[Bits] = 'gold'
+mg.config.fontname = 'Courier' # monospace font
+
+bits = Bits()
+
+# now add some some variables and expressions
+bits['a'] = 1
+bits['b'] = 48
+bits['c'] = 127
+bits['a << 3'] = bits['a'] << 3         # bit shift left by 3
+bits['b >> 3'] = bits['b'] >> 3         # bit shift right by 3
+bits['a | b']  = bits['a'] | bits['b']  # bitwise or
+bits['b & c']  = bits['b'] & bits['c']  # bitwise and
+bits['b ^ c']  = bits['b'] ^ bits['c']  # bitwise exclusive or
+
+# negative numbers, inverse, and two's complement
+bits['d'] = 240
+bits['e'] = -240
+bits['f'] = -241                        # -(d+1)
+bits['~d'] = ~ bits['d']                # inverse -(x+1)
+bits['~e'] = ~ bits['e']                # inverse -(x+1)
+bits['~f'] = ~ bits['f']                # inverse -(x+1)
+
+mg.s()
+```
+![bitwise_operators.png](https://raw.githubusercontent.com/bterwijn/memory_graph/main/images/bitwise_operators.png)
+
+Or see it in the [Memory Grah Web Debugger](https://memory-graph.com/#codeurl=https://raw.githubusercontent.com/bterwijn/memory_graph/refs/heads/main/src/bitwise_operators.py&breakpoints=22&continues=1&play)
 
 # Graph Depth #
 To limit the size of the graph the maximum depth of the graph is set by `mg.config.max_graph_depth`. Additionally for each type a depth can be set to further limit the graph, as is done for type `B` in the example below. Scissors indicate where the graph is cut short. Alternatively the `id()` of a data elements can be used to limit the graph for that specific element, as is done for the value referenced by variable `c`.

{memory_graph-0.3.59 → memory_graph-0.3.61}/memory_graph.egg-info/SOURCES.txt

@@ -20,6 +20,8 @@ images/bin_tree.png
 images/bin_tree.py
 images/binary.gif
 images/binary.py
+images/bitwise_operators.png
+images/bitwise_operators.py
 images/colab_example.png
 images/copy_immutable.png
 images/copy_immutable.py

{memory_graph-0.3.59 → memory_graph-0.3.61}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory_graph"
-version = "0.3.59"
+version = "0.3.61"
 description = "Teaching tool and debugging aid in context of references, mutable data types, and shallow and deep copy."
 authors = [
     {name = "Bas Terwijn", email = "bterwijn@gmail.com"}