update doc for dump_hdrh

Change-Id: Id0903709edb56d7fe78638071b4a0220b81916ad

README.rst

@@ -191,6 +191,45 @@ Just run tox without any argument (the first run will take more time as tox will
       lint: commands succeeded
       congratulations :)
 
+Utility to dump an encoded histogram string (dump_hdrh)
+-------------------------------------------------------
+
+You can dump any encoded histogram using the dump_hdrh tool (installed along with the package).
+
+.. code::
+
+   $ dump_hdrh
+
+   Usage: dump_hdrh [<string encoded hdr histogram>]*
+
+You can pass one or more histogram strings to the tools:
+
+.. code::
+
+   $ dump_hdrh 'HISTFAAAACl4nJNpmSzMwMDAxQABzFCaEUzOmNZg/wEi0NzIyPSYlWmpGBMAh4gG4A=='
+
+   Dumping histogram: HISTFAAAACl4nJNpmSzMwMDAxQABzFCaEUzOmNZg/wEi0NzIyPSYlWmpGBMAh4gG4A==
+
+         Value     Percentile TotalCount 1/(1-Percentile)
+
+   139647.000 0.000000000000          1           1.00
+   139647.000 0.100000000000          1           1.11
+   139647.000 0.190000000000          1           1.23
+   139647.000 0.271000000000          1           1.37
+   187135.000 0.343900000000          2           1.52
+   187135.000 0.409510000000          2           1.69
+   187135.000 0.468559000000          2           1.88
+   187135.000 0.521703100000          2           2.09
+   187135.000 0.569532790000          2           2.32
+   187135.000 0.612579511000          2           2.58
+   187135.000 0.651321559900          2           2.87
+   477695.000 0.686189403910          3           3.19
+   477695.000 1.000000000000          3
+   #[Mean    =   268074.667, StdDeviation   =   149397.390]
+   #[Max     =   477695.000, TotalCount     =        3.000]
+   #[Buckets =           14, SubBuckets     =         2048]
+
+
 Aggregation of Distributed Histograms
 -------------------------------------
 

hdrh/dump.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+'''
+Utility to dump any hdrh histogram from encoded string
+
+Written by Alec Hothan
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'''
+import sys
+
+from hdrh.histogram import HdrHistogram
+
+
+def main():
+    args = sys.argv[1:]
+    if args:
+        encoded_histograms = args
+        for hdrh in encoded_histograms:
+            print('\nDumping histogram: ' + hdrh + '\n')
+            HdrHistogram.dump(hdrh)
+    else:
+        print('\nUsage: %s [<string encoded hdr histogram>]*\n' % (sys.argv[0]))
+
+
+if __name__ == '__main__':
+    main()

hdrh/histogram.py

@@ -607,3 +607,26 @@ def output_percentile_distribution(self,
             self.significant_figures).encode() % (max, total))
         out_file.write(b'#[Buckets = %12d, SubBuckets     = %12d]\n' % (
             self.bucket_count, self.sub_bucket_count))
+
+    @staticmethod
+    def dump(encoded_histogram, output=None,
+             output_value_unit_scaling_ratio=1):
+        """Dump a string encoded histogram to the provider output
+
+        param output: a writable buffer output,
+                      if None output will be written to stdout
+        param output_value_unit_scaling_ratio: scaling ratio, the amount
+                    by which values will be divided for display, defaults to 1
+        """
+        histogram = HdrHistogram.decode(encoded_histogram)
+
+        if output is None:
+            # sys.stdout.buffer will raise AttributeError in python 2.7
+            try:
+                # python 3 requires .buffer to write bytes
+                output = sys.stdout.buffer
+            except AttributeError:
+                # in python 2.7, bytes can be writtent to sys.stdout
+                output = sys.stdout
+        histogram.output_percentile_distribution(output,
+                                                output_value_unit_scaling_ratio)

setup.cfg

@@ -21,3 +21,10 @@ classifier =
 [files]
 packages =
     hdrh
+
+[entry_points]
+console_scripts =
+    dump_hdrh = hdrh.dump:main
+
+[wheel]
+universal = 1

test/test_hdrh_dump.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python
 '''
 Test code for the python version of HdrHistogram.
 
@@ -25,40 +26,13 @@
 from hdrh.histogram import HdrHistogram
 
 
-ENCODE_SAMPLES_HDRHISTOGRAM_C = [
-    # standard Hdr test histogram
-    'HISTFAAAACF4nJNpmSzMwMDAzAABMJoRTM6Y1mD/ASLwN5oJAFuQBYU=',
-    'HISTFAAAACh4nJNpmSzMwMDAyQABzFCaEUzOmNZg/wEisL2Kaasc00ImJgCC8Qbe'
-]
-
-def dump_histogram(encoded_histogram):
-    print('\nDumping histogram: ' + encoded_histogram)
-    histogram = HdrHistogram.decode(encoded_histogram)
-
-    histogram.output_percentile_distribution(open(os.devnull, 'wb'), 1)
-    # sys.stdout.buffer will raise AttributeError in python 2.7
-    try:
-        # python 3 requires .buffer to write bytes
-        output = sys.stdout.buffer
-    except AttributeError:
-        # in python 2.7, bytes can be writtent to sys.stdout
-        output = sys.stdout
-    histogram.output_percentile_distribution(output, 1)
-
 def test_dump_histogram():
+    ENCODE_SAMPLES_HDRHISTOGRAM_C = [
+        # standard Hdr test histogram
+        'HISTFAAAACF4nJNpmSzMwMDAzAABMJoRTM6Y1mD/ASLwN5oJAFuQBYU=',
+        'HISTFAAAACh4nJNpmSzMwMDAyQABzFCaEUzOmNZg/wEisL2Kaasc00ImJgCC8Qbe'
+    ]
     for hdrh in ENCODE_SAMPLES_HDRHISTOGRAM_C:
-        dump_histogram(hdrh)
-
-def main():
-    args = sys.argv[1:]
-    if args:
-        encoded_histograms = args
-    else:
-        encoded_histograms = ENCODE_SAMPLES_HDRHISTOGRAM_C
-
-    for hdrh in encoded_histograms:
-        dump_histogram(hdrh)
-
+        HdrHistogram.dump(hdrh, output=open(os.devnull, 'wb'))
+        HdrHistogram.dump(hdrh)
 
-if __name__ == '__main__':
-    main()