# Competitive Analysis: PyForge vs Alternatives

Author: Abdulwahed Mansour

Honest assessment of PyForge's position relative to existing Rust-accelerated
Python libraries. For internal strategy — not marketing.

---

## 1. orjson — Fastest Python JSON Serializer

**What they do that we don't:**
- orjson serializes directly from Python objects to `bytes` in a single C call — no intermediate representation. Their hot path never allocates a Python dict; it writes UTF-8 bytes directly.
- They handle `datetime`, `date`, `time`, `uuid`, `Decimal`, `numpy`, `dataclass` natively at the C level, without going through Python's `__str__()` method.
- They support `OPT_SORT_KEYS`, `OPT_INDENT_2`, `OPT_NON_STR_KEYS` — output formatting options we don't offer.

**Where PyForge is better:**
- PyForge understands Django's field constraints (max_length, max_digits, decimal_places) and validates while serializing. orjson is a pure serializer — it doesn't validate.
- PyForge's `serialize_queryset_rows` batches entire querysets in one call. orjson serializes one object at a time.
- PyForge preserves Decimal precision by default (string output). orjson requires `OPT_SERIALIZE_NUMPY` flag for similar behavior.

**Where we're behind:**
- orjson is 2-3x faster than us on raw JSON serialization because they skip the intermediate `serde_json::Value` tree. We allocate a `Map<String, Value>` then convert to Python — they go directly to bytes.
- orjson has years of fuzzing, production hardening, and edge-case coverage that we lack.

**What it would take to close the gap:**
- Implement direct-to-bytes serialization (see IMPROVEMENTS.md #2). This is achievable but changes our API surface.
- orjson's speed advantage is most relevant for read-heavy APIs (list views). For write-heavy APIs (create/update), validation matters more than serialization — and we win there.

---

## 2. pydantic-core — Rust-Backed Python Validation

**What they do that we don't:**
- pydantic-core compiles a validation schema into a Rust `Validator` struct at model definition time. Our validation re-reads field constraints on every call.
- They support recursive models, discriminated unions, custom validators with Python callbacks — a full type system, not just field-level checks.
- Their error reporting is richer: each error carries a "location" path for nested structures (e.g., `["addresses", 0, "zip_code"]`).
- They have a "strict" vs "lax" mode for type coercion.

**Where PyForge is better:**
- PyForge is Django-native. pydantic-core requires defining separate Pydantic models that mirror your Django models — duplication. PyForge reads Django's `_meta` directly.
- PyForge's Rayon parallelism scales validation across CPU cores for large batches. pydantic-core validates sequentially.
- PyForge integrates with DRF serializers via a mixin — zero changes to existing code. pydantic requires rewriting your serializers.

**Where we're behind:**
- pydantic-core's compiled validator is fundamentally faster on a per-field basis because it eliminates dynamic dispatch. Our `match` on `DjangoFieldType` is slower.
- pydantic-core supports nested validation (JSON objects within fields). Our JSONField just passes through `serde_json::Value` without structure validation.
- pydantic-core has 3+ years of production use and extensive fuzzing.

**What it would take to close the gap:**
- Implement compiled validation (IMPROVEMENTS.md #1). Achievable in ~2 weeks.
- Nested JSON validation is a larger project — would need to define a schema DSL.

---

## 3. django-ninja — Fast Django REST API Framework

**What they do differently:**
- django-ninja uses Pydantic models for request/response validation, bypassing DRF's serializer layer entirely.
- They generate OpenAPI schemas from Pydantic type hints automatically.
- They use `orjson` for JSON encoding by default.

**Where PyForge is better:**
- PyForge works WITH existing DRF codebases. django-ninja requires rewriting your API layer.
- PyForge's mixin approach means adoption is incremental — you can accelerate one serializer at a time.
- For projects already on DRF (the vast majority of Django APIs), PyForge is the only option that doesn't require a rewrite.

**Where we're behind:**
- django-ninja's type-hint-driven approach provides better IDE support and auto-documentation.
- django-ninja + Pydantic is a more complete solution (validation + serialization + schema generation).

**What it would take to close the gap:**
- Add type stub generation (IMPROVEMENTS.md #5) for IDE support.
- We'll never match their schema generation — that's a different problem space. Our value is accelerating existing DRF, not replacing it.

---

## 4. Where PyForge Is Strictly Superior

**For Django projects that:**
1. Already use DRF and can't afford a rewrite → PyForge is the only option
2. Serve large list views (100+ records per response) → 4-8x speedup from Rust serialization
3. Process bulk form submissions → Rayon parallel validation scales linearly with cores
4. Use `DecimalField` heavily (finance, e-commerce) → guaranteed precision preservation
5. Run ASGI with async views → GIL-releasing bridge enables true concurrency

**No other library offers all five of these in a single drop-in package.**

---

## 5. Honest Assessment: Where We're Still Weak

| Area | Gap | Severity | Fix Effort |
|------|-----|----------|------------|
| Raw JSON speed | orjson is 2-3x faster | Medium | 2-3 weeks (direct-to-bytes) |
| Compiled validation | pydantic-core is faster per-field | Medium | 2 weeks |
| Nested validation | No JSONField structure checking | Low | 4+ weeks |
| Production hardening | No fuzzing, limited edge-case coverage | High | Ongoing |
| IDE support | No .pyi stubs | Low | 1 day |
| Schema generation | No OpenAPI support | Low | Not planned — different scope |

**Priority order for closing gaps:**
1. Production hardening (fuzzing, edge-case tests) — must happen before v1.0
2. Compiled validation — biggest single-item performance win
3. IDE support (.pyi stubs) — easy win for developer experience
4. Direct-to-bytes serialization — significant for read-heavy APIs
