gh-35100: New ABC sage.structure.element.NumberFieldElement, deprecate is_NumberFieldElement
    
<!-- ^^^^^
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
Fixes #34931

<!-- 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.
- [x] 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 #35033
    
URL: #35100
Reported by: Matthias Köppe
Reviewer(s): Matthias Köppe, Travis Scrimshaw

Author: Release Manager

src/sage/interfaces/maxima_lib.py

@@ -1164,6 +1164,8 @@ def reduce_load_MaximaLib():
 import sage.rings.real_double
 import sage.symbolic.expression
 import sage.symbolic.integration.integral
+
+from sage.rings.number_field.number_field_element_base import NumberFieldElement_base
 from sage.symbolic.operators import FDerivativeOperator, add_vararg, mul_vararg
 
 car=EclObject("car")
@@ -1523,9 +1525,11 @@ def pyobject_to_max(obj):
     """
     if isinstance(obj,sage.rings.rational.Rational):
         return EclObject(obj) if (obj.denom().is_one()) else EclObject([[rat], obj.numer(),obj.denom()])
-    elif isinstance(obj,sage.rings.number_field.number_field_element_quadratic.NumberFieldElement_quadratic) and obj.parent().defining_polynomial().list() == [1,0,1]:
-        re, im = obj.list()
-        return EclObject([[mplus], pyobject_to_max(re), [[mtimes], pyobject_to_max(im), max_i]])
+    elif isinstance(obj, NumberFieldElement_base):
+        from sage.rings.number_field.number_field_element_quadratic import NumberFieldElement_quadratic
+        if isinstance(obj, NumberFieldElement_quadratic) and obj.parent().defining_polynomial().list() == [1,0,1]:
+            re, im = obj.list()
+            return EclObject([[mplus], pyobject_to_max(re), [[mtimes], pyobject_to_max(im), max_i]])
     return EclObject(obj)
 
 # This goes from SR to EclObject

src/sage/rings/finite_rings/residue_field.pyx

@@ -160,9 +160,9 @@ from sage.rings.finite_rings.finite_field_ntl_gf2e import FiniteField_ntl_gf2e
 from sage.rings.finite_rings.finite_field_prime_modn import FiniteField_prime_modn
 from sage.rings.finite_rings.finite_field_pari_ffelt import FiniteField_pari_ffelt
 from sage.rings.ideal import is_Ideal
+from sage.rings.number_field.number_field_element_base import NumberFieldElement_base
 from sage.structure.element cimport Element
 
-from sage.rings.number_field.number_field_element import is_NumberFieldElement
 from sage.rings.number_field.number_field_ideal import is_NumberFieldIdeal
 
 from sage.modules.free_module_element import FreeModuleElement
@@ -295,7 +295,7 @@ class ResidueFieldFactory(UniqueFactory):
             if not is_Ideal(p):
                 if isinstance(p, (int, Integer, Rational)):
                     p = ZZ.ideal(p)
-                elif is_NumberFieldElement(p):
+                elif isinstance(p, NumberFieldElement_base):
                     if p.parent().is_field():
                         p = p.parent().ring_of_integers().ideal(p)
                     else:

src/sage/rings/integer_ring.pyx

@@ -58,6 +58,7 @@ import sage.libs.pari.all
 import sage.rings.ideal
 from sage.categories.basic import EuclideanDomains
 from sage.categories.infinite_enumerated_sets import InfiniteEnumeratedSets
+from sage.rings.number_field.number_field_element_base import NumberFieldElement_base
 from sage.structure.coerce cimport is_numpy_type
 from sage.structure.element cimport parent
 from sage.structure.parent_gens import ParentWithGens
@@ -414,8 +415,7 @@ cdef class IntegerRing_class(PrincipalIdealDomain):
         if x in self:
             return self
 
-        from sage.rings.number_field.number_field_element import NumberFieldElement
-        if isinstance(x, NumberFieldElement):
+        if isinstance(x, NumberFieldElement_base):
             K, from_K = parent(x).subfield(x)
             return K.order(K.gen())
 

src/sage/rings/number_field/__init__.py

@@ -1,15 +1,16 @@
 cimport sage.structure.element
 from sage.libs.gmp.types cimport mpz_t
 from sage.rings.integer cimport Integer
+from sage.rings.number_field.number_field_element_base cimport NumberFieldElement_base
 from sage.rings.polynomial.polynomial_element cimport Polynomial
-from sage.structure.element cimport FieldElement, RingElement, ModuleElement
 from sage.structure.parent cimport Parent
 from sage.structure.parent_base cimport ParentWithBase
 from sage.libs.ntl.types cimport ZZ_c, ZZX_c
 from sage.libs.ntl.ntl_ZZX cimport ntl_ZZX
 from sage.libs.ntl.ntl_ZZ cimport ntl_ZZ
 
-cdef class NumberFieldElement(FieldElement):
+
+cdef class NumberFieldElement(NumberFieldElement_base):
     cdef ZZX_c __numerator
     cdef ZZ_c __denominator
     # Pointers to the defining polynomial (with numerator) for the field.

src/sage/rings/number_field/number_field_element.pxd

@@ -5,7 +5,7 @@
 # distutils: extra_link_args = NTL_LIBEXTRA
 # distutils: language = c++
 """
