add more fixes for enumerate_totallyreal_*

Introduce a new keyword return_pari_objects that is set
to True by default so that current usage of these functions
is not affected.

Fix documentation and add doctests to the functions to show
the new behavior if return_pari_objects is set to False

src/sage/rings/number_field/totallyreal.pyx

@@ -183,7 +183,8 @@ cpdef double odlyzko_bound_totallyreal(int n):
 
 def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False,
                                       phc=False, keep_fields=False, t_2=False,
-                                      just_print=False):
+                                      just_print=False,
+                                      return_pari_objects=True):
     r"""
     This function enumerates primitive totally real fields of degree
     `n>1` with discriminant `d \leq B`; optionally one can specify the
@@ -202,24 +203,28 @@ def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False
 
     INPUT:
 
-    - ``n`` (integer): the degree
-    - ``B`` (integer): the discriminant bound
-    - ``a`` (list, default: []): the coefficient list to begin with
-    - ``verbose`` (integer or string, default: 0): if ``verbose == 1``
+    - ``n`` -- (integer) the degree
+    - ``B`` -- (integer) the discriminant bound
+    - ``a`` -- (list, default: []) the coefficient list to begin with
+    - ``verbose`` -- (integer or string, default: 0) if ``verbose == 1``
       (or ``2``), then print to the screen (really) verbosely; if verbose is
       a string, then print verbosely to the file specified by verbose.
-    - ``return_seqs`` (boolean, default False)If ``return_seqs``, then return
+    - ``return_seqs`` -- (boolean, default False) If ``True``, then return
       the polynomials as sequences (for easier exporting to a file).
     - ``phc`` -- boolean or integer (default: False)
-    - ``keep_fields`` (boolean or integer, default: False) If ``keep_fields`` is True,
-      then keep fields up to ``B*log(B)``; if ``keep_fields`` is an integer, then
-      keep fields up to that integer.
-    - ``t_2`` (boolean or integer, default: False) If ``t_2 = T``, then keep
-      only polynomials with t_2 norm >= T.
-    - ``just_print`` (boolean, default: False): if ``just_print`` is not False,
-      instead of creating a sorted list of totally real number fields, we simply
-      write each totally real field we find to the file whose filename is given by
-      ``just_print``. In this case, we don't return anything.
+    - ``keep_fields`` -- (boolean or integer, default: False) If
+      ``keep_fields`` is True, then keep fields up to ``B*log(B)``; if
+      ``keep_fields`` is an integer, then keep fields up to that integer.
+    - ``t_2`` -- (boolean or integer, default: False) If ``t_2 = T``, then
+      keep only polynomials with t_2 norm >= T.
+    - ``just_print`` -- (boolean, default: False): if ``just_print`` is not
+      False, instead of creating a sorted list of totally real number
+      fields, we simply write each totally real field we find to the file
+      whose filename is given by ``just_print``. In this case, we don't
+      return anything.
+    - ``return_pari_objects`` -- (boolean, default: True) if
+      ``return_seqs`` is ``False`` then it returns the elements as Sage
+      objects; otherwise it returns pari objects.
 
     OUTPUT:
 
@@ -247,6 +252,21 @@ def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False
         2720
         sage: len(enumerate_totallyreal_fields_prim(5,5**8)) # long time
         103
+
+    Each of the outputs must be elements of Sage if ``return_pari_objects``
+    is set to ``False``::
+
+        sage: enumerate_totallyreal_fields_prim(2, 10)
+        [[5, x^2 - x - 1], [8, x^2 - 2]]
+        sage: enumerate_totallyreal_fields_prim(2, 10)[0][1].parent()
+        Interface to the PARI C library
+        sage: enumerate_totallyreal_fields_prim(2, 10, return_pari_objects=False)[0][0].parent()
+        Integer Ring
+        sage: enumerate_totallyreal_fields_prim(2, 10, return_pari_objects=False)[0][1].parent()
+        Univariate Polynomial Ring in x over Rational Field
+        sage: enumerate_totallyreal_fields_prim(2, 10, return_seqs=True)[1][0][1][0].parent()
+        Rational Field
+
     """
 
     cdef pari_gen B_pari, d, d_poly, keepB, nf, t2val, ngt2, ng
@@ -476,6 +496,8 @@ def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False
     if return_seqs:
         return [[ZZ(counts[i]) for i in range(4)],
                 [[ZZ(s[0]), map(QQ, s[1].reverse().Vec())] for s in S]]
