Python HarmonyOS Compatibility Checker

intent

this skill validates whether Python packages work on HarmonyOS by downloading source code, scanning for Windows-specific dependencies, running the package's test suite via pytest, and generating detailed compatibility reports. use it before deploying Python libraries to HarmonyOS, migrating projects to HarmonyOS, or validating multiple packages in batch.

inputs

command-line parameters:

• package_names (positional args): one or more Python package names to check
• -w, --workers N (optional): number of parallel workers for batch checks, default 4
• --sequential (optional flag): run checks one at a time instead of in parallel, useful for debugging
• -r, --requirements FILE (optional): path to requirements.txt file, check all packages listed
• --keep-source (optional flag): retain downloaded source code in /tmp for manual inspection

external dependencies:

• Python 3.7+ with pip and pytest installed
• network access to GitHub and PyPI (for source downloads)
• /tmp directory with at least 500MB free space per concurrent worker
• optional: git binary if downloading from GitHub source repos

environment context:

• current working directory (reports written here)
• system timezone (reports use UTC+8/Beijing time)
• pytest configuration in current directory (setup.cfg, pytest.ini, or pyproject.toml if present)

procedure

1. parse input: read package names from command line args, -r requirements.txt file, or -w/--workers count. validate package names are non-empty strings. if both positional args and -r flag provided, combine both lists.

   output: list of package names, worker count (1 if --sequential), boolean flags for --keep-source

2. download source code: for each package, attempt GitHub source repo first (via git clone or API), fallback to PyPI source tarball (pip download --no-binary :all__ or direct PyPI fetch). save to /tmp/harmony_check_{package}_{timestamp}. if download fails, record error and skip to step 8 (report incompatible).

   output: local directory path containing source, or null if download failed

3. scan for Windows-specific dependencies: parse source files (*.py, setup.py, pyproject.toml) with regex patterns for these imports: win32api, win32con, win32gui, win32com, pythoncom, pywintypes, ctypes.windll, ctypes.WinDLL, winsound, msvcrt. also check dynamic imports via importlib.import_module('win32*') or string literals. if any detected, mark package incompatible and skip to step 8.

   output: list of detected Windows dependencies (empty if none found)

4. install package: run pip install {package} in isolated environment or current venv. if installation fails (missing binary, unmet dependencies), record error, skip to step 8 (mark incompatible).

   output: installed package path, or error message

5. discover test suite: attempt to locate pytest test files in installed package site-packages first (look for test_*.py or *_test.py in package root and tests/ subdirectory). if not found, search source directory from step 2. if no tests found, record warning but continue with empty test count (0 total tests, 0 passed, pass rate undefined).

   output: list of test file paths (may be empty)

6. run pytest: execute pytest -v --tb=short --import-mode=importlib {test_files} from a temporary working directory (/tmp/pytest_run_{timestamp}) to isolate imports. capture stdout and stderr. set 15-file limit and show progress every 5 files. parse output line-by-line for individual test results (PASSED, FAILED, ERROR, SKIPPED).

   output: raw pytest output, list of individual test results with status (passed/failed/error/skipped), error messages

7. classify failures: for each failed or error test, examine error message. categorize as: (a) environment issue (permission denied, cannot write to temp dir, file not found in /tmp), (b) code issue (ImportError, AttributeError, AssertionError, test logic failure), (c) platform issue (Windows API call, macOS-specific, X11 reference). count each category.

   output: pass count, fail count, environment issue count, code issue count, platform issue count

8. calculate status: compute metrics:

   • total tests = pass count + fail count + code issue count + platform issue count (exclude environment issues from total)
   • valid pass rate = pass count / (pass count + fail count + code issue count + platform issue count), or 0 if denominator is 0
   • status: if windows deps detected OR total tests > 0 and valid pass rate < 50% OR install failed, mark incompatible; else if valid pass rate 50-79%, mark partial; else if pass rate >= 80%, mark compatible

   output: status (compatible/partial/incompatible), pass rate percentage, metric counts

9. generate reports: write two files to current working directory:

   • compatibility_report_{package}_{timestamp}.md: human-readable markdown with package name, version, status, summary metrics, per-test results, detected Windows deps, and recommendations
   • compatibility_report_{package}_{timestamp}.json: machine-readable JSON with package, version, status, total_tests, passed, failed, environment_issues, code_issues, platform_issues, pass_rate, windows_deps, test_details (array of {name, status, error_message})

   output: file paths created

