Metadata-Version: 2.4
Name: canary-wm
Version: 26.9.2
Summary: canary: application testing with Python
Author: Tim Fuller, Others (See AUTHORS)
License: Copyright 2025 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms
        of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.
        
        The MIT License (MIT)
        
        Copyright (c) 2025 National Technology & Engineering Solutions of Sandia, LCC (NTESS)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
        associated documentation files (the "Software"), to deal in the Software without restriction,
        including without limitation the rights to use, copy, modify, merge, publish, distribute,
        sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or
        substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
        NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
        DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
        OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Documentation, https://canary-wm.readthedocs.io/en/production/
Project-URL: Issues, https://github.com/sandialabs/canary/issues
Project-URL: Repository, https://github.com/sandialabs/canary
Keywords: test,unittest
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: hpc-connect>=26.9.1
Requires-Dist: pluggy>=1.5
Requires-Dist: psutil
Requires-Dist: pyyaml
Requires-Dist: schema
Requires-Dist: rich
Requires-Dist: typing_extensions
Provides-Extra: dev
Requires-Dist: coverage; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pydata-sphinx-theme; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-design; extra == "dev"
Requires-Dist: xmlschema; extra == "dev"
Provides-Extra: requests
Requires-Dist: requests; extra == "requests"
Dynamic: license-file

# CANARY

`canary` is a Python package for defining, scheduling, and executing jobs across a wide range of computing environments, from developer laptops to large-scale HPC systems.

- **Documentation:** https://canary-wm.readthedocs.io


Originally developed for application testing, `canary` has evolved into a general-purpose workflow execution framework. Today it is used to automate software testing, manage analysis workflows, execute computational pipelines, and coordinate collections of dependent jobs.


`canary` is inspired by `vvtest` and retains its strengths in scalable test execution while providing a flexible foundation for broader workflow automation. Built on `pluggy`, `canary` uses a plugin-based architecture for job discovery and execution. Common plugins support Python-based job definitions in `.pyt` and `.vvt` files, while others provide integration with frameworks such as CMake/CTest. Given one or more filesystem paths, `canary` recursively discovers job definitions, constructs the execution graph, schedules work according to available resources and dependencies, executes jobs, and reports results.


Testing remains a primary use case, but it is no longer the defining purpose of the project. A `canary` job may represent a software test, simulation, data-processing stage, analysis task, validation check, or any other executable unit of work.


`canary` offers several advantages:


**Scalable Execution**: Hierarchical parallelism enables efficient utilization of available resources, allowing large collections of jobs to execute concurrently across diverse hardware platforms.


**Workflow and Testing**: The same framework supports both automated software testing and general workflow orchestration, reducing the need for separate tools.


**Python-Based Definitions**: Python-based plugins provide access to the full Python ecosystem while enabling concise and expressive workflow descriptions.


**Integration**: `canary` integrates with common development and automation tools such as CMake, CDash, and GitLab, simplifying testing and continuous integration workflows.


**Extensibility**: A plugin architecture allows users to customize discovery, scheduling, execution, reporting, job-definition formats, and other aspects of a `canary` session.


## Requirements

Python 3.10+


## Install

`canary` is distributed as a Python package and is most easily installed using `pip` (or another compatible package manager).


To install the latest production release:

```console
python3 -m pip install canary-wm
```


To install the latest development version:

```console
python3 -m pip install "canary-wm@git+ssh://git@github.com/sandialabs/canary"
```


> **NOTE:** Installing from the main development branch may depend on floating git references in one or more dependencies. For stable installations, use a published release.


## Developers

For developers wishing to modify or contribute to `canary`, install in editable mode:

```console
python3 -m pip install -e git+https://github.com/sandialabs/canary#egg=canary-wm[dev]
```


This places a working copy of the source in your Python distribution's `$prefix/src` directory, allowing changes to become immediately visible to the interpreter.


Alternatively:

```console
git clone git@github.com:sandialabs/canary
cd canary
python3 -m pip install --editable .[dev]
```


To format code and run `canary`'s internal test suite:

```console
canary check
```


## License

Canary is distributed under the terms of the MIT license. See `LICENSE` and `COPYRIGHT` for details.


SPDX-License-Identifier: MIT


SCR#:3170.0
