Merge pull request #388 from mabruzzo/gracklepy-on-pypi-release

Prepare for the release

Author: mabruzzo

CHANGELOG

@@ -1,3 +1,69 @@
+== Version 3.4.1 ==
+_Release date - Aug 22, 2025_
+
+* Bugfix: Fix a significant oversight in **GrackleConfig.cmake**
+  https://github.com/grackle-project/grackle/pull/330
+* Bugfix: H2 self shielding length scale factor fix
+  https://github.com/grackle-project/grackle/pull/325
+* Bugfix: address a bug in calc_temp_cloudy_g.F
+  https://github.com/grackle-project/grackle/pull/367
+* Enhancement: Standard Status Reporting Machinery
+  https://github.com/grackle-project/grackle/pull/269
+* Enhancement: Remove pygrackle/api.py & pygrackle/utilities/api.py
+  https://github.com/grackle-project/grackle/pull/352
+* Enhancement: Rename pygrackle -> gracklepy (so we can upload to PyPI)
+  https://github.com/grackle-project/grackle/pull/371 
+* Build-System: (core lib) introduce CMakePresets.json to enable compiler warnings in a CI job https://github.com/grackle-project/grackle/pull/334
+* Build-System: (core lib) Relocated all CMake dependency information into dependencies.cmake https://github.com/grackle-project/grackle/pull/296
+* Build-System: (core lib) assorted tweaks: https://github.com/grackle-project/grackle/pull/326 https://github.com/grackle-project/grackle/pull/329 https://github.com/grackle-project/grackle/pull/337 
+* Build-System: (gracklepy) tweak cython handling https://github.com/grackle-project/grackle/pull/319 https://github.com/grackle-project/grackle/pull/328
+* Build-System: (gracklepy) Introduce dependency groups https://github.com/grackle-project/grackle/pull/347
+* Testing: Support running subset of gracklepy test without an editable install
+  https://github.com/grackle-project/grackle/pull/335
+* Testing: Move `test_chemistry_struct_synched` between test suites
+  https://github.com/grackle-project/grackle/pull/327
+* Documentation: gracklepy test instruction tweaks
+  https://github.com/grackle-project/grackle/pull/309
+* Assorted tweaks to appearance of doc website
+  https://github.com/grackle-project/grackle/pull/285
+  https://github.com/grackle-project/grackle/pull/291
+  https://github.com/grackle-project/grackle/pull/346
+* Documentation: Fix spacing issues in docs
+  https://github.com/grackle-project/grackle/pull/340
+* Documentation: Simplify GitHub hyperlinks for repository locations in docs
+  https://github.com/grackle-project/grackle/pull/300
+* Documentation: Add more detail to gracklepy build documentation
+  https://github.com/grackle-project/grackle/pull/294
+* Documentation: Added missing He
+  https://github.com/grackle-project/grackle/pull/362
+* Documentation: Added chemistry network table
+  https://github.com/grackle-project/grackle/pull/361
+* Infrastructure: Optimize circleci workflows
+  https://github.com/grackle-project/grackle/pull/338
+* Infrastructure: Introduce an extremely simplistic `.pre-commit-config.yaml` file
+  https://github.com/grackle-project/grackle/pull/348
+* Infrastructure: Introduce GHA to upload Gracklepy wheels to PyPI
+  https://github.com/grackle-project/grackle/pull/320
+  https://github.com/grackle-project/grackle/pull/355
+  https://github.com/grackle-project/grackle/pull/356
+* Infrastructure: Bump pypa/cibuildwheel version
+  https://github.com/grackle-project/grackle/pull/360
+  https://github.com/grackle-project/grackle/pull/363
+  https://github.com/grackle-project/grackle/pull/365
+  https://github.com/grackle-project/grackle/pull/372
+* Infrastructure: Move test-data retrieval logic into ``scripts/ci/fetch-test-data.py``
+  https://github.com/grackle-project/grackle/pull/307
+* Address flake8 warnings (in files that it previously ignored)
+  https://github.com/grackle-project/grackle/pull/368
+  https://github.com/grackle-project/grackle/pull/369
+* Infrastructure: Use builtin GitHub feature to nicely redirect to Code of
+  Conduct
+  https://github.com/grackle-project/grackle/pull/342
+* Infrastructure: Convert README.md to README.rst (and deduplicate content on
+  the website landing page)
+  https://github.com/grackle-project/grackle/pull/350
+  https://github.com/grackle-project/grackle/pull/351
+
 == Version 3.4 ==
 _Release date - May 14, 2025_
 

README.rst

@@ -46,7 +46,7 @@ Our `method paper <http://adsabs.harvard.edu/abs/2017MNRAS.466.2217S>`__ provide
 Projects that provide out-of-the-box support for Grackle
 --------------------------------------------------------
 
