Allow passing label values as keyword arguments

Author: alex

README.md

@@ -185,7 +185,16 @@ c.labels('get', '/').inc()
 c.labels('post', '/submit').inc()
 ```
 
-Labels can also be provided as a dict:
+Labels can also be passed as keyword-arguments:
+
+```python
+from prometheus_client import Counter
+c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
+c.labels(method='get', endpoint='/').inc()
+c.labels(method='post', endpoint='/submit').inc()
+```
+
+Or as a dict:
 
 ```python
 from prometheus_client import Counter
@@ -369,7 +378,7 @@ REGISTRY.register(CustomCollector())
 ## Parser
 
 The Python client supports parsing the Promeheus text format.
-This is intended for advanced use cases where you have servers 
+This is intended for advanced use cases where you have servers
 exposing Prometheus metrics and need to get them into some other
 system.
 
@@ -379,4 +388,3 @@ for family in text_string_to_metric_families("my_gauge 1.0\n"):
   for sample in family.samples:
     print("Name: {0} Labels: {1} Value: {2}".format(*sample))
 ```
-

prometheus_client/core.py

@@ -253,7 +253,7 @@ def __init__(self, wrappedClass, name, labelnames, **kwargs):
             if l.startswith('__'):
                 raise ValueError('Invalid label metric name: ' + l)
 
-    def labels(self, *labelvalues):
+    def labels(self, *labelvalues, **labelkwargs):
         '''Return the child for the given labelset.
 
         All metrics can have labels, allowing grouping of related time series.
@@ -276,10 +276,17 @@ def labels(self, *labelvalues):
         See the best practices on [naming](http://prometheus.io/docs/practices/naming/)
         and [labels](http://prometheus.io/docs/practices/instrumentation/#use-labels).
         '''
+        if labelvalues and labelkwargs:
+            raise ValueError("Can't pass both *args and **kwargs")
+
         if len(labelvalues) == 1 and type(labelvalues[0]) == dict:
             if sorted(labelvalues[0].keys()) != sorted(self._labelnames):
                 raise ValueError('Incorrect label names')
             labelvalues = tuple([unicode(labelvalues[0][l]) for l in self._labelnames])
+        elif labelkwargs:
+            if sorted(labelkwargs) != sorted(self._labelnames):
+                raise ValueError('Incorrect label names')
+            labelvalues = tuple([unicode(labelkwargs[l]) for l in self._labelnames])
         else:
             if len(labelvalues) != len(self._labelnames):
                 raise ValueError('Incorrect label count')

tests/test_core.py

@@ -280,6 +280,21 @@ def test_labels_by_dict(self):
         self.assertRaises(ValueError, self.two_labels.labels, {'c': 'z'})
         self.assertRaises(ValueError, self.two_labels.labels, {})
 
+    def test_labels_by_kwarg(self):
+        self.counter.labels(l='x').inc()
+        self.assertEqual(1, self.registry.get_sample_value('c', {'l': 'x'}))
+        self.assertRaises(ValueError, self.counter.labels, l='x', m='y')
+        self.assertRaises(ValueError, self.counter.labels, m='y')
+        self.assertRaises(ValueError, self.counter.labels)
+        self.two_labels.labels(a='x', b='y').inc()
+        self.assertEqual(1, self.registry.get_sample_value('two', {'a': 'x', 'b': 'y'}))
+        self.assertRaises(ValueError, self.two_labels.labels, a='x', b='y', c='z')
+        self.assertRaises(ValueError, self.two_labels.labels, a='x', c='z')
+        self.assertRaises(ValueError, self.two_labels.labels, b='y', c='z')
+        self.assertRaises(ValueError, self.two_labels.labels, c='z')
+        self.assertRaises(ValueError, self.two_labels.labels)
+        self.assertRaises(ValueError, self.two_labels.labels, {'a': 'x'}, b='y')
+
     def test_invalid_names_raise(self):
         self.assertRaises(ValueError, Counter, '', 'help')
         self.assertRaises(ValueError, Counter, '^', 'help')