Naming and docs cleanup

Author: MadsAdrian

tikzplotlib/_hatches.py

@@ -1,24 +1,26 @@
-import warnings
+r"""
+    Map matplotlib hatches to tikz patterns
+
+    For matplotlib hatches, see:
+    https://matplotlib.org/3.1.1/gallery/shapes_and_collections/hatch_demo.html
 
-# From https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.patches.Patch.html:
-# > Letters can be combined, in which case all the specified hatchings are done.
-# > If same letter repeats, it increases the density of hatching of that pattern.
-# To achieve something like this, custom patterns must be created
-# https://tex.stackexchange.com/questions/29359/pgfplots-how-to-fill-the-area-under-a-curve-with-oblique-lines-hatching-as-a/29367#29367
+    For patterns in tikzpgf:
+    Ch 26 Pattern Lbrary in the manual
+    Requires \usetikzlibrary{patterns}
+"""
 
-# These methods exist, and might be relevant:
+# These methods exist, and might be relevant (in the future?):
 # matplotlib.backend_bases.GraphicsContextBase.set/get_hatch_color
 # matplotlib.backend_bases.GraphicsContextBase.set/get_hatch_linewidth
 # hatch_density is mentioned in mpl API Changes in 2.0.1
 
-# for matplotlib hatches, see:
-# https://matplotlib.org/3.1.1/gallery/shapes_and_collections/hatch_demo.html
 
-# hatches in tikzpgf: Ch 26 Pattern Lbrary with \usetikzlibrary{patterns}
+import warnings
+
 
 BAD_MP_HATCH = ["o", "O"]  # Bad hatch/pattern correspondance
