Add submodule for tools

[crnh]

Proposed change

Adds zospy.tools with base functionality and wrappers for tools.

1. Context manager for opening tools:

import zospy as zp
from zospy.functions.tools import open_tool

zos = zp.ZOS()
oss = zos.connect("extension")

with open_tool(oss, oss.Tools.OpenQuickFocus) as tool:
    tool.RunAndWaitForCompletion()

This context manager does 2 things:

1. It ensures no other tools are open. If another tool is already open, it closes it (if close_current is true) or otherwise raises an exception.
2. Close the tool after use, even if an exception occurred in the with block.

2. New tool wrapper class

BaseToolWrapper class with functionality similar to BaseAnalysisWrapper, but for tools.
Example for the Quick Focus tool:

@analysis_settings
class QuickFocusSettings:
    """Settings for the Quick Focus tool.

    Attributes
    ----------
    criterion : constants.Tools.General.QuickFocusCriterion | str
        The criterion to use for quick focusing. Defaults to 'SpotSizeRadial'.
    use_centroid : bool
        Reference all calculations to the image centroid rather than the chief ray. Defaults to True.
    """

    criterion: ZOSAPIConstant("Tools.General.QuickFocusCriterion") = Field(default="SpotSizeRadial")
    use_centroid: bool = Field(default=True)


class QuickFocus(BaseToolWrapper[None, QuickFocusSettings]):
    """Wrapper for the Quick Focus tool."""

    def __init__(
        self,
        *,
        criterion: str | constants.Tools.General.QuickFocusCriterion = "SpotSizeRadial",
        use_centroid: bool = True,
    ) -> None:
        """Initialize the Quick Focus tool.

        See Also
        --------
        QuickFocusSettings : Settings for the Quick Focus tool.
        """
        super().__init__(settings_kws=locals())

    def _get_tool_opener(self, oss) -> Callable[[], _ZOSAPI.Tools.General.IQuickFocus]:
        """Get a callable that opens the Quick Focus tool in OpticStudio and returns the tool object."""
        return oss.Tools.OpenQuickFocus

    def _run_tool(self, tool: _ZOSAPI.Tools.General.IQuickFocus) -> None:
        """Run the Quick Focus tool."""
        tool.Criterion = process_constant(constants.Tools.General.QuickFocusCriterion, self.settings.criterion)
        tool.UseCentroid = self.settings.use_centroid

        tool.RunAndWaitForCompletion()

For now, I chose to reuse the analysis_settings decorator because settings for tools and analyses behave the same.

Type of change

• Example (a notebook demonstrating how to use ZOSPy for a specific application)
• Bugfix (non-breaking change which fixes an issue)
• New analysis (a wrapper around an OpticStudio analysis)
• New feature (other than an analysis)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests
• Documentation (improvement of either the docstrings or the documentation website)

Additional information

• OpticStudio version: 25R1

Related issues

Checklist

• I have followed the contribution guidelines
• The code has been linted, formatted and tested (see the contribution guidelines).
• Local tests pass. Please fix any problems before opening a PR. If this is not possible, specify what doesn't work and why you can't fix it.
• I tested ZOSPy for all supported Python versions (hatch test -a).
• I added new tests for any features contributed, or updated existing tests.
• I updated CHANGELOG.md with my changes (except for refactorings and changes in the documentation).

If you updated an example:

• I executed all examples and verified that they run without errors (hatch run all-examples).

If you contributed an example:

• I contributed my example as a Jupyter notebook.

[Copilot]

Pull request overview

This PR introduces a small utility API in zospy.functions to manage OpticStudio “Tools” via a Python context manager, ensuring that tools are closed after use and optionally closing any already-open tool beforehand.

Changes:

• Added zospy.functions.tools.open_tool() context manager for opening/closing OpticStudio tools safely.
• Exposed the new tools submodule via zospy.functions.__init__.
• Added a dedicated test suite for open_tool behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
zospy/functions/tools.py	Adds the open_tool context manager for safe tool lifecycle management.
zospy/functions/__init__.py	Exposes the new tools functions submodule in the public zospy.functions API.
tests/functions/test_tools.py	Adds tests covering tool opening, closing, and exception-handling behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[crnh]

@jwmbeenakker @andibarg following the discussion in #225, I extended this PR with a wrapper class for tools. @andibarg you can check the QuickFocus tool wrapper for a basic implementation, and the corresponding tests to see how you can add unit tests for the batch ray trace tool.