.. _pythonresources: Python Resources ================ Pygacity exposes several objects (packages, classes, etc) that can be accessed by using a `pythontex` block in the document structure specified in your configuration file. All `\begin{pycode}...\end{pycode}` blocks will have access to these objects. Default pythontex resources: ``setup`` and ``teardown`` -------------------------------------------------------- ``setup`` ~~~~~~~~~ The following objects are available if the document structure includes a `pythontex` block that imports the `setup` package resource. For example, to import these objects, include the following block in the document structure: .. code-block:: yaml - pythontex: - setup **Packages**: - :pkg:`yaml` - :pkg:`random` - :pkg:`logging` - :pkg:`pickle` - :pkg:`os` - :pkg:`numpy` as :pkg:`np` - :pkg:`fractions` as :pkg:`fr` **Classes**: - :cls:`Namespace` from :pkg:`argparse` - :cls:`Path` from :pkg:`pathlib` - :cls:`AnswerSet` from :pkg:`pygacity.generate.answerset` - :cls:`Picker` from :pkg:`pygacity.generate.pick` - :cls:`FileCollector` from :pkg:`pygacity.util.collectors` **Modules**: - :mod:`pygacity.util.texutils` as :mod:`tu` **Objects**: - :var:`serial`: the unique serial number for the current document copy being built (an integer) - :var:`serialstr`: the formatted string representation of :var:`serial` — a plain decimal string by default, or a zero-padded lowercase hexadecimal string when ``build.serial-hex`` is ``true`` (width controlled by ``build.serial-hex-digits``). This is the same string used in output filenames. - :var:`serials`: a list of all serial integers for the current build run, in the order they were generated. Useful for generating content that references or summarises all exam versions. - :var:`serialstrs`: a list of the formatted string representations of all serials (same formatting rules as :var:`serialstr`), in the same order as :var:`serials`. - :var:`rng`: the random number generator instance seeded using **the document serial number**. (The ``seed`` value from the configuration file is only used to generate the list of serial numbers; each document copy gets its own RNG seeded by its serial number.) - :var:`Pick`: an instance of the ``Picker`` class that can be used to make random selections in a reproducible way across multiple document copies. - :var:`AnsSet`: an instance of the ``AnswerSet`` class that can be used to store and retrieve answers generated during the build process. - :var:`logger`: a logger instance that can be used to log messages during the build process; a user can include ``logger`` calls in their own `\begin{pycode}...\end{pycode}` code blocks to log messages to the build log. The name of the log file is by default ``pygacity_diagnostics.log`` and is located current working directory (not the build directory). - :var:`pythontexFC`: an instance of the ``FileCollector`` class that can be used to collect files during the build process generated by user-defined pythontex blocks. ``teardown`` ~~~~~~~~~~~~ Several default actions are performed if the document structure includes a ``pythontex`` block that imports the ``teardown`` package resource. For example, to import these objects, include the following block in the document structure: .. code-block:: yaml - pythontex: - teardown Actions performed by the ``teardown`` resource include: 1. removing the temporary matplotlib configuration directory (``_mplconfig``) created during the build process if the ``matplotlib`` resource was used. 2. saving the :var:`AnsSet` object to a pickle file in the build cache directory so that pygacity can read it when building the combined answer set document containing all answers for all document copies. 3. saving any files collected using the :var:`pythontexFC` object to a compressed archive file in the build directory for easy access after the build process is complete. Only files declared using the :meth:`pythontexFC.append()` method called within any ``\begin{pycode}...\end{pycode}`` blocks are saved here. Typically, the ``teardown`` resource is included at the end of the document structure to ensure that all other pythontex code has been executed before these actions are performed. Custom resources ---------------- ``matplotlib`` resource ~~~~~~~~~~~~~~~~~~~~~~~~ In addition to the default objects described above, users can also import additional package resources by specifying them in a `pythontex` block in the document structure. For example, to import the `matplotlib` resource, include the following block in the document structure: .. code-block:: yaml - pythontex: - matplotlib This will import the matplotlib package and the pyplot module as usual: .. code-block:: python import matplotlib import matplotlib.pyplot as plt The resource file also does some behind-the-scenes setup to ensure that matplotlib works correctly within the pythontex environment used by pygacity, primarily due to font path issues. It generates a ``_mplconfig`` directory in the build directory that contains a custom matplotlib configuration file used during the build process. It also sets the matplotlib backend to ``Agg`` to ensure compatibility with headless environments. ``sandler`` resource ~~~~~~~~~~~~~~~~~~~~ In addition to the default objects described above, users can also import the ``sandler`` package resource by specifying it in a ``pythontex`` block in the document structure. This resource wires in the `sandlertools `_ package, which provides a suite of utilities for generating problems and solutions based on Sandler's *Chemical, Biochemical, and Engineering Thermodynamics* textbook. .. code-block:: yaml - pythontex: - sandler This imports the following objects for use in subsequent `pycode` blocks: **Classes**: - :cls:`PropertiesDatabase`: A class for accessing thermodynamic property data. - :cls:`SandlerSteamState` as ``SANDLER``: A class for representing the state of steam using the steam tables provided in Appendix III of the textbook. - :cls:`SteamRequest`: A class for specifying requests to generate blocks of steam table for explicit inclusion in documents. - :cls:`Component`, :cls:`Reaction`, and :cls:`ChemEqSystem`: Classes for representing chemical components, reactions, and chemical equilibrium systems, respectively. - :cls:`CorrespondingStatesChartReader`: A class for reading and interpreting corresponding states charts from the textbook. - :cls:`GasConstant`: A class for representing gas constant in various units. - :cls:`IdealGasEOS`, :cls:`GeneralizedVDWEOS`, and :cls:`PengRobinsonEOS`: Classes for representing various equations of state for gases and fluids. **Objects**: - :var:`SteamTables`: The full steam tables data from Appendix III of the textbook. - :var:`R_pv`: the gas constant in units of bar-m3/(mol-K) - :var:`R`: the gas constant in units of J/(mol-K) - :var:`CSReader`: an instance of the :cls:`CorrespondingStatesChartReader` class for reading corresponding states charts. - :var:`STReq`: an instance of the :cls:`SteamRequest` class for generating steam table blocks. - :var:`suphPavail`: a list of pressures (in MPa) at which superheated steam table blocks are available in the textbook. - :var:`SandlerProps`: an instance of the :cls:`PropertiesDatabase` class for accessing thermodynamic property data. ``showsteamtables`` resource ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to the default objects described above, users can also import the `showsteamtables` package resource by specifying it in a `pythontex` block in the document structure. This resource wires in the `showsteamtables` package, which provides utilities for displaying steam tables in LaTeX documents. .. code-block:: yaml - pythontex: - showsteamtables This accesses teh ``STReq`` object and calls its ``.to_latex()`` method to generate LaTeX code for displaying steam tables in the document. Like ``teardown``, it is typically included at the end of the document structure to ensure that all steam table requests have been processed and included in the document.