Metadata-Version: 2.4
Name: pycomtypelib
Version: 0.1.0
Summary: Pure-Python decoder for COM type library (MSFT .tlb) binary format
Author: hardening-consulting
License: LGPL-2.1-or-later
Keywords: com,typelib,tlb,ole,automation,windows,reverse-engineering
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Disassemblers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pefile
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# pycomtypelib

A pure-Python, cross-platform decoder for the **MSFT** COM type library binary
format (`.tlb` files, and `RT_TYPELIB` resources embedded in `.dll` / `.ocx` /
`.exe` files). No Windows, no COM, no `oleaut32.dll` required.

This is a Python port of the type library reading logic in
[Wine's `dlls/oleaut32/typelib.c`](https://gitlab.winehq.org/wine/wine/-/blob/master/dlls/oleaut32/typelib.c)
and `typelib.h`, cross-checked against public documentation of the format
(notably [Geoff Chappell's notes on `ITypeLib`](https://www.geoffchappell.com/)).
Only the **MSFT** format is supported (the format produced by `ICreateTypeLib2`
/ MIDL and used by essentially all modern type libraries); the older **SLTG**
format (`ICreateTypeLib`, legacy VB5/VB6) is out of scope.

Wine's `typelib.c` is licensed LGPL-2.1-or-later; this project inherits that
license since its parsing logic is derived from it.

## Install

```bash
pip install -e .
```

## Library usage

```python
from pycomtypelib import load_typelib_file

tlb = load_typelib_file("stdole2.tlb")
print(tlb.name, tlb.guid, tlb.version)
for ti in tlb.typeinfos:
    print(ti.typekind.name, ti.name)
```

To pull a type library out of a compiled binary (DLL/OCX/EXE) instead of a
standalone `.tlb` file:

```python
from pycomtypelib import load_typelib_from_pe

tlb = load_typelib_from_pe("MSCOMCTL.OCX")
```

## CLI

```bash
pycomtypelib dump stdole2.tlb
pycomtypelib dump MSCOMCTL.OCX --json > mscomctl.json
```

Cross-library references (e.g. an interface inheriting from `IUnknown` or
`IDispatch`, which live in `stdole2.tlb`) can't be resolved to a full
`TypeInfo` without also parsing the imported library, so by default they're
shown by name via a small built-in table of well-known COM/OLE Automation
interface GUIDs (`pycomtypelib.WELL_KNOWN_INTERFACES`). Pass `-n` /
`--no-wellknown-guids` to disable that and show the raw GUID and import
library name instead:

```bash
pycomtypelib dump -n stdole2.tlb
```

This only affects display (`--json`'s `wellknown_name` field, and the IDL-like
text renderer); it never affects decoding itself.

## Scope

- Reads the MSFT binary layout: header, segment directory, GUID/name/string
  tables, type descriptors, array descriptors, per-`TypeInfo` function/variable/
  implemented-type records, imported type libraries, and custom data.
- Resolves this into a friendly object model (`TypeLib`, `TypeInfo`, `FuncDesc`,
  `VarDesc`, `ParamDesc`, `TypeDesc`, ...) analogous to what `ITypeInfo` exposes,
  including resolution of `VT_USERDEFINED` references to other `TypeInfo`
  entries (in the same library or in imported libraries).
- Read-only: this library decodes type libraries, it does not write/compile
  them.