-Grackle is a popular tool (the `method paper <http://adsabs.harvard.edu/abs/2017MNRAS.466.2217S>`__ has over 290 citations) and has been used in a wide variety of calculations.
+Grackle is a popular tool (the `method paper <http://adsabs.harvard.edu/abs/2017MNRAS.466.2217S>`__ has over 300 citations) and has been used in a wide variety of calculations.
 Below, we list open source projects that provide out-of-the-box support for Grackle:
 
 `ChaNGa <https://github.com/N-BodyShop/changa>`__,
@@ -63,7 +63,7 @@ Below, we list open source projects that provide out-of-the-box support for Grac
 Getting Grackle
 ---------------
 
-Currently, Grackle must be built from source.
+Currently, the core Grackle library must be built from source.
 If you only need Grackle as a dependency of a simulation code and that code is built with CMake, then that code's build system might be configured to automatically fetch, build, and link Grackle into the code for you (`Enzo-E <https://enzo-e.readthedocs.io/en/latest/>`__ is an example of a code configured in this manner).
 
 If you contribute to a simulation code, our `Integration Guide <https://grackle.readthedocs.io/en/latest/Integration.html>`__ provides guidance on simplifying the process (for you and your users) of configuring your code to use Grackle.
@@ -86,16 +86,21 @@ To install Grackle, invoke ``cmake --install ./build [--prefix <prefix/path>]``
 For more details **(especially if you encounter any errors),** see our comprehensive `Installation Guide <https://grackle.readthedocs.io/en/latest/Installation.html>`__.
 It provides more context for inexperienced CMake users, describes additional configuration options (relevant if you encounter issues), and describes Grackle's "classic" build-system.
 
-Building Gracklepy from Source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing Gracklepy
+~~~~~~~~~~~~~~~~~~~~
 
-Once you have a Fortran compiler and a copy of HDF5 (1.6 or newer), simply invoke the following from the root of the Grackle repository
+The easiest way to get Gracklepy is to invoke the following command
 
 .. code-block:: shell-session
 
-   ~/grackle $ pip install .
+   ~/grackle $ pip install gracklepy
 
-For more about installation see our `Gracklepy installation guide <https://grackle.readthedocs.io/en/latest/Python.html>`__.
+This will download a pre-built version (called a wheel) of Gracklepy from PyPI. This should "just work," unless you use a highly unusual system (if it fails please let us know).
+
+Be aware that the vast majority of Grackle calculation requires Grackle's data files.
+At this time you must download manually download these files (see the installation guide); we're working on streamlining this in the future.
+
+For more about installation (and downloading data files), see our `Gracklepy installation guide <https://grackle.readthedocs.io/en/latest/Python.html>`__ .
 
 **NOTE:** Gracklepy was formerly known as Pygrackle.
 If you previously installed Pygrackle, you should uninstall it before you install GracklePy.

VERSION

@@ -1 +1 @@
-3.4.1-dev
+3.4.1

doc/source/Python.rst

@@ -6,12 +6,43 @@ Gracklepy: Running Grackle in Python
 Grackle comes with a Python interface, called Gracklepy, which provides
 access to all of Grackle's functionality.
 
+If you are new user, we **strongly recommend** that you use a :ref:`pre-built version of Gracklepy <install-gracklepy-prebuilt>`.
+
 .. note::
 
    Gracklepy was formerly known as Pygrackle.
    If you previously installed Pygrackle, you should make sure that you uninstall it before upgrading
 
-To install Gracklepy, you'll need to make sure that HDF5 and a fortran compiler are installed (for building the Grackle library itself).
+
+.. _install-gracklepy-prebuilt:
+
+Pre-built installation (recommended)
+------------------------------------
+
+The easiest way to get Gracklepy is install a pre-built Gracklepy wheel from PyPI. This can be accomplished by invoking
+
+.. code-block:: shell-session
+
+   pip install gracklepy
+
+This command will install the Gracklepy package. Prebuilt copies of all dependencies, including the core Grackle library, are bundled with the installation (the package will use these versions of the dependencies instead of any copies you have installed on your machine).
+
+Be aware that the vast majority of Grackle calculation requires Grackle's data files.
+At this time you must download manually download these files (:gh-pr:`235` is a pending pull request that seeks to streamline this for the future).
+
+You can download the datafiles from `here <https://github.com/grackle-project/grackle_data_files/tree/main/input>`__.
+
+.. important::
+
+   **DO NOT** try linking arbitrary external C/C++ programs against the prebuilt copy of the core Grackle library that is bundled with Gracklepy.
+   This is something that we explicitly do not support (it is not a portable solution!)
+
+.. _install-gracklepy-source:
+
+Installation from Source Code
+-----------------------------
+
+To install Gracklepy from its source code, you'll need to make sure that HDF5 and a fortran compiler are installed (for building the Grackle library itself).
 
 Gracklepy's runtime-dependencies are:
 
