Core & versions¶
The top-level wowlib module holds the shared vocabulary — client versions and
expansions, locales, file keys, and the exception hierarchy — used across the
filesystem and format layers.
Reading and writing World of Warcraft client files: client filesystem access (MPQ and CASC), listfile databases, and a project-directory overlay for modding.
Bases: IntEnum
Which product line a client belongs to. Retail is the ordinary progression client, where the version number also tells you the engine generation. Every other flavor is a MODERN-engine client wearing a legacy version number: WoW Classic Era 1.15.9 is a Midnight-era client, Cataclysm Classic 4.4.2 a War Within-era one. Their file formats follow the build number, not the version tuple — see ClientVersion.format_lineage.
The enumerator also names the client's default TACT product code ('wow', 'wow_classic', 'wow_classic_era', 'wow_anniversary'); products outside these four (PTR, beta, 'wow_classic_titan') pick the closest flavor and pass their exact code to the filesystem explicitly.
ClientVersion(major: int = 0, minor: int = 0, patch: int = 0, build: int = 0, flavor: ClientFlavor | None = ...)
A full client version tuple (major.minor.patch, build) plus the product flavor it came from. Determines which storage backend and archive chain a client uses, and — through format_lineage — which engine generation its files are laid out for. The versions namespace provides constants for the releases wowlib targets.
The version tuple alone does NOT identify an engine: the Classic products reuse legacy version numbers on top of whatever retail branch was current when they were built (Classic 3.4.x spans three retail generations; 'wow_classic_titan' calls itself 3.80). The BUILD number does — Blizzard's build counter is global across every product — so every format decision keys on format_lineage, never on major/minor.
property
writable
¶
Expansion number, e.g. 3 for Wrath of the Lich King.
property
writable
¶
Exact client build number, e.g. 12340 for 3.3.5a. Unique and monotonic across ALL products, which is what makes it the only reliable engine-generation key.
property
writable
¶
flavor: ClientFlavor
Which product line this client is — Retail unless stated.
property
¶
Whether this is a Classic-family client: a modern engine wearing a legacy version number.
property
¶
storage_kind: StorageKind
Which storage technology this client uses: Mpq for pre-WoD (< 6.0) retail clients, Casc for everything else — every Classic client is CASC no matter what its version says.
property
¶
format_lineage: ClientVersion
The RETAIL release whose file formats this client's files follow — the version every format decision is actually made against.
For a retail client this is the version itself. For a Classic client it is the retail branch that was the live client when this build was produced, looked up by build number: Classic branches fork off the current retail engine, so Cataclysm Classic 4.4.2 (build 60895) lays its files out like The War Within, not like Cataclysm. Builds newer than the newest release wowlib models clamp to it.
property
¶
The TACT product code this flavor installs under by default ('wow', 'wow_classic', 'wow_classic_era', 'wow_anniversary'). PTR, beta and one-off products carry their own code — pass it to the filesystem explicitly.
Bases: IntEnum
Game client locale; enumerators use the client's own four-letter codes.
Bases: IntEnum
The expansion a client belongs to, in release order. The enumerable counterpart of a full ClientVersion: versioned format classes and factories are keyed on it (each enumerator maps to the last-minor-of-major release in the versions namespace).
A strongly-typed FileDataID — the numeric file identifier used by CASC-era clients (u32, matching the client's root manifest and DB2 references).
FileKey(file_id: FileDataID)
FileKey(file_path: str, file_id: FileDataID)
A file request: by client-internal path, by FileDataID, or both. The generic file identity for version-independent tools — code that handles any client generation operates on FileKeys without caring which half is available (on pre-CASC clients the FileDataID is simply absent); the storage backend uses the half it needs and FileSystem.resolve fills gaps through the listfile. The stored path is always in canonical form.
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
ArrayM2Vec2FP69x2(arg: list[M2Vec2FP69])
ArrayM2Vec2FP69x2(arg: Iterable[M2Vec2FP69])
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
Default constructor
Copy constructor
Construct from a length-N iterable
to_client_version(expansion: Expansion) -> ClientVersion
The last-minor-of-major client version wowlib targets for this expansion (the versions constant).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
expansion
|
Expansion
|
the expansion |
required |
Returns:
| Type | Description |
|---|---|
ClientVersion
|
the matching versions constant |
to_expansion(version: ClientVersion) -> Expansion | None
The expansion whose targeted release is exactly this version. Never matches a Classic constant — Classic clients are not expansion releases; pass version.format_lineage to ask which expansion's FORMATS one uses.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
version
|
ClientVersion
|
a full client version |
required |
Returns:
| Type | Description |
|---|---|
Expansion | None
|
the expansion, or None if the version is not one of the versions constants |
expansion_of(version: ClientVersion) -> Expansion | None
The expansion a client version belongs to, by major version — works for any build, not just the targeted releases.
This is the CONTENT axis: Cataclysm Classic 4.4.2 reports Cata, because that is the game it is. It is NOT the format axis — that same client writes War Within-era files. For formats, ask to_expansion(version.format_lineage) instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
version
|
ClientVersion
|
a full client version |
required |
Returns:
| Type | Description |
|---|---|
Expansion | None
|
the expansion, or None for unknown majors |
Version constants (wowlib.versions)¶
One ready-made ClientVersion per finished expansion — the exact
last-minor-of-major build wowlib targets — so code never spells build numbers:
from wowlib import versions
from wowlib.fs import FileSystem, FileSystemSettings
fs = FileSystem.open(FileSystemSettings("/Games/WoW 3.3.5a", versions.wotlk))
There is also one per living Classic product line (classic_era,
classic_bcc, classic_wotlk, classic_cata, classic_mop,
anniversary). Those are modern-engine clients wearing legacy version
numbers, so their flavor is not Retail and their file formats follow
format_lineage — the retail branch their build was cut on — rather than
their major. Since those products ship new builds continuously, the
constants are snapshots: for a real installation prefer
ClientInstall.detect.
The releases wowlib targets: the last-minor-of-major of every finished expansion (Midnight 12.x is ongoing and has no final build yet), plus the newest build of each living Classic product line. Builds verified against wago.tools.
The Classic constants are snapshots of a MOVING target — those products ship new builds continuously, and a newer build can land on a newer engine (Classic 4.4.0 is Dragonflight-era, 4.4.1 already War Within-era). Pin the exact build you have, or let ClientInstall.detect read it off the install.