Metadata-Version: 2.4
Name: pyjwt-rs
Version: 1.2.2
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: cryptography>=45.0.0
Requires-Dist: pyjwt>=2.12 ; extra == 'bench'
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Provides-Extra: bench
Provides-Extra: dev
License-File: LICENSE
Summary: Rust-backed PyJWT-compatible JWT library for Python
Keywords: jwt,pyjwt,rust,pyo3,openssl,json-web-token,authentication
Home-Page: https://github.com/StatPan/pyjwt-rs
Author: statpan
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/StatPan/pyjwt-rs/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/StatPan/pyjwt-rs
Project-URL: Issues, https://github.com/StatPan/pyjwt-rs/issues
Project-URL: Repository, https://github.com/StatPan/pyjwt-rs

# pyjwt-rs

`jwt_rs`는 `PyJWT` 호환을 목표로 하는 Rust 기반 Python 확장 모듈입니다.

핵심 목표는 두 가지입니다.

- 같은 코드에 `import jwt_rs as jwt`만 바꿔서 동작할 것
- Rust 코어로 주요 공개키 JWT workload에서 `PyJWT`보다 더 빠를 것

## Current Status

현재 공개 표면은 `PyJWT` 스타일을 유지합니다.

- `encode(payload, key, algorithm="HS256", headers=None)`
- `decode(token, key, algorithms=None, options=None, audience=None, issuer=None, leeway=0)`
- `decode_complete(...)`
- `get_unverified_header(token)`
- `PyJWS`, `PyJWK`, algorithm registry

현재 지원 알고리즘:

- HMAC: `HS256`, `HS384`, `HS512`
- RSA: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`
- EC: `ES256`, `ES384`, `ES512`, `ES256K`
- `EdDSA`

테스트 상태:

- `324 passed`

품질 정책:

- 테스트는 hidden warning 없이 통과해야 합니다. CI는 `-W error` 기반 게이트를 사용합니다.
- 의도된 skip은 `.quality/pytest-allowlist.json`에 명시되어야 합니다.
- 릴리스/호환성 작업은 공개 GitHub issue와 milestone으로 추적합니다.
- 자세한 운영 정책은 [CONTRIBUTING.md](/home/statpan/workspace/pypi_lib/pyjwt-rs/CONTRIBUTING.md:1), 호환성 갭은 [COMPATIBILITY_CHECKLIST.md](/home/statpan/workspace/pypi_lib/pyjwt-rs/COMPATIBILITY_CHECKLIST.md:1) 에서 관리합니다.

## Usage

```python
import jwt_rs as jwt

token = jwt.encode({"sub": "alice"}, "secret", algorithm="HS256")
claims = jwt.decode(token, "secret", algorithms=["HS256"])
header = jwt.get_unverified_header(token)
```

## Performance

성능 목표는 `모든 경로 일괄 2배`가 아니라, 먼저 `실사용 공개키 경로`에서 `PyJWT`를 확실히 추월하는 것입니다.

아래 블록은 benchmark 스크립트로 자동 생성됩니다. 수동으로 적지 않습니다.

<!-- BENCHMARK:START -->
_Auto-generated from `scripts/benchmark_same_api.py` on `2026-04-21T07:14:04+00:00` using `--iterations 150 --warmup 20`._

현재 same-API benchmark 기준:

| Case | encode | decode | decode_complete |
| --- | ---: | ---: | ---: |
| `hs256` | `1.43x` | `2.10x` | `2.04x` |
| `rs256` | `59.10x` | `2.15x` | `2.13x` |
| `es256` | `3.12x` | `1.76x` | `1.81x` |
| `eddsa` | `1.59x` | `1.06x` | `1.06x` |

좋은 구간:
- `rs256.encode`: `jwt_rs`가 `PyJWT` 대비 `59.10x`
- `es256.encode`: `jwt_rs`가 `PyJWT` 대비 `3.12x`
- `es256.decode`: `jwt_rs`가 `PyJWT` 대비 `1.76x`
- `eddsa.encode`: `jwt_rs`가 `PyJWT` 대비 `1.59x`

아직 미달인 구간:
- 현재 주요 추적 경로는 모두 `PyJWT` 이상입니다.

해석:
- `1.00x` 초과면 `jwt_rs`가 빠릅니다.
- `2.00x` 이상이면 README 목표인 `PyJWT 대비 2배`를 넘긴 것입니다.
- 현재 목표는 특히 공개키 경로에서 이 값을 끌어올리는 것입니다.
<!-- BENCHMARK:END -->

벤치 재현 명령:

```bash
uv run --with pyjwt python scripts/benchmark_same_api.py --iterations 150 --warmup 20
```

README 자동 갱신 명령:

```bash
uv run python scripts/update_readme_bench.py
```

## Development

```bash
source "$HOME/.cargo/env"
cd pyjwt-rs
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
uv run --with maturin maturin develop
uv run pytest -q
```

## Notes

- Python은 호환 인터페이스를 담당하고, 코어 sign/verify hot path는 Rust가 담당합니다.
- 현재 공개키 알고리즘 경로는 Rust 내부 OpenSSL backend를 사용합니다.
- `options={"verify_signature": False}` 경로는 별도 insecure decode 흐름을 사용합니다.
- 완전한 `PyJWT` parity를 목표로 하지만, 성능 최적화를 위해 내부 구현은 `PyJWT`와 다릅니다.
- 배포 버전과 `PyJWT` 호환 버전 구분은 [VERSIONING.md](/home/statpan/workspace/pypi_lib/pyjwt-rs/VERSIONING.md:1) 에 정리했습니다.

