From 8c4ec19e537c718d59786a144854032f88b83817 Mon Sep 17 00:00:00 2001
From: Gilles Lepretre <gilles.lepretre@kozea.fr>
Date: Sat, 29 Nov 2025 00:27:03 +0100
Subject: [PATCH] Add reverse_direction Gauge config parameter

Refactors https://github.com/Kozea/pygal/pull/567
---
 .../configuration/specific_options.rst        | 15 ++++++++
 docs/documentation/types/gauge.rst            | 15 ++++++++
 pygal/config.py                               |  4 +++
 pygal/graph/gauge.py                          |  5 ++-
 pygal/test/test_gauge.py                      | 35 +++++++++++++++++++
 5 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 pygal/test/test_gauge.py

diff --git a/docs/documentation/configuration/specific_options.rst b/docs/documentation/configuration/specific_options.rst
index 9f9c3941..74358259 100644
--- a/docs/documentation/configuration/specific_options.rst
+++ b/docs/documentation/configuration/specific_options.rst
@@ -30,6 +30,21 @@ half_pie
   pie_chart.add('Opera', 2.3)
 
 
+
+reverse_direction
+-----------------
+
+You can reverse the direction of the gauge by setting ``reverse_direction=True``:
+
+.. pygal-code::
+
+  gauge_chart = pygal.Gauge(reverse_direction=True)
+  gauge_chart.add('Chrome', 8212)
+  gauge_chart.add('Firefox', 8099)
+  gauge_chart.add('Opera', 2933)
+  gauge_chart.add('IE', 41)
+
+
 inner_radius
 ------------
 
diff --git a/docs/documentation/types/gauge.rst b/docs/documentation/types/gauge.rst
index c5c3ff47..06e17186 100644
--- a/docs/documentation/types/gauge.rst
+++ b/docs/documentation/types/gauge.rst
@@ -15,3 +15,18 @@ Gauge chart:
   gauge_chart.add('Firefox', 8099)
   gauge_chart.add('Opera', 2933)
   gauge_chart.add('IE', 41)
+
+Reverse
+~~~~~~~
+
+Gauge chart can be reversed:
+
+.. pygal-code:: 600 550
+
+  gauge_chart = pygal.Gauge(human_readable=True, reverse_direction=True)
+  gauge_chart.title = 'DeltaBlue V8 benchmark results'
+  gauge_chart.range = [0, 10000]
+  gauge_chart.add('Chrome', 8212)
+  gauge_chart.add('Firefox', 8099)
+  gauge_chart.add('Opera', 2933)
+  gauge_chart.add('IE', 41)
diff --git a/pygal/config.py b/pygal/config.py
index 35f0deeb..1ac190b2 100644
--- a/pygal/config.py
+++ b/pygal/config.py
@@ -324,6 +324,10 @@ class Config(CommonConfig):
 
     half_pie = Key(False, bool, "Look", "Create a half-pie chart")
 
+    reverse_direction = Key(
+        False, bool, "Look", "Reverse the direction of the gauge"
+    )
+
     x_labels = Key(
         None, list, "Label", "X labels, must have same len than data.",
         "Leave it to None to disable x labels display.", str
diff --git a/pygal/graph/gauge.py b/pygal/graph/gauge.py
index ee022e98..2acfda6b 100644
--- a/pygal/graph/gauge.py
+++ b/pygal/graph/gauge.py
@@ -132,7 +132,10 @@ def _compute(self):
             self.min_ -= 1
             self.max_ += 1
 
-        self._box.set_polar_box(0, 1, self.min_, self.max_)
+        if self.reverse_direction:
+            self._box.set_polar_box(0, 1, self.max_, self.min_)
+        else:
+            self._box.set_polar_box(0, 1, self.min_, self.max_)
 
     def _compute_x_labels(self):
         pass
diff --git a/pygal/test/test_gauge.py b/pygal/test/test_gauge.py
new file mode 100644
index 00000000..07696e81
--- /dev/null
+++ b/pygal/test/test_gauge.py
@@ -0,0 +1,35 @@
+from pygal import Gauge
+
+
+def test_gauge_reverse_direction():
+    """Test that reverse_direction config is respected"""
+    gauge = Gauge(reverse_direction=True)
+    assert gauge.config.reverse_direction is True
+
+    gauge.add('A', 10)
+    gauge.range = (0, 10)
+    gauge.setup()
+
+    # When reversed, the polar box should be (0, 1, max, min)
+    # min=0, max=10
+    # reversed: (0, 1, 10, 0)
+    assert gauge._box._tmin == 10
+    assert gauge._box._tmax == 0
+    assert gauge._box._rmin == 0
+    assert gauge._box._rmax == 1
+
+def test_gauge_normal_direction():
+    """Test that normal direction works as expected"""
+    gauge = Gauge()
+    assert gauge.config.reverse_direction is False
+
+    gauge.add('A', 10)
+    gauge.range = (0, 10)
+    gauge.setup()
+
+    # min=0, max=10
+    # normal: (0, 1, 0, 10)
+    assert gauge._box._tmin == 0
+    assert gauge._box._tmax == 10
+    assert gauge._box._rmin == 0
+    assert gauge._box._rmax == 1