Python SDK Alpha

[MaxMansfield]

---

name: Pull Request
about: Submit changes to the RTMS SDK

Description

This PR introduces significant improvements across multiple areas of the RTMS SDK:

🔧 Build System Enhancements

• N-API Multi-Version Support: Updated prebuild and upload commands to build and distribute both N-API v9 and v10 prebuilds for Node.js, ensuring compatibility with Node.js 20.3.0+ and 22.x LTS
• Dynamic Version Reading: Build scripts now read N-API versions directly from package.json (binary.napi_versions), eliminating hardcoded values and maintaining a single source of truth
• Architecture Constraints: Enforced proper architecture constraints (Linux: x64 only, Darwin: arm64 only) in prebuild and upload workflows

📚 Documentation Overhaul

• Fixed Outdated Version Requirements: Corrected all references to Node.js 18.17.0 → 20.3.0 and Python 3.8/3.9 → 3.10 across README.MD, CONTRIBUTING.md, and PUBLISHING.md
• Created Shared Documentation: Added docs/VERSION_REQUIREMENTS.md and docs/PLATFORM_SUPPORT.md as single sources of truth for version and platform information
• Eliminated Duplication: Removed duplicated version information across documentation files, with authoritative sources now referencing package.json and pyproject.toml
• Improved Maintainability: Future version updates now only require changes to package.json/pyproject.toml and the shared documentation files

🐍 Python SDK Improvements

• Version Alignment: Updated all Python documentation to reflect the minimum supported version (3.10+) and tested versions (3.10-3.13)
• Accurate CI Documentation: Fixed PUBLISHING.md to correctly describe the Python test matrix (3.10-3.13) instead of referencing outdated Python 3.9

🟢 Node.js SDK Improvements

• Correct Version Requirements: All documentation now accurately reflects Node.js 20.3.0 as the minimum version (required for N-API v9 support)
• EOL Alignment: Properly documented that Node.js 18.x (EOL April 2025) is no longer supported
• Multi-Version Prebuild Distribution: Both N-API v9 and v10 prebuilds are now created and uploaded to GitHub releases

Related Issues

This PR addresses issues related to:

• Incomplete N-API version coverage in prebuild distribution
• Outdated documentation referencing unsupported Node.js and Python versions
• Documentation duplication and maintenance challenges
• Build system improvements for better version management

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Tests (adding or improving tests)
• Build changes

Affected Components

• Core C++ implementation
• Node.js bindings (prebuild/upload workflow)
• Python bindings (documentation)
• Go bindings
• Build system
• Documentation
• Examples
• Other (please specify)

Changes Made

Build System (scripts/common/build.js)

1. Added imports: fs, join, getProjectRoot for reading package.json
2. Created getNapiVersions() function: Dynamically reads N-API versions from package.json → binary.napi_versions field
3. Updated prebuildNodeJS() function:
   • Now loops through all N-API versions (9, 10)
   • Enforces architecture constraints (x64 for Linux, arm64 for Darwin)
   • Dynamic log messages based on actual versions
4. Updated uploadNodeJS() function:
   • Uploads all N-API versions (9, 10)
   • Maintains same architecture constraints
   • Dynamic log messages

Documentation Files

README.MD (8 locations updated):

• Line 385: Prerequisites section - Node.js 18.17.0 → 20.3.0
• Line 386: Prerequisites section - Python 3.8+ → 3.10+
• Line 483: Troubleshooting - Root cause updated to < 20.3.0
• Line 490: Troubleshooting - Upgrade instructions updated
• Lines 497-498: Troubleshooting - Removed Node.js 18 install instructions
• Line 509: Troubleshooting - Prevention updated to 20.3.0

CONTRIBUTING.md (3 locations updated):

• Line 26: Prerequisites - Removed Node.js 18.x, now lists only 20.x and 22.x
• Line 27: Prerequisites - Python 3.8 → 3.10
• Line 118: Coding standards - Python 3.8+ → 3.10+

PUBLISHING.md (2 locations updated):

• Line 112: CI/CD workflow description - Python 3.9 → 3.10-3.13 matrix (accurate)
• Lines 8-9: Overview - Version numbers now reference package.json/pyproject.toml instead of hardcoded values

New Documentation Files Created:

• docs/VERSION_REQUIREMENTS.md: Single source of truth for Node.js and Python version requirements, EOL policy, N-API versions, upgrade instructions, and troubleshooting
• docs/PLATFORM_SUPPORT.md: Comprehensive platform and architecture documentation, supported platforms, requirements by platform, cross-platform building, and troubleshooting

Testing Performed

Build System Testing

• Verified getNapiVersions() correctly reads from package.json
• Confirmed NAPI_VERSIONS is populated with [9, 10]
• Tested that prebuild commands reference both N-API versions
• Validated that upload commands loop through all versions

Documentation Verification

• Searched all documentation files for outdated version references (18.17.0, 3.8, 3.9)
• Confirmed all version references now accurate (20.3.0, 3.10+)
• Verified new documentation files are properly linked and formatted
• Checked that package.json and pyproject.toml remain authoritative sources

Expected Behavior

• Running npm run prebuild:js:linux will create prebuilds for both N-API v9 and v10 (linux-x64)
• Running npm run upload:js:linux will upload both N-API v9 and v10 to GitHub releases
• Running npm run prebuild:js:darwin will create prebuilds for both N-API v9 and v10 (darwin-arm64)
• Running npm run upload:js:darwin will upload both N-API v9 and v10 to GitHub releases

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works (N/A - build system and documentation changes)
• New and existing unit tests pass locally with my changes (To be verified)
• Any dependent changes have been merged and published

Additional Context

Why These Changes Matter

N-API Multi-Version Support: Previously, only N-API v10 prebuilds were being uploaded, leaving Node.js 20.3.0-20.x users without optimized prebuilds. This PR ensures both N-API v9 (Node.js 20.3.0+) and N-API v10 (Node.js 22+) users get prebuilt binaries for faster installation.

Documentation Accuracy: Outdated version references (Node.js 18.17.0, Python 3.8/3.9) were causing confusion and potentially leading developers to use unsupported versions. All documentation now reflects the actual minimum requirements from package.json and pyproject.toml.

Single Source of Truth: By creating shared documentation files and having build scripts read from package.json, future version updates will be easier to maintain and less error-prone.

EOL Policy Alignment: The 6-month post-EOL support policy is now clearly documented and consistently applied across all materials.

Breaking Changes

None - These changes are entirely internal to the build/documentation system and do not affect the public API or existing installations.

Migration Guide

For Users: No action required. New installations will automatically benefit from the improved prebuild availability.

For Maintainers:

• When updating supported Node.js or Python versions, update package.json engines/binary fields and pyproject.toml requires-python field
• Update the shared documentation in docs/VERSION_REQUIREMENTS.md to reflect any policy changes
• The build scripts will automatically pick up N-API version changes from package.json

Future Enhancements

Consider adding:

• Automated validation script to ensure documentation versions match package.json/pyproject.toml
• Pre-commit hook to prevent version reference inconsistencies
• Badge automation to display current version requirements in README