@@ -24,25 +55,21 @@ The above dependencies are automatically installed with pip (alternatively you c
 
 If you want to run the gracklepy test-suite, you'll need the ``packaging`` and ``py.test`` packages. If pip is up to date (25.1 or newer), you can simply invoke ``pip install --group dev`` from the root of the repository.
 
-.. _install-gracklepy:
-
-Installing Gracklepy
---------------------
 
 Currently, the only way to get Gracklepy is to build it from source.
 
 There are 3 ways to build Gracklepy:
 
 1. As a standalone, self-contained module.
    The build command creates a fresh build of the Grackle library and packages it with the Gracklepy module.
-   **(This is the recommended approach)**
+   **(If you are going to build Gracklepy from source, this is the recommended way to do it)**
 
 2. As a module that links to an external copy of Grackle that was compiled with the :ref:`Classic build system <classic_build>`.
    (This is consistent with the legacy approach for building Gracklepy).
 
 3. As a module that links to an external copy of Grackle that was created with the :ref:`CMake build system <cmake_build>`.
 
-Currently, Gracklepy should be used with Grackle builds where OpenMP is disabled.
+Currently, Gracklepy should only be used with Grackle builds where OpenMP is disabled.
 
 .. warning::
 
@@ -226,14 +253,15 @@ There are a handful of additional packages required purely for developing
 Grackle. For example, these will enable :ref:`testing` and building
 the documentation locally. These dependencies are specified as dependency
 groups, which can be installed with pip (v25.1).
-To install all of these dependencies, you can invoke
+
+After downloading the git repository, you can install all of these dependencies by invoking
 
 .. code-block:: shell-session
 
    ~/grackle $ pip install --group dev
 
 The above command will install the dependencies independently of Gracklepy.
-To install these dependencies at the same time as Gracklepy, you can replace last line of the :ref:`gracklepy installation instructions <install-gracklepy>` with:
+To install these dependencies at the same time as you build Gracklepy from source, you can replace last line of the :ref:`installation instructions <install-gracklepy-source>` with:
 
 .. code-block:: shell-session
 

doc/source/Testing.rst

@@ -102,6 +102,11 @@ When you launch the tests, the output will look like the following:
 Running the gracklepy Test Suite
 --------------------------------
 
+.. important::
+
+   At the time of writing, the gracklepy suite **ONLY** works when you install :ref:`gracklepy from its source code <install-gracklepy-source>` in an editable installation.
+   Some tests won't work properly if you use a :ref:`prebuilt installation. <install-gracklepy-prebuilt>`
+
 As already noted, the gracklepy suite includes unit tests and answer tests.
 
 Unit tests (i.e., those with explicitly known correct answers) include
@@ -168,7 +173,7 @@ Sample Usage of the gracklepy Test Suite
 
 The following snippets illustrate ways how you might invoke the gracklepy test suite in different scenarios.
 
-Unless noted otherwise, each scenario assumes that you have already :ref:`installed gracklepy <install-gracklepy>` (reminder, you currently need editable installs for these tests).
+Unless noted otherwise, each scenario assumes that you have already :ref:`installed gracklepy from its source code <install-gracklepy-source>` (reminder, you currently need editable installs for these tests).
 Each shows snippets assuming that you are at the root of the Grackle directory.
 
 .. tabs::
@@ -238,7 +243,7 @@ Each shows snippets assuming that you are at the root of the Grackle directory.
          This scenario involves installing (and uninstalling) different versions of Gracklepy.
          These examples all use the simplest (and recommended) approach for installing Gracklepy, which builds it as a standalone library (and automatically manages all details about the core library).
 
-         You could also run the tests using :ref:`the other methods of installing Gracklepy <install-gracklepy>`, but that involves extra steps (in those cases you need to manually build and install/link the associated version of the core library).
+         You could also run the tests using :ref:`the other methods of installing Gracklepy from its source code <install-gracklepy-source>`, but that involves extra steps (in those cases you need to manually build and install/link the associated version of the core library).
 
 
       The basic premise is that you want to run the full gracklepy test suite (with answer verification) on a target version of the code called ``<target>``.

pyproject.toml

@@ -28,7 +28,7 @@ readme = "README.rst"
 #    https://scikit-build-core.readthedocs.io/en/latest/configuration.html#dynamic-metadata
 # but gracklepy can't (currently) do this since it lives in a "monorepo"
 #    https://github.com/pypa/setuptools_scm/issues/1056
-version = "1.1.1.dev1"
+version = "1.2"
 classifiers=[
   "Development Status :: 5 - Production/Stable",
   "Environment :: Console",