Legacy Python tooling and metadata no longer match supported runtime

[tylerlong]

Problem

The repository's documented Python support, dependency declarations, packaging metadata, automation, examples, and local development instructions have drifted apart. Several elements are obsolete or materially stale, and a documented setup currently produces an end-of-life Python environment linked against unsupported LibreSSL.

This issue records the confirmed problems. It intentionally does not choose a remediation plan yet.

Confirmed findings

Python support and local environment

• The README claims support for Python 3.7 and newer, but Python 3.7, 3.8, and 3.9 are end-of-life.
• The runtime constraint websockets==15.* requires Python 3.9 or newer, so the advertised Python 3.7 support is already false.
• The package publishes no Requires-Python metadata, allowing installers to attempt unsupported interpreter versions.
• CI tests only Python 3.11, while documentation promises a much wider range.
• Following the current local setup resulted in Python 3.9.6 linked against LibreSSL 2.8.3. urllib3 v2 does not support LibreSSL, producing NotOpenSSLWarning during real SDK use.
• That local environment also contained pip 21.2.4 and setuptools 58.0.4.

Runtime and development dependencies

• observable==0.3.* pins 0.3.2 from 2017. The upstream project's latest release is 1.0.3 from 2018, so this dependency is stale and apparently dormant.
• websockets==15.* is behind the current 17.1 release by two major versions.
• discover==0.4.0, released in 2010, remains a development dependency even though test discovery is built into Python 3's standard-library unittest.
• pdoc==14.4.0 is pinned behind the current 16.0.0 release.
• Minimum constraints such as coverage>=4.3.1, coveralls>=1.1, and requests-mock>=1.2.0 are many years old and no longer describe meaningful tested dependency bounds.
• There is no committed lockfile, so development and CI dependency resolution changes over time.

Packaging and release metadata

• The project has no pyproject.toml or standardized [build-system] declaration.
• Package metadata is maintained only in executable setup.py code, including a hard-coded version and requirements loaded from a separate file.
• Published metadata omits an explicit supported-Python range and useful modern project metadata.
• Release automation uses stored PyPI username/password secrets through Twine rather than a credentialless trusted-publishing flow.

GitHub Actions

• All workflows use actions/checkout@v3 and actions/setup-python@v3; current releases are v6.
• Documentation deployment uses peaceiris/actions-gh-pages@v3; the current release is v4.
• Workflows manually create and activate another virtual environment after setup-python has already provisioned an isolated runner.
• The unit-test and release steps are named “Test with pytest” but execute unittest.
• The documentation workflow installs python-dotenv explicitly and then installs the development requirements that already include it.

Python examples and contributor documentation

• WebSocket demos use asyncio.get_event_loop().run_until_complete(). On Python 3.14, get_event_loop() raises when no current event loop exists; top-level applications should use asyncio.run().
• Contributor notes instruct users to copy .env.sample, but that file does not exist.
• Contributor notes claim a subscription test requires credentials, but the repository currently has no subscription test.
• The README SMS example compares a string with is instead of == and calls time.sleep() without importing time.
• Documentation alternates among python, python3, pip, and pip3 without defining one reproducible environment workflow.

Impact

• New contributors can reproduce an unsupported TLS/Python environment by following repository guidance.
• The published compatibility promise is not enforced by package metadata or CI.
• Builds and tests are not reproducible across time or machines.
• Old actions and dependencies increase maintenance and compatibility risk.
• Some documented demos and examples fail on currently supported Python versions.

Planning boundary

A complete remediation plan, supported Python range, dependency upgrade policy, packaging backend, CI matrix, and release authentication approach still need to be decided. No implementation is authorized by this issue alone.

References

• Python version status: https://devguide.python.org/versions/
• urllib3 v2 migration guidance: https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html
• PyPA setup.py modernization guidance: https://packaging.python.org/en/latest/guides/modernize-setup-py-project/
• uv project documentation: https://docs.astral.sh/uv/guides/projects/

[tylerlong]

Candidate direction: full uv modernization

