patkit 0.22.2__tar.gz → 0.22.3__tar.gz

{patkit-0.22.2 → patkit-0.22.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: patkit
-Version: 0.22.2
+Version: 0.22.3
 Summary: Phonetic Analysis ToolKit: Tools for processing phonetic data
 Project-URL: bug_tracker, https://github.com/giuthas/patkit/issues
 Project-URL: changelog, https://github.com/giuthas/patkit/blob/main/docs/Release_notes.markdown
@@ -718,7 +718,7 @@ Description-Content-Type: text/markdown
 [![test](https://github.com/giuthas/patkit/actions/workflows/test.yaml/badge.svg)](https://github.com/giuthas/patkit/actions/workflows/test.yaml)
 # PATKIT - Phonetic Analysis ToolKIT 
 
-![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
+![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.2.png)
 
 PATKIT provides tools for phonetic analysis of speech data. It includes a GUI
 for manual assessment/analysis/annotation (see picture above), command line

{patkit-0.22.2 → patkit-0.22.3}/README.md

@@ -1,7 +1,7 @@
 [![test](https://github.com/giuthas/patkit/actions/workflows/test.yaml/badge.svg)](https://github.com/giuthas/patkit/actions/workflows/test.yaml)
 # PATKIT - Phonetic Analysis ToolKIT 
 
-![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.0.png)
+![PATKIT GUI](https://giuthas.github.io/patkit/PATKIT_UI_0.22.2.png)
 
 PATKIT provides tools for phonetic analysis of speech data. It includes a GUI
 for manual assessment/analysis/annotation (see picture above), command line

{patkit-0.22.2 → patkit-0.22.3}/patkit/constants.py

@@ -510,7 +510,21 @@ class DefaultCursorColors(str, Enum):
     Default colors for GUI cursor and selection elements.
     """
     SELECTION = "deepskyblue"
-    PLAYBACK = "red"
+    PLAYBACK = "#FD7400"
+
+    def __str__(self) -> str:
+        """
+        Ensure f-strings and print() output the string value.
+        """
+        return self.value
+
+
+class ColorPalettes(str, Enum):
+    """
+    Colors for plotting lines.
+    """
+    COLORBLIND_10 = 'tableau-colorblind10'
+    # COLORBLIND_6 = 'viscid-colorblind'
 
     def __str__(self) -> str:
         """

{patkit-0.22.2 → patkit-0.22.3}/patkit/data_loader.py

@@ -148,9 +148,13 @@ def read_recorded_session_from_dir(
         )
         return session
 
+    # TODO 1.0: if Sessions are no longer the highest possible container tier,
+    # this logic needs to change.
     file_info = FileInformation(
         recorded_path=recorded_data_path,
-        recorded_meta_file=session_config_path.name)
+        recorded_meta_file=session_config_path.name,
+        is_top_level_object=True,
+    )
     if session_config_path.is_file():
         session_config = load_session_config(
             recorded_data_path, session_config_path)

{patkit-0.22.2 → patkit-0.22.3}/patkit/data_structures/metadata_classes.py

@@ -69,6 +69,8 @@ class FileInformation:
         Name of the patkit meta file, if it exists. Defaults to None.
     patkit_path : Path | None
         Path to the saved patkit data, if it exists. Defaults to None.
+    is_top_level_object : bool
+        Is this the top level container, by default False.
     """
     recorded_data_file: str | None = None
     recorded_meta_file: str | None = None
@@ -76,6 +78,7 @@ class FileInformation:
     patkit_data_file: str | None = None
     patkit_meta_file: str | None = None
     patkit_path: Path | None = None
+    is_top_level_object: bool = False
 
     @property
     def basename(self) -> str:

{patkit-0.22.2 → patkit-0.22.3}/patkit/gui/__init__.py

@@ -34,7 +34,9 @@
 from .annotator_window import UiMainWindow
 from .audio_player import AudioPlayer
 from .boundary_animation import BoundaryAnimator
-from .exercise_dialogs import NewAnswerDialog, NewExerciseDialog
+from .exercise_dialogs import (
+    PackageExerciseDialog, NewAnswerDialog, NewExerciseDialog
+)
 from .image_save_dialog import ImageSaveDialog
 from .list_save_dialog import ListSaveDialog
 from .list_selection_dialog import ListSelectionDialog

{patkit-0.22.2 → patkit-0.22.3}/patkit/gui/annotator_window.py

@@ -275,6 +275,11 @@ class UiMainWindow(object):
         self.action_new_exercise.setObjectName("action_new_exercise")
         self.action_save_exercise = QtGui.QAction(main_window)
         self.action_save_exercise.setObjectName("action_save_exercise")
+        self.action_package_exercise = QtGui.QAction(main_window)
+        self.action_package_exercise.setObjectName("action_package_exercise")
+        self.action_unpackage_exercise = QtGui.QAction(main_window)
+        self.action_unpackage_exercise.setObjectName(
+            "action_unpackage_exercise")
         self.action_new_answer = QtGui.QAction(main_window)
         self.action_new_answer.setObjectName("action_new_answer")
         self.action_save_answer = QtGui.QAction(main_window)
@@ -289,6 +294,8 @@ class UiMainWindow(object):
 
         self.menu_exercise.addAction(self.action_new_exercise)
         self.menu_exercise.addAction(self.action_save_exercise)
+        self.menu_exercise.addAction(self.action_package_exercise)
+        self.menu_exercise.addAction(self.action_unpackage_exercise)
         self.menu_exercise.addSeparator()
         self.menu_exercise.addAction(self.action_new_answer)
         self.menu_exercise.addAction(self.action_save_answer)
@@ -450,6 +457,10 @@ class UiMainWindow(object):
             _translate("MainWindow", "Ctrl+Shift+N"))
         self.action_save_exercise.setText(
             _translate("MainWindow", "Save exercise"))
+        self.action_package_exercise.setText(
+            _translate("MainWindow", "Package exercise..."))
+        self.action_unpackage_exercise.setText(
+            _translate("MainWindow", "Unpackage exercise..."))
         self.action_new_answer.setText(
             _translate("MainWindow", "New answer..."))
         self.action_new_answer.setShortcut(

{patkit-0.22.2 → patkit-0.22.3}/patkit/gui/exercise_dialogs.py

@@ -36,8 +36,8 @@ Dialogs for Exercises and Answers.
 from pathlib import Path
 
 from PyQt6.QtWidgets import (
-    QComboBox, QDialog, QDialogButtonBox, QFileDialog, QHBoxLayout,
-    QLabel, QLineEdit, QSizePolicy, QVBoxLayout, QWidget
+    QCheckBox, QComboBox, QDialog, QDialogButtonBox, QFileDialog, QHBoxLayout,
+    QLabel, QLineEdit, QPushButton, QSizePolicy, QVBoxLayout, QWidget
 )
 
 from patkit.constants import ExerciseScrambler
@@ -188,3 +188,121 @@ class NewAnswerDialog(QDialog):
         if dialog.exec() == QDialog.DialogCode.Rejected:
             return None, None
         return dialog.answer_name, dialog.author_name
+
+
+class PackageExerciseDialog(QDialog):
+    """
+    Dialog for configuring an Exercise packaging.
+
+    This dialog allows the user to specify a package path and choose whether
+    to include the unscrambled Session TextGrids in the resulting archive.
+    """
+
+    def __init__(
+        self,
+        parent: QWidget | None = None,
+        default_path: Path | None = None
+    ) -> None:
+        """
+        Initialize the PackageExerciseDialog.
+
+        Parameters
+        ----------
+        parent : QWidget | None, optional
+            The parent widget, by default None.
+        default_path : Path | None, optional
+            The default file path to populate the dialog, by default None.
+        """
+        super().__init__(parent=parent)
+        self.setWindowTitle("Package Exercise")
+        self.resize(700, 100)
+
+        self.package_path: Path | None = None
+        self.include_textgrids: bool = False
+
+        self.path_label = QLabel(text="Package Path:", parent=self)
+        self.path_field = QLineEdit(parent=self)
+        if default_path is not None:
+            self.path_field.setText(str(default_path))
+
+        self.browse_button = QPushButton(text="Browse...", parent=self)
+        self.browse_button.clicked.connect(slot=self._browse)
+
+        path_layout = QHBoxLayout()
+        path_layout.addWidget(self.path_label)
+        path_layout.addWidget(self.path_field)
+        path_layout.addWidget(self.browse_button)
+
+        self.textgrid_checkbox = QCheckBox(
+            text=(
+                "Include original TextGrids (this will make "
+                "them viewable when running the exercise)."
+            ),
+            parent=self
+        )
+
+        dialog_buttons = (
+            QDialogButtonBox.StandardButton.Ok |
+            QDialogButtonBox.StandardButton.Cancel
+        )
+        self.ok_cancel_buttons = QDialogButtonBox(dialog_buttons)
+        self.ok_cancel_buttons.accepted.connect(slot=self._on_accepted)
+        self.ok_cancel_buttons.rejected.connect(slot=self.reject)
+
+        main_layout = QVBoxLayout(self)
+        main_layout.addLayout(path_layout)
+        main_layout.addWidget(self.textgrid_checkbox)
+        main_layout.addWidget(self.ok_cancel_buttons)
+
+        self.setMinimumWidth(450)
+
+    def _browse(self) -> None:
+        """Open a file dialog to select the destination zip path."""
+        file_path, _ = QFileDialog.getSaveFileName(
+            parent=self,
+            caption="Select Packaging Destination",
+            directory=self.path_field.text(),
+            filter="Zip Files (*.zip)"
+        )
+        if file_path:
+            self.path_field.setText(file_path)
+
+    def _on_accepted(self) -> None:
+        """Validate input and accept the dialog."""
+        path_text = self.path_field.text()
+        if not path_text:
+            self.reject()
+            return
+
+        self.package_path = Path(path_text)
+        self.include_textgrids = self.textgrid_checkbox.isChecked()
+        self.accept()
+
+    @staticmethod
+    def get_packaging_params(
+        parent: QWidget | None = None,
+        default_path: Path | None = None
+    ) -> tuple[Path | None, bool]:
+        """
+        Open the package dialog and query the user for packaging parameters.
+
+        Parameters
+        ----------
+        parent : QWidget | None, optional
+            Parent window.
+        default_path : Path | None, optional
+            The default file path to populate the line edit.
+
+        Returns
+        -------
+        tuple[Path | None, bool]
+            The selected file path and boolean indicating if TextGrids
+            should be included. Path is None if the user cancelled.
+        """
+        dialog = PackageExerciseDialog(
+            parent=parent, default_path=default_path
+        )
+        if dialog.exec() == QDialog.DialogCode.Rejected:
+            return None, False
+
+        return dialog.package_path, dialog.include_textgrids

{patkit-0.22.2 → patkit-0.22.3}/patkit/gui/image_save_dialog.py

@@ -34,12 +34,14 @@ import os
 from pathlib import Path
 
 from PyQt6 import QtCore
-from PyQt6.QtGui import QFontMetrics, QIcon
+from PyQt6.QtGui import QIcon
 from PyQt6.QtWidgets import (
     QCheckBox, QDialog, QDialogButtonBox, QFileDialog, QHBoxLayout, QLabel,
     QLineEdit, QPushButton, QVBoxLayout, QWidget
 )
 
+# TODO 1.0: docstrings
+
 
 class ImageSaveDialog(QDialog):
 
@@ -68,14 +70,14 @@ class ImageSaveDialog(QDialog):
         option_box = None
         if options is not None:
             option_box = QHBoxLayout()
-            self.option_checkboxes = {}
+            self.checkboxes = {}
             for option, checked in options.items():
                 checkbox = QCheckBox(option)
                 check = (QtCore.Qt.CheckState.Checked
                          if checked else QtCore.Qt.CheckState.Unchecked)
                 checkbox.setCheckState(check)
-                self.option_checkboxes[option] = checkbox
-                option_box.addWidget(self.option_checkboxes[option])
+                self.checkboxes[option] = checkbox
+                option_box.addWidget(self.checkboxes[option])
         path_and_name_box = QHBoxLayout()
         self.path_label = QLabel(self)
         self.path_label.setText("Path:")
@@ -110,7 +112,7 @@ class ImageSaveDialog(QDialog):
             vbox.addLayout(option_box)
         vbox.addLayout(path_and_name_box)
         vbox.addWidget(self.ok_cancel_buttons)
-        
+
         self.setWindowTitle(self.name)
         if icon:
             self.setWindowIcon(icon)
@@ -118,19 +120,21 @@ class ImageSaveDialog(QDialog):
         self.adjustSize()
 
     def _browse(self):
-        directory = QFileDialog.getSaveFileName(
+        # TODO 0.23: getSaveFileName doesn't necessarily match the purpose
+        # here?
+        path, something = QFileDialog.getSaveFileName(
             parent=self,
-            caption="Select Directory to Export to",
+            caption="Select Path to Export to",
             directory=self.path_field.text(),
             options=QFileDialog.Option.DontResolveSymlinks
         )
-        if directory:
-            self.path_field.setText(directory)
+        if path:
+            self.path_field.setText(path)
 
     def _on_accepted(self):
         if self.options is not None:
             for option in self.options:
-                self.options[option] = self.option_checkboxes[option].isChecked()
+                self.options[option] = self.checkboxes[option].isChecked()
         self.save_path = Path(self.path_field.text())
         self.accept()
 

{patkit-0.22.2 → patkit-0.22.3}/patkit/gui/plot_controller.py

@@ -44,7 +44,7 @@ import numpy as np
 from patkit.data_structures import Recording
 from patkit.configuration import DataConfig, GuiConfig
 from patkit.constants import (
-    AnnotatorMode, DefaultCanvasColors, DefaultCursorColors,
+    AnnotatorMode, ColorPalettes, DefaultCanvasColors, DefaultCursorColors,
     ExerciseMode, GuiColorScheme, GuiImageType
 )
 from patkit.plot_and_publish import (
@@ -136,7 +136,7 @@ class PlotController:
         matplotlib.rcParams.update(
             {'font.size': self.gui_config.default_font_size}
         )
-        plt.style.use('tableau-colorblind10')
+        plt.style.use(ColorPalettes.COLORBLIND_10)
 
     def to_annotator_mode(
         self,
@@ -156,6 +156,7 @@ class PlotController:
                 raise ValueError(
                     f"Unknown GUI color scheme: {gui_color_mode}"
                 )
+        plt.style.use(ColorPalettes.COLORBLIND_10)
 
     def to_exercise_mode(
         self,
@@ -175,6 +176,7 @@ class PlotController:
                 raise ValueError(
                     f"Unknown GUI color scheme: {gui_color_mode}"
                 )
+        plt.style.use(ColorPalettes.COLORBLIND_10)
 
     def to_example_mode(
         self,
@@ -194,6 +196,7 @@ class PlotController:
                 raise ValueError(
                     f"Unknown GUI color scheme: {gui_color_mode}"
                 )
+        plt.style.use(ColorPalettes.COLORBLIND_10)
 
     def to_answer_mode(
         self,
@@ -213,6 +216,7 @@ class PlotController:
                 raise ValueError(
                     f"Unknown GUI color scheme: {gui_color_mode}"
                 )
+        plt.style.use(ColorPalettes.COLORBLIND_10)
 
     def setup_axes(self) -> None:
         """
@@ -416,8 +420,11 @@ class PlotController:
             )
             boundaries_by_axis.append(boundary_set)
             axis.set_ylabel(
-                name, rotation=90, horizontalalignment="center",
-                verticalalignment="center")
+                name,
+                rotation=0,
+                horizontalalignment="center",
+                verticalalignment="center"
+            )
             axis.set_xlim(xlim)
             if name in self.gui_config.pervasive_tiers:
                 for data_axis in self.data_axes:
@@ -903,3 +910,10 @@ class PlotController:
         self.canvas.draw()
 
         self.update_multicursor()
+
+    def display_exclusion(self):
+        """
+        Updates title and graphs to show this Recording is excluded.
+        """
+        # TODO 0.23: do this correctly
+        pass

{patkit-0.22.2 → patkit-0.22.3}/patkit/qt_annotator.py

@@ -76,14 +76,14 @@ from patkit.export import (
 from patkit.gui import (
     AudioPlayer, ImageSaveDialog, ListSaveDialog,
     NewAnswerDialog, NewExerciseDialog,
-    ListSelectionDialog, PlotController,
+    ListSelectionDialog, PackageExerciseDialog, PlotController,
     ReplaceDialog, UiMainWindow,
 )
 from patkit.initialise import initialise_config, initialise_patkit
 from patkit.path_resolution import get_manifest_scenarios, resolve_open_path
 from patkit.save_and_load import (
-    load_answer, save_answer, save_exercise,
-    save_recording_session,
+    load_answer, package_exercise_to_zip, unpackage_exercise_from_zip,
+    save_answer, save_exercise, save_recording_session,
 )
 from patkit.ui_callbacks import UiCallbacks
 
@@ -203,6 +203,9 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
         self.action_new_exercise.triggered.connect(
             self.new_exercise)
         self.action_save_exercise.triggered.connect(self.save_exercise)
+        self.action_package_exercise.triggered.connect(self.package_exercise)
+        self.action_unpackage_exercise.triggered.connect(
+            self.unpackage_exercise)
         self.action_new_answer.triggered.connect(self.new_answer)
         self.action_save_answer.triggered.connect(self.save_answer)
         self.action_open_answer.triggered.connect(self.open_answer)
@@ -709,7 +712,7 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
 
         self.update()
         # In case labels change as new plots are drawn.
-        self.figure.align_ylabels()
+        self.plot_controller.figure.align_ylabels()
         self.update_ui()
 
     def open_file(self):
@@ -727,7 +730,7 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
         """
         Save derived modalities and annotations.
         """
-        # TODO 0.22.3: does this save textgrids too and how does it interact
+        # TODO 0.23.3: does this save textgrids too and how does it interact
         # with saving answers and exercises.
         save_recording_session(self.session)
 
@@ -755,7 +758,7 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
         """
         Save the all TextGrids in this Session.
         """
-        # TODO 0.22.3: write a call back for asking for overwrite confirmation.
+        # TODO 0.23.3: write a call back for asking for overwrite confirmation.
         if self.annotator_mode is AnnotatorMode.EXERCISE:
             return
 
@@ -809,6 +812,85 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
         """Save the active exercise to disk."""
         save_exercise(exercise=self.session.exercise)
 
+    def package_exercise(self) -> None:
+        """
+        Package the active exercise to a zip.
+        """
+        default_name = f"{self.session.patkit_path.name}.zip"
+        default_path = self.session.patkit_path.parent / default_name
+
+        zip_path, include_grids = PackageExerciseDialog.get_packaging_params(
+            parent=self,
+            default_path=default_path
+        )
+
+        if zip_path is None:
+            return
+
+        current_answer_name = self.session.exercise.current_answer.name
+
+        package_exercise_to_zip(
+            file_info=self.session.file_info,
+            zip_path=zip_path,
+            active_answer_name=current_answer_name,
+            include_root_textgrids=include_grids
+        )
+
+        # TODO: status message instead
+        # QMessageBox.information(
+        #     parent=self,
+        #     title="Export Successful",
+        #     text=f"Exercise successfully exported to:\n{zip_path}"
+        # )
+
+    def unpackage_exercise(self) -> None:
+        """
+        Prompt the user to extract a zipped exercise and load it.
+        """
+        zip_path_str, _ = QFileDialog.getOpenFileName(
+            parent=self,
+            caption="Open Zipped Exercise",
+            directory=str(Path.cwd()),
+            filter="Zip Files (*.zip)"
+        )
+
+        if not zip_path_str:
+            return
+
+        zip_path = Path(zip_path_str)
+
+        dest_dir_str = QFileDialog.getExistingDirectory(
+            parent=self,
+            caption="Select Destination for Extraction",
+            directory=str(zip_path.parent)
+        )
+
+        if not dest_dir_str:
+            return
+
+        dest_dir = Path(dest_dir_str) / zip_path.stem
+
+        # TODO 0.25: ask for confirmation before overwriting instead of just
+        # refusing. This should take the form of a callback handed to
+        # unpackage_exercise_from_zip, so that individual files can be
+        # confirmed as needed.
+        unpackage_exercise_from_zip(
+            zip_filepath=zip_path,
+            destination_directory=dest_dir
+        )
+
+        # TODO: status message instead
+        # msg_text = (
+        #     f"Exercise extracted to:\n{dest_dir}\n\n"
+        #     "Please open this directory as a new Session."
+        # )
+
+        # QMessageBox.information(
+        #     parent=self,
+        #     title="Import Successful",
+        #     text=msg_text
+        # )
+
     def new_answer(self) -> bool:
         """Create a new blank answer for the current exercise."""
         answer_name, author_name = NewAnswerDialog.get_answer_params(self)
@@ -854,7 +936,7 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
         if not ok or not answer_name:
             return
 
-        # TODO 0.22.3: The loading here might be redundant, if Exercise already
+        # TODO 0.23.3: The loading here might be redundant, if Exercise already
         # front loads every answer.
         directory = answers_dir / answer_name
         answer = load_answer(
@@ -990,7 +1072,8 @@ class PdQtAnnotator(QMainWindow, UiMainWindow):
             parent=self,
         )
         if filename is not None:
-            self.figure.savefig(filename, bbox_inches='tight', pad_inches=0.05)
+            self.plot_controller.figure.savefig(
+                filename, bbox_inches='tight', pad_inches=0.05)
             export_session_and_recording_meta(
                 filename=filename,
                 session=self.session,

{patkit-0.22.2 → patkit-0.22.3}/patkit/save_and_load/__init__.py

@@ -29,6 +29,9 @@
 # articles listed in README.md. They can also be found in
 # citations.bib in BibTeX format.
 #
+from .exercise_packaging import (
+    package_exercise_to_zip, unpackage_exercise_from_zip
+)
 from .load import (
     load_answer, load_exercise, load_recordings, load_recording_session
 )

patkit-0.22.3/patkit/save_and_load/exercise_packaging.py

@@ -0,0 +1,141 @@
+#
+# Copyright (c) 2019-2026
+# Pertti Palo, Scott Moisik, Matthew Faytak, and Motoki Saito.
+#
+# This file is part of the Phonetic Analysis ToolKIT
+# (see https://github.com/giuthas/patkit/).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+# The example data packaged with this program is licensed under the
+# Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+# International (CC BY-NC-SA 4.0) License. You should have received a
+# copy of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+# International (CC BY-NC-SA 4.0) License along with the data. If not,
+# see <https://creativecommons.org/licenses/by-nc-sa/4.0/> for details.
+#
+# When using the toolkit for scientific publications, please cite the
+# articles listed in README.md. They can also be found in
+# citations.bib in BibTeX format.
+#
+"""
+Utility functions for packaging and importing Patkit Exercises.
+"""
+
+import logging
+from zipfile import ZipFile, ZIP_DEFLATED
+from pathlib import Path
+
+from patkit.constants import SourceSuffix
+from patkit.data_structures import FileInformation
+
+_logger = logging.getLogger('patkit.exercise_packaging')
+
+
+def package_exercise_to_zip(
+    file_info: FileInformation,
+    zip_path: Path,
+    active_answer_name: str,
+    include_root_textgrids: bool = False,
+    include_wav_files: bool = True,
+) -> None:
+    """
+    Package a Patkit Session and Exercise into a zip file.
+
+    Please note that, if the wav files will be included in the zip, they will
+    be included in the *patkit directory* rather than as a separate recorded
+    data directory. This is regardless of where they are originally situated
+    and done to keep the whole exercise contained in one directory.
+
+    Parameters
+    ----------
+    file_info : FileInformation
+        The FileInformation for the Session.
+    zip_filepath : Path
+        The destination path for the output `.zip` file.
+    active_answer_name : str
+        The name of the specific answer to include in the archive. It will be
+        renamed to 'answer' in the resulting zip structure.
+    include_root_textgrids : bool, optional
+        Whether to include root-level `.TextGrid` files, by default False.
+    include_wav_files : bool, optional
+        Whether to include wav files, by default True.
+    """
+    _logger.info('Packing an exercise.')
+    with ZipFile(file=zip_path, mode='w', compression=ZIP_DEFLATED) as output:
+        patkit_path = file_info.patkit_path
+        for item in patkit_path.rglob('*'):
+            # Only include files.
+            if not item.is_file():
+                continue
+
+            # Skip root-level TextGrids if they are not being included.
+            if (
+                not include_root_textgrids and
+                item.parent == file_info.patkit_path and
+                (item.suffix.lower() == SourceSuffix.TEXTGRID.lower())
+            ):
+                _logger.info('skipping: %s', str(item))
+                continue
+            else:
+                _logger.info('including: %s', str(item))
+
+            relative_path = item.relative_to(patkit_path)
+
+            # Process the exercise directory to filter answers
+            if relative_path.parts[0] == 'exercise':
+                if (
+                    len(relative_path.parts) >= 3 and
+                    relative_path.parts[1] == 'answers'
+                ):
+                    # Only include the targeted answer,
+                    # and rename it to 'answer'
+                    if relative_path.parts[2] == active_answer_name:
+                        new_parts = list(relative_path.parts)
+                        new_parts[2] = 'answer'
+                        arcname = Path(*new_parts)
+                        output.write(filename=item, arcname=arcname)
+                    continue  # Skip all other answer directories
+
+            # Write all other allowed files
+            output.write(filename=item, arcname=relative_path)
+
+        recorded_path = file_info.recorded_path
+        if recorded_path is not None:
+            for item in recorded_path.glob('*' + SourceSuffix.WAV):
+                if not item.is_file():
+                    continue
+
+                output.write(filename=item, arcname=item.name)
+
+        # TODO 0.24: verify that wavs or in future other data files are
+        # included
+
+
+def unpackage_exercise_from_zip(
+    zip_filepath: Path,
+    destination_directory: Path
+) -> None:
+    """
+    Extract a Patkit Exercise zip archive.
+
+    Parameters
+    ----------
+    zip_filepath : Path
+        The path to the `.zip` file to extract.
+    destination_directory : Path
+        The folder where the archive's contents should be unpacked.
+    """
+    with ZipFile(file=zip_filepath, mode='r') as zip_file:
+        zip_file.extractall(path=destination_directory)

{patkit-0.22.2 → patkit-0.22.3}/patkit/save_and_load/save.py

@@ -387,7 +387,12 @@ def save_session_meta(
     meta['format_version'] = PATKIT_FILE_VERSION
 
     parameters = OrderedDict()
-    parameters['patkit_path'] = str(session.patkit_path.resolve())
+    if session.file_info.is_top_level_object:
+        parameters['patkit_path'] = '.'
+    else:
+        # TODO 0.23.3: The next two should probably not be resolved, but this
+        # may break something else, so test.
+        parameters['patkit_path'] = str(session.patkit_path.resolve())
     parameters['recorded_path'] = str(session.recorded_path.resolve())
     parameters['datasource_name'] = session.metadata.data_source_name.value
     parameters['path_structure'] = session.config.path_structure.model_dump()

{patkit-0.22.2 → patkit-0.22.3}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "patkit"
-version = "0.22.2"
+version = "0.22.3"
 description = "Phonetic Analysis ToolKit: Tools for processing phonetic data"
 authors = [
   {email = "giuthas@gmail.com"},