Use PyO3 functionality to remove Python files

CHANGELOG.md

@@ -12,6 +12,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - added new method `Grid::delete_orders` and the corresponding switch
   `--delete-orders` in the subcommand `write` of the CLI
 
+### Changed
+
+- Python API: dropped top-level Python interface layer
+- Python API: renamed `lumi` to `channel` in PyO3 Python interface. This
+  concerns 1) the argument names of `convolute_with_one` and similar functions;
+  2) the module `pineappl.lumi` was moved to `pineappl.channel`; 3) the class
+  `LumiEntry` was renamed to `Channel`
+- Python API: `.into()` needs to be explicitly called on subgrids when calling
+  `pineappl.grid.set_subgrid()`
+- Python API: replaced `pineappl.grid.PyPidBasis` with
+  `pineappl.evolution.PidBasis`
+- Python API: replaced `pineappl.grid.PyOperatorSliceInfo` with
+  `pineappl.evolution.OperatorSliceInfo`
+- Python API: drop all `Py` prefixes, for instance `PyEvolveInfo` was renamed
+  to `EvolveInfo`
+
+### Removed
+
+- Python API: removed `pineappl.grid.Grid.create()` and
+  `pineappl.fk_table.FkTable.from_grid()` methods; use the constructors
+  of the respective class instead
+
 ## [0.8.2] - 22/07/2024
 
 ### Changed

pineappl_py/.gitignore

@@ -21,8 +21,11 @@ coverage.xml
 .coverage
 
 # Sphinx documentation
-docs/_build/
-doc/_build/
+# Ignore auto generated module references
+# TODO: while apidoc does not work, we need to preserve that folder
+# docs/source/modules
+# ignore temporary build files
+docs/build/
 
 # Environments
 .env

pineappl_py/README.md

@@ -12,3 +12,31 @@ For installation instructions see the [documentation].
 [PyO3]: https://pyo3.rs
 [Rust API]: https://docs.rs/pineappl
 [documentation]: https://pineappl.readthedocs.io/en/latest/installation.html
+
+## Development
+
+Run
+
+```shell
+python -m venv env && . env/bin/activate
+pip install .[docs]
+```
+
+to setup a new environment.
+
+
+Run
+
+```shell
+maturin develop
+```
+
+to build the project.
+
+Run
+
+```shell
+cd docs && make html
+```
+
+to generate the documentation.

pineappl_py/docs/Makefile

@@ -24,8 +24,9 @@ clean:
 	rm -rf build
 	rm -rf _build
 
+# TODO: while apidoc does not work, we need to preserve that folder
 cleanall: clean
-	rm -rf $(PINEAPPLOUT)
+	# rm -rf $(PINEAPPLOUT)
 
 .PHONY: help Makefile
 

pineappl_py/docs/source/conf.py

@@ -1,174 +1,65 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-import pathlib
-import os
-import sys
-
-here = pathlib.Path(__file__).absolute().parent
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "pineappl"
-copyright = "2020-2021, the PineAPPL team"
-author = "the PineAPPL team"
+import pineappl
+import sys
+import pathlib
 
+project = 'pineappl'
+copyright = '2020–2024, the PineAPPL team'
+author = 'the PineAPPL team'
+release = pineappl.version
+version = release
 
-# -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.ifconfig",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.autosectionlabel",
-    "sphinx.ext.napoleon",
-    "sphinxcontrib.bibtex",
-    "sphinx.ext.graphviz",
-    "sphinx.ext.extlinks",
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx_rtd_theme',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = {
-    ".rst": "restructuredtext",
-    ".txt": "restructuredtext",
-}
-
-autosectionlabel_prefix_document = True
-# autosectionlabel_maxdepth = 10
-# Allow to embed rst syntax in  markdown files.
-enable_eval_rst = True
-
-# The master toctree document.
-master_doc = "index"
-bibtex_bibfiles = ["refs.bib"]
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["shared/*"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
-
-# A string to be included at the beginning of all files
-shared = here / "shared"
-rst_prolog = "\n".join([open(x).read() for x in os.scandir(shared)])
 
 extlinks = {
-    "yadism": ("https://nnpdf.github.io/yadism/%s", "yadism - %s"),
     "rustdoc": ("https://docs.rs/pineappl/latest/pineappl/%s", "PineAPPL - %s"),
-    "pineko": ("https://github.com/NNPDF/pineko/%s", "pineko - %s"),
 }
 
+templates_path = ['_templates']
+exclude_patterns = []
+
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
 
-# -- Extension configuration -------------------------------------------------
+# TODO: find a way to reactivate apidoc, which doesn't seem to work for the moment.
 
-# -- Options for intersphinx extension ---------------------------------------
+# here = pathlib.Path(__file__).absolute().parent
+# # https://github.com/readthedocs/readthedocs.org/issues/1139#issuecomment-312626491
+# def run_apidoc(_):
+#     from sphinx.ext.apidoc import main  # pylint: disable=import-outside-toplevel
+
+#     sys.path.append(str(here.parent))
+#     # analyse 'pineappl'
+#     docs_dest = here / "modules"
+#     import pineappl   # pylint: disable=import-outside-toplevel
+
+#     # note that we can NOT point to the local directory (`here.parents[1] / "pineappl"`)
+#     # but we need the package built by `maturin` and installed by `pip`
+#     package = pathlib.Path(pineappl.__file__).parent / "pineappl"
+#     main(["--module-first", "--no-toc", "-o", str(docs_dest), str(package)])
 
-# Example configuration for intersphinx: refer to the Python standard library.
-# Thanks https://github.com/bskinn/sphobjinv
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-}
-# -- Options for todo extension ----------------------------------------------
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
-
-mathjax3_config = {
-    "tex": {
-        "macros": {
-            # fncs
-            # "atan": [r"\text{atan}", 0],
-            # "span": [r"\text{span}", 0],
-        }
-    }
-}
 
