Merge pull request #678 from Mathics3/complete_docs_for_bytearray_changed_modules

doc for required modules

Author: rocky

mathics/builtin/binary/bytearray.py

@@ -4,27 +4,24 @@
 """
 
 from mathics.builtin.base import Builtin
-from mathics.core.atoms import (
-    ByteArrayAtom,
-    Integer,
-    String,
-)
+from mathics.core.atoms import ByteArrayAtom, Integer, String
 from mathics.core.convert.expression import to_mathics_list
 from mathics.core.expression import Expression
-from mathics.core.systemsymbols import (
-    SymbolByteArray,
-    SymbolFailed,
-)
+from mathics.core.systemsymbols import SymbolByteArray, SymbolFailed
 
 
 class ByteArray(Builtin):
     r"""
+    <url>:WMA link:
+    https://reference.wolfram.com/language/ref/ByteArray.html</url>
+
     <dl>
       <dt>'ByteArray[{$b_1$, $b_2$, ...}]'
-     <dd> Represents a sequence of Bytes $b_1$, $b_2$, ...
+      <dd> Represents a sequence of Bytes $b_1$, $b_2$, ...
 
       <dt>'ByteArray["string"]'
-     <dd> Constructs a byte array where bytes comes from decode a b64 encoded String
+      <dd> Constructs a byte array where bytes comes from decode a b64-encoded \
+           String
     </dl>
 
     >> A=ByteArray[{1, 25, 3}]
@@ -49,7 +46,7 @@ class ByteArray(Builtin):
     }
     summary_text = "array of bytes"
 
-    def apply_str(self, string, evaluation):
+    def eval_str(self, string, evaluation):
         "ByteArray[string_String]"
         try:
             atom = ByteArrayAtom(string.value)
@@ -58,15 +55,15 @@ def apply_str(self, string, evaluation):
             return SymbolFailed
         return Expression(SymbolByteArray, atom)
 
-    def apply_to_str(self, baa, evaluation):
+    def eval_to_str(self, baa, evaluation):
         "ToString[ByteArray[baa_ByteArrayAtom]]"
         return String('ByteArray["' + baa.__str__() + '"]')
 
-    def apply_normal(self, baa, evaluation):
+    def eval_normal(self, baa, evaluation):
         "System`Normal[ByteArray[baa_ByteArrayAtom]]"
         return to_mathics_list(*baa.value, elements_conversion_fn=Integer)
 
-    def apply_list(self, values, evaluation):
+    def eval_list(self, values, evaluation):
         "ByteArray[values_List]"
         if not values.has_form("List", None):
             return

mathics/builtin/colors/color_operations.py

@@ -8,21 +8,12 @@
 
 import itertools
 from math import floor
+
 from mathics.builtin.base import Builtin
-from mathics.builtin.colors.color_directives import (
-    _ColorObject,
-    ColorError,
-    RGBColor,
-)
+from mathics.builtin.colors.color_directives import ColorError, RGBColor, _ColorObject
 from mathics.builtin.colors.color_internals import convert_color
-from mathics.builtin.drawing.image import _ImageBuiltin, Image
-
-from mathics.core.atoms import (
-    Integer,
-    MachineReal,
-    Rational,
-    Real,
-)
+from mathics.builtin.drawing.image import Image, _ImageBuiltin
+from mathics.core.atoms import Integer, MachineReal, Rational, Real
 from mathics.core.convert.expression import to_expression, to_mathics_list
 from mathics.core.expression import Expression
 from mathics.core.list import ListExpression
@@ -32,8 +23,8 @@
 _image_requires = ("numpy", "PIL")
 
 try:
-    import PIL.ImageOps
     import numpy
+    import PIL.ImageOps
 
     _enabled = True
 except ImportError:
@@ -42,15 +33,19 @@
 
 class Blend(Builtin):
     """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/Blend.html</url>
+
     <dl>
-    <dt>'Blend[{$c1$, $c2$}]'
-        <dd>represents the color between $c1$ and $c2$.
-    <dt>'Blend[{$c1$, $c2$}, $x$]'
-        <dd>represents the color formed by blending $c1$ and $c2$ with
-        factors 1 - $x$ and $x$ respectively.
-    <dt>'Blend[{$c1$, $c2$, ..., $cn$}, $x$]'
-        <dd>blends between the colors $c1$ to $cn$ according to the
-        factor $x$.
+      <dt>'Blend[{$c1$, $c2$}]'
+      <dd>represents the color between $c1$ and $c2$.
+
+      <dt>'Blend[{$c1$, $c2$}, $x$]'
+      <dd>represents the color formed by blending $c1$ and $c2$ with
+          factors 1 - $x$ and $x$ respectively.
+
+      <dt>'Blend[{$c1$, $c2$, ..., $cn$}, $x$]'
+      <dd>blends between the colors $c1$ to $cn$ according to the
+          factor $x$.
     </dl>
 
     >> Blend[{Red, Blue}]
@@ -109,7 +104,7 @@ def do_blend(self, colors, values):
                 result = [r + p for r, p in zip(result, part)]
         return type(components=result)
 
-    def apply(self, colors, u, evaluation):
+    def eval(self, colors, u, evaluation):
         "Blend[{colors___}, u_]"
 
         colors_orig = colors
@@ -154,10 +149,13 @@ def apply(self, colors, u, evaluation):
 
 class ColorConvert(Builtin):
     """
+    <url>:WMA link:
+    https://reference.wolfram.com/language/ref/ColorConvert.html</url>
+
     <dl>
-    <dt>'ColorConvert[$c$, $colspace$]'
-        <dd>returns the representation of $c$ in the color space $colspace$. $c$
-        may be a color or an image.
+      <dt>'ColorConvert[$c$, $colspace$]'
+      <dd>returns the representation of $c$ in the color space $colspace$. $c$ \
+          may be a color or an image.
     </dl>
 
     Valid values for $colspace$ are:
