Update CLAUDE.md and format code with Black and isort

Improve CLAUDE.md with comprehensive build/test commands and code style guidelines.
Apply code formatting across the repository for consistency.

Co-authored-by: Claude <[email protected]>
Closes: #5

Author: aygp-dr

CLAUDE.md

@@ -6,34 +6,27 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 - Install dependencies: `make install` or `poetry install`
 - Create virtual environment: `make venv` or `python3 -m venv venv`
-- Lint code: `make lint` or `poetry run flake8 .`
-- Format code: `poetry run black .` and `poetry run isort .`
+- Format code: `make format` or `poetry run black . && poetry run isort .`
+- Lint code: `make lint` or `poetry run flake8 . && poetry run mypy .`
+- Type check: `make typecheck` or `poetry run mypy .`
 - Run all tests: `make test` or `poetry run pytest tests/`
-- Run single test: `poetry run pytest tests/test_file.py::TestClass::test_method -v`
+- Run single test file: `make test-file FILE=tests/test_file.py` or `poetry run pytest tests/test_file.py -v`
+- Run single test function: `make test-function FILE=tests/test_file.py::test_function` or `poetry run pytest tests/test_file.py::TestClass::test_method -v`
 - Run tests in exercises: `cd exercises && poetry run pytest test_file.py`
 
 ## Code Style Guidelines
 
 - Use Python 3.11+ features and syntax
-- Follow PEP 8 style guidelines
-- Use Black for code formatting and isort for import sorting
-- Use type hints for function parameters and return values
-- Use docstrings for all classes and functions
+- Follow PEP 8 style guidelines with Black (line-length=88) and isort
+- Use strict type hints throughout (mypy with disallow_untyped_defs=true)
+- Use snake_case for variables/functions, PascalCase for classes
 - Organize imports: standard library, third-party, local
-- Use snake_case for variables and functions, PascalCase for classes
-- Prefer context managers for file handling
-- Use proper error handling with specific exceptions
-- Organize code using modules and packages appropriately
+- Include docstrings for all modules, classes, and functions
+- Use context managers for resource handling
+- Raise specific exceptions with descriptive messages
+- Validate input parameters with assertions or value checks
+- Structure code using modules and packages appropriately
 
-## Documentation Standards
+## Language Implementation Notes
 
-- Include a docstring for each module, class, and function
-- Use descriptive variable and function names
-- When creating examples, follow the existing patterns in the repository
-
-## Simple Language Implementation
-
-- The repository includes a simple language implementation with lexer, parser, and evaluator
-- Key components: TokenType, Token, Lexer, Parser, Symbol, Environment, Procedure, and Evaluator classes
-- The language supports basic arithmetic, conditionals, and functional programming constructs
-- The interpreter includes reflection capabilities and a meta-circular evaluator
+The repository includes a simple language implementation with lexer, parser, and evaluator supporting functional programming constructs and reflection capabilities.

abstract_base_classes.py

