Refine script headers

braboj · braboj · commit bad3b20ffb5b · 2025-06-11T09:48:55.000+03:00
diff --git a/examples/16_data_types/comprehension_dictionary.py b/examples/16_data_types/comprehension_dictionary.py
@@ -1,4 +1,6 @@
-# Example dictionary comprehension
+# Dictionary comprehensions
+# -----------------------------------------------------------------------------
+# Dictionary comprehensions let you construct mappings concisely. They are ideal for transforming one form of data into key/value pairs.
 
 existing_list = [1, 2, 3, 4, 5]
 existing_dictionary = {1: "junior", 2: "mid", 3: "c", 4: "d", 5: "e"}
diff --git a/examples/16_data_types/comprehension_list.py b/examples/16_data_types/comprehension_list.py
@@ -1,4 +1,6 @@
-# Example list comprehension
+# List comprehensions
+# -----------------------------------------------------------------------------
+# List comprehensions allow you to create or filter lists concisely without explicit loops.
 
 existing_list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 
diff --git a/examples/16_data_types/data_array.py b/examples/16_data_types/data_array.py
@@ -1,4 +1,6 @@
-# Example: Array of data
+# Efficient arrays
+# -----------------------------------------------------------------------------
+# The array module stores numeric values more efficiently than lists because all elements share the same type.
 
 import array
 
diff --git a/examples/16_data_types/data_base64.py b/examples/16_data_types/data_base64.py
@@ -1,4 +1,6 @@
-# Example: Base64 Encoding and Decoding
+# Base64 encoding
+# -----------------------------------------------------------------------------
+# Base64 converts binary data to ASCII text. This is handy when transmitting bytes over text-based protocols.
 
 import base64
 
diff --git a/examples/16_data_types/data_binascii.py b/examples/16_data_types/data_binascii.py
@@ -1,4 +1,6 @@
-# Example: binascii module
+# Binary-to-ASCII conversions
+# -----------------------------------------------------------------------------
+# The binascii module exposes low-level routines for converting between binary data and various ASCII encodings.
 
 
 import binascii
diff --git a/examples/16_data_types/data_chainmap.py b/examples/16_data_types/data_chainmap.py
@@ -1,4 +1,6 @@
-# Example: ChainMap
+# Combining dictionaries with ChainMap
+# -----------------------------------------------------------------------------
+# ChainMap lets you combine several dictionaries into a single view without copying them.
 
 from collections import ChainMap
 
diff --git a/examples/16_data_types/data_codecs.py b/examples/16_data_types/data_codecs.py
@@ -1,4 +1,6 @@
-# Example: codecs module
+# Encoding text with codecs
+# -----------------------------------------------------------------------------
+# The codecs module provides tools for encoding and decoding streams of text in different character sets.
 
 import codecs
 import pprint
diff --git a/examples/16_data_types/data_codecs_custom.py b/examples/16_data_types/data_codecs_custom.py
@@ -1,4 +1,6 @@
-# Example: Custom Codec
+# Custom codecs
+# -----------------------------------------------------------------------------
+# Registering a custom codec allows you to handle data stored in a specialized encoding.
 
 import codecs
 
diff --git a/examples/16_data_types/data_copying.py b/examples/16_data_types/data_copying.py
@@ -1,4 +1,6 @@
-# Example: Data Copying
+# Deep and shallow copying
+# -----------------------------------------------------------------------------
+# Shallow and deep copying let you duplicate complex objects without affecting the originals.
 
 import copy
 
diff --git a/examples/16_data_types/data_counter_class.py b/examples/16_data_types/data_counter_class.py
@@ -1,4 +1,6 @@
-# Example: Counter class
+# Counting with Counter
+# -----------------------------------------------------------------------------
+# A Counter is a dictionary subclass for tallying hashable objects quickly.
 
 from collections import Counter
 
diff --git a/examples/16_data_types/data_dataclass.py b/examples/16_data_types/data_dataclass.py
@@ -1,4 +1,6 @@
-# Example: Data Classes (only Python 3.7+)
+# Lightweight data classes
+# -----------------------------------------------------------------------------
+# Dataclasses eliminate boilerplate when defining classes meant primarily to store data.
 
 import dataclasses
 from dataclasses import dataclass, field
diff --git a/examples/16_data_types/data_defaultdict.py b/examples/16_data_types/data_defaultdict.py
@@ -1,4 +1,6 @@
-# Example: defaultdict data structure
+# Automatic keys with defaultdict
+# -----------------------------------------------------------------------------
+# defaultdict automatically creates missing keys so your code doesn't need explicit checks.
 
 from collections import defaultdict
 