-Number Field Elements
+Number field elements (implementation using NTL)
 
 AUTHORS:
 
@@ -108,11 +108,19 @@ def is_NumberFieldElement(x):
 
         sage: from sage.rings.number_field.number_field_element import is_NumberFieldElement
         sage: is_NumberFieldElement(2)
+        doctest:warning...
+        DeprecationWarning: is_NumberFieldElement is deprecated;
+        use isinstance(..., sage.structure.element.NumberFieldElement) instead
+        See https://github.com/sagemath/sage/issues/34931 for details.
         False
         sage: k.<a> = NumberField(x^7 + 17*x + 1)
         sage: is_NumberFieldElement(a+1)
         True
     """
+    from sage.misc.superseded import deprecation
+    deprecation(34931,
+                'is_NumberFieldElement is deprecated; '
+                'use isinstance(..., sage.structure.element.NumberFieldElement) instead')
     return isinstance(x, NumberFieldElement)
 
 
@@ -189,7 +197,7 @@ def _inverse_mod_generic(elt, I):
     return I.small_residue(y)
 
 
-cdef class NumberFieldElement(FieldElement):
+cdef class NumberFieldElement(NumberFieldElement_base):
     """
     An element of a number field.
 
@@ -3884,7 +3892,7 @@ cdef class NumberFieldElement(FieldElement):
         """
         from .number_field_ideal import is_NumberFieldIdeal
         if not is_NumberFieldIdeal(P):
-            if is_NumberFieldElement(P):
+            if isinstance(P, NumberFieldElement):
                 P = self.number_field().fractional_ideal(P)
             else:
                 raise TypeError("P must be an ideal")

src/sage/rings/number_field/number_field_element.pyx

@@ -0,0 +1,5 @@
+from sage.structure.element cimport FieldElement
+
+
+cdef class NumberFieldElement_base(FieldElement):
+    pass

src/sage/rings/number_field/number_field_element_base.pxd

@@ -0,0 +1,33 @@
+r"""
+Number field elements (abstract base class)
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2023 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/
+# ****************************************************************************
+
+cdef class NumberFieldElement_base(FieldElement):
+    r"""
+    Abstract base class for :class:`~sage.rings.number_field.number_field_element.NumberFieldElement`
+
+    This class is defined for the purpose of :func:`isinstance` tests.  It should not be
+    instantiated.
+
+    EXAMPLES::
+
+        sage: k.<a> = NumberField(x^3 + x + 1)
+        sage: isinstance(a, sage.rings.number_field.number_field_element_base.NumberFieldElement_base)
+        True
+
+    By design, there is a unique direct subclass::
+
+        sage: len(sage.rings.number_field.number_field_element_base.NumberFieldElement_base.__subclasses__()) <= 1
+        True
+    """
+
+    pass

src/sage/rings/number_field/number_field_element_base.pyx

@@ -168,6 +168,7 @@
 from sage.structure.richcmp import rich_to_bool
 from sage.structure.unique_representation import UniqueRepresentation
 from sage.structure.element import FieldElement, parent
+
 from sage.structure.coerce import py_scalar_to_element
 from sage.categories.morphism import Morphism
 from sage.rings.ring import Field
@@ -176,6 +177,7 @@
 from sage.rings.rational import Rational
 
 from sage.rings.integer_ring import ZZ
+from sage.rings.number_field.number_field_element_base import NumberFieldElement_base
 from sage.rings.rational_field import QQ
 from sage.rings.infinity import Infinity
 from sage.rings.qqbar import AA, QQbar
@@ -1537,8 +1539,7 @@ def _element_constructor_(self, elt):
         import sage.rings.abc
         P = parent(elt)
         if isinstance(P, sage.rings.abc.NumberField_cyclotomic):
-            from sage.rings.number_field.number_field_element import NumberFieldElement
-            if isinstance(elt, NumberFieldElement):
+            if isinstance(elt, NumberFieldElement_base):
                 from sage.rings.number_field.number_field import CyclotomicField
                 n = P.gen().multiplicative_order()
                 elt = CyclotomicField(n)(elt)

src/sage/rings/universal_cyclotomic_field.py

@@ -42,6 +42,8 @@
 from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
 
 from sage.misc.cachefunc import cached_function
+from sage.rings.number_field.number_field_element_base import NumberFieldElement_base
+
 
 @cached_function
 def hilbert_class_polynomial(D, algorithm=None):
@@ -624,9 +626,7 @@ def is_cm_j_invariant(j, method='new'):
         True
     """
     # First we check that j is an algebraic number:
-    from sage.rings.number_field.number_field_element import NumberFieldElement
-    from sage.rings.number_field.number_field import NumberField
-    if not isinstance(j, NumberFieldElement) and j not in QQ:
+    if not isinstance(j, NumberFieldElement_base) and j not in QQ:
         raise NotImplementedError("is_cm_j_invariant() is only implemented for number field elements")
 
     # for j in ZZ we have a lookup-table:
@@ -672,6 +672,8 @@ def is_cm_j_invariant(j, method='new'):
 
     K = j.parent()
     if h < K.absolute_degree():
+        from sage.rings.number_field.number_field import NumberField
+
         K = NumberField(jpol, 'j')
         j = K.gen()