10. cleanup: if --keep-source flag not set, delete /tmp/harmony_check_{package}_{timestamp} directory. always delete /tmp/pytest_run_{timestamp} after report generation.

output: none (side effect: disk cleanup)

decision points

if download fails (step 2): mark package incompatible, record download error in report, skip to step 8. do not attempt install or testing.

if Windows dependencies detected (step 3): immediately mark incompatible, skip steps 4-7, jump to step 8. no further testing needed.

if package installation fails (step 4): mark incompatible, record install error, skip steps 5-6, jump to step 8.

if no test files found (step 5): log warning, continue to step 6 with empty test list. pytest will run with no test discovery and return 0 tests. final metrics will show 0 total, 0 passed, undefined pass rate. mark as incompatible due to insufficient test coverage data (cannot validate).

if pytest execution times out (step 6): after 5 minutes per package, kill process, record timeout error, treat as code failure. count timeout as 1 failed test.

if valid pass rate cannot be calculated (zero denominator in step 8): assign pass_rate as null, status as incompatible (insufficient data).

if environment issue count > 0 (step 7): exclude these from total test count when computing valid pass rate. report environment issues separately from code issues in output so user can distinguish transient failures from real incompatibilities.

if running in parallel mode with worker failures: if a single worker crashes, log error and continue with other workers. collect all results and merge into single summary report or separate per-package reports depending on batch size.

output contract

file locations:

• compatibility_report_{package_name}_{YYYYMMDD_HHMMSS_UTC+8}.md (markdown report)
• compatibility_report_{package_name}_{YYYYMMDD_HHMMSS_UTC+8}.json (json report)

both files written to current working directory (pwd).

markdown format:

# Compatibility Report: {package} v{version}

## Status
✅ Compatible | ⚠️ Partial | ❌ Incompatible

## Summary
- Pass Rate: X%
- Total Tests: N | Passed: M | Failed: K
- Valid Pass Rate: Y% (excludes environment issues)
- Windows Dependencies: [list or none]

## Test Results
[table or list of individual test outcomes]

## Environment Issues
[list of permission/temp dir errors if any]

## Recommendations
[actionable next steps based on failures]

json format:

{
  "package": "string",
  "version": "string",
  "status": "compatible|partial|incompatible",
  "timestamp": "ISO8601_UTC+8",
  "metrics": {
    "total_tests": integer,
    "passed": integer,
    "failed": integer,
    "environment_issues": integer,
    "code_issues": integer,
    "platform_issues": integer,
    "pass_rate_percent": float or null
  },
  "windows_dependencies": [array of strings],
  "install_error": "string or null",
  "download_error": "string or null",
  "test_details": [
    {
      "test_name": "string",
      "status": "PASSED|FAILED|ERROR|SKIPPED",
      "error_message": "string or null",
      "issue_type": "environment|code|platform|none"
    }
  ]
}

outcome signal

skill succeeded if:

• markdown and json reports were written to current directory
• user can open .md file and see status, metrics, and test breakdown
• json file parses as valid JSON with all required fields
• status field clearly states compatible/partial/incompatible

skill failed if:

• no report files generated
• script exited with non-zero exit code
• error message in stderr indicates unhandled exception

user can verify by:

• ls -la compatibility_report_*.{md,json} in current directory
• cat compatibility_report_*.md to read human summary
• jq . compatibility_report_*.json to validate json and inspect metrics

known issues and edge cases

rate limiting: PyPI and GitHub may rate-limit large batch requests. if downloading 50+ packages in parallel with --workers 8, expect 429 errors on some packages. retry with --sequential or reduce worker count to 2-4.

auth expiry: if GitHub API token in env var expires mid-batch, subsequent downloads from private repos will fail. manually refresh token and re-run.

empty result sets: packages with zero tests will have pass_rate as null and status incompatible (no data to validate). this is correct behavior, not a failure.

network timeouts: source downloads may timeout on slow networks. default timeout 30 seconds per package. if behind corporate proxy, may need to configure pip with pip config set global.index-url https://....

pytest config conflicts: if package's pytest.ini conflicts with system pytest, use --import-mode=importlib to isolate. some packages may still fail due to fixture incompatibilities.

binary compilation failures: packages with C extensions (numpy, pandas) may fail to install if gcc/clang missing. error will be caught in step 4 and marked incompatible.

transient test failures: some tests pass/fail non-deterministically (network calls, file timing). run with multiple instances or use --sequential for stable baseline.

Windows module false positives: dynamic imports like getattr(module, 'win32api') may not be detected. always review --keep-source output manually for edge cases.