diff --git a/examples/16_data_types/data_deque_fifo.py b/examples/16_data_types/data_deque_fifo.py
@@ -1,4 +1,6 @@
-# Example: FIFO deque data structure
+# Deque as FIFO queue
+# -----------------------------------------------------------------------------
+# Deque offers fast O(1) operations at both ends, making it ideal for implementing queues.
 
 from collections import deque
 
diff --git a/examples/16_data_types/data_deque_lifo.py b/examples/16_data_types/data_deque_lifo.py
@@ -1,4 +1,6 @@
-# Example: LIFO deque data structure
+# Deque as LIFO stack
+# -----------------------------------------------------------------------------
+# Using deque as a stack provides efficient push and pop operations.
 
 from collections import deque
 
diff --git a/examples/16_data_types/data_dill.py b/examples/16_data_types/data_dill.py
@@ -1,4 +1,6 @@
-# Example: Serializing and Deserializing Objects with Pickle
+# Serializing with dill
+# -----------------------------------------------------------------------------
+# dill extends pickle and can serialize a wider range of Python objects.
 
 import dill
 import sys
diff --git a/examples/16_data_types/data_filtering.py b/examples/16_data_types/data_filtering.py
@@ -1,4 +1,6 @@
-# Example: Filter Data using the filter() function
+# Filtering with filter()
+# -----------------------------------------------------------------------------
+# The built-in filter() returns elements for which a function returns True.
 
 
 def is_even(x):
diff --git a/examples/16_data_types/data_heapq.py b/examples/16_data_types/data_heapq.py
@@ -1,4 +1,6 @@
-# Example: heapq as a priority queue
+# heapq priority queue
+# -----------------------------------------------------------------------------
+# A heap lets you maintain a priority queue with O(log n) push/pop operations.
 
 import heapq
 
diff --git a/examples/16_data_types/data_mapping.py b/examples/16_data_types/data_mapping.py
@@ -1,4 +1,6 @@
-# Example: Filter Data using the filter() function
+# Mapping with map()
+# -----------------------------------------------------------------------------
+# map() applies a function to every element of an iterable, returning the results.
 
 
 def sqr(x):
diff --git a/examples/16_data_types/data_namedtuple.py b/examples/16_data_types/data_namedtuple.py
@@ -1,4 +1,6 @@
-# Example: namedtuple data structure
+# Named tuples
+# -----------------------------------------------------------------------------
+# namedtuples give tuple-like objects readable field names without extra overhead.
 
 from collections import namedtuple
 
diff --git a/examples/16_data_types/data_ordered_dict.py b/examples/16_data_types/data_ordered_dict.py
@@ -1,4 +1,6 @@
-# Example: OrderedDict
+# Ordered dictionaries
+# -----------------------------------------------------------------------------
+# OrderedDict remembers the insertion order of keys, which can be useful for reproducible iteration.
 
 from collections import OrderedDict
 
diff --git a/examples/16_data_types/data_packing.py b/examples/16_data_types/data_packing.py
@@ -1,4 +1,6 @@
-# Example: Packing Data using the * and ** operators
+# Packing *args and **kwargs
+# -----------------------------------------------------------------------------
+# Packing arguments allows functions to accept an arbitrary number of positional or keyword parameters.
 
 def func1(*args):
 
diff --git a/examples/16_data_types/data_pickle.py b/examples/16_data_types/data_pickle.py
@@ -1,4 +1,6 @@
-# Example: Serializing and Deserializing Objects with Pickle
+# Object serialization with pickle
+# -----------------------------------------------------------------------------
+# pickle serializes and deserializes Python objects so they can be saved and restored later.
 
 import pickle
 import sys
diff --git a/examples/16_data_types/data_queue_fifo.py b/examples/16_data_types/data_queue_fifo.py
@@ -1,4 +1,6 @@
-# Example: FIFO queue data structure
+# FIFO queue with Queue
+# -----------------------------------------------------------------------------
+# queue.Queue provides a thread-safe FIFO structure for coordinating producer/consumer workloads.
 
 from six.moves import queue
 
diff --git a/examples/16_data_types/data_queue_lifo.py b/examples/16_data_types/data_queue_lifo.py
@@ -1,4 +1,6 @@
-# Example: LIFO queue data structure
+# LIFO queue with LifoQueue
+# -----------------------------------------------------------------------------
+# LifoQueue behaves like a stack while remaining safe for use with multiple threads.
 
 from six.moves import queue
 
