Trac #29265: little fixes in combinat/combinat

URL: https://trac.sagemath.org/29265
Reported by: chapoton
Ticket author(s): Frédéric Chapoton
Reviewer(s): Travis Scrimshaw

src/sage/combinat/combinat.py

@@ -171,8 +171,10 @@
 
 def bell_number(n, algorithm='flint', **options):
     r"""
-    Return the `n`-th Bell number (the number of ways to partition a set
-    of `n` elements into pairwise disjoint nonempty subsets).
+    Return the `n`-th Bell number.
+
+    This is the number of ways to partition a set
+    of `n` elements into pairwise disjoint nonempty subsets.
 
     INPUT:
 
@@ -587,8 +589,12 @@ def eulerian_number(n, k, algorithm='recursive'):
 
         sage: [eulerian_number(6,i,"formula") for i in range(6)]
         [1, 57, 302, 302, 57, 1]
+        sage: [eulerian_number(3,i) for i in range(-1, 4)]
+        [0, 1, 4, 1, 0]
     """
     n = ZZ(n)
+    if k < 0 or k > n - 1:
+        return ZZ.zero()
     if k == 0 or k == n - 1:
         return ZZ.one()
     if algorithm == "recursive":
@@ -707,6 +713,7 @@ def fibonacci(n, algorithm="pari"):
     else:
         raise ValueError("no algorithm {}".format(algorithm))
 
