Metadata-Version: 2.4
Name: winuvloop
Version: 0.2.3
Summary: Use uvloop on Linux/macOS and winloop on Windows through one small asyncio compatibility import.
Keywords: asyncio,event-loop,event-loop-policy,uvloop,winloop,asyncio-run,windows,linux,macos,cross-platform,asgi,performance
Author: Aviad Rozenhek
Author-email: Aviad Rozenhek <aviadr1@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Dist: uvloop>=0.22.1 ; platform_python_implementation == 'CPython' and sys_platform != 'win32'
Requires-Dist: winloop>=0.6.2 ; platform_python_implementation == 'CPython' and sys_platform == 'win32'
Requires-Python: >=3.8.1
Project-URL: Homepage, https://github.com/aviadr1/winuvloop
Project-URL: Documentation, https://github.com/aviadr1/winuvloop#readme
Project-URL: Repository, https://github.com/aviadr1/winuvloop.git
Project-URL: Issues, https://github.com/aviadr1/winuvloop/issues
Project-URL: Changelog, https://github.com/aviadr1/winuvloop/blob/main/CHANGELOG.md
Project-URL: Source: uvloop, https://github.com/MagicStack/uvloop
Project-URL: Source: winloop, https://github.com/Vizonex/Winloop
Description-Content-Type: text/markdown

# winuvloop