diff --git a/examples/16_data_types/data_queue_priority.py b/examples/16_data_types/data_queue_priority.py
@@ -1,4 +1,6 @@
-# Example: FIFO queue data structure
+# Priority queues
+# -----------------------------------------------------------------------------
+# PriorityQueue orders tasks by priority, letting the smallest value be retrieved first.
 
 from six.moves import queue
 
diff --git a/examples/16_data_types/data_reducing.py b/examples/16_data_types/data_reducing.py
@@ -1,4 +1,6 @@
-# Example: Reduce Data using the reduce() function
+# Aggregating with reduce()
+# -----------------------------------------------------------------------------
+# reduce() repeatedly applies a function to items, collapsing them into a single result.
 
 from functools import reduce
 
diff --git a/examples/16_data_types/data_reversing.py b/examples/16_data_types/data_reversing.py
@@ -1,4 +1,6 @@
-# Example: Filter Data using the filter() function
+# Reverse iteration
+# -----------------------------------------------------------------------------
+# The reversed() built-in returns an iterator that yields items from the end to the start.
 
 # Sample data
 sample_1 = [1, 2, 5, 4, 3]
diff --git a/examples/16_data_types/data_sorting.py b/examples/16_data_types/data_sorting.py
@@ -1,4 +1,6 @@
-# Example: Sort Data using the sorted() function
+# Sorting with sorted()
+# -----------------------------------------------------------------------------
+# sorted() creates a new sorted list from any iterable, optionally using a key function.
 
 class Book(object):
 
diff --git a/examples/16_data_types/data_struct.py b/examples/16_data_types/data_struct.py
@@ -1,4 +1,6 @@
-# Example: Serializing and Deserializing Objects with Pickle
+# Working with struct
+# -----------------------------------------------------------------------------
+# The struct module packs and unpacks binary data to interact with C-style structs.
 
 import struct
 
diff --git a/examples/16_data_types/data_struct_with_buffer.py b/examples/16_data_types/data_struct_with_buffer.py
@@ -1,4 +1,6 @@
-# Example: Serializing and Deserializing Objects with Pickle
+# Struct packing into buffers
+# -----------------------------------------------------------------------------
+# Packing directly into an existing buffer lets you build binary data without intermediate strings.
 
 import struct
 
diff --git a/examples/16_data_types/data_unpacking.py b/examples/16_data_types/data_unpacking.py
@@ -1,4 +1,6 @@
-# Example: Unpacking Arguments using the * operator and ** operator
+# Argument unpacking
+# -----------------------------------------------------------------------------
+# Unpacking with * and ** lets you pass iterables or mappings as arguments in a clean syntax.
 
 # A list of arguments
 pos_args = [1, 2, 3, 4]
diff --git a/examples/16_data_types/data_zipping.py b/examples/16_data_types/data_zipping.py
@@ -1,4 +1,6 @@
-# Example: Zipping Data using the zip() function
+# Pairing items with zip()
+# -----------------------------------------------------------------------------
+# zip() pairs elements from multiple iterables so you can iterate over them in lockstep.
 
 # Sample data
 numbers = [1, 2, 3]
diff --git a/examples/16_data_types/unpack_dict.py b/examples/16_data_types/unpack_dict.py
@@ -1,3 +1,6 @@
+# Dictionary unpacking
+# -----------------------------------------------------------------------------
+# The * operator can expand a mapping's items into function arguments or into new dictionaries.
 """
 https://realpython.com/python-kwargs-and-args/#unpacking-with-the-asterisk-operators
 """
diff --git a/examples/16_data_types/unpack_list.py b/examples/16_data_types/unpack_list.py
@@ -1,3 +1,6 @@
+# List unpacking
+# -----------------------------------------------------------------------------
+# Using * with a list expands its items when calling a function.
 """
 https://realpython.com/python-kwargs-and-args/#unpacking-with-the-asterisk-operators
 """
@@ -16,4 +19,4 @@
 first = [1, 2, 3]
 second = [4, 5, 6]
 merged = [*first, *second]
-print(merged)
+print(merged)
diff --git a/examples/16_data_types/unpack_snippets.py b/examples/16_data_types/unpack_snippets.py
@@ -1,3 +1,6 @@
+# Unpacking snippets
+# -----------------------------------------------------------------------------
+# These small examples show how the * operator can gather or scatter items from sequences.
 test_string = "PYTHON"
 test_list = [1, 2, 3, 4]
 test_dict = {"A": 1, "B": 2}
@@ -17,4 +20,4 @@
 # Copy dictionary
 test = {**test_dict}
 print(test)
-print(test is test_dict)
+print(test is test_dict)