+
 def lucas_number1(n, P, Q):
     r"""
     Return the `n`-th Lucas number "of the first kind" (this is not
@@ -773,6 +780,7 @@ def lucas_number1(n, P, Q):
     from sage.libs.gap.libgap import libgap
     return libgap.Lucas(P, Q, n)[0].sage()
 
+
 def lucas_number2(n, P, Q):
     r"""
     Return the `n`-th Lucas number "of the second kind" (this is not
@@ -856,9 +864,11 @@ def stirling_number1(n, k):
 def stirling_number2(n, k, algorithm=None):
     r"""
     Return the `n`-th Stirling number `S_2(n,k)` of the second
-    kind (the number of ways to partition a set of `n` elements into `k`
-    pairwise disjoint nonempty subsets). (The `n`-th Bell number is the
-    sum of the `S_2(n,k)`'s, `k=0,...,n`.)
+    kind.
+
+    This is the number of ways to partition a set of `n` elements into `k`
+    pairwise disjoint nonempty subsets. The `n`-th Bell number is the
+    sum of the `S_2(n,k)`'s, `k=0,...,n`.
 
     INPUT:
 
@@ -970,7 +980,8 @@ def stirling_number2(n, k, algorithm=None):
          ...
          ValueError: unknown algorithm: CloudReading
     """
-    n = ZZ(n);  k = ZZ(k)
+    n = ZZ(n)
+    k = ZZ(k)
     if algorithm is None:
         return _stirling_number2(n, k)
     elif algorithm == 'gap':
@@ -1075,7 +1086,7 @@ def _repr_(self):
 
     def __eq__(self, other):
         """
-        Test equality of self and other.
+        Test equality of ``self`` and ``other``.
 
         EXAMPLES::
 
@@ -1230,7 +1241,7 @@ def __add__(self, other):
 
     def __hash__(self):
         """
-        Computes the hash of self by computing the hash of the string
+        Compute the hash of ``self`` by computing the hash of the string
         representation of self._list. The hash is cached and stored in
         self._hash.
 
@@ -1480,7 +1491,7 @@ def __init__(self, category = None):
 
     def is_finite(self):
         """
-        Returns whether self is finite or not.
+        Return whether ``self`` is finite or not.
 
         EXAMPLES::
 
@@ -1493,7 +1504,7 @@ def is_finite(self):
 
     def __getitem__(self, i):
         """
-        Returns the combinatorial object of rank i.
+        Return the combinatorial object of rank i.
 
         EXAMPLES::
 
@@ -1514,7 +1525,7 @@ def __getitem__(self, i):
 
     def __str__(self):
         """
-        Returns a string representation of self.
+        Return a string representation of self.
 
         EXAMPLES::
 
@@ -1537,7 +1548,7 @@ def _repr_(self):
 
     def __contains__(self, x):
         """
-        Tests whether or not the combinatorial class contains the object x.
+        Test whether or not the combinatorial class contains the object x.
         This raises a NotImplementedError as a default since _all_
         subclasses of CombinatorialClass should override this.
 
@@ -1576,7 +1587,7 @@ def __eq__(self, other):
 
     def __ne__(self, other):
         """
-        Test unequality of self and other.
+        Test unequality of ``self`` and ``other``.
 
         EXAMPLES::
 
@@ -1629,7 +1640,7 @@ def __cardinality_from_iterator(self):
 
     def __call__(self, x):
         """
-        Returns x as an element of the combinatorial class's object class.
+        Return x as an element of the combinatorial class's object class.
 
         EXAMPLES::
 
@@ -1978,8 +1989,8 @@ def __previous_from_iterator(self, obj):
 
     def filter(self, f, name=None):
         """
-        Returns the combinatorial subclass of f which consists of the
-        elements x of self such that f(x) is True.
+        Return the combinatorial subclass of f which consists of the
+        elements x of ``self`` such that f(x) is ``True``.
 
         EXAMPLES::
 
@@ -1992,8 +2003,8 @@ def filter(self, f, name=None):
 
     def union(self, right_cc, name=None):
         """
-        Returns the combinatorial class representing the union of self and
-        right_cc.
+        Return the combinatorial class representing the union of ``self`` and
+        ``right_cc``.
 
         EXAMPLES::
 
@@ -2008,7 +2019,7 @@ def union(self, right_cc, name=None):
 
     def map(self, f, name=None):
         r"""
-        Returns the image `\{f(x) | x \in \text{self}\}` of this combinatorial
+        Return the image `\{f(x) | x \in \text{self}\}` of this combinatorial
         class by `f`, as a combinatorial class.
 
         `f` is supposed to be injective.
@@ -2040,6 +2051,7 @@ class by `f`, as a combinatorial class.
         """
         return MapCombinatorialClass(self, f, name)
 
+
 class FilteredCombinatorialClass(CombinatorialClass):
     def __init__(self, combinatorial_class, f, name=None):
         """
@@ -2118,6 +2130,7 @@ def __iter__(self):
             if self.f(x):
                 yield x
 
+
 class UnionCombinatorialClass(CombinatorialClass):
     def __init__(self, left_cc, right_cc, name=None):
         """
@@ -2354,7 +2367,7 @@ def __repr__(self):
 
     def cardinality(self):
         """
-        Returns the cardinality of this combinatorial class
+        Return the cardinality of this combinatorial class
 
         EXAMPLES::
 
@@ -2367,7 +2380,7 @@ def cardinality(self):
 
     def __iter__(self):
         """
-        Returns an iterator over the elements of this combinatorial class
+        Return an iterator over the elements of this combinatorial class
 
         EXAMPLES::
 
@@ -2380,7 +2393,7 @@ def __iter__(self):
 
     def an_element(self):
         """
-        Returns an element of this combinatorial class
+        Return an element of this combinatorial class
 
         EXAMPLES::
 
@@ -2404,7 +2417,7 @@ class InfiniteAbstractCombinatorialClass(CombinatorialClass):
     """
     def cardinality(self):
         """
-        Counts the elements of the combinatorial class.
+        Count the elements of the combinatorial class.
 
         EXAMPLES::
 
@@ -2416,7 +2429,7 @@ def cardinality(self):
 
     def list(self):
         """
-        Returns an error since self is an infinite combinatorial class.
+        Return an error since ``self`` is an infinite combinatorial class.
 
         EXAMPLES::
 
@@ -2430,7 +2443,7 @@ def list(self):
 
     def __iter__(self):
         """
-        Returns an iterator for the infinite combinatorial class self if
+        Return an iterator for the infinite combinatorial class ``self`` if
         possible or raise a NotImplementedError.
 
         EXAMPLES::