gh-35230: sage.rings.function_field: Modularization fixes

    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
### 📚 Description
- We split out `.derivations` (which uses modules) from `.maps` (which
doesn't).
- We separate the implementation of rational function fields (which do
not need Singular for Gröbner basis calculations) from the
implementation of more complicated function fields (which do).
- We move some imports into methods.

This is for modularization purposes:
- Part of #29705



<!-- Describe your changes here in detail -->
<!-- Why is this change required? What problem does it solve? -->
<!-- If it resolves an open issue, please link to the issue here. For
example "Closes #1337" -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->

- [x] I have made sure that the title is self-explanatory and the
description concisely explains the PR.
- [ ] I have linked an issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies
<!-- List all open pull requests that this PR logically depends on -->
<!--
- #xyz: short description why this is a dependency
- #abc: ...
-->
- Depends on #35237 (for the feature `sage.libs.singular`)
- Depends on #35119 (to preempt merge conflicts)
    
URL: #35230
Reported by: Matthias Köppe
Reviewer(s): Kwankyu Lee, Matthias Köppe

src/doc/en/developer/packaging_sage_library.rst

@@ -567,6 +567,15 @@ doctests that depend on :class:`sage.symbolic.ring.SymbolicRing` for integration
 testing. Hence, these doctests are marked ``# optional -
 sage.symbolic``.
 
+When defining new features for the purpose of doctest annotations, it may be a good
+idea to hide implementation details from feature names. For example, all doctests that
+use finite fields have to depend on PARI. However, we have defined a feature
+:mod:`sage.rings.finite_rings` (which implies the presence of :mod:`sage.libs.pari`).
+Annotating the doctests ``# optional - sage.rings.finite_rings`` expresses the
+dependency in a clearer way than using ``# optional - sage.libs.pari``, and it
+will be a smaller maintenance burden when implementation details change.
+
+
 Testing the distribution in virtual environments with tox
 ---------------------------------------------------------
 

src/doc/en/reference/function_fields/index.rst

@@ -11,13 +11,27 @@ algebraic closure of `\QQ`.
    :maxdepth: 1
 
    sage/rings/function_field/function_field
+   sage/rings/function_field/function_field_rational
+   sage/rings/function_field/function_field_polymod
    sage/rings/function_field/element
+   sage/rings/function_field/element_rational
+   sage/rings/function_field/element_polymod
    sage/rings/function_field/order
+   sage/rings/function_field/order_rational
+   sage/rings/function_field/order_basis
+   sage/rings/function_field/order_polymod
    sage/rings/function_field/ideal
+   sage/rings/function_field/ideal_rational
+   sage/rings/function_field/ideal_polymod
    sage/rings/function_field/place
+   sage/rings/function_field/place_rational
+   sage/rings/function_field/place_polymod
    sage/rings/function_field/divisor
    sage/rings/function_field/differential
    sage/rings/function_field/valuation_ring
+   sage/rings/function_field/derivations
+   sage/rings/function_field/derivations_rational
+   sage/rings/function_field/derivations_polymod
    sage/rings/function_field/maps
    sage/rings/function_field/extensions
    sage/rings/function_field/constructor

src/doc/en/reference/valuations/index.rst

@@ -201,7 +201,7 @@ More Details
    sage/rings/valuation/mapped_valuation
    sage/rings/valuation/scaled_valuation
 
-   sage/rings/function_field/function_field_valuation
+   sage/rings/function_field/valuation
    sage/rings/padics/padic_valuation
 
 .. include:: ../footer.txt

src/sage/categories/function_fields.py

@@ -52,14 +52,14 @@ def _call_(self, x):
         EXAMPLES::
 
             sage: C = FunctionFields()
-            sage: K.<x>=FunctionField(QQ)
+            sage: K.<x> = FunctionField(QQ)
             sage: C(K)
             Rational function field in x over Rational Field
             sage: Ky.<y> = K[]
-            sage: L = K.extension(y^2-x)
-            sage: C(L)
+            sage: L = K.extension(y^2 - x)                                              # optional - sage.rings.function_field
+            sage: C(L)                                                                  # optional - sage.rings.function_field
             Function field in y defined by y^2 - x
-            sage: C(L.equation_order())
+            sage: C(L.equation_order())                                                 # optional - sage.rings.function_field
             Function field in y defined by y^2 - x
         """
         try:

src/sage/features/__init__.py

@@ -52,6 +52,19 @@
 As can be seen above, features try to produce helpful error messages.
 """
 
+# *****************************************************************************
+#       Copyright (C) 2016      Julian Rüth
+#                     2018      Jeroen Demeyer
+#                     2018      Timo Kaufmann
+#                     2019-2022 Matthias Koeppe
+#                     2021      Kwankyu Lee
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 from __future__ import annotations
 
 import os

src/sage/features/all.py

@@ -2,6 +2,15 @@
 Enumeration of all defined features
 """
 
+# *****************************************************************************
+#       Copyright (C) 2021 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 def all_features():
     r"""
     Return an iterable of all features.

src/sage/features/bliss.py

@@ -1,7 +1,18 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of ``bliss``
 """
+
+# *****************************************************************************
+#       Copyright (C) 2016 Julian Rüth
+#                     2018 Jeroen Demeyer
+#                     2021 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 from . import CythonFeature, PythonModule
 from .join_feature import JoinFeature
 

src/sage/features/cddlib.py

@@ -1,6 +1,16 @@
 r"""
 Feature for testing the presence of ``cddlib``
 """
+
+# *****************************************************************************
+#       Copyright (C) 2022 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 from . import Executable
 
 

src/sage/features/csdp.py

@@ -3,6 +3,18 @@
 Feature for testing the presence of ``csdp``
 """
 
+# *****************************************************************************
+#       Copyright (C) 2016 Julian Rüth
+#                     2018 Jeroen Demeyer
+#                     2019 David Coudert
+#                     2021 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 import os
 import re
 import subprocess

src/sage/features/cython.py

@@ -1,8 +1,16 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of ``cython``
 """
 
+# *****************************************************************************
+#       Copyright (C) 2021 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 from . import CythonFeature
 
 

src/sage/features/databases.py

@@ -1,8 +1,21 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of various databases
 """
 
+# *****************************************************************************
+#       Copyright (C) 2016      Julian Rüth
+#                     2018-2019 Jeroen Demeyer
+#                     2018      Timo Kaufmann
+#                     2020-2022 Matthias Koeppe
+#                     2020-2022 Sebastian Oehms
+#                     2021      Kwankyu Lee
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 
 from . import StaticFile, PythonModule
 from sage.env import (

src/sage/features/dvipng.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 r"""
 Feature for testing the presence of ``dvipng``
 """

src/sage/features/ffmpeg.py

@@ -1,9 +1,8 @@
-# -*- coding: utf-8 -*-
 r"""
 Feature for testing the presence of ``ffmpeg``
 """
 # ****************************************************************************
-#       Copyright (C) 2018 Sebastien Labbe <[email protected]>
+#       Copyright (C) 2018-2022 Sebastien Labbe <[email protected]>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

src/sage/features/gap.py

@@ -1,9 +1,18 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of GAP packages
 """
+# *****************************************************************************
+#       Copyright (C) 2016 Julian Rüth
+#                     2018 Jeroen Demeyer
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
 
-from . import Feature, FeatureTestResult
+from . import Feature, FeatureTestResult, PythonModule
+from .join_feature import JoinFeature
 
 
 class GapPackage(Feature):
@@ -48,3 +57,34 @@ def _is_present(self):
         else:
             return FeatureTestResult(self, False,
                     reason="`{command}` evaluated to `{presence}` in GAP.".format(command=command, presence=presence))
+
+
+class sage__libs__gap(JoinFeature):
+    r"""
+    A :class:`sage.features.Feature` describing the presence of :mod:`sage.libs.gap`
+    (the library interface to GAP) and :mod:`sage.interfaces.gap` (the pexpect
+    interface to GAP). By design, we do not distinguish between these two, in order
+    to facilitate the conversion of code from the pexpect interface to the library
+    interface.
+
+    EXAMPLES::
+
+        sage: from sage.features.gap import sage__libs__gap
+        sage: sage__libs__gap().is_present()                       # optional - sage.libs.gap
+        FeatureTestResult('sage.libs.gap', True)
+    """
+    def __init__(self):
+        r"""
+        TESTS::
+
+            sage: from sage.features.gap import sage__libs__gap
+            sage: isinstance(sage__libs__gap(), sage__libs__gap)
+            True
+        """
+        JoinFeature.__init__(self, 'sage.libs.gap',
+                             [PythonModule('sage.libs.gap.libgap'),
+                              PythonModule('sage.interfaces.gap')])
+
+
+def all_features():
+    return [sage__libs__gap()]

src/sage/features/gfan.py

@@ -2,6 +2,15 @@
 Features for testing the presence of ``gfan``
 """
 
+# *****************************************************************************
+#       Copyright (C) 2022 Matthias Koeppe
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 from . import Executable
 
 

src/sage/features/graph_generators.py

@@ -1,8 +1,20 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of various graph generator programs
 """
 
+# *****************************************************************************
+#       Copyright (C) 2016 Julian Rüth
+#                     2018 Jeroen Demeyer
+#                     2019 Frédéric Chapoton
+#                     2021 Matthias Koeppe
+#                     2021 Kwankyu Lee
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# *****************************************************************************
+
 import os
 import subprocess
 

src/sage/features/graphviz.py

@@ -1,16 +1,18 @@
-# -*- coding: utf-8 -*-
 r"""
 Features for testing the presence of ``graphviz``
 """
+
 # ****************************************************************************
 #       Copyright (C) 2018 Sebastien Labbe <[email protected]>
+#                     2021 Matthias Koeppe
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 2 of the License, or
 # (at your option) any later version.
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
+
 from . import Executable
 from .join_feature import JoinFeature
 

src/sage/features/igraph.py

@@ -1,6 +1,17 @@
 r"""
 Check for igraph
 """
+
+# ****************************************************************************
+#       Copyright (C) 2021 Matthias Koeppe
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
 from . import PythonModule
 from .join_feature import JoinFeature
 

src/sage/features/imagemagick.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 r"""
 Feature for testing the presence of ``imagemagick``
 
@@ -7,8 +6,9 @@
 ``identify``, ``composite``, ``montage``, ``compare``, etc. could be also
 checked in this module.
 """
+
 # ****************************************************************************
-#       Copyright (C) 2018 Sebastien Labbe <[email protected]>
+#       Copyright (C) 2018-2022 Sebastien Labbe <[email protected]>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

src/sage/features/interfaces.py

@@ -1,6 +1,17 @@
 r"""
 Features for testing whether interpreter interfaces are functional
 """
+
+# ****************************************************************************
+#       Copyright (C) 2021 Matthias Koeppe
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
 import importlib
 
 from . import Feature, FeatureTestResult, PythonModule