@@ -178,15 +176,15 @@ class ColorConvert(Builtin):
     }
     summary_text = "convert between color models"
 
-    def apply(self, input, colorspace, evaluation):
+    def eval(self, input, colorspace, evaluation):
         "ColorConvert[input_, colorspace_String]"
 
         if isinstance(input, Image):
             return input.color_convert(colorspace.get_string_value())
         else:
             from mathics.builtin.colors.color_directives import (
-                expression_to_color,
                 color_to_expression,
+                expression_to_color,
             )
 
             py_color = expression_to_color(input)
@@ -208,6 +206,8 @@ def apply(self, input, colorspace, evaluation):
 
 class ColorNegate(_ImageBuiltin):
     """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/ColorNegate.html</url>
+
     <dl>
       <dt>'ColorNegate[$image$]'
       <dd>returns the negative of $image$ in which colors have been negated.
@@ -223,7 +223,7 @@ class ColorNegate(_ImageBuiltin):
 
     summary_text = "the negative color of a given color"
 
-    def apply_for_color(self, color, evaluation):
+    def eval_for_color(self, color, evaluation):
         "ColorNegate[color_RGBColor]"
         # Get components
         r, g, b = [element.to_python() for element in color.elements]
@@ -232,13 +232,15 @@ def apply_for_color(self, color, evaluation):
         # Reconstitute
         return Expression(SymbolRGBColor, Real(r), Real(g), Real(b))
 
-    def apply_for_image(self, image, evaluation):
+    def eval_for_image(self, image, evaluation):
         "ColorNegate[image_Image]"
         return image.filter(lambda im: PIL.ImageOps.invert(im))
 
 
 class Darker(Builtin):
     """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/Darker.html</url>
+
     <dl>
     <dt>'Darker[$c$, $f$]'
         <dd>is equivalent to 'Blend[{$c$, Black}, $f$]'.
@@ -262,23 +264,33 @@ class Darker(Builtin):
 
 class DominantColors(_ImageBuiltin):
     """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/DominantColors.html</url>
+
     <dl>
-    <dt>'DominantColors[$image$]'
+      <dt>'DominantColors[$image$]'
       <dd>gives a list of colors which are dominant in the given image.
-    <dt>'DominantColors[$image$, $n$]'
+
+      <dt>'DominantColors[$image$, $n$]'
       <dd>returns at most $n$ colors.
-    <dt>'DominantColors[$image$, $n$, $prop$]'
-      <dd>returns the given property $prop$, which may be "Color" (return RGB colors), "LABColor" (return
-      LAB colors), "Count" (return the number of pixels a dominant color covers), "Coverage" (return the
-      fraction of the image a dominant color covers), or "CoverageImage" (return a black and white image
-      indicating with white the parts that are covered by a dominant color).
+
+      <dt>'DominantColors[$image$, $n$, $prop$]'
+      <dd>returns the given property $prop$, which may be:
+        <ul>
+           <li>"Color": return RGB colors,
+           <li> "LABColor": return  LAB colors,
+           <li> "Count": return the number of pixels a dominant color covers,
+           <li> "Coverage": return the fraction of the image a dominant color \
+                 covers, or
+           <li> "CoverageImage": return a black and white image indicating with \
+                 white the parts that are covered by a dominant color.
+        </ul>
     </dl>
 
-    The option "ColorCoverage" specifies the minimum amount of coverage needed to include a dominant color
-    in the result.
+    The option "ColorCoverage" specifies the minimum amount of coverage needed to \
+    include a dominant color in the result.
 
-    The option "MinColorDistance" specifies the distance (in LAB color space) up to which colors are merged
-    and thus regarded as belonging to the same dominant color.
+    The option "MinColorDistance" specifies the distance (in LAB color space) up \
+    to which colors are merged and thus regarded as belonging to the same dominant color.
 
     >> img = Import["ExampleData/lena.tif"]
      = -Image-
@@ -316,7 +328,7 @@ class DominantColors(_ImageBuiltin):
     options = {"ColorCoverage": "Automatic", "MinColorDistance": "Automatic"}
     summary_text = "find a list of dominant colors"
 
-    def apply(self, image, n, prop, evaluation, options):
+    def eval(self, image, n, prop, evaluation, options):
         "DominantColors[image_Image, n_Integer, prop_String, OptionsPattern[%(name)s]]"
 
         py_prop = prop.get_string_value()
@@ -379,9 +391,9 @@ def apply(self, image, n, prop, evaluation, options):
         num_pixels = im.size[0] * im.size[1]
 
         from mathics.algorithm.clusters import (
-            agglomerate,
-            PrecomputedDistances,
             FixedDistanceCriterion,
+            PrecomputedDistances,
+            agglomerate,
         )
 
         norm = numpy.linalg.norm
@@ -416,7 +428,7 @@ def result():
                     elif py_prop == "Coverage":
                         yield Rational(int(count), num_pixels)
                     elif py_prop == "CoverageImage":
-                        mask = numpy.ndarray(shape=pixels.shape, dtype=numpy.bool)
+                        mask = numpy.ndarray(shape=pixels.shape, dtype=bool)
                         mask.fill(0)
                         for i in members:
                             mask = mask | (pixels == i)
@@ -433,6 +445,8 @@ def result():
 
 class Lighter(Builtin):
     """
+    <url>:WMA link:https://reference.wolfram.com/language/ref/Lighter.html</url>
+
     <dl>
       <dt>'Lighter[$c$, $f$]'
       <dd>is equivalent to 'Blend[{$c$, White}, $f$]'.