This is a candidate modernization shape for later discussion, not an approved implementation plan.

1. Define the supported Python contract

• Select one minimum supported CPython version. Python 3.11 is the natural baseline because current CI already uses it and it remains security-supported.
• Declare the supported range in project.requires-python.
• Test the minimum and current stable Python versions in CI rather than promising untested versions.
• Add a .python-version for the default contributor interpreter while retaining the package's broader declared range.
• Use uv-managed Python locally so contributors do not depend on the macOS system interpreter or LibreSSL.

2. Make pyproject.toml authoritative

• Add standardized [build-system] and [project] metadata.
• Initially retain setuptools as the build backend to avoid combining a metadata migration with a package-layout or backend migration.
• Move the package name, version, description, README, author, license, URLs, supported Python range, classifiers, and runtime dependencies into standardized metadata.
• Preserve the existing import package and distribution contents.
• Remove setup.py, setup.cfg, MANIFEST.in, and runtime requirements.txt only after wheel and source-distribution parity is proven.

3. Adopt uv dependency management

• Put runtime dependencies in [project.dependencies].
• Put test, coverage, documentation, build, and publishing tools in appropriate dependency groups.
• Commit uv.lock for reproducible development and CI environments; do not expose exact lock versions as restrictive runtime requirements for SDK consumers.
• Use uv sync --locked for setup and uv run for repository commands.
• Remove the obsolete discover dependency.
• Evaluate observable deliberately: verify upgrade compatibility and maintenance status before choosing upgrade, replacement, or retention.
• Upgrade websockets and pdoc only with focused compatibility checks.
• Refresh the remaining dependency constraints based on the supported Python range and actual tested versions.

4. Standardize developer commands

Target workflow:

uv sync --locked
uv run coverage run -m unittest discover . --pattern '*test.py'
uv run coverage report
uv run pdoc --output ./docs ./ringcentral
uv build --no-sources

Document uv installation, environment recreation, dependency updates, tests, demos, documentation, and package builds. Remove manual activation as a required step; it may remain optional for contributors who prefer it.

5. Modernize CI

• Replace manual Python, venv, and pip setup with the official astral-sh/setup-uv action.
• Use uv sync --locked and uv run consistently.
• Test at least the minimum and newest supported Python versions.
• Upgrade GitHub actions from the v3 generations and pin third-party actions according to the repository's chosen security policy.
• Upgrade or replace the GitHub Pages deployment action.
• Keep deterministic unit tests in CI; do not add credentialed live-server tests.

6. Modernize demos and documentation

• Replace top-level get_event_loop().run_until_complete() calls with asyncio.run().
• Repair the SMS example and other executable snippets.
• Either add a safe .env.sample containing names only or stop instructing users to copy one.
• Align README, contributor notes, package metadata, and CI around the same Python support and command contract.
• Correct stale references to pytest and nonexistent credentialed tests.

7. Modernize build and release

• Build both source and wheel artifacts with uv build --no-sources.
• Inspect artifact contents and metadata and install the wheel in a clean environment before changing release automation.
• Keep the existing upload mechanism during the first packaging migration if that reduces rollback risk.
• Consider a later switch to PyPI Trusted Publishing and uv publish as a separately verified release-security change.
• Preserve the current tag-driven version/release behavior unless an explicit versioning decision changes it.

8. Verification and migration order

A safe sequence would be:

1. Establish artifact and test baselines from the current project.
2. Add pyproject.toml with setuptools and prove artifact parity.
3. Add uv dependency groups and uv.lock; prove clean uv sync and tests.
4. Upgrade or remove dependencies one independently verifiable group at a time.
5. Update demos and contributor documentation.
6. Move CI and documentation deployment to uv.
7. Remove superseded packaging and requirements files.
8. Update release automation only after local and hosted build parity is confirmed.

Acceptance should include unit tests across the supported Python matrix, clean locked synchronization, documentation generation, source/wheel inspection, installation and import from the built wheel, and a release dry run that uploads nothing.