django-explain-errors 0.2.0__tar.gz

django_explain_errors-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_explain_errors-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include README.rst
+include LICENSE

django_explain_errors-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: django-explain-errors
+Version: 0.2.0
+Summary: Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.
+Home-page: https://github.com/topunix/django-explain-errors
+Author: topunix
+Author-email: topunixguy@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: asgiref>=3.6
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Django Explain Errors Middleware
+
+This Django middleware captures errors and exceptions, sends them to OpenAI for explanation, and prints the explanation to stdout when debug mode is enabled. It uses an environment variable to securely manage the OpenAI API key.
+
+The middleware supports both synchronous (WSGI) and asynchronous (ASGI) views. It auto-detects the view chain at startup and routes requests through the matching sync or async path, so no extra configuration is required to use it under either server type.
+
+## Features
+
+- Captures Django errors and exceptions
+- Uses OpenAI to explain the error
+- Securely manages the OpenAI API key using environment variables
+- Works with both sync (WSGI) and async (ASGI) views
+
+## Installation
+
+1. Install django-explain-errors by running:
+```bash
+pip install django-explain-errors
+```
+
+2. **Add the middleware to your Django project**:
+
+   - Open your `settings.py` file and add the middleware to the `MIDDLEWARE` list. Ensure that the middleware is added last in the list:
+
+     ```python
+     MIDDLEWARE = [
+         ...
+         'explain_errors.middleware.ExplainErrorsMiddleware',
+     ]
+     ```
+
+3. **Set up environment variables**:
+
+   - Create a `.env` file in your project's root directory and add your OpenAI API key. Alternatively, you can set the API key in `settings.py`:
+
+     ```plaintext
+     OPENAI_API_KEY=your_openai_api_key_here
+     ```
+
+## Usage
+
+1. **Ensure DEBUG is set to True**:
+
+   Open your `settings.py` file and set:
+
+   ```python
+   DEBUG = True
+   ```
+
+2. **Trigger an error in your Django application**:
+
+   The middleware will capture the error, send it to OpenAI for explanation, and print the explanation to stdout. When an exception is caught, it returns a JSON `500` response containing the error message and the explanation.
+
+## Async Support
+
+The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
+
+- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
+- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking OpenAI call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
+
+No additional settings are needed. Place the middleware last in `MIDDLEWARE` for both modes.
+
+## Configuration
+
+| Setting / variable | Required | Description |
+| ------------------ | -------- | ----------- |
+| `OPENAI_API_KEY` (env or settings) | Yes, when `DEBUG=True` | API key used to authenticate with OpenAI. Read first from the environment, then from `settings`. |
+| `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
+| `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
+| `OPENAI_MAX_TOKENS` | No | Maximum tokens in the explanation. Defaults to `150`. |
+| `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
+| `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
+
+## Example
+
+Here is an example of how to use the middleware in a Django project:
+
+```python
+# settings.py
+
+DEBUG = True
+
+MIDDLEWARE = [
+    ...
+    'explain_errors.middleware.ExplainErrorsMiddleware',
+]
+
+# .env
+
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+When an error occurs, you will see an explanation printed to stdout.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Acknowledgements
+
+- [Django](https://www.djangoproject.com/)
+- [OpenAI](https://www.openai.com/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)

django_explain_errors-0.2.0/README.md

@@ -0,0 +1,107 @@
+# Django Explain Errors Middleware
+
+This Django middleware captures errors and exceptions, sends them to OpenAI for explanation, and prints the explanation to stdout when debug mode is enabled. It uses an environment variable to securely manage the OpenAI API key.
+
+The middleware supports both synchronous (WSGI) and asynchronous (ASGI) views. It auto-detects the view chain at startup and routes requests through the matching sync or async path, so no extra configuration is required to use it under either server type.
+
+## Features
+
+- Captures Django errors and exceptions
+- Uses OpenAI to explain the error
+- Securely manages the OpenAI API key using environment variables
+- Works with both sync (WSGI) and async (ASGI) views
+
+## Installation
+
+1. Install django-explain-errors by running:
+```bash
+pip install django-explain-errors
+```
+
+2. **Add the middleware to your Django project**:
+
+   - Open your `settings.py` file and add the middleware to the `MIDDLEWARE` list. Ensure that the middleware is added last in the list:
+
+     ```python
+     MIDDLEWARE = [
+         ...
+         'explain_errors.middleware.ExplainErrorsMiddleware',
+     ]
+     ```
+
+3. **Set up environment variables**:
+
+   - Create a `.env` file in your project's root directory and add your OpenAI API key. Alternatively, you can set the API key in `settings.py`:
+
+     ```plaintext
+     OPENAI_API_KEY=your_openai_api_key_here
+     ```
+
+## Usage
+
+1. **Ensure DEBUG is set to True**:
+
+   Open your `settings.py` file and set:
+
+   ```python
+   DEBUG = True
+   ```
+
+2. **Trigger an error in your Django application**:
+
+   The middleware will capture the error, send it to OpenAI for explanation, and print the explanation to stdout. When an exception is caught, it returns a JSON `500` response containing the error message and the explanation.
+
+## Async Support
+
+The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
+
+- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
+- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking OpenAI call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
+
+No additional settings are needed. Place the middleware last in `MIDDLEWARE` for both modes.
+
+## Configuration
+
+| Setting / variable | Required | Description |
+| ------------------ | -------- | ----------- |
+| `OPENAI_API_KEY` (env or settings) | Yes, when `DEBUG=True` | API key used to authenticate with OpenAI. Read first from the environment, then from `settings`. |
+| `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
+| `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
+| `OPENAI_MAX_TOKENS` | No | Maximum tokens in the explanation. Defaults to `150`. |
+| `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
+| `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
+
+## Example
+
+Here is an example of how to use the middleware in a Django project:
+
+```python
+# settings.py
+
+DEBUG = True
+
+MIDDLEWARE = [
+    ...
+    'explain_errors.middleware.ExplainErrorsMiddleware',
+]
+
+# .env
+
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+When an error occurs, you will see an explanation printed to stdout.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Acknowledgements
+
+- [Django](https://www.djangoproject.com/)
+- [OpenAI](https://www.openai.com/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)

django_explain_errors-0.2.0/README.rst

@@ -0,0 +1,107 @@
+# Django Explain Errors Middleware
+
+This Django middleware captures errors and exceptions, sends them to OpenAI for explanation, and prints the explanation to stdout when debug mode is enabled. It uses an environment variable to securely manage the OpenAI API key.
+
+The middleware supports both synchronous (WSGI) and asynchronous (ASGI) views. It auto-detects the view chain at startup and routes requests through the matching sync or async path, so no extra configuration is required to use it under either server type.
+
+## Features
+
+- Captures Django errors and exceptions
+- Uses OpenAI to explain the error
+- Securely manages the OpenAI API key using environment variables
+- Works with both sync (WSGI) and async (ASGI) views
+
+## Installation
+
+1. Install django-explain-errors by running:
+```bash
+pip install django-explain-errors
+```
+
+2. **Add the middleware to your Django project**:
+
+   - Open your `settings.py` file and add the middleware to the `MIDDLEWARE` list. Ensure that the middleware is added last in the list:
+
+     ```python
+     MIDDLEWARE = [
+         ...
+         'explain_errors.middleware.ExplainErrorsMiddleware',
+     ]
+     ```
+
+3. **Set up environment variables**:
+
+   - Create a `.env` file in your project's root directory and add your OpenAI API key. Alternatively, you can set the API key in `settings.py`:
+
+     ```plaintext
+     OPENAI_API_KEY=your_openai_api_key_here
+     ```
+
+## Usage
+
+1. **Ensure DEBUG is set to True**:
+
+   Open your `settings.py` file and set:
+
+   ```python
+   DEBUG = True
+   ```
+
+2. **Trigger an error in your Django application**:
+
+   The middleware will capture the error, send it to OpenAI for explanation, and print the explanation to stdout. When an exception is caught, it returns a JSON `500` response containing the error message and the explanation.
+
+## Async Support
+
+The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
+
+- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
+- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking OpenAI call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
+
+No additional settings are needed. Place the middleware last in `MIDDLEWARE` for both modes.
+
+## Configuration
+
+| Setting / variable | Required | Description |
+| ------------------ | -------- | ----------- |
+| `OPENAI_API_KEY` (env or settings) | Yes, when `DEBUG=True` | API key used to authenticate with OpenAI. Read first from the environment, then from `settings`. |
+| `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
+| `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
+| `OPENAI_MAX_TOKENS` | No | Maximum tokens in the explanation. Defaults to `150`. |
+| `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
+| `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
+
+## Example
+
+Here is an example of how to use the middleware in a Django project:
+
+```python
+# settings.py
+
+DEBUG = True
+
+MIDDLEWARE = [
+    ...
+    'explain_errors.middleware.ExplainErrorsMiddleware',
+]
+
+# .env
+
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+When an error occurs, you will see an explanation printed to stdout.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Acknowledgements
+
+- [Django](https://www.djangoproject.com/)
+- [OpenAI](https://www.openai.com/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)

django_explain_errors-0.2.0/django_explain_errors.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: django-explain-errors
+Version: 0.2.0
+Summary: Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.
+Home-page: https://github.com/topunix/django-explain-errors
+Author: topunix
+Author-email: topunixguy@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: asgiref>=3.6
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Django Explain Errors Middleware
+
+This Django middleware captures errors and exceptions, sends them to OpenAI for explanation, and prints the explanation to stdout when debug mode is enabled. It uses an environment variable to securely manage the OpenAI API key.
+
+The middleware supports both synchronous (WSGI) and asynchronous (ASGI) views. It auto-detects the view chain at startup and routes requests through the matching sync or async path, so no extra configuration is required to use it under either server type.
+
+## Features
+
+- Captures Django errors and exceptions
+- Uses OpenAI to explain the error
+- Securely manages the OpenAI API key using environment variables
+- Works with both sync (WSGI) and async (ASGI) views
+
+## Installation
+
+1. Install django-explain-errors by running:
+```bash
+pip install django-explain-errors
+```
+
+2. **Add the middleware to your Django project**:
+
+   - Open your `settings.py` file and add the middleware to the `MIDDLEWARE` list. Ensure that the middleware is added last in the list:
+
+     ```python
+     MIDDLEWARE = [
+         ...
+         'explain_errors.middleware.ExplainErrorsMiddleware',
+     ]
+     ```
+
+3. **Set up environment variables**:
+
+   - Create a `.env` file in your project's root directory and add your OpenAI API key. Alternatively, you can set the API key in `settings.py`:
+
+     ```plaintext
+     OPENAI_API_KEY=your_openai_api_key_here
+     ```
+
+## Usage
+
+1. **Ensure DEBUG is set to True**:
+
+   Open your `settings.py` file and set:
+
+   ```python
+   DEBUG = True
+   ```
+
+2. **Trigger an error in your Django application**:
+
+   The middleware will capture the error, send it to OpenAI for explanation, and print the explanation to stdout. When an exception is caught, it returns a JSON `500` response containing the error message and the explanation.
+
+## Async Support
+
+The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
+
+- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
+- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking OpenAI call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
+
+No additional settings are needed. Place the middleware last in `MIDDLEWARE` for both modes.
+
+## Configuration
+
+| Setting / variable | Required | Description |
+| ------------------ | -------- | ----------- |
+| `OPENAI_API_KEY` (env or settings) | Yes, when `DEBUG=True` | API key used to authenticate with OpenAI. Read first from the environment, then from `settings`. |
+| `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
+| `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
+| `OPENAI_MAX_TOKENS` | No | Maximum tokens in the explanation. Defaults to `150`. |
+| `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
+| `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
+
+## Example
+
+Here is an example of how to use the middleware in a Django project:
+
+```python
+# settings.py
+
+DEBUG = True
+
+MIDDLEWARE = [
+    ...
+    'explain_errors.middleware.ExplainErrorsMiddleware',
+]
+
+# .env
+
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+When an error occurs, you will see an explanation printed to stdout.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Acknowledgements
+
+- [Django](https://www.djangoproject.com/)
+- [OpenAI](https://www.openai.com/)
+- [python-dotenv](https://github.com/theskumar/python-dotenv)

django_explain_errors-0.2.0/django_explain_errors.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+README.rst
+setup.py
+django_explain_errors.egg-info/PKG-INFO
+django_explain_errors.egg-info/SOURCES.txt
+django_explain_errors.egg-info/dependency_links.txt
+django_explain_errors.egg-info/requires.txt
+django_explain_errors.egg-info/top_level.txt
+explain_errors/__init__.py
+explain_errors/middleware.py
+tests/test_middleware.py

django_explain_errors-0.2.0/django_explain_errors.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_explain_errors-0.2.0/django_explain_errors.egg-info/requires.txt

@@ -0,0 +1,4 @@
+Django>=4.2
+openai>=1.0
+python-dotenv>=1.0
+asgiref>=3.6

django_explain_errors-0.2.0/django_explain_errors.egg-info/top_level.txt

@@ -0,0 +1 @@
+explain_errors

django_explain_errors-0.2.0/explain_errors/middleware.py

@@ -0,0 +1,109 @@
+import os
+import asyncio
+import traceback
+
+from openai import OpenAI
+from dotenv import load_dotenv
+from django.conf import settings
+from django.http import JsonResponse
+from asgiref.sync import sync_to_async
+
+
+class ExplainErrorsMiddleware:
+    """
+    Captures unhandled exceptions, asks OpenAI to explain them, and prints the
+    explanation to stdout when DEBUG is True. Supports both sync (WSGI) and
+    async (ASGI) views.
+    """
+
+    async_capable = True
+    sync_capable = True
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self._is_async = asyncio.iscoroutinefunction(get_response)
+        self.api_called = False
+        self.openai_client = None
+
+        if settings.DEBUG:
+            # Load environment variables from .env file
+            load_dotenv()
+            # Get the OpenAI API key from environment variable (or settings)
+            openai_api_key = os.getenv(
+                "OPENAI_API_KEY", getattr(settings, "OPENAI_API_KEY", None)
+            )
+            if not openai_api_key:
+                raise ValueError(
+                    "OpenAI API key not found. Please set the OPENAI_API_KEY "
+                    "environment variable."
+                )
+
+            # Configurable via settings, with sensible defaults.
+            self.model = getattr(settings, "OPENAI_MODEL", "gpt-4o-mini")
+            self.max_tokens = getattr(settings, "OPENAI_MAX_TOKENS", 150)
+            timeout = getattr(settings, "OPENAI_TIMEOUT", 10)
+
+            self.openai_client = OpenAI(api_key=openai_api_key, timeout=timeout)
+
+    def __call__(self, request):
+        # Delegate to the async path when wrapped around an async view chain.
+        if self._is_async:
+            return self.__acall__(request)
+        return self._sync_handler(request)
+
+    # --------- Sync path ----------
+    def _sync_handler(self, request):
+        try:
+            response = self.get_response(request)
+        except Exception as exception:
+            return self.process_exception(request, exception)
+        return response
+
+    # --------- Async path ----------
+    async def __acall__(self, request):
+        try:
+            response = await self.get_response(request)
+        except Exception as exception:
+            # process_exception performs blocking OpenAI I/O, so run it in a
+            # thread to keep the event loop free.
+            return await sync_to_async(self.process_exception)(request, exception)
+        return response
+
+    def process_exception(self, request, exception):
+        if not settings.DEBUG:
+            return None
+
+        explanation = None
+        if not self.api_called:
+            # Get the exception traceback, trimmed to the most recent frames to
+            # cap token usage and stay within the model's context window.
+            tb = traceback.format_exc()
+            max_tb_chars = getattr(settings, "OPENAI_MAX_TRACEBACK_CHARS", 3000)
+            if len(tb) > max_tb_chars:
+                tb = "...(truncated)...\n" + tb[-max_tb_chars:]
+            # Construct the prompt
+            prompt = f"Explain the following Django error in simple terms:\n\n{tb}"
+
+            try:
+                # Call OpenAI API
+                response = self.openai_client.chat.completions.create(
+                    model=self.model,
+                    messages=[
+                        {"role": "system", "content": "You are a helpful assistant."},
+                        {"role": "user", "content": prompt},
+                    ],
+                    max_tokens=self.max_tokens,
+                )
+                explanation = response.choices[0].message.content
+
+                # Print the explanation to stdout
+                print("Error Explanation by OpenAI:\n", explanation)
+                self.api_called = True  # Set flag after the call
+            except Exception as e:
+                # If the OpenAI call fails, surface the failure but still return
+                # a 500 so the request lifecycle completes cleanly.
+                print("Failed to get an explanation from OpenAI:", e)
+
+        return JsonResponse(
+            {"error": "An error occurred.", "message": explanation}, status=500
+        )

django_explain_errors-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_explain_errors-0.2.0/setup.py

@@ -0,0 +1,48 @@
+import os
+from setuptools import find_packages, setup
+
+# allow setup.py to be run from any path
+os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
+
+# get README
+with open('README.md', encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='django-explain-errors',
+    version='0.2.0',
+    packages=find_packages(exclude=['tests', 'tests.*']),
+    description='Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.',
+    long_description_content_type='text/markdown',
+    long_description=long_description,
+    python_requires='>=3.9',
+    install_requires=[
+        'Django>=4.2',
+        'openai>=1.0',
+        'python-dotenv>=1.0',
+        'asgiref>=3.6',
+    ],
+    url='https://github.com/topunix/django-explain-errors',
+    author='topunix',
+    author_email='topunixguy@gmail.com',
+    license='MIT',
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Environment :: Web Environment',
+        'Framework :: Django',
+        'Framework :: Django :: 4.2',
+        'Framework :: Django :: 5.0',
+        'Framework :: Django :: 5.1',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: MIT License',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Programming Language :: Python :: 3.13',
+        'Topic :: Internet :: WWW/HTTP',
+    ],
+)

django_explain_errors-0.2.0/tests/test_middleware.py

@@ -0,0 +1,160 @@
+import json
+from unittest.mock import MagicMock, patch
+
+from django.http import JsonResponse, HttpResponse
+from django.test import SimpleTestCase, RequestFactory, AsyncRequestFactory, override_settings
+
+from explain_errors.middleware import ExplainErrorsMiddleware
+
+
+def _mock_openai():
+    """Return a patch context for OpenAI plus a configured fake client."""
+    patcher = patch("explain_errors.middleware.OpenAI")
+    mock_cls = patcher.start()
+    client = MagicMock()
+    client.chat.completions.create.return_value = MagicMock(
+        choices=[MagicMock(message=MagicMock(content="Mocked explanation."))]
+    )
+    mock_cls.return_value = client
+    return patcher, client
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class ExplainErrorsMiddlewareTest(SimpleTestCase):
+
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    def _build(self, get_response):
+        return ExplainErrorsMiddleware(get_response)
+
+    # ---- capability markers ----
+    def test_capability_markers(self):
+        self.assertTrue(ExplainErrorsMiddleware.async_capable)
+        self.assertTrue(ExplainErrorsMiddleware.sync_capable)
+
+    def test_is_async_detection(self):
+        sync_mw = self._build(lambda r: HttpResponse("ok"))
+        self.assertFalse(sync_mw._is_async)
+
+        async def aget(r):
+            return HttpResponse("ok")
+
+        self.assertTrue(self._build(aget)._is_async)
+
+    # ---- process_exception (original test, adapted) ----
+    def test_process_exception_with_error(self):
+        request = self.factory.get("/")
+        middleware = self._build(lambda request: None)
+
+        response = middleware.process_exception(request, Exception("Test Exception"))
+
+        self.assertIsInstance(response, JsonResponse)
+        self.assertEqual(response.status_code, 500)
+        self.assertIn("error", json.loads(response.content))
+
+    def test_api_called_flag_prevents_second_call(self):
+        request = self.factory.get("/")
+        middleware = self._build(lambda request: None)
+
+        middleware.process_exception(request, Exception("Test"))
+        self.assertTrue(middleware.api_called)
+
+        resp = middleware.process_exception(request, Exception("Test"))
+        self.assertEqual(self.client.chat.completions.create.call_count, 1)
+        self.assertEqual(resp.status_code, 500)
+
+    # ---- sync request path ----
+    def test_sync_passthrough(self):
+        sentinel = HttpResponse("ok")
+        mw = self._build(lambda r: sentinel)
+        self.assertIs(mw(self.factory.get("/")), sentinel)
+
+    def test_sync_exception_returns_500(self):
+        def boom(r):
+            raise ValueError("boom")
+
+        resp = self._build(boom)(self.factory.get("/"))
+        self.assertIsInstance(resp, JsonResponse)
+        self.assertEqual(resp.status_code, 500)
+        self.assertIn("error", json.loads(resp.content))
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class ExplainErrorsMiddlewareAsyncTest(SimpleTestCase):
+
+    def setUp(self):
+        self.factory = AsyncRequestFactory()
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    async def test_async_passthrough(self):
+        sentinel = HttpResponse("ok")
+
+        async def aget(r):
+            return sentinel
+
+        mw = ExplainErrorsMiddleware(aget)
+        self.assertIs(await mw(self.factory.get("/")), sentinel)
+
+    async def test_async_exception_returns_500(self):
+        async def boom(r):
+            raise ValueError("async boom")
+
+        mw = ExplainErrorsMiddleware(boom)
+        resp = await mw(self.factory.get("/"))
+        self.assertIsInstance(resp, JsonResponse)
+        self.assertEqual(resp.status_code, 500)
+        self.assertIn("error", json.loads(resp.content))
+
+
+@override_settings(DEBUG=False)
+class ExplainErrorsMiddlewareDebugOffTest(SimpleTestCase):
+
+    def test_process_exception_returns_none_when_debug_off(self):
+        factory = RequestFactory()
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        self.assertIsNone(mw.process_exception(factory.get("/"), Exception("x")))
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class OpenAICallConfigTest(SimpleTestCase):
+
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    def test_default_model(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        mw.process_exception(self.factory.get("/"), Exception("x"))
+        kwargs = self.client.chat.completions.create.call_args.kwargs
+        self.assertEqual(kwargs["model"], "gpt-4o-mini")
+        self.assertEqual(kwargs["max_tokens"], 150)
+
+    @override_settings(OPENAI_MODEL="gpt-5-mini", OPENAI_MAX_TOKENS=50)
+    def test_configurable_model_and_tokens(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        mw.process_exception(self.factory.get("/"), Exception("x"))
+        kwargs = self.client.chat.completions.create.call_args.kwargs
+        self.assertEqual(kwargs["model"], "gpt-5-mini")
+        self.assertEqual(kwargs["max_tokens"], 50)
+
+    @override_settings(OPENAI_MAX_TRACEBACK_CHARS=200)
+    def test_traceback_is_truncated(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        try:
+            raise ValueError("x" * 5000)
+        except ValueError as exc:
+            mw.process_exception(self.factory.get("/"), exc)
+        prompt = self.client.chat.completions.create.call_args.kwargs["messages"][1]["content"]
+        self.assertIn("(truncated)", prompt)
+        self.assertLess(len(prompt), 400)
+
+    def test_timeout_passed_to_client(self):
+        with override_settings(OPENAI_TIMEOUT=7):
+            with patch("explain_errors.middleware.OpenAI") as mock_cls:
+                ExplainErrorsMiddleware(lambda r: None)
+                self.assertEqual(mock_cls.call_args.kwargs["timeout"], 7)