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

login
register
mail settings
Submitter Pierre-Yves David
Date April 9, 2017, 5:41 p.m.
Message ID <0ae7bb16d6ceb88bbb76.1491759714@nodosa.octopoid.net>
Download mbox | patch
Permalink /patch/20039/
State Changes Requested
Headers show

Comments

Pierre-Yves David - April 9, 2017, 5:41 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 0ae7bb16d6ceb88bbb76859dbdf30c9f92490369
# Parent  94eac6f88d489757b183229681baf0d3f44284e7
# 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 0ae7bb16d6ce
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 handler. We update the docstring to clarify this.
Ryan McElroy - April 10, 2017, 9:17 a.m.
On 4/9/17 6:41 PM, Pierre-Yves David wrote:
> # 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 0ae7bb16d6ceb88bbb76859dbdf30c9f92490369
> # Parent  94eac6f88d489757b183229681baf0d3f44284e7
> # EXP-Topic bundle2.doc
> 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 handler. We update the docstring to clarify this.

s/handler/handlers

>
> diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
> --- a/mercurial/bundle2.py
> +++ b/mercurial/bundle2.py
> @@ -621,12 +621,18 @@ 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 of bundle2 protocol only.
s/of/by the

> +        Do not use it to implement higher level"""

higher-level *what*?

I'd say "Do not use it to implement higher-level functions"

I'd also explain why it might be a bad idea, otherwise someone will 
still try to use it.

>           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 of bundle2 protocol.
s/of/by the

> +        Do not use it to implement higher level"""

Again, it would be worth noting why using it in a higher-level function 
could lead to bad results.

>           return changegroup.readexactly(self._fp, size)
>   
>       def seek(self, offset, whence=0):
>

Patch

diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
--- a/mercurial/bundle2.py
+++ b/mercurial/bundle2.py
@@ -621,12 +621,18 @@  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 of bundle2 protocol only.
+        Do not use it to implement higher level"""
         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 of bundle2 protocol.
+        Do not use it to implement higher level"""
         return changegroup.readexactly(self._fp, size)
 
     def seek(self, offset, whence=0):