scripting changes

Author: cmelone

tutorial_scripting.rst

@@ -11,49 +11,51 @@
 Scripting with Spack
 ====================
 
-This tutorial introduces advanced Spack features related to scripting.
-Specifically, we will show you how to write scripts using ``spack find`` and ``spack python``.
-Earlier sections of the tutorial demonstrated using ``spack find`` to list and search installed packages.
-The ``spack python`` command gives you access to all of Spack's `internal APIs <https://spack.readthedocs.io/en/latest/spack.html>`_, allowing you to write more complex queries, for example.
+This tutorial introduces advanced Spack features related to scripting.  
+Specifically, we'll show how to write scripts using ``spack find`` and ``spack python``.
 
-Since Spack has an extensive API, we'll only scratch the surface here.
-We'll give you enough information to start writing your own scripts and to find what you need, with a little digging.
+Earlier sections demonstrated using ``spack find`` to list and search installed packages.  
+The ``spack python`` command provides access to all of Spack's `internal APIs <https://spack.readthedocs.io/en/latest/spack.html>`_, allowing you to write more complex queries.
+
+Since Spack has an extensive API, we'll only scratch the surface here.  
+Our goal is to give you enough information to start writing your own scripts and to help you discover what you need—with a little digging.
 
 -----------------------------
 Scripting with ``spack find``
 -----------------------------
 
-So far, the output we've seen from ``spack find`` has been for human consumption.
-But you can take advantage of some advanced options of the command to generate machine-readable output suitable for piping to a script.
+So far, the output we've seen from ``spack find`` has been intended for human consumption.  
+However, the command also provides options for generating machine-readable output that can be piped into scripts.
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 ``spack find --format``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The main job of ``spack find`` is to show the user a bunch of concrete specs that correspond to installed packages.
-By default, we display them with some default attributes, like the ``@version`` suffix you're used to seeing in the output.
+The main purpose of ``spack find`` is to display information about concrete specs corresponding to installed packages.  
+By default, it shows these specs with a set of standard attributes, such as the familiar ``@version`` suffix.
+
+The ``--format`` argument allows you to customize the output string for each found package.  
+Format strings let you specify which *parts* of each spec you want to display.
 
-The ``--format`` argument allows you to display the specs however you choose, using custom format strings.
-Format strings let you specify the names of particular *parts* of the specs you want displayed.
-Let's see the first option in action.
+Let's see this option in action.
 
-Suppose you only want to display the *name*, *version*, and first ten (10) characters of the *hash* for every package installed in your Spack instance.
+Suppose you only want to display the *name*, *version*, and the first ten (10) characters of the *hash* for every package installed in your Spack instance.  
 You can generate that output with the following command:
 
 .. literalinclude:: outputs/scripting/find-format.out
    :language: console
    :emphasize-lines: 1
 
-Note that ``name``, ``version``, and ``hash`` are attributes of Spack's internal ``Spec`` object and enclosing them in braces ensures they are output according to your format string.
+Note that ``name``, ``version``, and ``hash`` are attributes of Spack's internal ``Spec`` object, and enclosing them in braces ensures they are rendered according to your format string.
 
-Using ``spack find --format`` allows you to retrieve just the information you need to do things like pipe the output to typical UNIX command-line tools like ``sort`` or ``uniq``.
+Using ``spack find --format`` allows you to retrieve only the information you need—making it easy to pipe the output into standard UNIX command-line tools like ``sort`` or ``uniq``.
 
 ^^^^^^^^^^^^^^^^^^^^^
 ``spack find --json``
 ^^^^^^^^^^^^^^^^^^^^^
 
-Alternatively, you can get a serialized version of Spec objects in the `JSON` format using the ``--json`` option.
-For example, you can get attributes for all installations of ``zlib-ng`` by entering:
+Alternatively, you can get a serialized version of ``Spec`` objects in `JSON` format using the ``--json`` option.  
+For example, to retrieve attributes for all installations of ``zlib-ng``, you can run:
 
 .. literalinclude:: outputs/scripting/find-json.out
    :language: console
@@ -64,51 +66,51 @@ You can pipe its output to JSON filtering tools like ``jq`` to extract just the
 
 Check out the `basic usage docs <https://spack.readthedocs.io/en/latest/basic_usage.html#machine-readable-output>`_ for more examples.
 
-
 ----------------------------------------
 Introducing the ``spack python`` command
 ----------------------------------------
 
 What if we need to perform more advanced queries?
 
