us "loopcode" in H3Poly and H3MultiPoly reprs

src/h3/_h3shape.py

@@ -63,28 +63,21 @@ def __init__(self, outer, *holes):
         )
 
     def __repr__(self):
-        # if self.holes:
-        #     s = '<H3Poly |outer|={}, |holes|={}>'.format(
-        #         len(self.outer),
-        #         tuple(map(len, self.holes)),
-        #     )
-        # else:
-        #     s = '<H3Poly |outer|={}>'.format(
-        #     len(self.outer),
-        # )
-
-        s = '<H3Poly{}>'.format(self.loopcode)
-
-        return s
+        return '<H3Poly: {}>'.format(self.loopcode)
 
     def __len__(self):
         """
-        Should this be the number of points in the outer loop, the number of holes (or +1 for the outer loop)?
+        Should this be the number of points in the outer loop,
+        the number of holes (or +1 for the outer loop)?
         """
         raise NotImplementedError('No clear definition of length for H3Poly().')
 
     @property
     def loopcode(self):
+        """ Short code for describing the length of the outer loop and each hole
+
+        Example: [382/(18, 6, 6)]
+        """
         outer = len(self.outer)
         holes = tuple(map(len, self.holes))
 
@@ -97,7 +90,6 @@ def loopcode(self):
 
         return '[' + out + ']'
 
-
     @property
     def __geo_interface__(self):
         ll2 = _polygon_to_LL2(self)
@@ -115,7 +107,10 @@ def __init__(self, *polys):
                 raise ValueError('H3MultiPoly requires each input to be an H3Poly object, instead got: ' + str(p)) # noqa
 
     def __repr__(self):
-        return 'H3MultiPoly' + str(self.polys)
+        out = [p.loopcode for p in self.polys]
+        out = ', '.join(out)
+        out = f'<H3MultiPoly: {out}>'
+        return out
 
     def __iter__(self):
         return iter(self.polys)
@@ -125,29 +120,30 @@ def __len__(self):
         """
 
         """
-        TODO: Pandas series or dataframe representation changes depending on if __len__ is defined.
+        TODO: Pandas series or dataframe representation changes depending
+        on if __len__ is defined.
 
         I'd prefer the one that states `H3MultiPoly`. It seems like Pandas is assuming
         an iterable is best-described by its elements when choosing the representation.
 
         when __len__ *IS NOT* defined:
 
