docs: add README for script usage and setup

test: improve test mocks for DataFetcher
fix: handle invalid gradient color in create_background
```

Author: anyulled

scripts/README.md

@@ -0,0 +1,67 @@
+# DevBcn scripts
+
+This directory contains Python scripts for generating conference story images
+for speakers and sessions.
+
+## Setup instructions
+
+### Setting up a virtual environment
+
+It's recommended to use a virtual environment to isolate the dependencies for
+these scripts.
+
+```shell
+python3 -m venv venv
+
+source venv/bin/activate
+```
+
+### Installing dependencies
+
+Once your virtual environment is activated, install the required dependencies
+using the requirements.txt file:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+The main script is `generate-story-images.py`, which generates story images for
+conference speakers and sessions.
+
+```bash
+# Navigate to the scripts directory
+cd scripts
+
+# Run the script with default settings
+python generate-story-images.py
+
+# Run with custom settings
+python generate-story-images.py --output-dir custom_output --max-workers 5 --timeout 15
+```
+
+### Available Options
+
+- `--output-dir`: directory to save generated images (default: 'output')
+- `--max-workers`: maximum number of worker threads (default: 10)
+- `--timeout`: timeout for HTTP requests in seconds (default: 10)
+
+## Project structure
+
+- `config.py`: configuration settings for story image generation
+- `data_fetcher.py`: module for fetching data from APIs and local resources
+- `file_utils.py`: utilities for file operations
+- `image_processor.py`: image processing utilities
+- `story_generator.py`: story image generator module
+- `text_renderer.py`: module for text rendering operations
+- `tests/`: unit tests for the modules
+
+## Deactivating the virtual environment
+
+When you're done working with the scripts, you can deactivate the virtual
+environment:
+
+```bash
+deactivate
+```

scripts/image_processor.py

@@ -13,10 +13,10 @@ class ImageProcessor:
 
     def crop_to_square(self, image: Image.Image) -> Image.Image:
         """Crop an image to a square shape, centered
-        
+
         Args:
             image: The image to crop
-            
+
         Returns:
             Cropped square image
         """
@@ -26,93 +26,94 @@ def crop_to_square(self, image: Image.Image) -> Image.Image:
         top = (height - size) // 2
         right = left + size
         bottom = top + size
-        
+
         return image.crop((left, top, right, bottom))
 
     def resize_image(self, image: Image.Image, size: Tuple[int, int]) -> Image.Image:
         """Resize an image
-        
+
         Args:
             image: The image to resize
             size: Target size (width, height)
-            
+
         Returns:
             Resized image
         """
         return image.resize(size)
 
     def apply_gradient_fade(self, image: Image.Image, fade_height: int) -> Image.Image:
         """Apply a gradient fade to the bottom of an image
-        
+
         Args:
             image: The image to process
             fade_height: Height of the fade effect in pixels
-            
+
         Returns:
             Image with applied fade effect
         """
         width, height = image.size
         fade = Image.new("L", (width, height), color=255)
-        
+
         for y in range(height - fade_height, height):
             opacity = int(255 * (1 - (y - (height - fade_height)) / fade_height))
             for x in range(width):
                 fade.putpixel((x, y), opacity)
-                
+
         result = image.copy()
         result.putalpha(fade)
         return result
 
     def create_background(self, size: Tuple[int, int], top_color: str, bottom_color: str) -> Image.Image:
         """Create a gradient background
-        
+
         Args:
             size: Image size (width, height)
             top_color: Hex color code for the top of the gradient
             bottom_color: Hex color code for the bottom of the gradient
-            
+
         Returns:
             Image with gradient background
         """
         try:
             bg = Image.new("RGBA", size, top_color)
             gradient = Image.new("RGBA", size)
             draw = ImageDraw.Draw(gradient)
-            
+
             for y in range(size[1]):
                 ratio = y / size[1]
                 r = int(int(top_color[1:3], 16) * (1 - ratio) + int(bottom_color[1:3], 16) * ratio)
                 g = int(int(top_color[3:5], 16) * (1 - ratio) + int(bottom_color[3:5], 16) * ratio)
                 b = int(int(top_color[5:7], 16) * (1 - ratio) + int(bottom_color[5:7], 16) * ratio)
                 draw.line([(0, y), (size[0], y)], fill=(r, g, b, 255))
-                
+
             bg.alpha_composite(gradient)
             return bg
         except ValueError as e:
             logger.error(f"Error creating background: {e}")
             # Fallback to solid color if gradient fails
-            return Image.new("RGBA", size, top_color)
+            # Use a default color (#000000) instead of the potentially invalid top_color
+            return Image.new("RGBA", size, "#000000")
 
     def position_logo(self, base_image: Image.Image, logo: Image.Image, 
                       margin: int, logo_width_percentage: float = 0.2) -> Image.Image:
         """Position a logo on the top right of the base image
-        
+
         Args:
             base_image: The base image
             logo: The logo image
             margin: Margin from the edges
             logo_width_percentage: Width of the logo as a percentage of the base image width
-            
+
         Returns:
             Image with logo placed on it
         """
         base_width = base_image.width
         logo_width = int(base_width * logo_width_percentage)
         logo_height = int(logo.height * logo_width / logo.width)
-        
+
         logo_resized = logo.resize((logo_width, logo_height))
-        
+
         result = base_image.copy()
         result.paste(logo_resized, (base_width - logo_width - margin, margin), logo_resized)
-        
+
         return result

scripts/tests/test_data_fetcher.py

@@ -16,120 +16,122 @@
 
 class TestDataFetcher(unittest.TestCase):
     """Tests for the DataFetcher class"""
-    
+
     def setUp(self):
         """Set up test fixtures"""
         self.fetcher = DataFetcher(request_timeout=5)
-    
+
     @patch('requests.get')
     def test_fetch_json_success(self, mock_get):
         """Test successful JSON fetch"""
         # Mock response
         mock_response = Mock()
         mock_response.json.return_value = {"key": "value"}
         mock_get.return_value = mock_response
-        
+
         # Test
         result = self.fetcher.fetch_json("http://example.com/api")
-        
+
         # Verify
         mock_get.assert_called_once_with("http://example.com/api", timeout=5)
         mock_response.raise_for_status.assert_called_once()
         self.assertEqual(result, {"key": "value"})
-    
+
     @patch('requests.get')
     def test_fetch_json_error(self, mock_get):
         """Test JSON fetch with request error"""
         # Mock response
         mock_get.side_effect = requests.RequestException("Connection error")
-        
+
         # Test
         with self.assertRaises(requests.RequestException):
             self.fetcher.fetch_json("http://example.com/api")
-    
+
     @patch('requests.get')
     @patch('PIL.Image.open')
     def test_fetch_image_success(self, mock_open, mock_get):
         """Test successful image fetch"""
         # Mock response
         mock_response = Mock()
+        mock_response.content = b'fake_image_content'
         mock_get.return_value = mock_response
-        
+
         # Mock image
         mock_image = MagicMock(spec=Image.Image)
         mock_image.convert.return_value = mock_image
         mock_open.return_value = mock_image
-        
+
         # Test
         result = self.fetcher.fetch_image("http://example.com/image.jpg")
-        
+
         # Verify
         mock_get.assert_called_once_with("http://example.com/image.jpg", timeout=5)
         mock_response.raise_for_status.assert_called_once()
         mock_image.convert.assert_called_once_with("RGBA")
         self.assertEqual(result, mock_image)
-    
+
     @patch('requests.get')
     def test_fetch_image_request_error(self, mock_get):
         """Test image fetch with request error"""
         # Mock response
         mock_get.side_effect = requests.RequestException("Connection error")
-        
+
         # Test
         with self.assertRaises(requests.RequestException):
             self.fetcher.fetch_image("http://example.com/image.jpg")
-    
+
     @patch('requests.get')
     @patch('PIL.Image.open')
     def test_fetch_image_processing_error(self, mock_open, mock_get):
         """Test image fetch with image processing error"""
         # Mock response
         mock_response = Mock()
+        mock_response.content = b'invalid_image_content'
         mock_get.return_value = mock_response
-        
+
         # Mock image open error
         mock_open.side_effect = UnidentifiedImageError("invalid image")
-        
+
         # Test
         with self.assertRaises(IOError):
             self.fetcher.fetch_image("http://example.com/image.jpg")
-    
+
     @patch('PIL.Image.open')
     def test_load_local_image_success(self, mock_open):
         """Test successful local image load"""
         # Mock image
         mock_image = MagicMock(spec=Image.Image)
         mock_image.convert.return_value = mock_image
         mock_open.return_value = mock_image
-        
+
         # Test
         result = self.fetcher.load_local_image("path/to/image.png")
-        
+
         # Verify
         mock_open.assert_called_once_with("path/to/image.png")
         mock_image.convert.assert_called_once_with("RGBA")
         self.assertEqual(result, mock_image)
-    
+
     @patch('PIL.Image.open')
     def test_load_local_image_file_not_found(self, mock_open):
         """Test local image load with file not found"""
         # Mock error
         mock_open.side_effect = FileNotFoundError("File not found")
-        
+
         # Test
         with self.assertRaises(FileNotFoundError):
             self.fetcher.load_local_image("path/to/nonexistent.png")
-    
+
     @patch('PIL.Image.open')
     def test_load_local_image_processing_error(self, mock_open):
         """Test local image load with processing error"""
         # Mock error
         mock_open.side_effect = IOError("Invalid image")
-        
+
         # Test
         with self.assertRaises(IOError):
             self.fetcher.load_local_image("path/to/invalid.png")
-    
+
     @patch.object(DataFetcher, 'fetch_json')
     def test_fetch_speakers(self, mock_fetch_json):
         """Test fetching speakers"""
@@ -138,17 +140,17 @@ def test_fetch_speakers(self, mock_fetch_json):
             {"id": "1", "name": "Speaker 1"},
             {"id": "2", "name": "Speaker 2"}
         ]
-        
+
         # Test
         result = self.fetcher.fetch_speakers("http://example.com/speakers")
-        
+
         # Verify
         mock_fetch_json.assert_called_once_with("http://example.com/speakers")
         self.assertEqual(result, {
             "1": {"id": "1", "name": "Speaker 1"},
             "2": {"id": "2", "name": "Speaker 2"}
         })
-    
+
     @patch.object(DataFetcher, 'fetch_json')
     def test_fetch_sessions_by_track(self, mock_fetch_json):
         """Test fetching sessions by track"""
@@ -168,10 +170,10 @@ def test_fetch_sessions_by_track(self, mock_fetch_json):
                 ]
             }
         ]
-        
+
         # Test
         result = self.fetcher.fetch_sessions_by_track("http://example.com/sessions")
-        
+
         # Verify
         mock_fetch_json.assert_called_once_with("http://example.com/sessions")
         self.assertEqual(result, {
@@ -183,16 +185,16 @@ def test_fetch_sessions_by_track(self, mock_fetch_json):
                 {"id": "3", "title": "Session 3"}
             ]
         })
-    
+
     @patch.object(DataFetcher, 'fetch_json')
     def test_fetch_sessions_by_track_empty(self, mock_fetch_json):
         """Test fetching sessions by track with empty data"""
         # Mock data
         mock_fetch_json.return_value = []
-        
+
         # Test
         result = self.fetcher.fetch_sessions_by_track("http://example.com/sessions")
-        
+
         # Verify
         mock_fetch_json.assert_called_once_with("http://example.com/sessions")
         self.assertEqual(result, {})