-Spack provides the ``spack python`` command to launch a python interpreter with Spack's python modules available to import.
-It uses the underlying python for the rest of its commands.
-So you can write scripts to:
+Spack provides the ``spack python`` command, which launches a Python interpreter with Spack's modules available for import.  
+This interpreter uses the same underlying Python environment that Spack uses for its other commands.
+
+Using this interface, you can write scripts to:
 
-- run Spack commands;
-- explore abstract and concretized specs; and
+- run Spack commands;  
+- explore abstract and concretized specs; and  
 - directly access other internal components of Spack.
 
-Let's launch a Spack-aware python interpreter by entering:
+Let's launch a Spack-aware Python interpreter by entering:
 
 .. literalinclude:: outputs/scripting/spack-python-1.out
    :language: console
    :emphasize-lines: 1,5
 
-Since we are in a python interpreter, use ``exit()`` to end the session and return to the terminal.
+Since we are in a Python interpreter, use ``exit()`` to end the session and return to the terminal.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Accessing the ``Spec`` object
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Now let's take a look at the internal representation of the Spack ``Spec``.
-As you already know, specs can be either *abstract* or *concrete*.
-The specs you've seen in ``package.py`` files (e.g., in the ``install()`` method) have been *concrete*, or fully specified.
-The specs you've typed on the command line have been *abstract*.
-Understanding the differences between the two types is key to using Spack's internal API.
+Now let's take a look at the internal representation of the Spack ``Spec``.  
+As you may already know, specs can be either *abstract* or *concrete*.  
+The specs you've seen in ``package.py`` files (e.g., in the ``install()`` method) have been *concrete*—fully specified with resolved dependencies, compilers, and variants.  
+In contrast, the specs you've typed on the command line have been *abstract*.
 
-Let's open another python interpreter with ``spack python``, instantiate the ``zlib`` spec, and check a few properties of an abstract spec:
+Understanding the difference between these two forms is key to effectively using Spack's internal API.
+
+Let's open another Python interpreter using ``spack python``, instantiate the ``zlib`` spec, and inspect a few properties of an abstract spec:
 
 .. literalinclude:: outputs/scripting/spack-python-abstract.out
    :language: console
    :emphasize-lines: 1-3,5,11,13
 
-Notice that there are ``Spec`` properties and methods that are not accessible to abstract specs; specifically:
+Notice that certain ``Spec`` properties and methods are not accessible on abstract specs:
 
-- an exception -- ``SpecError`` -- is raised if we try to access its
-  ``version``;
-- there are no associated ``versions``; and
-- the spec's operating system is ``None``.
+- An exception—``SpecError``—is raised if you try to access the ``version``.
+- There are no associated ``versions``.
+- The spec's operating system is ``None``.
 
 Now, without exiting the interpreter, let's concretize the spec and try again:
 
@@ -119,10 +121,10 @@ Now, without exiting the interpreter, let's concretize the spec and try again:
 Notice that the concretized spec now:
 
 - has a ``version``;
-- has a single entry in its ``versions`` list; and
-- the operating system is now ``ubuntu22.04``.
+- includes a single entry in its ``versions`` list; and  
+- has ``ubuntu22.04`` as its operating system.
 
-It is not necessary to store the intermediate abstract spec -- you can use the ``.concretized()`` method as shorthand:
+It's not necessary to store the intermediate abstract spec—you can use the ``.concretized()`` method as a shorthand:
 
 .. literalinclude:: outputs/scripting/spack-python-sans-intermediate.out
    :language: console
