Trac #33095: again some details in Dyck words

* shorten the code of {{{area}}}
* fix some {{{SEEALSO}}} cross-links inside the doc
* display some examples where there were TESTS only
* enhance some typing annotations
* do not use {{{list}}} as a variable
* more direct call to {{{multinomial}}}

URL: https://trac.sagemath.org/33095
Reported by: chapoton
Ticket author(s): Frédéric Chapoton
Reviewer(s): Samuel Lelièvre

src/sage/combinat/dyck_word.py

@@ -552,9 +552,9 @@ def _repr_lattice(self, type=None, labelling=None, underpath=True) -> str:
                     row += "__"*(alst[-i-2]-alst[-i-1])+"| " + "x "*(n-c-2-i) + " ."*i + labels[-1] + "\n"
                 labels.pop()
             if underpath:
-                row += "|" + labels[-1] + " ."*(n-1) + "\n"
+                row += "|" + labels[-1] + " ." * (n - 1) + "\n"
             else:
-                row += "| "+" ."*(n-1) + labels[-1] + "\n"
+                row += "| " + " ." * (n - 1) + labels[-1] + "\n"
             return row
         else:
             raise ValueError("The given type (=%s) is not valid." % type)
@@ -629,7 +629,7 @@ def to_path_string(self, unicode=False) -> str:
         """
         if unicode:
             import unicodedata
-            space = u' '
+            space = ' '
             up = unicodedata.lookup('BOX DRAWINGS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT')
             down = unicodedata.lookup('BOX DRAWINGS LIGHT DIAGONAL UPPER LEFT TO LOWER RIGHT')
         else:
@@ -1129,7 +1129,7 @@ def associated_parenthesis(self, pos) -> int | None:
                 height -= 1
         return pos
 
-    def ascent_prime_decomposition(self) -> list:
+    def ascent_prime_decomposition(self) -> list[DyckWord]:
         r"""
         Decompose this Dyck word into a sequence of ascents and prime
         Dyck paths.
@@ -1183,7 +1183,7 @@ def ascent_prime_decomposition(self) -> list:
         result.append(DyckWord([open_symbol] * up))  # type:ignore
         return result
 
-    def catalan_factorization(self) -> list:
+    def catalan_factorization(self) -> list[DyckWord]:
         r"""
         Decompose this Dyck word into a sequence of complete Dyck
         words.
@@ -1401,7 +1401,7 @@ def number_of_double_rises(self) -> int:
         """
         return len(self.positions_of_double_rises())
 
-    def returns_to_zero(self) -> list:
+    def returns_to_zero(self) -> list[int]:
         r"""
         Return a list of positions where ``self`` has height `0`,
         excluding the position `0`.
@@ -1428,7 +1428,7 @@ def returns_to_zero(self) -> list:
                 points.append(i + 1)
         return points
 
-    def touch_points(self) -> list:
+    def touch_points(self) -> list[int]:
         r"""
         Return the abscissae (or, equivalently, ordinates) of the
         points where the Dyck path corresponding to ``self`` (comprising
@@ -1577,7 +1577,7 @@ def to_standard_tableau(self):
         from sage.combinat.tableau import StandardTableau
         return StandardTableau([x for x in [open_positions, close_positions] if x])
 
-    def to_tamari_sorting_tuple(self) -> list:
+    def to_tamari_sorting_tuple(self) -> list[int]:
         """
         Convert a Dyck word to a Tamari sorting tuple.
 
@@ -1600,7 +1600,7 @@ def to_tamari_sorting_tuple(self) -> list:
             sage: DyckWord([1, 1, 0, 1, 0, 0]).to_tamari_sorting_tuple()
             [2, 0, 0]
 
-        .. SEEALSO:: :meth:`to_Catalan_code`
+        .. SEEALSO:: :meth:`~DyckWord_complete.to_Catalan_code`
         """
         position = 0
         resu = [-i - 1 for i in range(len(self) // 2)]
@@ -1923,7 +1923,7 @@ def number_of_parking_functions(self) -> int:
             6
         """
         from sage.arith.all import multinomial
-        return multinomial(list(self.rise_composition()))
+        return multinomial(self.rise_composition())
 
     def list_parking_functions(self):
         r"""
@@ -2295,7 +2295,7 @@ def to_noncrossing_partition(self, bijection=None):
         from [Stu2008]_, see also the method :meth:`to_noncrossing_permutation`.
 
         Thanks to Mathieu Dutour for describing the bijection.  See also
-        :func:`~DyckWords.from_noncrossing_partition`.
+        :func:`~CompleteDyckWords.from_noncrossing_partition`.
 
         EXAMPLES::
 
@@ -2718,14 +2718,14 @@ def reverse(self) -> DyckWord:
             sage: DyckWord([]).reverse()
             []
         """
-        list = []
+        alist = []
         for i in range(len(self)):
             if self[i] == open_symbol:
-                list.append(close_symbol)
+                alist.append(close_symbol)
             else:
-                list.append(open_symbol)
-        list.reverse()
-        return DyckWord(list)  # type:ignore
+                alist.append(open_symbol)
+        alist.reverse()
+        return DyckWord(alist)  # type:ignore
 
     def first_return_decomposition(self) -> tuple:
         r"""
@@ -2923,16 +2923,7 @@ def area(self) -> int:
             sage: DyckWord([1,0,1,0,1,0,1,0]).area()
             0
         """
-        above = 0
-        diagonal = 0
-        a = 0
-        for move in self:
-            if move == open_symbol:
-                above += 1
-            elif move == close_symbol:
-                diagonal += 1
-                a += above - diagonal
-        return a
+        return sum(self._area_sequence_iter())
 
     def bounce_path(self) -> DyckWord:
         r"""
@@ -3811,7 +3802,7 @@ def from_area_sequence(self, code) -> DyckWord:
         See :meth:`~DyckWord.to_area_sequence` for a definition of the area
         sequence of a Dyck word.
 
-        .. SEEALSO:: :meth:`~DyckWord.area`, :meth:`~DyckWord.to_area_sequence`.
+        .. SEEALSO:: :meth:`~DyckWord_complete.area`, :meth:`~DyckWord.to_area_sequence`.
 
         INPUT:
 
@@ -3845,15 +3836,13 @@ def from_noncrossing_partition(self, ncp) -> DyckWord:
         r"""
         Convert a noncrossing partition ``ncp`` to a Dyck word.
 
-        TESTS::
+        EXAMPLES::
 
             sage: DyckWord(noncrossing_partition=[[1,2]]) # indirect doctest
             [1, 1, 0, 0]
             sage: DyckWord(noncrossing_partition=[[1],[2]])
             [1, 0, 1, 0]
 
-        ::
-
             sage: dws = DyckWords(5).list()
             sage: ncps = [x.to_noncrossing_partition() for x in dws]
             sage: dws2 = [DyckWord(noncrossing_partition=x) for x in ncps]