Patchwork [2,of,4,V2] bundle2: clarify the docstring of unpackermixin methods

login
register
mail settings
Submitter Pierre-Yves David
Date April 10, 2017, 3:33 p.m.
Message ID <f77b40e01801531ef1b5.1491838386@nodosa.octopoid.net>
Download mbox | patch
Permalink /patch/20068/
State Accepted
Headers show

Comments

Pierre-Yves David - April 10, 2017, 3:33 p.m.
# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@ens-lyon.org>
# Date 1491754374 -7200
#      Sun Apr 09 18:12:54 2017 +0200
# Node ID f77b40e01801531ef1b5824c49318d0ef081bf30
# Parent  75799788617866ec78984b08225e025eeca73790
# EXP-Topic bundle2.doc
# Available At https://www.mercurial-scm.org/repo/users/marmoute/mercurial/
#              hg pull https://www.mercurial-scm.org/repo/users/marmoute/mercurial/ -r f77b40e01801
bundle2: clarify the docstring of unpackermixin methods

The unpackermixin is a utility used to implement the bundle2 protocol. It should
not be used when writing part handlers. We update the docstring to clarify this.

Patch

diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
--- a/mercurial/bundle2.py
+++ b/mercurial/bundle2.py
@@ -621,12 +621,24 @@  class unpackermixin(object):
                           util.safehasattr(fp, 'tell'))
 
     def _unpack(self, format):
-        """unpack this struct format from the stream"""
+        """unpack this struct format from the stream
+
+        This method is meant for internal usage by the bundle2 protocol only.
+        They directly manipulate the low level stream including bundle2 level
+        instruction.
+
+        Do not use it to implement higher-level logic or methods."""
         data = self._readexact(struct.calcsize(format))
         return _unpack(format, data)
 
     def _readexact(self, size):
-        """read exactly <size> bytes from the stream"""
+        """read exactly <size> bytes from the stream
+
+        This method is meant for internal usage by the bundle2 protocol only.
+        They directly manipulate the low level stream including bundle2 level
+        instruction.
+
+        Do not use it to implement higher-level logic or methods."""
         return changegroup.readexactly(self._fp, size)
 
     def seek(self, offset, whence=0):