django-mercury-performance


Namedjango-mercury-performance JSON
Version 0.0.2 PyPI version JSON
download
home_pagehttps://github.com/Django-Mercury/Performance-Testing
SummaryA performance testing framework for Django that helps you understand and fix performance issues, not just detect them
upload_time2025-08-03 14:55:32
maintainerNone
docs_urlNone
authorDjango Mercury Team
requires_python>=3.8
licenseGPL-3.0-or-later
keywords django performance testing monitoring optimization n+1 queries profiling mercury rest-framework api benchmarking
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Django Mercury ๐Ÿš€

[![PyPI version](https://badge.fury.io/py/django-mercury-performance.svg)](https://badge.fury.io/py/django-mercury-performance)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Django 3.2-5.1](https://img.shields.io/badge/django-3.2--5.1-green.svg)](https://docs.djangoproject.com/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Built for: EduLite](https://img.shields.io/badge/Built%20for-EduLite-orange)](https://github.com/ibrahim-sisar/EduLite)
[![Values: Open](https://img.shields.io/badge/Values-Open%20%7C%20Free%20%7C%20Fair-purple)](https://github.com/80-20-Human-In-The-Loop)

**Part of the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) ecosystem**

> Test Django app speed. Learn why it's slow. Fix it.

## ๐Ÿš€ Quick Install

```bash
pip install django-mercury-performance
```

Then in your test files:
```python
from django_mercury import DjangoMercuryAPITestCase

class MyPerformanceTest(DjangoMercuryAPITestCase):
    def test_api_performance(self):
        response = self.client.get('/api/endpoint/')
        # Performance is automatically monitored and reported!
```

## ๐ŸŒŸ Origin Story

Mercury started at [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn with slow internet. We found our UserSearchView made **825 database queries** to show one page!

We built Mercury to find these problems and teach you how to fix them. Mercury follows EduLite's values: **Fair**, **Free**, and **Open**. Everyone can use it and learn.

## ๐ŸŽฏ Current Status: v0.0.2 on PyPI! ๐ŸŽ‰

**What Works Now:**
- โœ… **Install from PyPI** - `pip install django-mercury-performance`
- โœ… Finds N+1 query problems
- โœ… Grades speed (F to A+) 
- โœ… Two test types: `DjangoMercuryAPITestCase` and `DjangoPerformanceAPITestCase`
- โœ… Knows what type of code runs
- โœ… Teaches when tests fail
- โœ… Fast C code for speed
- โœ… Tracks time, queries, and memory

**What We Actually Found:**
```text
๐Ÿšจ POTENTIAL N+1 QUERY PROBLEM! ๐Ÿšจ
Severity: CRITICAL (825 queries)
```

**Coming Soon:**
- ๐Ÿ”œ AI help to fix slow code
- ๐Ÿ”œ Track speed over time
- ๐Ÿ”œ Test all view types
- ๐Ÿ”œ Find when code gets slower
- ๐Ÿ”œ Better test support

## ๐Ÿ“ฆ Installation

### Install from PyPI (Recommended)

```bash
pip install django-mercury-performance
```

### Install from Source

```bash
# Clone the repository
git clone https://github.com/Django-Mercury/Performance-Testing.git
cd Django-Mercury-Performance-Testing

# Install in development mode
pip install -e .

# If you want to modify the C extensions
cd django_mercury/c_core
make clean && make
```

## ๐Ÿš€ Quick Start

### Two Ways to Test Performance

Choose the test class that fits your needs.

#### 1. DjangoMercuryAPITestCase - Automatic Testing

Mercury watches your tests automatically. You write normal tests. Mercury finds problems.

```python
from django_mercury import DjangoMercuryAPITestCase

class UserSearchPerformanceTest(DjangoMercuryAPITestCase):
    """Mercury monitors every test automatically."""
    
    def test_user_search(self):
        # Write your normal test
        response = self.client.get('/api/users/search/?q=test')
        self.assertEqual(response.status_code, 200)
        # Mercury checks performance automatically
```

**What Mercury does:**
- Counts database queries
- Measures response time  
- Tracks memory usage
- Finds N+1 problems
- Shows clear reports

#### 2. DjangoPerformanceAPITestCase - Manual Control

You control when to monitor. Good for specific performance checks.

```python
from django_mercury import DjangoPerformanceAPITestCase
from django_mercury import monitor_django_view

class AdvancedPerformanceTest(DjangoPerformanceAPITestCase):
    """Control exactly what you test."""
    
    def test_with_assertions(self):
        with monitor_django_view("search") as monitor:
            response = self.client.get('/api/users/search/')
        
        # Check specific limits
        self.assertResponseTimeLess(monitor, 100)  # Under 100ms
        self.assertQueriesLess(monitor, 10)         # Under 10 queries
        self.assertNoNPlusOne(monitor)              # No N+1 problems
```

**You control:**
- When monitoring starts
- What to check
- Your performance limits

## ๐Ÿ“Š Real Output from Mercury

This is actual output from testing EduLite:

```text
๐ŸŽจ MERCURY PERFORMANCE DASHBOARD - UserSearchPerformanceTest
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ ๐Ÿš€ Overall Status: NEEDS IMPROVEMENT                          โ”‚
โ”‚ ๐ŸŽ“ Overall Grade: F (20.5/100)                               โ”‚
โ”‚ ๐Ÿ“Š Tests Executed: 12                                        โ”‚
โ”‚ โฑ๏ธ  Avg Response Time: 105.6ms                                โ”‚
โ”‚ ๐Ÿง  Avg Memory Usage: 91.7MB                                  โ”‚
โ”‚ ๐Ÿ—ƒ๏ธ  Total Queries: 2761 (230.1 avg)                          โ”‚
โ”‚ ๐Ÿšจ N+1 Issues: 10/12 tests affected                          โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
```

## ๐ŸŽ“ How Mercury Works

Mercury follows the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop/Community) way:

**80% Computer Help:**
- Watches performance automatically
- Finds N+1 problems
- Grades your code speed
- Manages limits

**20% Human Control:**
- You understand WHY speed matters
- You choose how to fix problems
- You learn from the guides
- You make design choices

**Example: How Mercury Teaches**

When a test fails, Mercury helps you learn:

```text
๐Ÿ“š MERCURY EDUCATIONAL GUIDANCE
============================================================
๐ŸŽฏ Test: test_user_list_view
โš ๏ธ  Default thresholds exceeded

๐Ÿ—ƒ๏ธ  Query Count: 230 (limit: 10)
   โ†’ 220 extra queries (2200% exceeded)

๐Ÿ’ก SOLUTION: N+1 Query Pattern Detected
   Your code is likely missing select_related() or prefetch_related()
   
   Try: User.objects.select_related('profile').prefetch_related('groups')

๐Ÿ› ๏ธ  Quick Fix for Testing:
   cls.set_performance_thresholds({'query_count_max': 250})
   
   But the REAL fix is optimizing your queries!
============================================================
```

## ๐Ÿ› ๏ธ Performance Checks

### Test Methods You Can Use

```python
# Check response time
self.assertResponseTimeLess(monitor, 100)    # Must be under 100ms
self.assertPerformanceFast(monitor)          # Must be fast
self.assertPerformanceNotSlow(monitor)       # Must not be slow

# Check database queries  
self.assertQueriesLess(monitor, 10)          # Must use less than 10 queries
self.assertNoNPlusOne(monitor)               # Must not have N+1 problems

# Check memory use
self.assertMemoryLess(monitor, 50)           # Must use less than 50MB
self.assertMemoryEfficient(monitor)          # Must use memory well

# Check cache use
self.assertGoodCachePerformance(monitor, 0.8) # Must hit cache 80% of time
```

## ๐Ÿ”ง Setup Options

```python
class MyTest(DjangoMercuryAPITestCase):
    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        
        # Turn Mercury features on or off
        cls.configure_mercury(
            enabled=True,               # Turn on Mercury
            auto_scoring=True,          # Grade tests automatically
            verbose_reporting=False,    # Show less detail
            educational_guidance=True   # Show help messages
        )
        
        # Set your speed limits
        cls.set_performance_thresholds({
            'response_time_ms': 100,    # Max time: 100ms
            'query_count_max': 10,      # Max queries: 10
            'memory_overhead_mb': 20,   # Max extra memory: 20MB
        })
```

## ๐Ÿงช Testing Django Mercury

We provide two test runners to help you test the framework.

### What Our Tests Do

Tests make sure Django Mercury works correctly. They check:
- Python code works as expected
- C extensions compile and run fast
- Performance monitoring catches problems
- Everything works together

### Two Test Runners

#### 1. Python Test Runner: `test_runner.py`

Tests all Python code with performance timing.

**Features:**
- Shows test speed with colors (๐ŸŸข fast, ๐ŸŸก medium, ๐Ÿ”ด slow, ๐Ÿ’€ very slow)
- Coverage reports (how much code is tested)
- Finds slow tests automatically
- Groups results by module

#### 2. C Test Runner: `c_test_runner.sh`  

Tests all C extensions for speed and correctness.

**Features:**
- Builds C libraries
- Runs unit tests
- Checks memory safety
- Generates coverage reports

### How to Run Tests

#### Quick Start (Test Everything)

```bash
# Test Python code
python test_runner.py

# Test C code  
./c_test_runner.sh test
```

#### Detailed Testing

```bash
# Python tests with coverage report
python test_runner.py --coverage --verbose

# C tests with coverage analysis
./c_test_runner.sh coverage

# Test everything
python test_runner.py --all
./c_test_runner.sh all
```

### Understanding Test Output

#### Python Test Colors

Your tests show timing with colors:

| Color | Time | Meaning |
|-------|------|---------|
| ๐ŸŸข Green | <0.1s | Fast - Great! |
| ๐ŸŸก Yellow | 0.1-0.5s | Medium - OK |
| ๐Ÿ”ด Red | 0.5-2s | Slow - Needs work |
| ๐Ÿ’€ Purple | >2s | Very slow - Problem! |

#### Example Output

```
๐Ÿš€ Starting Timed Test Run
==================================================
Legend: ๐ŸŸข <0.1s | ๐ŸŸก 0.1-0.5s | ๐Ÿ”ด >0.5s | ๐Ÿ’€ >2s
==================================================

๐Ÿƒ Running: tests.monitor.test_django_base ... ๐ŸŸข 0.045s โœ…
๐Ÿƒ Running: tests.monitor.test_metrics ... ๐ŸŸก 0.234s โœ…
๐Ÿƒ Running: tests.integration.test_api ... ๐Ÿ”ด 0.678s โœ…

๐Ÿ“Š PERFORMANCE SUMMARY
Total time: 0.957s
Average per test: 0.319s
```

### Common Testing Tasks

#### Run Specific Tests

```bash
# Test only monitor module
python test_runner.py --module monitor

# List all test modules
python test_runner.py --list-modules
```

#### Build and Clean

```bash
# Clean everything
./c_test_runner.sh clean

# Rebuild C libraries
./c_test_runner.sh build

# Run benchmarks
./c_test_runner.sh benchmark
```

#### Before You Commit

Always run these commands:

```bash
# 1. Check Python tests pass
python test_runner.py

# 2. Check C tests pass
./c_test_runner.sh test

# 3. Check code style
black django_mercury/
ruff check django_mercury/
```

### Adding Your Own Tests

#### Python Tests

Create a file in `tests/` directory:

```python
# tests/test_my_feature.py
import unittest
from django_mercury import DjangoMercuryAPITestCase

class TestMyFeature(DjangoMercuryAPITestCase):
    def test_feature_works(self):
        # Your test here
        response = self.client.get('/api/test/')
        self.assertEqual(response.status_code, 200)
```

#### C Tests

Create a file in `django_mercury/c_core/tests/`:

```c
// simple_test_myfeature.c
#include <stdio.h>
#include <assert.h>

int main() {
    printf("Testing my feature...\n");
    // Your test here
    assert(1 == 1);
    printf("โœ… Test passed!\n");
    return 0;
}
```

### Getting Help

- **Test failures?** Check the error message first
- **Slow tests?** Look for `time.sleep()` or database queries
- **C compilation errors?** Run `./c_test_runner.sh clean` then `build`
- **Still stuck?** Open an issue with your test output

## ๐ŸŽฏ Real Results at EduLite

Before Mercury:
- UserSearchView used **825 queries** to show one page
- We could not see speed problems
- Students with slow internet could not use the app

After Mercury:
- Found the exact problem
- Fixed it to use only **12 queries**
- Now we check speed on every code change

## ๐Ÿšง Future Plans

### Phase 1: First Release โœ…
- โœ… Watch performance
- โœ… Find N+1 problems
- โœ… Show helpful guides
- โœ… Available on PyPI

### Phase 2: Make It Better
- ๐Ÿ”œ Fix test problems
- ๐Ÿ”œ Support all view types
- ๐Ÿ”œ Track speed over time
- ๐Ÿ”œ Find when code gets slower
- ๐Ÿ”œ Better guides and examples

### Phase 3: Add AI Help
- ๐Ÿ”œ AI suggests fixes
- ๐Ÿ”œ Create fixes you can review
- ๐Ÿ”œ Help new developers learn
- ๐Ÿ”œ Let you add custom checks

## ๐Ÿค Contributing

Mercury is part of [EduLite](https://github.com/ibrahim-sisar/EduLite) and [Human in the Loop](https://github.com/80-20-Human-In-The-Loop). We welcome everyone.

### Our Values

- **Education First**: Tools should teach, not just find problems
- **Human Understanding**: You control your code
- **Open Source**: Built together, shared with everyone

### How You Can Help

1. **Test Mercury** - Try it on your Django project
2. **Report Problems** - Tell us what doesn't work
3. **Share Ideas** - Suggest improvements
4. **Write Code** - Fix bugs or add features
5. **Improve Docs** - Make them clearer
6. **Help Others** - Answer questions

### Getting Started

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

**New to open source?** Start here:
- Look for "good first issue" labels
- Ask questions - we're here to help
- Small fixes matter too

## ๐Ÿซ Made for Learning

Mercury was made for [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn even with slow internet. Mercury helps by:

- Working on slow computers
- Teaching as it tests
- Helping developers learn
- Making apps work for everyone

## ๐Ÿ“„ License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

### Why GPL-3.0?

We use GPL-3.0 because it matches our values:

- **๐ŸŒ Open**: Code stays open for everyone
- **๐Ÿ†“ Free**: You can use, study, share, and improve it
- **โš–๏ธ Fair**: Improvements must be shared
- **๐Ÿค Copyleft**: Stays free forever

If you share a changed version, you must:
- Share your code
- Use GPL-3.0 license
- Keep all notices
- List your changes

This keeps knowledge open for all.

For the full license text, see [LICENSE](LICENSE) or visit [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).

## ๐Ÿ™ Thanks To

- [EduLite Team](https://github.com/ibrahim-sisar/EduLite) - For showing us the need
- [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) - For the ideas
- Django/DRF Community - For the tools

---

**Mercury**: Making performance testing simple for everyone.

*Built with โค๏ธ by developers who believe people should understand their code.*

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Django-Mercury/Performance-Testing",
    "name": "django-mercury-performance",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Mathew Storm <mathewstormdev@gmail.com>",
    "keywords": "django, performance, testing, monitoring, optimization, n+1, queries, profiling, mercury, rest-framework, api, benchmarking",
    "author": "Django Mercury Team",
    "author_email": "Django Mercury Team <mathewstormdev@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/e6/e1/933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb/django_mercury_performance-0.0.2.tar.gz",
    "platform": null,
    "description": "# Django Mercury \ud83d\ude80\n\n[![PyPI version](https://badge.fury.io/py/django-mercury-performance.svg)](https://badge.fury.io/py/django-mercury-performance)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Django 3.2-5.1](https://img.shields.io/badge/django-3.2--5.1-green.svg)](https://docs.djangoproject.com/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Built for: EduLite](https://img.shields.io/badge/Built%20for-EduLite-orange)](https://github.com/ibrahim-sisar/EduLite)\n[![Values: Open](https://img.shields.io/badge/Values-Open%20%7C%20Free%20%7C%20Fair-purple)](https://github.com/80-20-Human-In-The-Loop)\n\n**Part of the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) ecosystem**\n\n> Test Django app speed. Learn why it's slow. Fix it.\n\n## \ud83d\ude80 Quick Install\n\n```bash\npip install django-mercury-performance\n```\n\nThen in your test files:\n```python\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass MyPerformanceTest(DjangoMercuryAPITestCase):\n    def test_api_performance(self):\n        response = self.client.get('/api/endpoint/')\n        # Performance is automatically monitored and reported!\n```\n\n## \ud83c\udf1f Origin Story\n\nMercury started at [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn with slow internet. We found our UserSearchView made **825 database queries** to show one page!\n\nWe built Mercury to find these problems and teach you how to fix them. Mercury follows EduLite's values: **Fair**, **Free**, and **Open**. Everyone can use it and learn.\n\n## \ud83c\udfaf Current Status: v0.0.2 on PyPI! \ud83c\udf89\n\n**What Works Now:**\n- \u2705 **Install from PyPI** - `pip install django-mercury-performance`\n- \u2705 Finds N+1 query problems\n- \u2705 Grades speed (F to A+) \n- \u2705 Two test types: `DjangoMercuryAPITestCase` and `DjangoPerformanceAPITestCase`\n- \u2705 Knows what type of code runs\n- \u2705 Teaches when tests fail\n- \u2705 Fast C code for speed\n- \u2705 Tracks time, queries, and memory\n\n**What We Actually Found:**\n```text\n\ud83d\udea8 POTENTIAL N+1 QUERY PROBLEM! \ud83d\udea8\nSeverity: CRITICAL (825 queries)\n```\n\n**Coming Soon:**\n- \ud83d\udd1c AI help to fix slow code\n- \ud83d\udd1c Track speed over time\n- \ud83d\udd1c Test all view types\n- \ud83d\udd1c Find when code gets slower\n- \ud83d\udd1c Better test support\n\n## \ud83d\udce6 Installation\n\n### Install from PyPI (Recommended)\n\n```bash\npip install django-mercury-performance\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/Django-Mercury/Performance-Testing.git\ncd Django-Mercury-Performance-Testing\n\n# Install in development mode\npip install -e .\n\n# If you want to modify the C extensions\ncd django_mercury/c_core\nmake clean && make\n```\n\n## \ud83d\ude80 Quick Start\n\n### Two Ways to Test Performance\n\nChoose the test class that fits your needs.\n\n#### 1. DjangoMercuryAPITestCase - Automatic Testing\n\nMercury watches your tests automatically. You write normal tests. Mercury finds problems.\n\n```python\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass UserSearchPerformanceTest(DjangoMercuryAPITestCase):\n    \"\"\"Mercury monitors every test automatically.\"\"\"\n    \n    def test_user_search(self):\n        # Write your normal test\n        response = self.client.get('/api/users/search/?q=test')\n        self.assertEqual(response.status_code, 200)\n        # Mercury checks performance automatically\n```\n\n**What Mercury does:**\n- Counts database queries\n- Measures response time  \n- Tracks memory usage\n- Finds N+1 problems\n- Shows clear reports\n\n#### 2. DjangoPerformanceAPITestCase - Manual Control\n\nYou control when to monitor. Good for specific performance checks.\n\n```python\nfrom django_mercury import DjangoPerformanceAPITestCase\nfrom django_mercury import monitor_django_view\n\nclass AdvancedPerformanceTest(DjangoPerformanceAPITestCase):\n    \"\"\"Control exactly what you test.\"\"\"\n    \n    def test_with_assertions(self):\n        with monitor_django_view(\"search\") as monitor:\n            response = self.client.get('/api/users/search/')\n        \n        # Check specific limits\n        self.assertResponseTimeLess(monitor, 100)  # Under 100ms\n        self.assertQueriesLess(monitor, 10)         # Under 10 queries\n        self.assertNoNPlusOne(monitor)              # No N+1 problems\n```\n\n**You control:**\n- When monitoring starts\n- What to check\n- Your performance limits\n\n## \ud83d\udcca Real Output from Mercury\n\nThis is actual output from testing EduLite:\n\n```text\n\ud83c\udfa8 MERCURY PERFORMANCE DASHBOARD - UserSearchPerformanceTest\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \ud83d\ude80 Overall Status: NEEDS IMPROVEMENT                          \u2502\n\u2502 \ud83c\udf93 Overall Grade: F (20.5/100)                               \u2502\n\u2502 \ud83d\udcca Tests Executed: 12                                        \u2502\n\u2502 \u23f1\ufe0f  Avg Response Time: 105.6ms                                \u2502\n\u2502 \ud83e\udde0 Avg Memory Usage: 91.7MB                                  \u2502\n\u2502 \ud83d\uddc3\ufe0f  Total Queries: 2761 (230.1 avg)                          \u2502\n\u2502 \ud83d\udea8 N+1 Issues: 10/12 tests affected                          \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## \ud83c\udf93 How Mercury Works\n\nMercury follows the [Human in the Loop](https://github.com/80-20-Human-In-The-Loop/Community) way:\n\n**80% Computer Help:**\n- Watches performance automatically\n- Finds N+1 problems\n- Grades your code speed\n- Manages limits\n\n**20% Human Control:**\n- You understand WHY speed matters\n- You choose how to fix problems\n- You learn from the guides\n- You make design choices\n\n**Example: How Mercury Teaches**\n\nWhen a test fails, Mercury helps you learn:\n\n```text\n\ud83d\udcda MERCURY EDUCATIONAL GUIDANCE\n============================================================\n\ud83c\udfaf Test: test_user_list_view\n\u26a0\ufe0f  Default thresholds exceeded\n\n\ud83d\uddc3\ufe0f  Query Count: 230 (limit: 10)\n   \u2192 220 extra queries (2200% exceeded)\n\n\ud83d\udca1 SOLUTION: N+1 Query Pattern Detected\n   Your code is likely missing select_related() or prefetch_related()\n   \n   Try: User.objects.select_related('profile').prefetch_related('groups')\n\n\ud83d\udee0\ufe0f  Quick Fix for Testing:\n   cls.set_performance_thresholds({'query_count_max': 250})\n   \n   But the REAL fix is optimizing your queries!\n============================================================\n```\n\n## \ud83d\udee0\ufe0f Performance Checks\n\n### Test Methods You Can Use\n\n```python\n# Check response time\nself.assertResponseTimeLess(monitor, 100)    # Must be under 100ms\nself.assertPerformanceFast(monitor)          # Must be fast\nself.assertPerformanceNotSlow(monitor)       # Must not be slow\n\n# Check database queries  \nself.assertQueriesLess(monitor, 10)          # Must use less than 10 queries\nself.assertNoNPlusOne(monitor)               # Must not have N+1 problems\n\n# Check memory use\nself.assertMemoryLess(monitor, 50)           # Must use less than 50MB\nself.assertMemoryEfficient(monitor)          # Must use memory well\n\n# Check cache use\nself.assertGoodCachePerformance(monitor, 0.8) # Must hit cache 80% of time\n```\n\n## \ud83d\udd27 Setup Options\n\n```python\nclass MyTest(DjangoMercuryAPITestCase):\n    @classmethod\n    def setUpClass(cls):\n        super().setUpClass()\n        \n        # Turn Mercury features on or off\n        cls.configure_mercury(\n            enabled=True,               # Turn on Mercury\n            auto_scoring=True,          # Grade tests automatically\n            verbose_reporting=False,    # Show less detail\n            educational_guidance=True   # Show help messages\n        )\n        \n        # Set your speed limits\n        cls.set_performance_thresholds({\n            'response_time_ms': 100,    # Max time: 100ms\n            'query_count_max': 10,      # Max queries: 10\n            'memory_overhead_mb': 20,   # Max extra memory: 20MB\n        })\n```\n\n## \ud83e\uddea Testing Django Mercury\n\nWe provide two test runners to help you test the framework.\n\n### What Our Tests Do\n\nTests make sure Django Mercury works correctly. They check:\n- Python code works as expected\n- C extensions compile and run fast\n- Performance monitoring catches problems\n- Everything works together\n\n### Two Test Runners\n\n#### 1. Python Test Runner: `test_runner.py`\n\nTests all Python code with performance timing.\n\n**Features:**\n- Shows test speed with colors (\ud83d\udfe2 fast, \ud83d\udfe1 medium, \ud83d\udd34 slow, \ud83d\udc80 very slow)\n- Coverage reports (how much code is tested)\n- Finds slow tests automatically\n- Groups results by module\n\n#### 2. C Test Runner: `c_test_runner.sh`  \n\nTests all C extensions for speed and correctness.\n\n**Features:**\n- Builds C libraries\n- Runs unit tests\n- Checks memory safety\n- Generates coverage reports\n\n### How to Run Tests\n\n#### Quick Start (Test Everything)\n\n```bash\n# Test Python code\npython test_runner.py\n\n# Test C code  \n./c_test_runner.sh test\n```\n\n#### Detailed Testing\n\n```bash\n# Python tests with coverage report\npython test_runner.py --coverage --verbose\n\n# C tests with coverage analysis\n./c_test_runner.sh coverage\n\n# Test everything\npython test_runner.py --all\n./c_test_runner.sh all\n```\n\n### Understanding Test Output\n\n#### Python Test Colors\n\nYour tests show timing with colors:\n\n| Color | Time | Meaning |\n|-------|------|---------|\n| \ud83d\udfe2 Green | <0.1s | Fast - Great! |\n| \ud83d\udfe1 Yellow | 0.1-0.5s | Medium - OK |\n| \ud83d\udd34 Red | 0.5-2s | Slow - Needs work |\n| \ud83d\udc80 Purple | >2s | Very slow - Problem! |\n\n#### Example Output\n\n```\n\ud83d\ude80 Starting Timed Test Run\n==================================================\nLegend: \ud83d\udfe2 <0.1s | \ud83d\udfe1 0.1-0.5s | \ud83d\udd34 >0.5s | \ud83d\udc80 >2s\n==================================================\n\n\ud83c\udfc3 Running: tests.monitor.test_django_base ... \ud83d\udfe2 0.045s \u2705\n\ud83c\udfc3 Running: tests.monitor.test_metrics ... \ud83d\udfe1 0.234s \u2705\n\ud83c\udfc3 Running: tests.integration.test_api ... \ud83d\udd34 0.678s \u2705\n\n\ud83d\udcca PERFORMANCE SUMMARY\nTotal time: 0.957s\nAverage per test: 0.319s\n```\n\n### Common Testing Tasks\n\n#### Run Specific Tests\n\n```bash\n# Test only monitor module\npython test_runner.py --module monitor\n\n# List all test modules\npython test_runner.py --list-modules\n```\n\n#### Build and Clean\n\n```bash\n# Clean everything\n./c_test_runner.sh clean\n\n# Rebuild C libraries\n./c_test_runner.sh build\n\n# Run benchmarks\n./c_test_runner.sh benchmark\n```\n\n#### Before You Commit\n\nAlways run these commands:\n\n```bash\n# 1. Check Python tests pass\npython test_runner.py\n\n# 2. Check C tests pass\n./c_test_runner.sh test\n\n# 3. Check code style\nblack django_mercury/\nruff check django_mercury/\n```\n\n### Adding Your Own Tests\n\n#### Python Tests\n\nCreate a file in `tests/` directory:\n\n```python\n# tests/test_my_feature.py\nimport unittest\nfrom django_mercury import DjangoMercuryAPITestCase\n\nclass TestMyFeature(DjangoMercuryAPITestCase):\n    def test_feature_works(self):\n        # Your test here\n        response = self.client.get('/api/test/')\n        self.assertEqual(response.status_code, 200)\n```\n\n#### C Tests\n\nCreate a file in `django_mercury/c_core/tests/`:\n\n```c\n// simple_test_myfeature.c\n#include <stdio.h>\n#include <assert.h>\n\nint main() {\n    printf(\"Testing my feature...\\n\");\n    // Your test here\n    assert(1 == 1);\n    printf(\"\u2705 Test passed!\\n\");\n    return 0;\n}\n```\n\n### Getting Help\n\n- **Test failures?** Check the error message first\n- **Slow tests?** Look for `time.sleep()` or database queries\n- **C compilation errors?** Run `./c_test_runner.sh clean` then `build`\n- **Still stuck?** Open an issue with your test output\n\n## \ud83c\udfaf Real Results at EduLite\n\nBefore Mercury:\n- UserSearchView used **825 queries** to show one page\n- We could not see speed problems\n- Students with slow internet could not use the app\n\nAfter Mercury:\n- Found the exact problem\n- Fixed it to use only **12 queries**\n- Now we check speed on every code change\n\n## \ud83d\udea7 Future Plans\n\n### Phase 1: First Release \u2705\n- \u2705 Watch performance\n- \u2705 Find N+1 problems\n- \u2705 Show helpful guides\n- \u2705 Available on PyPI\n\n### Phase 2: Make It Better\n- \ud83d\udd1c Fix test problems\n- \ud83d\udd1c Support all view types\n- \ud83d\udd1c Track speed over time\n- \ud83d\udd1c Find when code gets slower\n- \ud83d\udd1c Better guides and examples\n\n### Phase 3: Add AI Help\n- \ud83d\udd1c AI suggests fixes\n- \ud83d\udd1c Create fixes you can review\n- \ud83d\udd1c Help new developers learn\n- \ud83d\udd1c Let you add custom checks\n\n## \ud83e\udd1d Contributing\n\nMercury is part of [EduLite](https://github.com/ibrahim-sisar/EduLite) and [Human in the Loop](https://github.com/80-20-Human-In-The-Loop). We welcome everyone.\n\n### Our Values\n\n- **Education First**: Tools should teach, not just find problems\n- **Human Understanding**: You control your code\n- **Open Source**: Built together, shared with everyone\n\n### How You Can Help\n\n1. **Test Mercury** - Try it on your Django project\n2. **Report Problems** - Tell us what doesn't work\n3. **Share Ideas** - Suggest improvements\n4. **Write Code** - Fix bugs or add features\n5. **Improve Docs** - Make them clearer\n6. **Help Others** - Answer questions\n\n### Getting Started\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n**New to open source?** Start here:\n- Look for \"good first issue\" labels\n- Ask questions - we're here to help\n- Small fixes matter too\n\n## \ud83c\udfeb Made for Learning\n\nMercury was made for [EduLite](https://github.com/ibrahim-sisar/EduLite). EduLite helps students learn even with slow internet. Mercury helps by:\n\n- Working on slow computers\n- Teaching as it tests\n- Helping developers learn\n- Making apps work for everyone\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0).\n\n### Why GPL-3.0?\n\nWe use GPL-3.0 because it matches our values:\n\n- **\ud83c\udf0d Open**: Code stays open for everyone\n- **\ud83c\udd93 Free**: You can use, study, share, and improve it\n- **\u2696\ufe0f Fair**: Improvements must be shared\n- **\ud83e\udd1d Copyleft**: Stays free forever\n\nIf you share a changed version, you must:\n- Share your code\n- Use GPL-3.0 license\n- Keep all notices\n- List your changes\n\nThis keeps knowledge open for all.\n\nFor the full license text, see [LICENSE](LICENSE) or visit [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).\n\n## \ud83d\ude4f Thanks To\n\n- [EduLite Team](https://github.com/ibrahim-sisar/EduLite) - For showing us the need\n- [Human in the Loop](https://github.com/80-20-Human-In-The-Loop) - For the ideas\n- Django/DRF Community - For the tools\n\n---\n\n**Mercury**: Making performance testing simple for everyone.\n\n*Built with \u2764\ufe0f by developers who believe people should understand their code.*\n",
    "bugtrack_url": null,
    "license": "GPL-3.0-or-later",
    "summary": "A performance testing framework for Django that helps you understand and fix performance issues, not just detect them",
    "version": "0.0.2",
    "project_urls": {
        "Bug Tracker": "https://github.com/Django-Mercury/Performance-Testing/issues",
        "Changelog": "https://github.com/Django-Mercury/Performance-Testing/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/Django-Mercury/Performance-Testing#readme",
        "Homepage": "https://github.com/Django-Mercury/Performance-Testing",
        "Repository": "https://github.com/Django-Mercury/Performance-Testing.git"
    },
    "split_keywords": [
        "django",
        " performance",
        " testing",
        " monitoring",
        " optimization",
        " n+1",
        " queries",
        " profiling",
        " mercury",
        " rest-framework",
        " api",
        " benchmarking"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9d0c287e60b924400bd0ccad5cdd62c26ac0e284f9c27b54e99e8d6c6db5917c",
                "md5": "280df6fcdd79eb70c4a2fda72c87b543",
                "sha256": "ab6083790140019d6de4d3e3c6723ca9c32487945204f6459b63e1440376bdea"
            },
            "downloads": -1,
            "filename": "django_mercury_performance-0.0.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "280df6fcdd79eb70c4a2fda72c87b543",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 235765,
            "upload_time": "2025-08-03T14:55:31",
            "upload_time_iso_8601": "2025-08-03T14:55:31.191956Z",
            "url": "https://files.pythonhosted.org/packages/9d/0c/287e60b924400bd0ccad5cdd62c26ac0e284f9c27b54e99e8d6c6db5917c/django_mercury_performance-0.0.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e6e1933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb",
                "md5": "b4ad68e7481a7cf7b24e95512d2d6c0d",
                "sha256": "abf009017caab572c27a47330e562b9a1dff93897fa327c815632f34db2b7093"
            },
            "downloads": -1,
            "filename": "django_mercury_performance-0.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "b4ad68e7481a7cf7b24e95512d2d6c0d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 253854,
            "upload_time": "2025-08-03T14:55:32",
            "upload_time_iso_8601": "2025-08-03T14:55:32.756223Z",
            "url": "https://files.pythonhosted.org/packages/e6/e1/933212934ab0d3a20a7ea0ec303760a20d8e58230183b4fa9a9b0288bddb/django_mercury_performance-0.0.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-03 14:55:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Django-Mercury",
    "github_project": "Performance-Testing",
    "github_not_found": true,
    "lcname": "django-mercury-performance"
}
        
Elapsed time: 0.72524s