[![PyPI](https://img.shields.io/pypi/v/winuvloop.svg)](https://pypi.org/project/winuvloop/)
[![Python](https://img.shields.io/pypi/pyversions/winuvloop.svg)](https://pypi.org/project/winuvloop/)
[![Downloads](https://img.shields.io/pypi/dm/winuvloop.svg)](https://pypi.org/project/winuvloop/)
[![CI](https://github.com/aviadr1/winuvloop/actions/workflows/ci.yml/badge.svg)](https://github.com/aviadr1/winuvloop/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/winuvloop.svg)](https://github.com/aviadr1/winuvloop/blob/main/LICENSE)

`winuvloop` is a tiny cross-platform asyncio event loop selector for projects
that want one import to do the right thing on developer laptops, CI, and
production runners:

| Platform | Backend used by `winuvloop` |
| --- | --- |
| Windows | [`winloop`](https://github.com/Vizonex/Winloop) |
| Linux, macOS, other POSIX | [`uvloop`](https://github.com/MagicStack/uvloop) |

It is useful when the same Python application, example, benchmark, CLI, or
service should use a high-performance asyncio loop on both Windows and
Unix-like systems without duplicating platform checks at every entry point.

## Why This Exists

[`uvloop`](https://github.com/MagicStack/uvloop) is the established
high-performance asyncio event loop for Linux, macOS, and other POSIX
platforms. It is widely used for network-heavy asyncio workloads such as API
servers, proxies, websocket services, crawlers, and async database clients.

[`winloop`](https://github.com/Vizonex/Winloop) provides a uvloop-compatible
API for Windows, where `uvloop` itself is not the Windows backend.

`winuvloop` does not replace either upstream project, vendor their code, or
hide backend bugs. It gives you one import that chooses the right upstream
backend:

```python
import winuvloop


async def main() -> None:
    ...


winuvloop.run(main())
```

The wrapper stays deliberately small: platform detection, clear diagnostics,
common API re-exports, typing stubs, and platform-specific dependency markers.
Runtime behavior comes from the selected upstream backend.

## When To Use It

Use `winuvloop` when:

- your project supports both Windows and Linux/macOS
- examples or docs should stay platform-neutral
- your CLI or application wants the fastest available asyncio loop by default
- you want one dependency that resolves `uvloop` or `winloop` through platform
  markers
- you want to log or inspect which optimized backend was selected
- you maintain library examples that should work for both Unix and Windows
  users

Use the upstream packages directly when:

- your project only targets Linux/macOS: use `uvloop`
- your project only targets Windows: use `winloop`
- you need backend-specific APIs and do not want a selector layer
- you are debugging an upstream event-loop issue and need to remove wrappers

| Situation | Recommended dependency |
| --- | --- |
| Linux/macOS-only service | `uvloop` |
| Windows-only service | `winloop` |
| Cross-platform CLI, app, benchmark, or documentation | `winuvloop` |
| Backend-specific feature work or bug isolation | upstream backend directly |

## Installation

```bash
pip install winuvloop
```

With `uv`:

```bash
uv add winuvloop
```

`winuvloop` declares platform-specific dependencies. Installers resolve only
the backend needed for the current environment.

## Usage

Prefer `run()` for application entry points:

```python
import winuvloop


async def main() -> str:
    return "done"


result = winuvloop.run(main())
```

For frameworks or legacy code that expects a global event-loop policy, use
`install()`:

```python
import asyncio

import winuvloop


winuvloop.install()
asyncio.run(main())
```

You can inspect the selected backend for diagnostics and support logs:

```python
import winuvloop


print(winuvloop.backend_name())  # "uvloop" or "winloop"
print(winuvloop.backend_version())
print(winuvloop.__backend__)
print(winuvloop.backend().__name__)
```

The module re-exports the common backend API:

- `run`
- `install`
- `new_event_loop`
- `Loop`
- `EventLoopPolicy`
- `backend`
- `backend_name`
- `backend_version`

Backend-specific attributes are delegated to the selected upstream module.

For issue reports, include this diagnostic snippet:

```bash
python - <<'PY'
import platform
import winuvloop

print("python:", platform.python_version(), platform.python_implementation())
print("platform:", platform.platform())
print("backend:", winuvloop.backend_name(), winuvloop.backend_version())
PY
```

## Typing

`winuvloop` ships a `py.typed` marker and public API stubs for the selector
module. The runtime values remain direct aliases to the selected upstream
backend, so `winuvloop.Loop` is still `uvloop.Loop` on POSIX and `winloop.Loop`
on Windows.

## Compatibility

`winuvloop` targets CPython 3.8.1 and newer. The optimized backend packages are
native CPython packages, so PyPy and other Python implementations are not a
supported target for this selector.

| Environment | Status |
| --- | --- |
| CPython 3.8-3.14 | Supported by current upstream wheels |
| Linux/macOS | Uses `uvloop` |
| Windows | Uses `winloop` |
| PyPy | Not supported by the upstream native backends |
| Windows ARM64 | Supported when `winloop` publishes a matching wheel |
| Linux/macOS ARM64 | Supported when `uvloop` publishes a matching wheel |

If an upstream backend does not publish a wheel for a specific interpreter or
platform, installation may require local build tooling for that backend.

## Upstream Support Boundary

Report selector problems here when platform selection, dependency markers,
typing stubs, documentation, or packaging are wrong.

Report backend behavior problems upstream when the issue also reproduces after
importing the selected backend directly:

- `uvloop`: <https://github.com/MagicStack/uvloop/issues>
- `winloop`: <https://github.com/Vizonex/Winloop/issues>

This keeps backend fixes close to the projects that own event-loop internals
while keeping `winuvloop` focused on cross-platform ergonomics.

## Testing Strategy

CI runs on Linux, macOS, and Windows. It includes:

- lockfile validation with `uv lock --check`
- linting with `ruff`
- formatting checks with `ruff format --check`
- bytecode compilation checks for `src` and `tests`
- wrapper unit tests that mock both backends
- real backend smoke tests that call `winuvloop.run()` on the platform backend
- source distribution and wheel builds
- package metadata validation with `twine check`

This keeps the wrapper behavior fast to test while still proving that the
published backend dependencies are usable on each runner family.

## Development

This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management,
locking, and builds.

```bash
uv sync
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build
uv run twine check dist/*
```

## Release And Automation

Dependabot updates are grouped for upstream event loops, Python tooling, and
GitHub Actions. Dependabot PRs auto-merge after the CI workflow passes.

Releases are automatic:

1. Change `project.version` in `pyproject.toml`.
2. Merge to `main`.
3. After CI passes on `main`, GitHub Actions creates the missing `vX.Y.Z` tag.
4. GitHub Actions dispatches `release.yml` for that tag.
5. The release workflow smoke-tests Linux, macOS, and Windows, then builds,
   validates, publishes to PyPI, and creates a GitHub Release.

PyPI trusted publishing must be configured for the `release.yml` workflow and
the `pypi` environment for credential-free publishing. If the repository still
uses a `PYPI_API_TOKEN` secret, the release workflow can use that as a fallback.
Manual tag pushes with the `vX.Y.Z` format still run the same release workflow.

## License

MIT. See [LICENSE](LICENSE).
