Another round of docstring improvments (#1306)

Also some linting

Author: rocky

CHANGES.rst

@@ -6,6 +6,7 @@ New Builtins
 ++++++++++++
 
 * ``Between``
+* ``Breakpoint`` - forces a Python ``breakpoint()``
 * ``CheckAbort``
 * ``FileNameDrop``
 * ``FormatValues``
@@ -57,7 +58,7 @@ Internals
 tables produced from the Mathics Scanner project.
 * Patterns in ``eval_`` and ``format_`` methods of builtin classes
   parses patterns in docstrings of the form
-  ``Symbol: Expr`` as `Pattern[Symbol, Expr]`.
+  ``Symbol: Expr`` as ``Pattern[Symbol, Expr]``.
   To specify associated format in ``format_`` methods the
   docstring, the list of format must be wrapped in parenthesis, like
   ``(InputForm,): Definitions[...]`` instead of just ``InputForm: Definitions[...]``.
@@ -86,13 +87,18 @@ Bugs
 Mathics3 Packages
 +++++++++++++++++
 
-* ``BoolEval``
-* ``CleanSlate``
+* Added ``BoolEval``
+* Added ``CleanSlate``
 * ``Combinatorica`` moved to a separate repository and v.9 renamed to 0.9.1.
     More code v0.9.1 works. v2.0 renamed v2.0.1 and some code now works.
 * ``Rubi`` version 4.17 (work in progress; algebraic integrations work)
 
 
+Mathics3 Modules
+++++++++++++++++
+
+* Added preliminary Mathics3 debugger ("pymathics.trepan")
+
 Python Package Updates
 +++++++++++++++++++++++
 
@@ -809,13 +815,13 @@ New variables and builtins
 Enhancements
 ++++++++++++
 
-#. a function `evaluate_predicate` allows for a basic predicate evaluation using `$Assumptions`.
+#. a function ``evaluate_predicate`` allows for a basic predicate evaluation using ``$Assumptions``.
 #. ``Attributes`` accepts a string parameter.
 #. ``Cases`` accepts Heads option. Issue #1302.
 #. ``ColorNegate`` for colors is supported.
 #. ``D`` and ``Derivative`` improvements.
 #. ``Expand`` and ``ExpandAll`` now support a second parameter ``patt`` Issue #1301.
-#. ``Expand`` and ``ExpandAll`` works with hyperbolic functions (`Sinh`, `Cosh`, `Tanh`, `Coth`).
+#. ``Expand`` and ``ExpandAll`` works with hyperbolic functions (``Sinh``, ``Cosh``, ``Tanh``, ``Coth``).
 #. ``FileNames`` returns a sorted list. Issue #1250.
 #. ``FindRoot`` now accepts several optional parameters like ``Method`` and ``MaxIterations``. See Issue #1235.
 #. ``FixedPoint`` now supports the ``SameTest`` option.
@@ -900,10 +906,10 @@ Bug fixes
 ``TeXForm[]`` for integrals are now properly formatted.
 
 
-Pymathics Modules
-+++++++++++++++++
+Mathics3 Modules
+++++++++++++++++
 
-#. Pymathics modules now can run initialization code when are loaded.
+#. Mathics3 modules now can run initialization code when are loaded.
 #. The ``builtins`` list is not hard-linked to the library anymore. This simplifies the loading and reloading of pymathics modules.
 #. Decoupling of BoxConstructors from the library. Now are defined at the level of the definition objects. This is useful for customizing the Graphics output if it is available.
 

mathics/builtin/file_operations/file_properties.py

@@ -67,7 +67,7 @@ class FileDate(Builtin):
             "Change" -> FileDate[filepath, "Change"],
             "Modification" -> FileDate[filepath, "Modification"]}""",
     }
-    summary_text = "date and time of the last change in a file"
+    summary_text = "get date and time of the last change in a file"
 
     def eval(self, path, timetype, evaluation):
         "FileDate[path_, timetype_]"
@@ -107,7 +107,10 @@ def eval(self, path, timetype, evaluation):
         epochtime_expr = Expression(
             SymbolAbsoluteTime, String(time.strftime("%Y-%m-%d %H:%M", time.gmtime(0)))
         )
-        epochtime = eval_N(epochtime_expr, evaluation).to_python()
+        epochtime_N = eval_N(epochtime_expr, evaluation)
+        if epochtime_N is None:
+            return None
+        epochtime = epochtime_N.to_python()
         result += epochtime
 
         return to_expression("DateList", Real(result))
@@ -201,7 +204,7 @@ class FileType(Builtin):
             "File specification `1` is not a string of " "one or more characters."
         ),
     }
-    summary_text = "type of a file"
+    summary_text = "get the file extension or file type of a file"
 
     def eval(self, filename, evaluation):
         "FileType[filename_]"
@@ -210,7 +213,7 @@ def eval(self, filename, evaluation):
             return
         path = filename.to_python()[1:-1]
 
-        path, is_temporary_file = path_search(path)
+        path, _ = path_search(path)
 
         if path is None:
             return SymbolNone
@@ -288,7 +291,7 @@ def eval(self, filename, datelist, attribute, evaluation):
         ):
             evaluation.message("SetFileDate", "fstr", filename)
             return
-        py_filename, is_temporary_file = path_search(py_filename[1:-1])
+        py_filename, _ = path_search(py_filename[1:-1])
 
         if py_filename is None:
             evaluation.message("SetFileDate", "nffil", expr)
@@ -317,9 +320,11 @@ def eval(self, filename, datelist, attribute, evaluation):
         )
 
         stattime = to_expression("AbsoluteTime", from_python(py_datelist))
-        stattime = eval_N(stattime, evaluation).to_python()
+        stattime_N = eval_N(stattime, evaluation)
+        if stattime_N is None:
+            return
 
-        stattime -= epochtime
+        stattime = stattime_N.to_python() - epochtime
 
         try:
             os.stat(py_filename)

mathics/builtin/forms/other.py

@@ -37,7 +37,7 @@ class SequenceForm(FormBaseClass):
         "CharacterEncoding": '"Unicode"',
     }
 
-    summary_text = "format make an string from a template and a list of parameters"
+    summary_text = "format a string from a template and a list of parameters"
 
     def eval_makeboxes(self, args, form, evaluation, options: dict):
         """MakeBoxes[SequenceForm[args___, OptionsPattern[SequenceForm]],
@@ -73,7 +73,7 @@ class StringForm(FormBaseClass):
 
     in_outputforms = False
     in_printforms = False
-    summary_text = "make an string from a template and a list of parameters"
+    summary_text = "format a string from a template and a list of parameters"
 
     def eval_makeboxes(self, s, args, form, evaluation):
         """MakeBoxes[StringForm[s_String, args___],

mathics/builtin/intfns/combinatorial.py

@@ -230,8 +230,13 @@ class EulerE(SympyFunction):
       <dd>Euler polynomial $E$_$n$($x$).
     </dl>
 
-    >> Table[EulerE[k], {k, 0, 10}]
-     = {1, 0, -1, 0, 5, 0, -61, 0, 1385, 0, -50521}
+    Odd-index Euler numbers are zero:
+    >> Table[EulerE[k], {k, 1, 9, 2}]
+     = {0, 0, 0, 0, 0}
+
+    Even-index Euler numbers alternate in sign:
+    >> Table[EulerE[k], {k, 0, 8, 2}]
+     = {1, -1, 5, -61, 1385}
 
     >> EulerE[5, z]
      = -1 / 2 + 5 z ^ 2 / 2 - 5 z ^ 4 / 2 + z ^ 5