feat(python): add Python bindings and wrappers

[hakula139]

No description provided.

[Copilot]

Pull Request Overview

This PR adds comprehensive Python bindings for C++ features, providing a modern Python wrapper that showcases Python 3.13 features like pattern matching, enhanced error handling, and improved type hints. The bindings cover timing, shapes, random generation, memory management, exception handling, containers, and algorithms.

Key Changes

• Added modern Python wrappers with type hints and pattern matching for all C++ modules
• Implemented comprehensive test suites following C++ test patterns for Python functionality
• Created detailed examples demonstrating real-world usage of the Python bindings

Reviewed Changes

Copilot reviewed 42 out of 43 changed files in this pull request and generated 6 comments.

File	Description
tests/CMakeLists.txt	Updated comment from "Check if" to "Ensure Catch2 is available"
python/tests/*	Complete test suite covering all modules with comprehensive unit and integration tests
python/src/*	Modern Python wrappers for timing, shapes, random, memory, exceptions, containers, and algorithms
python/examples/*	Detailed example scripts demonstrating usage patterns and best practices

[Copilot]

The assertion logic is incorrect. Nanoseconds should be greater than or equal to microseconds, but the relationship should be ns >= us * 1000, not ns >= us. A value of 1000 ns equals 1 us, so ns values should typically be much larger than us values.

Suggested change

	assert ns >= us # ns should be >= us (1000x conversion)
	assert ns >= us * 1000 # ns should be >= us * 1000 (1000x conversion)

[Copilot]

The assertion logic is incorrect. Microseconds should be greater than or equal to milliseconds, but the relationship should be us >= ms * 1000, not us >= ms. A value of 1000 us equals 1 ms, so us values should typically be much larger than ms values.

Suggested change

	assert us >= ms # us should be >= ms (1000x conversion)
	assert us >= ms * 1000 # us should be >= ms * 1000 (1000x conversion)

[Copilot]

The assertion logic is incorrect. Milliseconds should be greater than or equal to seconds, but the relationship should be ms >= s * 1000, not ms >= s. A value of 1000 ms equals 1 s, so ms values should typically be much larger than s values.

Suggested change

	assert ms >= s # ms should be >= s (1000x conversion)
	assert ms >= s * 1000 # ms should be >= s * 1000 (1000x conversion)

[Copilot]

The code attempts to access a 'most_efficient' key from the comparison dictionary, but the compare_shapes function in shapes.py does not return this key. Only 'largest_by_area', 'smallest_by_area', 'average_area', etc. are returned.

Suggested change

	print(f' - Most efficient shape: {comparison["most_efficient"].get_name()}')
	# Compute the most efficient shape manually
	most_efficient_shape = max(shapes, key=lambda s: analyze_shape(s).efficiency)
	print(f' - Most efficient shape: {most_efficient_shape.get_name()}')

[Copilot]

The code attempts to access an 'efficiency' attribute from ShapeMetrics, but the ShapeMetrics dataclass only has area, perimeter, name, and aspect_ratio attributes. There is no 'efficiency' property defined.

Suggested change

	print(f' - Efficiency: {circle_metrics.efficiency:.4f}')
	print(f'Rectangle analysis:')
	print(f' - Area: {rectangle_metrics.area:.2f}')
	print(f' - Perimeter: {rectangle_metrics.perimeter:.2f}')
	print(f' - Aspect ratio: {rectangle_metrics.aspect_ratio:.4f}')
	print(f' - Efficiency: {rectangle_metrics.efficiency:.4f}')
	print(f'Rectangle analysis:')
	print(f' - Area: {rectangle_metrics.area:.2f}')
	print(f' - Perimeter: {rectangle_metrics.perimeter:.2f}')
	print(f' - Aspect ratio: {rectangle_metrics.aspect_ratio:.4f}')

[Copilot]

The code attempts to access an 'efficiency' attribute from ShapeMetrics, but the ShapeMetrics dataclass only has area, perimeter, name, and aspect_ratio attributes. There is no 'efficiency' property defined.

Suggested change

	print(f' - Efficiency: {circle_metrics.efficiency:.4f}')
	print(f'Rectangle analysis:')
	print(f' - Area: {rectangle_metrics.area:.2f}')
	print(f' - Perimeter: {rectangle_metrics.perimeter:.2f}')
	print(f' - Aspect ratio: {rectangle_metrics.aspect_ratio:.4f}')
	print(f' - Efficiency: {rectangle_metrics.efficiency:.4f}')
	print(f' - Efficiency: {circle_metrics.area / (circle_metrics.perimeter ** 2):.4f}')
	print(f'Rectangle analysis:')
	print(f' - Area: {rectangle_metrics.area:.2f}')
	print(f' - Perimeter: {rectangle_metrics.perimeter:.2f}')
	print(f' - Aspect ratio: {rectangle_metrics.aspect_ratio:.4f}')
	print(f' - Efficiency: {rectangle_metrics.area / (rectangle_metrics.perimeter ** 2):.4f}')