Patchwork [1,of,9] util: document bundle compression

login
register
mail settings
Submitter Gregory Szorc
Date April 1, 2017, 10:31 p.m.
Message ID <360b42187ffe5efc75ed.1491085912@ubuntu-vm-main>
Download mbox | patch
Permalink /patch/19893/
State Accepted
Headers show

Comments

Gregory Szorc - April 1, 2017, 10:31 p.m.
# HG changeset patch
# User Gregory Szorc <gregory.szorc@gmail.com>
# Date 1491078541 25200
#      Sat Apr 01 13:29:01 2017 -0700
# Node ID 360b42187ffe5efc75ed82dc67bf82937b3d1269
# Parent  6be6e4becaafd1bf24f01a2d0464df9cea67588d
util: document bundle compression

An upcoming patch will add support for documenting bundle
specifications in more detail. As part of this, we'd like to
enumerate available bundle compression formats. In order to do
this, we need to provide the help mechanism a dict of names
and objects with docstrings.

This patch adds docstrings to compengine.bundletype and adds
a function for retrieving a dict of them. The code is not yet
used.

Patch

diff --git a/mercurial/util.py b/mercurial/util.py
--- a/mercurial/util.py
+++ b/mercurial/util.py
@@ -3270,6 +3270,9 @@  class compressionengine(object):
 
         If bundle compression is supported, the class must also implement
         ``compressstream`` and `decompressorreader``.
+
+        The docstring of this method is used in the help system to tell users
+        about this engine.
         """
         return None
 
@@ -3354,6 +3357,12 @@  class _zlibengine(compressionengine):
         return 'zlib'
 
     def bundletype(self):
+        """zlib compression using the DEFLATE algorithm.
+
+        All Mercurial clients should support this format. The compression
+        algorithm strikes a reasonable balance between compression ratio
+        and size.
+        """
         return 'gzip', 'GZ'
 
     def wireprotosupport(self):
@@ -3435,6 +3444,17 @@  class _bz2engine(compressionengine):
         return 'bz2'
 
     def bundletype(self):
+        """An algorithm that produces smaller bundles than ``gzip``.
+
+        All Mercurial clients should support this format.
+
+        This engine will likely produce smaller bundles than ``gzip`` but
+        will be significantly slower, both during compression and
+        decompression.
+
+        If available, the ``zstd`` engine can yield similar or better
+        compression at much higher speeds.
+        """
         return 'bzip2', 'BZ'
 
     # We declare a protocol name but don't advertise by default because
@@ -3488,6 +3508,10 @@  class _noopengine(compressionengine):
         return 'none'
 
     def bundletype(self):
+        """No compression is performed.
+
+        Use this compression engine to explicitly disable compression.
+        """
         return 'none', 'UN'
 
     # Clients always support uncompressed payloads. Servers don't because
@@ -3534,6 +3558,17 @@  class _zstdengine(compressionengine):
         return bool(self._module)
 
     def bundletype(self):
+        """A modern compression algorithm that is fast and highly flexible.
+
+        Only supported by Mercurial 4.1 and newer clients.
+
+        With the default settings, zstd compression is both faster and yields
+        better compression than ``gzip``. It also frequently yields better
+        compression than ``bzip2`` while operating at much higher speeds.
+
+        If this engine is available and backwards compatibility is not a
+        concern, it is likely the best available engine.
+        """
         return 'zstd', 'ZS'
 
     def wireprotosupport(self):
@@ -3632,5 +3667,35 @@  class _zstdengine(compressionengine):
 
 compengines.register(_zstdengine())
 
+def bundlecompressiontopics():
+    """Obtains a list of available bundle compressions for use in help."""
+    # help.makeitemsdocs() expects a dict of names to items with a .__doc__.
+    items = {}
+
+    # We need to format the docstring. So use a dummy object/type to hold it
+    # rather than mutating the original.
+    class docobject(object):
+        pass
+
+    for name in compengines:
+        engine = compengines[name]
+
+        if not engine.available():
+            continue
+
+        bt = engine.bundletype()
+        if not bt or not bt[0]:
+            continue
+
+        doc = pycompat.sysstr('``%s``\n    %s' % (
+            bt[0], engine.bundletype.__doc__))
+
+        value = docobject()
+        value.__doc__ = doc
+
+        items[bt[0]] = value
+
+    return items
+
 # convenient shortcut
 dst = debugstacktrace