feat: add debug mode support for Django with VS Code integration (#158)

* feat: add debug mode support for Django with VS Code integration

* refactor: remove outdated VS Code Docker tasks and update debugpy version to 1.8.14

* refactor: remove unused import of CommandError in runserver_debug.py

* refactor: add a blank line for improved readability in runserver_debug.py

Author: prakashchoudhary07

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Remote Attach (Django in Docker)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "/app"
+                }
+            ],
+            "justMyCode": false,
+            "django": true,
+            "subProcess": false
+        }
+    ]
+}

README.md

@@ -104,4 +104,48 @@
 5. To fix lint issues
     ```
     ruff check --fix
-    ```
+    ```
+
+## Debug Mode with VS Code
+
+### Prerequisites
+- VS Code with Python extension installed
+- Docker and docker-compose
+
+### Debug Setup
+
+1. **Start the application with debug mode:**
+   ```
+   python manage.py runserver_debug 0.0.0.0:8000
+   ```
+
+2. **Available debug options:**
+   ```bash
+   # Basic debug mode (default debug port 5678)
+   python manage.py runserver_debug 0.0.0.0:8000
+   
+   # Custom debug port
+   python manage.py runserver_debug 0.0.0.0:8000 --debug-port 5679
+   
+   # Wait for debugger before starting (useful for debugging startup code)
+   python manage.py runserver_debug 0.0.0.0:8000 --wait-for-client
+   ```
+
+3. **Attach VS Code debugger:**
+   - Press `F5` or go to `Run > Start Debugging`
+   - Select `Python: Remote Attach (Django in Docker)` from the dropdown
+   - Set breakpoints in your Python code
+   - Make requests to trigger the breakpoints
+
+### Debug Features
+- **Debug server port**: 5678 (configurable)
+- **Path mapping**: Local code mapped to container paths
+- **Django mode**: Special Django debugging features enabled
+- **Hot reload**: Code changes reflected immediately
+- **Variable inspection**: Full debugging capabilities in VS Code
+
+### Troubleshooting
+- If port 5678 is in use, specify a different port with `--debug-port`
+- Ensure VS Code Python extension is installed
+- Check that breakpoints are set in the correct files
+- Verify the debug server shows "Debug server listening on port 5678"

docker-compose.yml

@@ -2,17 +2,22 @@ services:
   django-app:
     build: .
     container_name: todo-django-app
-    command: python manage.py runserver 0.0.0.0:8000
+    command: python -Xfrozen_modules=off manage.py runserver_debug 0.0.0.0:8000 --debug-port 5678
     environment:
       MONGODB_URI: mongodb://db:27017
       DB_NAME: todo-app
+      PYTHONUNBUFFERED: 1
+      PYDEVD_DISABLE_FILE_VALIDATION: 1
     volumes:
       - .:/app
     ports:
       - "8000:8000"
+      - "5678:5678"  # Debug port
     depends_on:
       - db
       - mongo-init
+    stdin_open: true
+    tty: true
 
   db:
     image: mongo:latest

requirements.txt

@@ -27,3 +27,4 @@ requests==2.32.3
 email-validator==2.2.0
 testcontainers[mongodb]==4.10.0
 drf-spectacular==0.28.0
+debugpy==1.8.14

todo/management/commands/runserver_debug.py

@@ -0,0 +1,59 @@
+import debugpy
+import socket
+from django.core.management.commands.runserver import Command as RunServerCommand
+
+
+class Command(RunServerCommand):
+    help = "Run the Django development server with debugpy for VS Code debugging"
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+        parser.add_argument("--debug-port", type=int, default=5678, help="Port for the debug server (default: 5678)")
+        parser.add_argument(
+            "--wait-for-client", action="store_true", help="Wait for debugger client to attach before starting server"
+        )
+
+    def is_port_in_use(self, port):
+        """Check if a port is already in use"""
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("0.0.0.0", port))
+                return False
+            except OSError:
+                return True
+
+    def handle(self, *args, **options):
+        debug_port = options.get("debug_port", 5678)
+        wait_for_client = options.get("wait_for_client", False)
+
+        # Check if debugpy is already initialized or connected
+        if debugpy.is_client_connected():
+            self.stdout.write(self.style.WARNING(f"Debugger already connected on port {debug_port}"))
+        else:
+            # Check if debug port is in use
+            if self.is_port_in_use(debug_port):
+                self.stdout.write(self.style.ERROR(f"Port {debug_port} is already in use. Debug server not started."))
+                self.stdout.write(self.style.WARNING("Django server will start without debug capability."))
+            else:
+                try:
+                    # Only configure debugpy if not already configured
+                    if not hasattr(debugpy, "_is_configured") or not debugpy._is_configured:
+                        # Listen for debugger connections
+                        debugpy.listen(("0.0.0.0", debug_port))
+                        self.stdout.write(self.style.SUCCESS(f"Debug server listening on port {debug_port}"))
+
+                        if wait_for_client:
+                            self.stdout.write(self.style.WARNING("Waiting for debugger client to attach..."))
+                            debugpy.wait_for_client()
+                            self.stdout.write(self.style.SUCCESS("Debugger client attached!"))
+                        else:
+                            self.stdout.write(self.style.SUCCESS("Server starting - you can now attach the debugger"))
+                    else:
+                        self.stdout.write(self.style.WARNING("Debug server already configured"))
+
+                except Exception as e:
+                    self.stdout.write(self.style.ERROR(f"Failed to start debug server: {str(e)}"))
+                    self.stdout.write(self.style.WARNING("Django server will start without debug capability."))
+
+        # Call the parent runserver command
+        super().handle(*args, **options)