@@ -20,25 +20,26 @@
 """
 
 import abc
-from abc import ABC, abstractmethod
-from collections.abc import Sequence, Mapping
 import sys
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
 from typing import Protocol, runtime_checkable
 
+
 # Basic ABC Example
 class Shape(ABC):
     """Abstract base class representing a geometric shape."""
-    
+
     @abstractmethod
     def area(self):
         """Calculate the area of the shape."""
         pass
-    
+
     @abstractmethod
     def perimeter(self):
         """Calculate the perimeter of the shape."""
         pass
-    
+
     def describe(self):
         """Non-abstract method that subclasses inherit without overriding."""
         return f"This shape has area {self.area()} and perimeter {self.perimeter()}"
@@ -47,54 +48,56 @@ def describe(self):
 # Concrete implementation of Shape
 class Rectangle(Shape):
     """A rectangle implementation of the Shape ABC."""
-    
+
     def __init__(self, width, height):
         self.width = width
         self.height = height
-    
+
     def area(self):
         return self.width * self.height
-    
+
     def perimeter(self):
         return 2 * (self.width + self.height)
 
 
 class Circle(Shape):
     """A circle implementation of the Shape ABC."""
-    
+
     def __init__(self, radius):
         self.radius = radius
-    
+
     def area(self):
         import math
-        return math.pi * self.radius ** 2
-    
+
+        return math.pi * self.radius**2
+
     def perimeter(self):
         import math
+
         return 2 * math.pi * self.radius
 
 
 # Abstract Properties Example
 class DataSource(ABC):
     """Abstract base class for data sources with required properties."""
-    
+
     @property
     @abstractmethod
     def name(self):
         """The name of the data source."""
         pass
-    
+
     @property
     @abstractmethod
     def connection_string(self):
         """The connection string for the data source."""
         pass
-    
+
     @abstractmethod
     def connect(self):
         """Connect to the data source."""
         pass
-    
+
     @abstractmethod
     def fetch_data(self, query):
         """Fetch data from the data source."""
@@ -103,24 +106,24 @@ def fetch_data(self, query):
 
 class DatabaseSource(DataSource):
     """A database implementation of DataSource."""
-    
+
     def __init__(self, db_name, host="localhost", port=5432):
         self._db_name = db_name
         self._host = host
         self._port = port
-    
+
     @property
     def name(self):
         return f"Database: {self._db_name}"
-    
+
     @property
     def connection_string(self):
         return f"postgresql://{self._host}:{self._port}/{self._db_name}"
-    
+
     def connect(self):
         print(f"Connecting to {self.connection_string}")
         # In real code: return psycopg2.connect(self.connection_string)
-    
+
     def fetch_data(self, query):
         print(f"Executing query on {self.name}: {query}")
         # In real code: return conn.execute(query).fetchall()
@@ -129,12 +132,12 @@ def fetch_data(self, query):
 # Advanced: Abstract Base Class Registration
 class JSONSerializable(ABC):
     """Abstract base class for objects that can be serialized to JSON."""
-    
+
     @abstractmethod
     def to_json(self):
         """Convert the object to a JSON-compatible dictionary."""
         pass
-    
+
     @classmethod
     def __subclasshook__(cls, subclass):
         """Special method to determine if a class is a subclass without explicit inheritance."""
@@ -149,7 +152,7 @@ class User:
     def __init__(self, name, email):
         self.name = name
         self.email = email
-    
+
     def to_json(self):
         return {"name": self.name, "email": self.email}
 
@@ -162,25 +165,25 @@ def to_json(self):
 @runtime_checkable
 class Drawable(Protocol):
     """A protocol defining objects that can be drawn."""
-    
+
     def draw(self) -> None:
         """Draw the object."""
         ...
 
 
 class Canvas:
     """A canvas that can draw any Drawable object."""
-    
+
     def __init__(self):
         self.elements = []
-    
+
     def add_element(self, element):
         """Add an element to the canvas."""
         if isinstance(element, Drawable):
             self.elements.append(element)
         else:
             raise TypeError("Element must be Drawable")
-    
+
     def draw_all(self):
         """Draw all elements on the canvas."""
         for element in self.elements:
@@ -190,27 +193,27 @@ def draw_all(self):
 # This class satisfies the Drawable protocol without explicit inheritance
 class Button:
     """A button that can be drawn."""
-    
+
     def __init__(self, label):
         self.label = label
-    
+
     def draw(self):
         print(f"Drawing button: {self.label}")
 
 
 # Real-world Example: Custom Container with ABC
 class SortedItems(Sequence):
     """A sequence that keeps items in sorted order."""
-    
+
     def __init__(self, items=None):
         self._items = sorted(items) if items else []
-    
+
     def __getitem__(self, index):
         return self._items[index]
-    
+
     def __len__(self):
         return len(self._items)
-    
+
     def add(self, item):
         """Add an item to the collection, maintaining sorted order."""
         self._items.append(item)
@@ -221,15 +224,15 @@ def add(self, item):
 def exercises():
     """Exercises for abstract base classes"""
     print("\nExercises:")
-    
+
     # Exercise 1: Create a FileHandler ABC with concrete implementations
     print("Exercise 1: Create a FileHandler ABC with methods read() and write()")
     # Your solution here
-    
+
     # Exercise 2: Implement a Validator protocol for data validation
     print("Exercise 2: Implement a Validator protocol")
     # Your solution here
-    
+
     # Exercise 3: Create a custom ABC for caching mechanisms
     print("Exercise 3: Create a Cacheable ABC")
     # Your solution here
@@ -238,17 +241,17 @@ def exercises():
 # Main function
 if __name__ == "__main__":
     print("Abstract Base Classes in Python\n")
-    
+
     # Demonstrate basic ABC
     rectangle = Rectangle(5, 10)
     circle = Circle(7)
-    
+
     print("Basic ABC Example:")
     print(f"Rectangle area: {rectangle.area()}, perimeter: {rectangle.perimeter()}")
     print(f"Circle area: {circle.area():.2f}, perimeter: {circle.perimeter():.2f}")
     print(f"Rectangle description: {rectangle.describe()}")
     print()
-    
+
     # Demonstrate abstract properties
     db = DatabaseSource("customers_db")
     print("Abstract Properties Example:")
@@ -257,15 +260,19 @@ def exercises():
     db.connect()
     db.fetch_data("SELECT * FROM customers")
     print()
-    
+
     # Demonstrate ABC registration
     user = User("Alice", "[email protected]")
     print("ABC Registration Example:")
-    print(f"Is User a subclass of JSONSerializable? {issubclass(User, JSONSerializable)}")
-    print(f"Is user an instance of JSONSerializable? {isinstance(user, JSONSerializable)}")
+    print(
+        f"Is User a subclass of JSONSerializable? {issubclass(User, JSONSerializable)}"
+    )
+    print(
+        f"Is user an instance of JSONSerializable? {isinstance(user, JSONSerializable)}"
+    )
     print(f"User as JSON: {user.to_json()}")
     print()
-    
+
     # Demonstrate Protocol
     if sys.version_info >= (3, 8):
         print("Protocol Example (Python 3.8+):")
@@ -277,11 +284,11 @@ def exercises():
             canvas.draw_all()
         except TypeError as e:
             print(f"Error: {e}")
-        
+
         # This would fail:
         # canvas.add_element("not drawable")
         print()
-    
+
     # Demonstrate custom container with ABC
     print("Custom Container Example:")
     sorted_items = SortedItems([3, 1, 5, 2, 4])
@@ -291,6 +298,6 @@ def exercises():
     print(f"Item at index 2: {sorted_items[2]}")
     print(f"Length: {len(sorted_items)}")
     print()
-    
+
     # Run exercises
-    exercises()
+    exercises()