gh-40894: Remove usage of `SAGE_SHARE` from sagelib
    
The `SAGE_SHARE` variable is still used in sagelib to manage some data
files. This is problematic for a few reasons:

- `SAGE_SHARE` can only store a single path, but data can be installed
in multiple different paths (eg. system vs user paths)
- Some methods try to write there, which is not possible if the path is
not writeable (as it is the case on distro packages, where `SAGE_SHARE`
generally points to `/usr/share`)

We replace all uses in sagelib with more appropriate solutions. For
locating data files, we use `sage_data_paths`, which on Linux includes
in particular `XDG_DATA_DIRS`. When writing files we always use a user
path under `DOT_SAGE`, which is the only one we can assume to be
writeable.

`SAGE_SHARE` is still used as a fallback value for `sage_data_paths`, so
this should be backwards compatible.
    
URL: #40894
Reported by: Antonio Rojas
Reviewer(s): Antonio Rojas, Tobias Diez

Author: Release Manager

pkgs/sage-conf/_sage_conf/_conf.py.in

@@ -8,7 +8,6 @@ VERSION = "@PACKAGE_VERSION@"
 # to it.
 SAGE_LOCAL = "@prefix@"
 SAGE_ROOT = "@SAGE_ROOT@"
-SAGE_SHARE = "@SAGE_SHARE@"
 
 # The semicolon-separated list of GAP root paths. This is the list of
 # locations that are searched for GAP packages. This is passed directly

src/sage/combinat/cluster_algebra_quiver/mutation_type.py

@@ -1257,30 +1257,30 @@ def load_data(n: int, user=True) -> dict:
     We test data from the ``database_mutation_class`` optional package::
 
         sage: load_data(2, user=False)      # optional - database_mutation_class