+    elif return_pari_objects:
+        return S
     else:
         Px = PolynomialRing(QQ, 'x')
         return [[ZZ(s[0]), Px(map(QQ, s[1].list()))]

src/sage/rings/number_field/totallyreal_rel.py

@@ -634,7 +634,9 @@ def incr(self, f_out, verbose=False, haltk=0):
 # Main routine
 #***********************************************************************************************
 
-def enumerate_totallyreal_fields_rel(F, m, B, a = [], verbose=0, return_seqs=False):
+def enumerate_totallyreal_fields_rel(F, m, B, a = [], verbose=0,
+                                     return_seqs=False,
+                                     return_pari_objects=True):
     r"""
     This function enumerates (primitive) totally real field extensions of
     degree `m>1` of the totally real field F with discriminant `d \leq B`;
@@ -662,7 +664,11 @@ def enumerate_totallyreal_fields_rel(F, m, B, a = [], verbose=0, return_seqs=Fal
     - ``B`` -- integer, the discriminant bound
     - ``a`` -- list (default: []), the coefficient list to begin with
     - ``verbose`` -- boolean or string (default: 0)
-    - ``return_seqs`` -- boolean (default: False)
+    - ``return_seqs`` -- (boolean, default False) If ``True``, then return
+      the polynomials as sequences (for easier exporting to a file).
+    - ``return_pari_objects`` -- (boolean, default: True) if
+      ``return_seqs`` is ``False`` then it returns the elements as Sage
+      objects; otherwise it returns pari objects.
 
     OUTPUT:
 
@@ -678,6 +684,22 @@ def enumerate_totallyreal_fields_rel(F, m, B, a = [], verbose=0, return_seqs=Fal
         sage: enumerate_totallyreal_fields_rel(F, 2, 2000)
         [[1600, x^4 - 6*x^2 + 4, xF^2 + xF - 1]]
 
+    TESTS:
+
+    Each of the outputs must be elements of Sage if ``return_pari_objects``
+    is set to ``False``::
+
+        sage: enumerate_totallyreal_fields_rel(F, 2, 2000)[0][1].parent()
+        Interface to the PARI C library
+        sage: enumerate_totallyreal_fields_rel(F, 2, 2000, return_pari_objects=False)[0][0].parent()
+        Integer Ring
+        sage: enumerate_totallyreal_fields_rel(F, 2, 2000, return_pari_objects=False)[0][1].parent()
+        Univariate Polynomial Ring in x over Rational Field
+        sage: enumerate_totallyreal_fields_rel(F, 2, 2000, return_pari_objects=False)[0][2].parent()
+        Univariate Polynomial Ring in xF over Number Field in t with defining polynomial x^2 - 2
+        sage: enumerate_totallyreal_fields_rel(F, 2, 2000, return_seqs=True)[1][0][1][0].parent()
+        Rational Field
+
     AUTHORS:
 
     - John Voight (2007-11-01)
@@ -852,15 +874,29 @@ def enumerate_totallyreal_fields_rel(F, m, B, a = [], verbose=0, return_seqs=Fal
                 [[s[0], map(QQ, s[1].reverse().Vec()), s[2].coeffs()]
                  for s in S]
                ]
+    elif return_pari_objects:
+        return S
     else:
         Px = PolynomialRing(QQ, 'x')
         return [[s[0], Px(map(QQ, s[1].list())), s[2]] for s in S]
 
-def enumerate_totallyreal_fields_all(n, B, verbose=0, return_seqs=False):
+def enumerate_totallyreal_fields_all(n, B, verbose=0, return_seqs=False,
+                                     return_pari_objects=True):
     r"""
     Enumerates *all* totally real fields of degree `n` with discriminant `\le B`,
     primitive or otherwise.
 
+    INPUT:
+
+    - ``n`` -- integer, the degree
+    - ``B`` -- integer, the discriminant bound
+    - ``verbose`` -- boolean or string (default: 0)
+    - ``return_seqs`` -- (boolean, default False) If ``True``, then return
+      the polynomials as sequences (for easier exporting to a file).
+    - ``return_pari_objects`` -- (boolean, default: True) if
+      ``return_seqs`` is ``False`` then it returns the elements as Sage
+      objects; otherwise it returns pari objects.
+
     EXAMPLES::
 
         sage: enumerate_totallyreal_fields_all(4, 2000)
@@ -870,6 +906,19 @@ def enumerate_totallyreal_fields_all(n, B, verbose=0, return_seqs=False):
         [1957, x^4 - 4*x^2 - x + 1],
         [2000, x^4 - 5*x^2 + 5]]
 
+    TESTS:
+
+    Each of the outputs must be elements of Sage if ``return_pari_objects``
+    is set to ``False``::
+
+        sage: enumerate_totallyreal_fields_all(2, 10)
+        [[5, x^2 - x - 1], [8, x^2 - 2]]
+        sage: enumerate_totallyreal_fields_all(2, 10)[0][1].parent()
+        Interface to the PARI C library
+        sage: enumerate_totallyreal_fields_all(2, 10, return_pari_objects=False)[0][1].parent()
+        Univariate Polynomial Ring in x over Rational Field
+
+
     In practice most of these will be found by :func:`~sage.rings.number_field.totallyreal.enumerate_totallyreal_fields_prim`, which is guaranteed to return all primitive fields but often returns many non-primitive ones as well. For instance, only one of the five fields in the example above is primitive, but :func:`~sage.rings.number_field.totallyreal.enumerate_totallyreal_fields_prim` finds four out of the five (the exception being `x^4 - 6x^2 + 4`).
     """
 
@@ -922,6 +971,8 @@ def enumerate_totallyreal_fields_all(n, B, verbose=0, return_seqs=False):
     if return_seqs:
         return [map(ZZ, counts),
                 [[ZZ(s[0]), map(QQ, s[1].reverse().Vec())] for s in S]]
+    elif return_pari_objects:
+        return S
     else:
         Px = PolynomialRing(QQ, 'x')
         return [[ZZ(s[0]), Px(map(QQ, s[1].list()))]