Merge pull request #93 from braboj/codex/add-header-to-dunder-methods-examples

Add explanatory headers to dunder examples

Author: braboj

examples/15_dunder_methods/__init__.py

@@ -0,0 +1,3 @@
+# Dunder method examples
+# ---------------------------------------------------------------------------
+# Examples demonstrating how special methods customize object behavior

examples/15_dunder_methods/demo_iterator.py

@@ -1,11 +1,10 @@
-"""
-* An iterable is an object that implements the __iter__ method which returns an iterator.
-* An iterator is an object that implements the __iter__ method which returns itself and the __next__ method which
-returns the next element.
-
-https://www.pythontutorial.net/advanced-python/python-iterator-vs-iterable/
-
-"""
+# Dunder methods and iteration
+# ---------------------------------------------------------------------------
+# Demonstrates how special methods customize iteration behavior.
+# * An iterable implements __iter__ returning an iterator.
+# * An iterator implements __iter__ returning itself and __next__ returning
+#   the next element.
+# https://www.pythontutorial.net/advanced-python/python-iterator-vs-iterable/
 
 
 ##################################################################################################

examples/15_dunder_methods/dunder_arithmetic_operators.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for arithmetic operators
+# Dunder methods for arithmetic operators
+# ---------------------------------------------------------------------------
+# By defining special arithmetic methods, objects can participate in Python's
+# numeric operations. These dunder hooks let a class customize how instances
+# respond to +, -, *, and other operators.
 
 class Complex(object):
 

examples/15_dunder_methods/dunder_attributes.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for context manager
+# Dunder methods for attribute access
+# ---------------------------------------------------------------------------
+# Attribute related dunder methods such as __getattr__, __setattr__ and
+# __delattr__ give objects dynamic control over attribute access. They enable
+# customized lookup, assignment and deletion behavior.
 
 class Complex(object):
 

examples/15_dunder_methods/dunder_builtin_types.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for object representation
+# Dunder methods for object representation
+# ---------------------------------------------------------------------------
+# Built-in type conversion functions like bool(), int() and bytes() call
+# corresponding dunder methods on objects. Implementing these hooks lets a
+# class define how it converts to fundamental Python types.
 
 import struct
 import math

examples/15_dunder_methods/dunder_context_manager.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for context manager
+# Dunder methods for context manager
+# ---------------------------------------------------------------------------
+# The __enter__ and __exit__ methods allow an object to define its own
+# setup and teardown logic when used in a with-statement. This example shows
+# how implementing these hooks customizes resource management behavior.
 
 class Complex(object):
 

examples/15_dunder_methods/dunder_customize_behavior.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for customizing object behavior
+# Dunder methods for customizing object behavior
+# ---------------------------------------------------------------------------
+# This script demonstrates several special methods that hook into object
+# creation, calling and destruction. Implementing these dunder methods lets a
+# class take control over how instances are created, invoked and cleaned up.
 
 class TestClass(object):
 

examples/15_dunder_methods/dunder_iterator_protocol.py

@@ -1,4 +1,9 @@
-# Example: Dunder methods for the iterator protocol
+# Dunder methods for the iterator protocol
+# ---------------------------------------------------------------------------
+# Special (dunder) methods allow objects to integrate with Python features.
+# By implementing __iter__ and __next__, this class customizes iteration
+# behavior so that instances work seamlessly in for-loops and other iterable
+# contexts.
 
 class Stack(object):
 

examples/15_dunder_methods/dunder_object_representation.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for object representation
+# Dunder methods for object representation
+# ---------------------------------------------------------------------------
+# Special representation methods like __repr__ and __str__ let objects control
+# how they are displayed. This example highlights how these hooks customize the
+# string and byte output of a class.
 
 import struct
 

examples/15_dunder_methods/dunder_operator_overloading.py

@@ -1,4 +1,8 @@
-# Example: Dunder methods for operator overloading
+# Dunder methods for operator overloading
+# ---------------------------------------------------------------------------
+# Overloading arithmetic operators with dunder methods allows custom classes
+# to behave like built-in numeric types. The following Point class defines
+# how instances react to +, -, * and other operations.
 
 class Point(object):