nxdk-pgraph-test-runner 0.0.1__tar.gz

nxdk_pgraph_test_runner-0.0.1/.github/workflows/build.yml

@@ -0,0 +1,107 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '.github/**'
+      - '!.github/workflows/**'
+  pull_request:
+    paths-ignore:
+      - '.github/**'
+      - '!.github/workflows/**'
+      - 'README.md'
+  release:
+    types: [ published ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  select-python-version-for-publishing:
+    runs-on: ubuntu-latest
+    outputs:
+      python-version: ${{ steps.select-version.outputs.version }}
+    steps:
+      - id: select-version
+        run: echo "version=3.11" >> $GITHUB_OUTPUT
+
+  Build:
+    needs: [ select-python-version-for-publishing ]
+    name: Build source and wheel distributions
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: [ "3.11", "3.12", "3.13" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Hatch
+        uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
+
+      - name: Hatch fmt and type check
+        run: |
+          hatch fmt --check
+          hatch run types:check
+
+      - name: Build sdist and wheel
+        run: |
+          hatch build
+
+      - name: Test
+        run: |
+          hatch test
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version == needs.select-python-version-for-publishing.outputs.python-version
+        with:
+          name: source
+          path: dist/*.tar.gz
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version == needs.select-python-version-for-publishing.outputs.python-version
+        with:
+          name: wheels
+          path: dist/*.whl
+
+  Publish:
+    needs: [ Build, select-python-version-for-publishing ]
+    name: Publish distribution to PyPi
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: source
+          path: dist
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: github.event.release.prerelease
+        with:
+          user: __token__
+          password: ${{ secrets.TESTPYPI_API_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: github.event.release.prerelease == false
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

nxdk_pgraph_test_runner-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+
+__pycache__/
+*.pyc
+
+dist/
+
+.venv-mypy/
+venv/
+
+.work/
+results/
+
+.idea/

nxdk_pgraph_test_runner-0.0.1/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Erik Abair <erik.abair@bearbrains.work>
+
+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.

nxdk_pgraph_test_runner-0.0.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: nxdk-pgraph-test-runner
+Version: 0.0.1
+Summary: Executes and captures the results of https://github.com/abaire/nxdk_pgraph_tests in an emulator
+Project-URL: Documentation, https://github.com/abaire/nxdk-pgraph-test-runner#readme
+Project-URL: Issues, https://github.com/abaire/nxdk-pgraph-test-runner/issues
+Project-URL: Source, https://github.com/abaire/nxdk-pgraph-test-runner
+Author-email: Erik Abair <erik.abair@bearbrains.work>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: nv2a,pgraph,xbox,xemu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.11
+Requires-Dist: docker~=7.1.0
+Requires-Dist: ifaddr~=0.2.0
+Requires-Dist: mergedeep~=1.3.4
+Requires-Dist: platformdirs~=4.3.6
+Requires-Dist: pyfatx~=0.0.7
+Requires-Dist: pyftpdlib~=2.0.1
+Requires-Dist: tomli-w~=1.2.0
+Description-Content-Type: text/markdown
+
+# nxdk-pgraph-test-runner
+
+[![PyPI - Version](https://img.shields.io/pypi/v/nxdk-pgraph-test-runner.svg)](https://pypi.org/project/nxdk-pgraph-test-runner)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nxdk-pgraph-test-runner.svg)](https://pypi.org/project/nxdk-pgraph-test-runner)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [License](#license)
+
+## Purpose
+
+This test harness utilizes
+the [nxdk_pgraph_tests](https://github.com/abaire/nxdk_pgraph_tests) project to
+exercise the NV2A 3D accelerator on the original Microsoft Xbox. The runner is
+intended to be used with an emulator (e.g., [xemu](https://xemu.app)) and is
+able to detect and recover from crashes.
+
+## Installation
+
+### Prerequisites
+
+* Docker - required
+* An xbox emulator (e.g., [xemu](https://xemu.app)) - required
+
+### pip installation
+
+```console
+# Optionally create a virtual env
+#   pip -m venv .venv
+#   source .venv/bin/activate
+
+pip install nxdk-pgraph-test-runner
+
+nxdk-pgraph-test-runner --help
+```
+
+## Configuration
+
+A default config may be generated by running the `nxdk-pgraph-test-runner`
+command.
+
+### Emulator command line
+
+`"emulator_command = /path/to/emulator {ISO}"`
+
+The command may utilize the following macros:
+
+* `{ISO}` - Replaced with the path to the `nxdk_pgraph_tests.iso` xiso file.
+
+### Example invocation
+
+This is a sample invocation that will run xemu against a previously downloaded
+nxdk_pgraph_tests iso. It will create a `results` directory with the results of
+the tests.
+
+```shell
+nxdk-pgraph-test-runner \
+    --override-ftp-ip 10.0.2.2 \
+    --iso-path ~/nxdk_pgraph_tests_xiso.iso \
+    --emulator-command "/path/to/xemu -dvd_path \"{ISO}\"" \
+    -I lo0
+```
+
+This assumes that xemu is configured to use NAT networking, so the IP reported
+to the pgraph tester is set to the qemu `10.0.2.2` host address and the loopback
+interface (-I `lo0`) is used.
+
+## License
+
+`nxdk-pgraph-test-runner` is distributed under the terms of
+the [MIT](https://spdx.org/licenses/MIT.html) license.

nxdk_pgraph_test_runner-0.0.1/README.md

@@ -0,0 +1,75 @@
+# nxdk-pgraph-test-runner
+
+[![PyPI - Version](https://img.shields.io/pypi/v/nxdk-pgraph-test-runner.svg)](https://pypi.org/project/nxdk-pgraph-test-runner)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nxdk-pgraph-test-runner.svg)](https://pypi.org/project/nxdk-pgraph-test-runner)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [License](#license)
+
+## Purpose
+
+This test harness utilizes
+the [nxdk_pgraph_tests](https://github.com/abaire/nxdk_pgraph_tests) project to
+exercise the NV2A 3D accelerator on the original Microsoft Xbox. The runner is
+intended to be used with an emulator (e.g., [xemu](https://xemu.app)) and is
+able to detect and recover from crashes.
+
+## Installation
+
+### Prerequisites
+
+* Docker - required
+* An xbox emulator (e.g., [xemu](https://xemu.app)) - required
+
+### pip installation
+
+```console
+# Optionally create a virtual env
+#   pip -m venv .venv
+#   source .venv/bin/activate
+
+pip install nxdk-pgraph-test-runner
+
+nxdk-pgraph-test-runner --help
+```
+
+## Configuration
+
+A default config may be generated by running the `nxdk-pgraph-test-runner`
+command.
+
+### Emulator command line
+
+`"emulator_command = /path/to/emulator {ISO}"`
+
+The command may utilize the following macros:
+
+* `{ISO}` - Replaced with the path to the `nxdk_pgraph_tests.iso` xiso file.
+
+### Example invocation
+
+This is a sample invocation that will run xemu against a previously downloaded
+nxdk_pgraph_tests iso. It will create a `results` directory with the results of
+the tests.
+
+```shell
+nxdk-pgraph-test-runner \
+    --override-ftp-ip 10.0.2.2 \
+    --iso-path ~/nxdk_pgraph_tests_xiso.iso \
+    --emulator-command "/path/to/xemu -dvd_path \"{ISO}\"" \
+    -I lo0
+```
+
+This assumes that xemu is configured to use NAT networking, so the IP reported
+to the pgraph tester is set to the qemu `10.0.2.2` host address and the loopback
+interface (-I `lo0`) is used.
+
+## License
+
+`nxdk-pgraph-test-runner` is distributed under the terms of
+the [MIT](https://spdx.org/licenses/MIT.html) license.

nxdk_pgraph_test_runner-0.0.1/githooks/pre-commit

@@ -0,0 +1,76 @@
+#!/bin/bash
+#
+# To enable this hook, rename this file to "pre-commit" and copy into the
+# ../.git/hooks directory.
+
+
+function check_no_diffmarkers_or_whitespace_errors {
+  # If there are whitespace errors, print the offending file names and fail.
+  set -e
+  git diff-index --check --cached "${1}" --
+  set +e
+}
+
+
+function reformat {
+  # Reformat the files in-place and re-add any that were changed.
+  #
+  # Note that this has the side effect of incorporating changes to staged files
+  # that were not themselves staged. E.g., if you edit a file, `git add`, then
+  # edit some more, then commit, all of the changes will be committed, not just
+  # the staged ones. Depending on typical workflows it might be better to do
+  # something more complicated here, or to just have the hook fail instead of
+  # perform an in-place fix.
+  local files_to_format="$(echo "${changed_python_filenames}" | grep -v '3rdparty')"
+  if [[ -n "${files_to_format}" ]]; then
+    hatch fmt
+    hatch run types:check
+
+    echo "${files_to_format}" | xargs git add
+  fi
+}
+
+function check_no_donotsubmit {
+  local filenames="$1"
+
+  if [[ -z "${filenames}" ]]; then
+    return
+  fi
+
+  set +e
+  output="$(grep -H -ni 'DONOTSUBMIT' -- "$1" 2>/dev/null)"
+  found=$?
+  set -e
+
+  if [[ $found -eq 0 ]]; then
+    echo "${output}"
+    echo "DONOTSUBMIT tag found, aborting"
+    exit 1
+  fi
+}
+
+
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  against=HEAD
+else
+  # Initial commit: diff against an empty tree object
+  against=$(git hash-object -t tree /dev/null)
+fi
+
+# Redirect output to stderr.
+exec 1>&2
+
+
+added_and_modified_filenames="$(git diff --cached --name-only --diff-filter=d)"
+changed_python_filenames="$(echo "${added_and_modified_filenames}" | \
+                            grep -E '.*\.py$')"
+
+
+# Allow blank line at EOF.
+git config --local core.whitespace -blank-at-eof
+
+reformat
+
+check_no_donotsubmit "${changed_python_filenames}"
+check_no_diffmarkers_or_whitespace_errors "${against}"
+

nxdk_pgraph_test_runner-0.0.1/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nxdk-pgraph-test-runner"
+dynamic = ["version"]
+description = 'Executes and captures the results of https://github.com/abaire/nxdk_pgraph_tests in an emulator'
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["xemu", "nv2a", "xbox", "pgraph"]
+authors = [
+  { name = "Erik Abair", email = "erik.abair@bearbrains.work" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "docker~=7.1.0",
+  "platformdirs~=4.3.6",
+  "tomli_w~=1.2.0",
+  "pyfatx~=0.0.7",
+  "ifaddr~=0.2.0",
+  "mergedeep~=1.3.4",
+  "pyftpdlib~=2.0.1",
+]
+
+[project.urls]
+Documentation = "https://github.com/abaire/nxdk-pgraph-test-runner#readme"
+Issues = "https://github.com/abaire/nxdk-pgraph-test-runner/issues"
+Source = "https://github.com/abaire/nxdk-pgraph-test-runner"
+
+[project.scripts]
+nxdk-pgraph-test-runner = "nxdk_pgraph_test_runner:run"
+
+[tool.hatch.version]
+path = "src/nxdk_pgraph_test_runner/__about__.py"
+
+[tool.hatch.envs.types]
+type = "virtual"
+path = ".venv-mypy"
+extra-dependencies = [
+  "pip",
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/nxdk_pgraph_test_runner tests}"
+
+[tool.mypy]
+disable_error_code = ["import-untyped", "import-not-found"]
+
+[tool.coverage.run]
+source_pkgs = ["nxdk_pgraph_test_runner", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/nxdk_pgraph_test_runner/__about__.py",
+]
+
+[tool.coverage.paths]
+nxdk_pgraph_test_runner = ["src/nxdk_pgraph_test_runner", "*/nxdk-pgraph-test-runner/src/nxdk_pgraph_test_runner"]
+tests = ["tests", "*/nxdk-pgraph-test-runner/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.hatch.envs.default]
+type = "virtual"
+path = "venv"
+
+[tool.hatch.envs.hatch-test]
+type = "virtual"
+path = "venv"
+extra-dependencies = [
+  "pytest",
+]

nxdk_pgraph_test_runner-0.0.1/src/nxdk_pgraph_test_runner/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Erik Abair <erik.abair@bearbrains.work>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.1"

nxdk_pgraph_test_runner-0.0.1/src/nxdk_pgraph_test_runner/__init__.py

@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2025-present Erik Abair <erik.abair@bearbrains.work>
+#
+# SPDX-License-Identifier: MIT
+
+# ruff: noqa: T201 `print` found
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+
+from platformdirs import user_config_dir
+
+from nxdk_pgraph_test_runner._config import Config
+from nxdk_pgraph_test_runner.runner import entrypoint
+
+logger = logging.getLogger(__name__)
+
+
+def run():
+    """Parses program arguments and executes the runner."""
+    default_config_path = os.path.join(user_config_dir("nxdk-pgraph-test-runner"), "config.toml")
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-c", "--config", help="Path to the runner config file.", default=default_config_path)
+    parser.add_argument(
+        "--emulator-commandline",
+        help=(
+            "String used to launch the Xbox emulator. A `${ISO}` parameter will be replaced with the path to the "
+            "tester xiso."
+        ),
+    )
+    parser.add_argument("--iso-path", help="Path to the nxdk_pgraph_tests.iso xiso file.")
+    parser.add_argument("--no-save-config", "-N", action="store_true", help="Do not update the config file.")
+    parser.add_argument(
+        "--override-ftp-ip",
+        help="Use the given IP instead of the local IP when configuring the pgraph runner for artifact reporting.",
+    )
+    parser.add_argument(
+        "--ftp-ip",
+        help="Bind the FTP server to the given local IP.",
+    )
+    parser.add_argument(
+        "--ftp-interface",
+        "-I",
+        help="Bind the FTP server to the given network interface (e.g., lo0).",
+    )
+    parser.add_argument(
+        "--xbox-artifact-path",
+        "-P",
+        default="e:/nxdk_pgraph_tests",
+        help="Xbox path into which test artifacts will be written",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        help="Enables verbose logging information",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        "-T",
+        help="Maximum period of time to execute the emulator before considering everything failed.",
+        type=int,
+    )
+    parser.add_argument(
+        "--work-dir",
+        "-W",
+        help="Host directory used to store temporary data",
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        help="Host directory used to store results of the runner",
+    )
+    parser.add_argument(
+        "--test-failure-retries",
+        "-r",
+        default=1,
+        help="Number of times to retry failed tests before considering them permanently failed",
+        type=int,
+    )
+    args = parser.parse_args()
+
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(level=log_level)
+
+    config = Config.load(args.config)
+    if not config:
+        print("Using default config")
+        config = Config()
+
+    if args.emulator_commandline:
+        config.set_emulator_command(args.emulator_commandline)
+    if args.iso_path:
+        config.iso_path = args.iso_path
+    if args.ftp_ip:
+        config.ftp_ip = args.ftp_ip
+    if args.ftp_interface:
+        config.ftp_preferred_interface = args.ftp_interface
+    if args.override_ftp_ip:
+        config.ftp_ip_override = args.override_ftp_ip
+    if args.timeout_seconds:
+        config.timeout_seconds = args.timeout_seconds
+    if args.work_dir:
+        config.set_work_dir = args.work_dir
+    if args.output_dir:
+        config.set_output_dir = args.output_dir
+    config.test_failure_retries = args.test_failure_retries
+    config.xbox_artifact_path = args.xbox_artifact_path
+
+    if not args.no_save_config:
+        logger.debug("Updating config file at %s", args.config)
+        config.store(args.config)
+
+    sys.exit(entrypoint(config))

nxdk_pgraph_test_runner-0.0.1/src/nxdk_pgraph_test_runner/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025-present Erik Abair <erik.abair@bearbrains.work>
+#
+# SPDX-License-Identifier: MIT
+
+from nxdk_pgraph_test_runner import run
+
+run()