-# https://stackoverflow.com/questions/1871549/determine-if-python-is-running-inside-virtualenv
-def get_base_prefix_compat():
-    """Get base/real prefix, or sys.prefix if there is none."""
-    return (
-        getattr(sys, "base_prefix", None)
-        or getattr(sys, "real_prefix", None)
-        or sys.prefix
-    )
-
-
-def in_virtualenv():
-    return get_base_prefix_compat() != sys.prefix
-
-
-# https://github.com/readthedocs/readthedocs.org/issues/1139#issuecomment-312626491
-def run_apidoc(_):
-    import subprocess  # pylint: disable=import-outside-toplevel
-
-    from sphinx.ext.apidoc import main  # pylint: disable=import-outside-toplevel
-
-    sys.path.append(str(here.parent))
-    # run maturin to have the latest stuff
-    pkg_root = here.parents[1]
-    # if in_virtualenv():  # in local repos we're always in a virtualenv
-    #     subprocess.run(["maturin", "develop"], cwd=pkg_root)
-    # else:  # on RTD we can't (for some reason we're not inside the virtualenv - or maybe only the subshell isn't)
-    #     subprocess.run(["maturin", "build"], cwd=pkg_root)
-    #     # On RTD we were already installing before, but of course this was fake
-    #     # as it only had the raw Python stuff, so let's do it again
-    #     subprocess.run(["pip", "uninstall", "pineappl", "-y"], cwd=pkg_root)
-    #     wheels = list((pkg_root / "target" / "wheels").glob("pineappl*.whl"))
-    #     # In case there are several wheels (as on RTD) find the one matching (and let the others happily fail)
-    #     for wheel in wheels:
-    #         subprocess.run(["pip", "install", str(wheel.absolute())], cwd=pkg_root)
-
-    # analyse 'pineappl'
-    docs_dest = here / "modules" / "pineappl"
-    import pineappl
-
-    # note that we can NOT point to the local directory (`here.parents[1] / "pineappl"`)
-    # but we need the package built by `maturin` and installed by `pip`
-    package = pathlib.Path(pineappl.__file__).parent
-    main(["--module-first", "-o", str(docs_dest), str(package)])
-    (docs_dest / "modules.rst").unlink()
-
-
-def setup(app):
-    app.connect("builder-inited", run_apidoc)
+# def setup(app):
+#     app.connect("builder-inited", run_apidoc)

pineappl_py/docs/source/index.rst

@@ -1,14 +1,15 @@
 Welcome to PineAPPL
 ===================
 
-This is the Python wrapper for the `Rust PineAPPL library <https://nnpdf.github.io/pineappl/>`_.
+This is the Python wrapper for the `Rust PineAPPL library <https://nnpdf.github.io/pineappl/>`_ using `PyO3 <https://pyo3.rs>`_.
 
 PineAPPL is a computer library that makes it possible to produce fast-interpolation grids for fitting parton distribution functions (PDFs) including corrections of strong and electroweak origin.
 
 The :doc:`installation` instructions are given :doc:`here <installation>`.
 
 A practical example can be found in the ``example/`` subfolder of the `repository <https://github.com/NNPDF/pineappl/>`_.
-The Python wrapper is also used in :yadism:`\ ` and :pineko:`\ `. We also list some common :doc:`recipes` here.
+The Python wrapper is also used in `yadism <https://nnpdf.github.io/yadism/>`_ and `pineko <https://github.com/NNPDF/pineko/>`_.
+We also list some common :doc:`recipes` here.
 
 .. toctree::
    :maxdepth: 1
@@ -17,17 +18,5 @@ The Python wrapper is also used in :yadism:`\ ` and :pineko:`\ `. We also list s
 
    installation
    recipes
-   implementation
-   API <modules/pineappl/pineappl>
+   API <modules/pineappl>
    indices
-
-.. important::
-
-   If you are looking for the methods of a specific class, be aware that part of
-   them are just passed to the underlying Rust object, whose class is the same
-   of the user-facing one, but prefixed with a ``Py``, e.g.:
-   :class:`pineappl.grid.Grid` and :class:`pineappl.pineappl.grid.PyGrid`.
-
-   You will find the documentation of the unwrapped method in the raw ``Py``
-   class, while part of the methods are wrapped and thus even documented in the
-   user-facing class.