# median-xl/pympq architecture

> Architecture diagram of the GitHub repository median-xl/pympq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/median-xl/pympq
- Repository: https://github.com/median-xl/pympq

## Overview

Pympq is a Windows-oriented Python binding for StormLib’s MPQ archive API. The main workflow is for a Python caller to create or open an archive, manage its contents, and open or extract files; file handles expose basic metadata and closing. The C++ extension translates Python calls and flag aliases into StormLib operations. The README documents additional archive and file capabilities, but the sampled implementation is incomplete, so those are represented at the archive-operation level rather than as detailed call chains.

Main entry points: [`src/mpq.h`](https://github.com/median-xl/pympq/blob/master/src/mpq.h) (Archive handle), [`src/pympq.cpp`](https://github.com/median-xl/pympq/blob/master/src/pympq.cpp) (Extension API), [`stormlib/x64/StormLib.h`](https://github.com/median-xl/pympq/blob/master/stormlib/x64/StormLib.h) (StormLib API), [`pympq/__init__.py`](https://github.com/median-xl/pympq/blob/master/pympq/__init__.py) (Package export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python interface"]
  node_package["Package export<br/>[__init__.py]"]
end

subgraph group_binding["Native binding"]
  node_extension["Extension API<br/>[pympq.cpp]"]
  node_aliases["Flag aliases<br/>[constant_alias.h]"]
end

subgraph group_mpq["MPQ operations"]
  node_archive["Archive handle<br/>[mpq.h]"]
  node_filehandle["File handle<br/>[mpq_file.h]"]
  node_storm["StormLib API<br/>[StormLib.h]"]
end

node_caller(("Python caller"))
node_archivefile[("MPQ archive file")]
node_extracted["Extracted file"]

node_caller -->|"imports"| node_package
node_package -->|"re-exports"| node_extension
node_caller -->|"calls API"| node_extension
node_extension -->|"translates flags"| node_aliases
node_extension -->|"creates or opens"| node_storm
node_extension -->|"returns handle"| node_archive
node_archive -->|"translates flags"| node_aliases
node_archive -->|"manages archive"| node_storm
node_archive -->|"reads or writes"| node_archivefile
node_archive -->|"opens file handle"| node_filehandle
node_archive -->|"extracts file"| node_extracted
node_filehandle -->|"queries or closes"| node_storm
node_storm -->|"operates on"| node_archivefile

click node_package "https://github.com/median-xl/pympq/blob/master/pympq/__init__.py"
click node_extension "https://github.com/median-xl/pympq/blob/master/src/pympq.cpp"
click node_aliases "https://github.com/median-xl/pympq/blob/master/src/constant_alias.h"
click node_archive "https://github.com/median-xl/pympq/blob/master/src/mpq.h"
click node_filehandle "https://github.com/median-xl/pympq/blob/master/src/mpq_file.h"
click node_storm "https://github.com/median-xl/pympq/blob/master/stormlib/x64/StormLib.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package toneBlue
class node_extension,node_aliases,node_archivefile toneAmber
class node_archive,node_filehandle,node_storm toneMint
class node_caller,node_extracted toneIndigo
```

## Components

### Python interface

- [Package export](https://github.com/median-xl/pympq/blob/master/pympq/__init__.py): `pympq/__init__.py`

### Native binding

- [Extension API](https://github.com/median-xl/pympq/blob/master/src/pympq.cpp): `src/pympq.cpp`
- [Flag aliases](https://github.com/median-xl/pympq/blob/master/src/constant_alias.h): `src/constant_alias.h`

### MPQ operations

- [Archive handle](https://github.com/median-xl/pympq/blob/master/src/mpq.h): `src/mpq.h`
- [File handle](https://github.com/median-xl/pympq/blob/master/src/mpq_file.h): `src/mpq_file.h`
- [StormLib API](https://github.com/median-xl/pympq/blob/master/stormlib/x64/StormLib.h): `stormlib/x64/StormLib.h`

### Other components

- **Python caller**
- **MPQ archive file**
- **Extracted file**

## Connections

- Python caller → Package export: imports
- Package export → Extension API: re-exports
- Python caller → Extension API: calls API
- Extension API → Flag aliases: translates flags
- Extension API → StormLib API: creates or opens
- Extension API → Archive handle: returns handle
- Archive handle → Flag aliases: translates flags
- Archive handle → StormLib API: manages archive
- Archive handle → MPQ archive file: reads or writes
- Archive handle → File handle: opens file handle
- Archive handle → Extracted file: extracts file
- File handle → StormLib API: queries or closes
- StormLib API → MPQ archive file: operates on