-        0    H3MultiPoly(<H3Poly |outer|=368>, <H3Poly |out...
-        1    H3MultiPoly(<H3Poly |outer|=632, |holes|=(6, 6...
-        2    H3MultiPoly(<H3Poly |outer|=490, |holes|=(6, 6...
-        3    H3MultiPoly(<H3Poly |outer|=344, |holes|=(6,)>...
-        4    H3MultiPoly(<H3Poly |outer|=382, |holes|=(18, ...
+        0                      <H3MultiPoly: [368], [20], [6]>
+        1    <H3MultiPoly: [632/(6, 6, 6, 6, 6)], [290/(6,)...
+        2    <H3MultiPoly: [490/(6, 6, 10, 10, 14, 10, 6)],...
+        3    <H3MultiPoly: [344/(6,)], [22], [6], [10], [6]...
+        4    <H3MultiPoly: [382/(18, 6, 6)], [32], [6], [18...
 
         when __len__ *IS* defined:
-        0    (<H3Poly |outer|=368>, <H3Poly |outer|=20>, <H...
-        1    (<H3Poly |outer|=632, |holes|=(6, 6, 6, 6, 6)>...
-        2    (<H3Poly |outer|=490, |holes|=(6, 6, 10, 10, 1...
-        3    (<H3Poly |outer|=344, |holes|=(6,)>, <H3Poly |...
-        4    (<H3Poly |outer|=382, |holes|=(18, 6, 6)>, <H3...
+
+        0     (<H3Poly: [368]>, <H3Poly: [20]>, <H3Poly: [6]>)
+        1    (<H3Poly: [632/(6, 6, 6, 6, 6)]>, <H3Poly: [29...
+        2    (<H3Poly: [490/(6, 6, 10, 10, 14, 10, 6)]>, <H...
+        3    (<H3Poly: [344/(6,)]>, <H3Poly: [22]>, <H3Poly...
+        4    (<H3Poly: [382/(18, 6, 6)]>, <H3Poly: [32]>, <...
         """
         return len(self.polys)
 
-
     def __getitem__(self, index):
         return self.polys[index]
 

src/h3/api/_api_template.py

@@ -440,13 +440,15 @@ def h3shape_to_cells(self, h3shape, res):
 
         return self._out_unordered(mv)
 
-    def cells_to_h3shape(self, cells):
+    def cells_to_h3shape(self, cells, tight=False):
         """
         Return a H3MultiPoly describing the area covered by a set of H3 cells.
 
         Parameters
         ----------
         cells : iterable of H3 cells
+        tight : bool
+            If True, return H3Poly if possible. If False, always return H3MultiPoly
 
         Returns
         -------
@@ -456,19 +458,19 @@ def cells_to_h3shape(self, cells):
         --------
 
         >>> cells = ['8428309ffffffff', '842830dffffffff']
-        >>> h3.cells_to_h3shape(cells)
-        [<H3Poly |outer|=10, |holes|=()>]
-
+        >>> h3.cells_to_h3shape(cells, tight=True)
+        <H3Poly: [10]>
+        >>> h3.cells_to_h3shape(cells, tight=False)
+        <H3MultiPoly: [10]>
         """
         cells = self._in_collection(cells)
         mpoly = _cy.cells_to_multi_polygon(cells)
 
         polys = [H3Poly(*poly) for poly in mpoly]
         out = H3MultiPoly(*polys)
 
-        # todo: consider returning the H3Poly if possible?
-        # if len(out) == 1:
-        #     out = out[0]
+        if tight and len(out) == 1:
+            out = out[0]
 
         return out
 
@@ -484,7 +486,7 @@ def geo_to_cells(self, geo, res):
         h3shape = geo_to_h3shape(geo)
         return self.h3shape_to_cells(h3shape, res)
 
-    def cells_to_geo(self, cells):
+    def cells_to_geo(self, cells, tight=False):
         """
         Parameters
         ----------
@@ -495,7 +497,7 @@ def cells_to_geo(self, cells):
         dict
             in `__geo_interface__` format
         """
-        h3shape = self.cells_to_h3shape(cells)
+        h3shape = self.cells_to_h3shape(cells, tight=tight)
         return h3shape_to_geo(h3shape)
 
     def is_pentagon(self, h):

tests/polyfill/test_h3.py

@@ -90,7 +90,7 @@ def test_shape_repr():
     mpoly = h3.H3MultiPoly(poly)
 
     assert (
-        'H3MultiPoly(<H3Poly |outer|=3, |holes|=()>,)'
+        '<H3MultiPoly: [3]>'
         == str(mpoly)
         == repr(mpoly)
     )

tests/polyfill/test_polygon_class.py

@@ -16,12 +16,12 @@ def test_repr():
     mpoly2 = sorted(map(str, mpoly2))
 
     assert mpoly1 == [
-        '<H3Poly |outer|=30, |holes|=(18,)>',
-        '<H3Poly |outer|=6, |holes|=()>',
+        '<H3Poly: [30/(18,)]>',
+        '<H3Poly: [6]>',
     ]
 
     assert mpoly2 == [
-        '<H3Poly |outer|=30, |holes|=(18,)>',
-        '<H3Poly |outer|=6, |holes|=()>',
-        '<H3Poly |outer|=6, |holes|=()>',
+        '<H3Poly: [30/(18,)]>',
+        '<H3Poly: [6]>',
+        '<H3Poly: [6]>',
     ]