-        {('G', 2): [('AO', (((0, 1), (1, -3)), )), ('AO', (((0, 1), (3, -1)), ))]}
+        {('G', 2): [('AO', (((0, 1), (1, -3)),)), ('AO', (((0, 1), (3, -1)),))]}
         sage: D = load_data(3, user=False)  # optional - database_mutation_class
         sage: sorted(D.items())             # optional - database_mutation_class
         [(('G', 2, -1),
-          [('BH?', (((1, 2), (1, -3)), )),
-           ('BGO', (((2, 1), (3, -1)), )),
-           ('BW?', (((0, 1), (3, -1)), )),
-           ('BP?', (((0, 1), (1, -3)), )),
+          [('BH?', (((1, 2), (1, -3)),)),
+           ('BGO', (((2, 1), (3, -1)),)),
+           ('BW?', (((0, 1), (3, -1)),)),
+           ('BP?', (((0, 1), (1, -3)),)),
            ('BP_', (((0, 1), (1, -3)), ((2, 0), (3, -1)))),
            ('BP_', (((0, 1), (3, -1)), ((1, 2), (1, -3)), ((2, 0), (2, -2))))]),
          (('G', 2, 1),
-          [('BH?', (((1, 2), (3, -1)), )),
-           ('BGO', (((2, 1), (1, -3)), )),
-           ('BW?', (((0, 1), (1, -3)), )),
-           ('BP?', (((0, 1), (3, -1)), )),
+          [('BH?', (((1, 2), (3, -1)),)),
+           ('BGO', (((2, 1), (1, -3)),)),
+           ('BW?', (((0, 1), (1, -3)),)),
+           ('BP?', (((0, 1), (3, -1)),)),
            ('BKO', (((1, 0), (3, -1)), ((2, 1), (1, -3)))),
            ('BP_', (((0, 1), (2, -2)), ((1, 2), (1, -3)), ((2, 0), (3, -1))))])]
     """
-    from sage.env import DOT_SAGE, SAGE_SHARE
+    from sage.env import DOT_SAGE, sage_data_paths
 
     # we check
     # - if the data is stored by the user, and if this is not the case
     # - if the data is stored by the optional package install
-    paths = [Path(SAGE_SHARE)]
+    paths = [Path(path) for path in sage_data_paths()]
     if user:
         paths.append(Path(DOT_SAGE))
     data = {}

src/sage/databases/all.py

@@ -34,7 +34,7 @@
     sage: oeis
     The On-Line Encyclopedia of Integer Sequences (https://oeis.org/)
 
-    sage: SymbolicData()
+    sage: SymbolicData() # optional - database_symbolic_data
     SymbolicData with ... ideals
 """
 

src/sage/databases/cremona.py

@@ -20,8 +20,8 @@
 This causes the latest version of the database to be downloaded from
 the internet.
 
-Both the mini and full versions of John Cremona's tables are stored in
-SAGE_SHARE/cremona as SQLite databases. The mini version has the layout::
+Both the mini and full versions of John Cremona's tables are stored
+as SQLite databases. The mini version has the layout::
 
     CREATE TABLE t_class(conductor INTEGER, class TEXT PRIMARY KEY, rank INTEGER);
     CREATE TABLE t_curve(class TEXT, curve TEXT PRIMARY KEY, eqn TEXT UNIQUE, tors INTEGER);
@@ -115,8 +115,8 @@ def build(name, data_tgz, largest_conductor=0, mini=False, decompress=True):
 
         sage: d = sage.databases.cremona.build('cremona','ecdata.tgz')   # not tested
     """
-    from sage.env import SAGE_SHARE
-    db_path = os.path.join(SAGE_SHARE,'cremona',name.replace(' ','_')+'.db')
+    from sage.env import DOT_SAGE
+    db_path = os.path.join(DOT_SAGE, 'db', 'cremona', name.replace(' ','_')+'.db')
     if os.path.exists(db_path):
         raise RuntimeError('Please (re)move %s before building ' % db_path
                 + 'database')

src/sage/databases/cunningham_tables.py

@@ -19,7 +19,7 @@
 from sage.misc.cachefunc import cached_function
 from sage.rings.integer import Integer
 from sage.misc.persist import load
-from sage.env import SAGE_SHARE
+from sage.env import sage_data_paths
 
 
 @cached_function
@@ -43,11 +43,11 @@ def cunningham_prime_factors():
          17,
          ...
     """
-    file = os.path.join(SAGE_SHARE,'cunningham_tables','cunningham_prime_factors.sobj')
-    if os.path.exists(file):
-        return [Integer(_) for _ in load(file)]
-    else:
-        from warnings import warn
-        warn("You might consider installing the optional package for factoring Cunningham numbers"
-             " with the following command: ``sage -i cunningham_tables``")
-        return []
+    for path in sage_data_paths('cunningham_tables'):
+        file = os.path.join(path, 'cunningham_prime_factors.sobj')
+        if os.path.exists(file):
+            return [Integer(_) for _ in load(file)]
+
+    from warnings import warn
+    warn("The optional cunningham_tables package for factoring Cunningham numbers is not installed")
+    return []

src/sage/databases/db_modular_polynomials.py

@@ -32,6 +32,7 @@
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
 import bz2
+import os
 from pathlib import Path
 
 
@@ -52,14 +53,14 @@ def _dbz_to_string(name) -> str:
         sage: _dbz_to_string('PolHeeg/Cls/0000001-0005000/pol.0000003.dbz')
         '0\n1\n'
     """
-    from sage.env import SAGE_SHARE
-    filename = Path(SAGE_SHARE) / 'kohel' / name
-    try:
-        with open(filename, 'rb') as f:
-            data = bz2.decompress(f.read())
-    except OSError:
-        raise FileNotFoundError('file not found in the Kohel database')
-    return data.decode()
+    from sage.env import sage_data_paths
+    for path in sage_data_paths('kohel'):
+        filename = Path(path) / name
+        if os.path.exists(filename):
+            with open(filename, 'rb') as f:
+                data = bz2.decompress(f.read())
+            return data.decode()
+    raise FileNotFoundError('file not found in the Kohel database')
 
 
 def _dbz_to_integer_list(name) -> list[list]:

src/sage/databases/jones.py

@@ -73,7 +73,6 @@
 from sage.rings.rational_field import RationalField
 from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
 from sage.combinat.subset import powerset
-from sage.env import SAGE_SHARE
 
 from sage.misc.persist import load, save
 

src/sage/databases/odlyzko.py

@@ -29,7 +29,7 @@
 import os
 
 from sage.misc.persist import load
-from sage.env import SAGE_SHARE
+from sage.env import sage_data_paths
 
 
 def zeta_zeros():
@@ -54,6 +54,9 @@ def zeta_zeros():
         2001052
     """
     from sage.misc.verbose import verbose
-    sobj = os.path.join(SAGE_SHARE, 'odlyzko', 'zeros.sobj')
-    verbose("Loading Odlyzko database from " + sobj)
-    return load(sobj)
+    for path in sage_data_paths('odlyzko'):
+        sobj = os.path.join(path, 'zeros.sobj')
+        if os.path.exists(sobj):
+            verbose("Loading Odlyzko database from " + sobj)
+            return load(sobj)
+    raise FileNotFoundError('Could not find the odlyzko database')

src/sage/databases/sloane.py

@@ -1,3 +1,4 @@
+# sage.doctest: needs sloane_database
 """
 Local copy of the On-Line Encyclopedia of Integer Sequences
 
@@ -11,29 +12,29 @@
 
 ::
 
-    sage: SloaneEncyclopedia[60843]  # optional - sloane_database
+    sage: SloaneEncyclopedia[60843]
     [1, 6, 21, 107, 47176870]
 
 To get the name of a sequence, type
 
 ::
 
-    sage: SloaneEncyclopedia.sequence_name(1)  # optional - sloane_database
+    sage: SloaneEncyclopedia.sequence_name(1)
     'Number of groups of order n.'
 
 To search locally for a particular subsequence, type
 
 ::
 
-    sage: SloaneEncyclopedia.find([1,2,3,4,5], 1)    # optional - sloane_database
+    sage: SloaneEncyclopedia.find([1,2,3,4,5], 1)
     [(15, [1, 2, 3, 4, 5, 7, 7, 8, 9, 11, 11, 13, 13, 16, 16, 16, 17, 19, 19, 23, 23, 23, 23, 25, 25, 27, 27, 29, 29, 31, 31, 32, 37, 37, 37, 37, 37, 41, 41, 41, 41, 43, 43, 47, 47, 47, 47, 49, 49, 53, 53, 53, 53, 59, 59, 59, 59, 59, 59, 61, 61, 64, 64, 64, 67, 67, 67, 71, 71, 71, 71, 73])]
 
 The default maximum number of results is 30, but to return up to
 100, type
 
 ::
 
-    sage: SloaneEncyclopedia.find([1,2,3,4,5], 100)  # optional - sloane_database
+    sage: SloaneEncyclopedia.find([1,2,3,4,5], 100)
     [(15, [1, 2, 3, 4, 5, 7, 7, 8, 9, 11, 11, ...
 
 Results in either case are of the form [ (number, list) ].
@@ -87,7 +88,7 @@
 import ssl
 
 from sage.misc.verbose import verbose
-from sage.env import SAGE_SHARE
+from sage.env import DOT_SAGE, sage_data_paths
 from sage.rings.integer_ring import ZZ
 
 
@@ -101,7 +102,12 @@ def __init__(self):
         """
         Initialize the database but do not load any of the data.
         """
-        self.__path__ = os.path.join(SAGE_SHARE, 'sloane')
+        self.__path__ = os.path.join(DOT_SAGE, 'db', 'sloane')
+        for path in sage_data_paths('sloane'):
+            file_oeis = os.path.join(path, 'sloane-oeis.bz2')
+            file_names = os.path.join(path, 'sloane-names.bz2')
+            if os.path.exists(file_oeis) and os.path.exists(file_names):
+                self.__path__ = path
         self.__file__ = os.path.join(self.__path__, 'sloane-oeis.bz2')
         self.__file_names__ = os.path.join(self.__path__, 'sloane-names.bz2')
         self.__loaded__ = False
@@ -155,7 +161,7 @@ def is_installed(self):
 
         EXAMPLES::
 
-            sage: SloaneEncyclopedia.is_installed()  # optional - sloane_database
+            sage: SloaneEncyclopedia.is_installed()
             True
         """
         return os.path.exists(self.__file__) and os.path.exists(self.__file_names__)
@@ -333,7 +339,7 @@ def sequence_name(self, N):
 
         EXAMPLES::
 
-            sage: SloaneEncyclopedia.sequence_name(1) # optional - sloane_database
+            sage: SloaneEncyclopedia.sequence_name(1)
             'Number of groups of order n.'
         """
         self.load()

src/sage/databases/stein_watkins.py

@@ -1,3 +1,4 @@
+# sage.doctest: needs database_stein_watkins
 r"""
 The Stein-Watkins table of elliptic curves
 
@@ -41,7 +42,6 @@
 We type ``next(d)`` to get each isogeny class of
 curves from ``d``::
 
-    sage: # optional - database_stein_watkins
     sage: C = next(d)
     sage: C
     Stein-Watkins isogeny class of conductor 11
@@ -56,7 +56,6 @@
 
 ::
 
-    sage: # optional - database_stein_watkins
     sage: C.data
     ['11', '[11]', '0', '0.253842', '25', '+*1']
     sage: C.curves
@@ -83,24 +82,23 @@
 following::
 
     sage: d = SteinWatkinsAllData(1)
-    sage: C = next(d)                                  # optional - database_stein_watkins
-    sage: C                                            # optional - database_stein_watkins
+    sage: C = next(d)
+    sage: C
     Stein-Watkins isogeny class of conductor 100002
-    sage: C.curves                                     # optional - database_stein_watkins
+    sage: C.curves
     [[[1, 1, 0, 112, 0], '(8,1,2,1)', 'X', '2'],
      [[1, 1, 0, -448, -560], '[4,2,1,2]', 'X', '2']]
 
 Next we access the prime-conductor data::
 
     sage: d = SteinWatkinsPrimeData(0)
-    sage: C = next(d)                                  # optional - database_stein_watkins
-    sage: C                                            # optional - database_stein_watkins
+    sage: C = next(d)
+    sage: C
     Stein-Watkins isogeny class of conductor 11
 
 Each call ``next(d)`` gives another elliptic curve of
 prime conductor::
 
-    sage: # optional - database_stein_watkins
     sage: C = next(d)
     sage: C
     Stein-Watkins isogeny class of conductor 17
@@ -137,7 +135,7 @@
 import bz2
 import os
 
-from sage.env import SAGE_SHARE
+from sage.env import sage_data_paths
 
 
 class SteinWatkinsIsogenyClass:
@@ -183,7 +181,13 @@ def __init__(self, num):
             raise RuntimeError("num (=%s) must be a nonnegative integer" % num)
         name = str(num)
         name = '0' * (3 - len(name)) + name
-        self._file = os.path.join(SAGE_SHARE, 'stein_watkins', 'a.%s.bz2' % name)
+        self._file = None
+        for path in sage_data_paths('stein_watkins'):
+            file = os.path.join(path, 'a.%s.bz2' % name)
+            if os.path.exists(file):
+                self._file = file
+        if not self._file:
+            raise FileNotFoundError('Could not find the Stein-Watkins database')
         self._iter = iter(self)
 
     def __repr__(self):
@@ -201,8 +205,8 @@ def __iter__(self):
         EXAMPLES::
 
             sage: d = SteinWatkinsAllData(0)
-            sage: d = d[10:20]                         # optional - database_stein_watkins; long time
-            sage: for C in d:                          # optional - database_stein_watkins; long time
+            sage: d = d[10:20]
+            sage: for C in d:
             ....:     print(C)
             Stein-Watkins isogeny class of conductor 11
             Stein-Watkins isogeny class of conductor 14
@@ -250,7 +254,7 @@ def __getitem__(self, N):
         EXAMPLES::
 
             sage: d = SteinWatkinsAllData(0)
-            sage: d[15:18]                             # optional - database_stein_watkins; long time
+            sage: d[15:18]
             [Stein-Watkins isogeny class of conductor 15, Stein-Watkins isogeny
              class of conductor 17]
         """
@@ -281,12 +285,12 @@ def iter_levels(self):
 
             sage: d = SteinWatkinsAllData(1)
             sage: E = d.iter_levels()
-            sage: next(E)                             # optional - database_stein_watkins
+            sage: next(E)
             [Stein-Watkins isogeny class of conductor 100002]
-            sage: next(E)                             # optional - database_stein_watkins
+            sage: next(E)
             [Stein-Watkins isogeny class of conductor 100005,
             Stein-Watkins isogeny class of conductor 100005]
-            sage: next(E)                             # optional - database_stein_watkins
+            sage: next(E)
             [Stein-Watkins isogeny class of conductor 100007]
         """
         it = iter(self)
@@ -317,7 +321,13 @@ def __init__(self, num):
             raise RuntimeError("num (=%s) must be a nonnegative integer" % num)
         name = str(num)
         name = '0' * (2 - len(name)) + name
-        self._file = os.path.join(SAGE_SHARE, 'stein_watkins', 'p.%s.bz2' % name)
+        self._file = None
+        for path in sage_data_paths('stein_watkins'):
+            file = os.path.join(path, 'p.%s.bz2' % name)
+            if os.path.exists(file):
+                self._file = file
+        if not self._file:
+            raise FileNotFoundError('Could not find the Stein-Watkins database')
         self._iter = iter(self)
 
     def __repr__(self):
@@ -338,7 +348,7 @@ def ecdb_num_curves(max_level=200000):
 
     EXAMPLES::
 
-        sage: sage.databases.stein_watkins.ecdb_num_curves(100) # optional - database_stein_watkins
+        sage: sage.databases.stein_watkins.ecdb_num_curves(100)
         [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 6, 8, 0, 4, 0, 3, 4, 6, 0, 0,
          6, 0, 5, 4, 0, 0, 8, 0, 4, 4, 4, 3, 4, 4, 5, 4, 4, 0, 6, 1, 2, 8, 2, 0,
          6, 4, 8, 2, 2, 1, 6, 4, 6, 7, 3, 0, 0, 1, 4, 6, 4, 2, 12, 1, 0, 2, 4, 0,