Trac #33754: Update src/doc/en/developer/coding_basics.rst and coding…

…_in_python.rst regarding imports

It gives some outdated advice regarding "all.py"

it should point to
https://doc.sagemath.org/html/en/developer/packaging_sage_library.html
#dependencies-and-distribution-packages

Also we add some material from https://wiki.sagemath.org/import (and
delete it there, and also delete outdated material there).

URL: https://trac.sagemath.org/33754
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): John Palmieri

src/doc/en/developer/coding_basics.rst

@@ -113,7 +113,7 @@ of the directory containing the Sage sources:
         upstream/            # tarballs of upstream sources
         local/               # installed binaries
 
-Python Sage library code goes into ``src/`` and uses the following
+Python Sage library code goes into ``src/sage/`` and uses the following
 conventions. Directory names may be plural (e.g. ``rings``) and file
 names are almost always singular (e.g. ``polynomial_ring.py``). Note
 that the file ``polynomial_ring.py`` might still contain definitions
@@ -125,29 +125,34 @@ of several different types of polynomial rings.
    discussions, etc., in your package.  Make these plain text files
    (with extension ``.txt``) in a subdirectory called ``notes``.
 
-If you want to create a new directory in the Sage library
-``SAGE_ROOT/src/sage`` (say, ``measure_theory``), that directory
-should contain a file ``__init__.py`` that contains the single line
-``import all`` in addition to whatever
-files you want to add (say, ``borel_measure.py`` and
-``banach_tarski.py``), and also a file ``all.py`` listing imports from
-that directory that are important enough to be in the Sage’s global
-namespace at startup.
-The file ``all.py`` might look like this::
+If you want to create a new directory (`package
+<https://docs.python.org/3/tutorial/modules.html#packages>`_) in the
+Sage library ``SAGE_ROOT/src/sage`` (say, ``measure_theory``), that
+directory will usually contain an empty file ``__init__.py``, which
+marks the directory as an ordinary package (see
+:ref:`section_namespace_packages`), and also a file ``all.py``,
+listing imports from this package that are user-facing and important
+enough to be in the global namespace of Sage at startup.  The file
+``all.py`` might look like this::
 
-    from borel_measure import BorelMeasure
-    from banach_tarski import BanachTarskiParadox
+    from .borel_measure import BorelMeasure
+    from .banach_tarski import BanachTarskiParadox
 
-but it is generally better to use the lazy import framework::
+but it is generally better to use the :mod:`~sage.misc.lazy_import`
+framework::
 
     from sage.misc.lazy_import import lazy_import
-    lazy_import('sage.measure_theory.borel_measue', 'BorelMeasure')
+    lazy_import('sage.measure_theory.borel_measure', 'BorelMeasure')
     lazy_import('sage.measure_theory.banach_tarski', 'BanachTarskiParadox')
 
 Then in the file ``SAGE_ROOT/src/sage/all.py``, add a line ::
 
     from sage.measure_theory.all import *
 
+Adding new top-level packages below :mod:`sage` should be done
+sparingly.  It is often better to create subpackages of existing
+packages.
+
 Non-Python Sage source code and supporting files can be included in one
 of the following places:
 

src/doc/en/developer/coding_in_python.rst

@@ -496,7 +496,8 @@ Importing
 =========
 
 We mention two issues with importing: circular imports and importing
-large third-party modules.
+large third-party modules. See also :ref:`section_dependencies_distributions`
+for a discussion of imports from the viewpoint of modularization.
 
 First, you must avoid circular imports. For example, suppose that the
 file ``SAGE_ROOT/src/sage/algebras/steenrod_algebra.py``
@@ -542,7 +543,7 @@ look like this (omitting the documentation string):
         return steenrod_algebra_basis(n, basis=self._basis_name, p=self.prime)
 
 Second, do not import at the top level of your module a third-party
-module that will take a long time to initialize (e.g. matplotlib). As
+module that will take a long time to initialize (e.g. :mod:`matplotlib`). As
 above, you might instead import specific components of the module when
 they are needed, rather than at the top level of your file.
 
@@ -555,6 +556,27 @@ import but delay it until the object is actually used. See
 :ref:`chapter-directory-structure` for an example using lazy imports
 for a new module.
 
+If your module needs to make some precomputed data available at the top level,
+you can reduce its load time (and thus startup time, unless your module is
+imported using :mod:`sage.misc.lazy_import`) by using the decorator
+:func:`sage.misc.cachefunc.cached_function` instead. For example, replace
+
+.. CODE-BLOCK:: python
+
+    big_data = initialize_big_data()  # bad: runs at module load time
+
+by
+
+.. CODE-BLOCK:: python
+
+    from sage.misc.cachefunc import cached_function
+
+    @cached_function                  # good: runs on first use
+    def big_data():
+        return initialize_big_data()
+
+
+
 
 Deprecation
 ===========

src/doc/en/developer/packaging_sage_library.rst

@@ -75,6 +75,8 @@ Sage-specific distribution.  Examples:
   :mod:`sage.ext.memory_allocator`, a part of the Sage library.
 
 
+.. _section_namespace_packages:
+
 Ordinary packages vs. implicit namespace packages
 -------------------------------------------------
 
@@ -203,6 +205,7 @@ Because the distribution packages are included in the source tree, we set them
 up as "script packages" instead of "normal packages", see :ref:`section-package-source-types`.
 
 
+.. _section_dependencies_distributions:
 
 Dependencies and distribution packages
 ======================================