-UNUSED_PGF_HATCH = ["dots"]
-_MP_HATCH2PGF_HATCH = {
+UNUSED_PGF_PATTERN = ["dots"]
+_MP_HATCH2PGF_PATTERN = {
     "-": "horizontal lines",
     "|": "vertical lines",
     "/": "north east lines",
@@ -32,89 +34,83 @@
 }
 
 
-def add_custom_pattern(mpl_hatch, pattern_name, pattern_definition):
-    pass
+def add_custom_pattern(mpl_hatch, pattern_name, pattern_definition=None):
+    """
+        The patterns of tikzpgf are quite simple, and cannot be customized but for the
+        color. A solution is to expose a function like this one to allow the user to
+        populate _MP_HATCH2PGF_PATTERN with custom (hatch, pattern) pairs. mpl does no
+        validation of the hatch string, it just ignores it if it does not recognize it,
+        so it is possible to have <any> string be a mpl_hatch.
+
+        If the pattern definition is passed, it could be added at the start of the code
+        in a similar fashion to
+        > data["custom colors"] = {}
+        in get_tikz_code(). tikzplotlib pattern definitions would mend the bad
+        correspondence between the mpl hatches and tikz patterns, with custom patterns
+        for the mpl hatches 'o' and 'O'
+
+        Want some opinions on this before I implement it..
+
+        From https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.patches.Patch.html:
+        > Letters can be combined, in which case all the specified hatchings are done.
+        > If same letter repeats, it increases the density of hatching of that pattern.
+        To achieve something like this, custom patterns must be created
+        https://tex.stackexchange.com/questions/29359/pgfplots-how-to-fill-the-area-
+        under-a-curve-with-oblique-lines-hatching-as-a/29367#29367
+    """
 
 
-def __validate_mpl_hatch(mpl_hatch):
-    if len(mpl_hatch) > 1:
+def __validate_hatch(hatch):
+    """ Warn about the shortcomings of patterns """
+    if len(hatch) > 1:
         warnings.warn(
-            f"tikzplotlib: Hatch '{mpl_hatch}' cannot be rendered. "
+            f"tikzplotlib: Hatch '{hatch}' cannot be rendered. "
             + "Only single character hatches are supported, e.g., "
             + r"{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}. "
-            + f"Hatch '{mpl_hatch[0]}' will be used."
+            + f"Hatch '{hatch[0]}' will be used."
         )
-        mpl_hatch = mpl_hatch[0]
+        hatch = hatch[0]
 
-    if mpl_hatch in BAD_MP_HATCH:
+    if hatch in BAD_MP_HATCH:
         warnings.warn(
             f"tikzplotlib: The hatches {BAD_MP_HATCH} do not have good PGF"
             + " counterparts."
         )
-    return mpl_hatch
+    return hatch
 
 
-def _mpl_hatch2pgfp_hatch(data, mpl_hatch, color_name, color_rgba):
-    """
-        Translates a hatch style of matplotlib to the corresponding style
-        in PGFPlots.
+def _mpl_hatch2pgfp_pattern(data, hatch, color_name, color_rgba):
+    r"""
+        Translates a hatch from matplotlib to the corresponding patten in PGFPlots.
+
+        Input:
+            hatch - str, like {'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
+            color_name - str, xcolor or custom color name
+            color_rgba - np.array, the rgba value of the color
+        Output:
+            draw_options - list, empty or with a post action string
     """
     data["tikz libs"].add("patterns")
 
-    mpl_hatch = __validate_mpl_hatch(mpl_hatch)
+    hatch = __validate_hatch(hatch)
     try:
-        pgfplots_hatch = _MP_HATCH2PGF_HATCH.get(mpl_hatch)
+        pgfplots_pattern = _MP_HATCH2PGF_PATTERN.get(hatch)
     except KeyError:
-        warnings.warn("tikzplotlib: The hatch", mpl_hatch, "cannot be handled.")
+        warnings.warn("tikzplotlib: The hatch", hatch, "is ignored.")
         return data, []
-    else:
-        pattern_options = [f"pattern={pgfplots_hatch}"]
-        if color_name != "black":
-            # PGFPlots render patterns in 'pattern color' (default: black)
-            pattern_options += [f"pattern color={color_name}"]
-        if color_rgba[3] != 1:
-            ff = data["float format"]
-            # PGFPlots render patterns according to opacity fill.
-            pattern_options.append(("fill opacity=" + ff).format(color_rgba[3]))
-
-    # Add pattern as postaction to allow fill and pattern
+
+    pattern_options = [f"pattern={pgfplots_pattern}"]
+    if color_name != "black":
+        # PGFPlots render patterns in 'pattern color' (default: black)
+        pattern_options += [f"pattern color={color_name}"]
+    if color_rgba[3] != 1:
+        ff = data["float format"]
+        # PGFPlots render patterns according to opacity fill.
+        pattern_options.append(("fill opacity=" + ff).format(color_rgba[3]))
+
+    # Add pattern as postaction to allow color fill and pattern together
     # https://tex.stackexchange.com/questions/24964/
     # how-to-combine-fill-and-pattern-in-a-pgfplot-bar-plot
-    hatch_postaction = f"postaction={{{', '.join(pattern_options)}}}"
-
-    return data, [hatch_postaction]
-
-
-if __name__ == "__main__":
-    import warnings
-    import matplotlib.pyplot as plt
-    import matplotlib
-
-    fig, ax = plt.subplots()
-
-    ax.bar(range(1, 5), range(1, 5), color="red", edgecolor="black", hatch="O")
-
-    for c in ax.get_children():
-        try:
-            hatch = c.get_hatch()
-        except AttributeError as error:
-            pass
-        else:
-            if hatch is not None:
-                print(c, hatch)
-        try:
-            color = c.get_hatch_color()
-        except AttributeError as error:
-            pass
-        else:
-            if color is not None:
-                print(c, color)
-        try:
-            lw = c.get_hatch_linewidth()
-        except AttributeError as error:
-            pass
-        else:
-            if lw is not None:
-                print(c, lw)
-
-    plt.show()
+    postaction = f"postaction={{{', '.join(pattern_options)}}}"
+
+    return data, [postaction]