@@ -132,24 +134,26 @@ It is not necessary to store the intermediate abstract spec -- you can use the `
 Querying the Spack database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Even more powerful queries are available when we look at the information stored in the Spack database.
-The ``Database`` object in Spack is in the ``spack.store.STORE.db`` variable.
-We'll interact with it mainly through the ``query()`` method.
-Let's see the documentation available for ``query()`` using python's built-in ``help()`` function:
+More powerful queries become available when interacting with Spack's installation database.  
+The ``Database`` object is accessible via the ``spack.store.STORE.db`` variable.  
+We'll primarily interact with it through the ``query()`` method.
+Let's view the documentation for ``query()`` using Python's built-in ``help()`` function:
+
 
 .. literalinclude:: outputs/scripting/spack-python-db-query-help.out
    :language: console
    :emphasize-lines: 1-2,9-13
 
 We will primarily make use of the ``query_spec`` argument.
 
-Recall that queries using the ``spack find`` command are limited to queries of attributes with matching values, not values they do *not* have.
-In other words, we cannot use the ``spack find`` command for all packages that *do not* satisfy a certain criterion.
+Recall that queries using the ``spack find`` command are primarily intended to *match* packages based on specified criteria.  
+However, it's more difficult to use ``spack find`` for queries that involve *excluding* packages based on complex logic (e.g., “does *not* depend on X”).
+
+Using the Python interface, we *can* write these more advanced queries.  
+For example, let's find all packages that were compiled with ``gcc`` but do **not** depend on ``mpich``.
+
+We'll use ``spack.cmd.display_specs`` to print the results, replicating the display behavior of the ``spack find`` command:
 
-We *can* use the python interface to write these types of queries.
-For example, let's find all packages that were compiled with ``gcc`` but do not depend on ``mpich``.
-We can do this by using custom python code and Spack database queries.
-We will use the ``spack.cmd.display_specs`` for output to achieve the same printing functionality as the ``spack find`` command:
 
 .. literalinclude:: outputs/scripting/spack-python-db-query-exclude.out
    :language: console
@@ -169,15 +173,15 @@ before generalizing the functionality for reuse.
 Using scripts
 ^^^^^^^^^^^^^
 
-Now let's parameterize our script to accept arguments on the command line.
-With a few generalizations to use the include and exclude specs as arguments, we can create a powerful, general-purpose query script.
+Now let's parameterize our script to accept command-line arguments.  
+With a few generalizations, we can use the include and exclude specs as arguments to create a powerful, general-purpose query script.
 
-Open a file called ``find_exclude.py`` in your preferred editor and add the following code:
+Open a file named ``find_exclude.py`` in your preferred editor and add the following code:
 
 .. literalinclude:: outputs/scripting/0.find_exclude.py.example
    :language: python
 
-Notice we added importing and using the system package (``sys``) to access the first and second command line arguments.
+Notice that we've imported the ``sys`` module and used it to access the first and second command-line arguments.
 
 Now we can run our new script by entering the following:
 
@@ -191,12 +195,12 @@ This is *great* for us, as long as we remember to use Spack's ``python`` command
 Using the ``spack-python`` executable
 -------------------------------------
 
-What if we want to make our script available for others to use without the hassle of having to remember to use ``spack python``?
+What if we want to make our script available for others to use—without requiring them to remember to run it with ``spack python``?
 
-We can take advantage of the shebang line typically added as the first line of python executable files.
-But there is a catch, as we will soon see.
+We can take advantage of a shebang line, typically included as the first line in executable Python scripts.  
+However, there's a catch, as we'll see shortly.
 
-Open the ``find_exclude.py`` script we created above in your preferred editor and add the shebang line with ``spack python`` as the arguments to ``env``:
+Open the ``find_exclude.py`` script you created earlier in your preferred editor, and add a shebang line that invokes ``spack python`` using ``env``:
 
 .. literalinclude:: outputs/scripting/1.find_exclude.py.example
    :language: python
@@ -208,25 +212,26 @@ Then exit our editor and add execute permissions to the script before running it
    :language: console
    :emphasize-lines: 1-2
 
-If you are lucky, it worked on your system, but there is no guarantee.
-Some systems only support a single argument on the shebang line (see `here <https://www.in-ulm.de/~mascheck/various/shebang/>`_). ``spack-python``, which is a wrapper script for ``spack python``, solves this issue.
+If you're lucky, the script worked on your system—but there's no guarantee.  
+Some systems only support a single argument on the shebang line (see `here <https://www.in-ulm.de/~mascheck/various/shebang/>`_).  
+``spack-python``, a wrapper script for ``spack python``, solves this limitation.
 
-Bring up the file in your editor again and change the ``env`` argument to ``spack-python`` as follows:
+Open the script in your editor again and change the ``env`` argument to ``spack-python`` as shown below:
 
 .. literalinclude:: outputs/scripting/2.find_exclude.py.example
    :language: python
    :emphasize-lines: 1
 
-Exit your editor and let's run the script again:
+Exit your editor, and let's run the script again:
 
 .. literalinclude:: outputs/scripting/find-exclude-3.out
    :language: console
    :emphasize-lines: 1
 
-Congratulations!  It will now work on any system with Spack installed.
+Congratulations! It will now work on any system with Spack installed.
 
-You now have the basic tools to create your own custom Spack queries and prototype ideas.
-We hope one day you'll contribute them back to Spack.
+You now have the basic tools to write your own custom Spack queries and prototype new ideas.  
+We hope you'll consider contributing them back to Spack in the future.
 
 ..  LocalWords:  LLC Spack's APIs hdf zlib literalinclude json uniq jq
 ..  LocalWords:  docs concretized REPL API SpecError spec's py ubuntu