PyPI Publishing Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The PyPI Publishing Pipeline for mlx-qwen3-asr is a rigorous, multi-stage process designed to ensure that only high-quality, benchmark-validated code reaches the Python Package Index. The pipeline encompasses versioning, strict quality gates (including linting, unit testing, and reference parity), build procedures using modern Python tooling (uv), and final distribution.
This pipeline is critical for maintaining the project's "Production-grade" status, ensuring that the standalone MLX reimplementation of Qwen3-ASR remains stable for Apple Silicon users.
Sources: CLAUDE.md:14-22, CLAUDE.md:214-227
Pipeline Workflow Overview
The publishing process follows a deterministic sequence of steps to move from local development to a public PyPI release.
The diagram shows the linear progression from versioning to final tagging.
Sources: CLAUDE.md:214-224
Core Components and Configuration
Metadata and Dependencies
The pipeline's configuration is primarily defined in pyproject.toml. It specifies the build backend (setuptools.build_meta) and defines the core dependencies required for the package to function on Apple Silicon.
| Category | Details |
|---|---|
| Package Name | mlx-qwen3-asr |
| Build System | setuptools >= 68, wheel |
| Required Python | >= 3.10 |
| Primary Deps | mlx >= 0.18.0, numpy, regex, huggingface-hub >= 0.20.0 |
| Optional Extras | aligner, diarize, mic, serve, dev, eval |
Sources: pyproject.toml:1-40
Single Source of Truth for Versioning
The project utilizes mlx_qwen3_asr/_version.py as the definitive source for the package version. This version is manually bumped at the start of the publishing pipeline.
# mlx_qwen3_asr/_version.py
__version__ = "0.3.5"
Sources: mlx_qwen3_asr/_version.py:1-4, CLAUDE.md:215
The Quality Gate
A central feature of the pipeline is the quality_gate.py script. Before any release, the developer must execute this gate to ensure no regressions have been introduced.
Gate Modes
The pipeline supports different levels of validation:
- Fast Mode: Standard checks including
rufffor linting,mypyfor type checking (targeting core modules), andpytestfor unit tests. - Release Mode: Comprehensive validation including performance benchmarks, streaming quality evaluation, and reference parity checks.
Sources: scripts/quality_gate.py:21-36, CLAUDE.md:216
Validation Logic
The run_gate function orchestrates several subprocesses to validate the repository state.
The flow shows how release mode extends the standard "fast" checks with deep architectural and performance validation.
Sources: scripts/quality_gate.py:539-722
Build and Distribution
Package Building
The pipeline uses uv build to generate the distribution artifacts. The resulting wheel is a pure Python wheel (py3-none-any). Developers are required to verify the wheel contains all 22 modules, py.typed markers, and assets like mel_filters.npz and korean_dict_jieba.dict.
Sources: CLAUDE.md:217-218, pyproject.toml:50-52
PyPI Upload
Distribution is handled via twine. The pipeline expects a PyPI token with scope limited to the mlx-qwen3-asr project.
uv build
uv tool run twine upload dist/*
Sources: CLAUDE.md:217-219
Post-Publishing Monitoring
Download Statistics
After publication, the project includes scripts/pypi_download_stats.py to monitor package visibility and adoption via the PyPIStats API. This tool can generate Markdown reports detailing recent snapshots and daily series summaries.
| Feature | Description |
|---|---|
| API Base | https://pypistats.org/api/packages |
| Lookback Window | Default 90 days |
| Breakdowns | Python major/minor version, System OS |
Sources: scripts/pypi_download_stats.py:20-25, scripts/pypi_download_stats.py:118-150
Documentation and Metadata Updates
The scripts/update_readme_stats.py script is used to keep the README.md synchronized with the actual state of the published code, updating metrics such as total test counts and lines of source code.
Sources: scripts/update_readme_stats.py:11-20, scripts/update_readme_stats.py:44-55
Conclusion
The PyPI Publishing Pipeline for mlx-qwen3-asr is designed for reliability and transparency. By enforcing strict "Correctness Invariants" through the quality_gate.py and utilizing modern build tools like uv, the pipeline ensures that Apple Silicon users receive a high-performance, validated speech recognition package.