portacom 0.1.0__tar.gz

portacom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahmoud Komaiha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

portacom-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: portacom
+Version: 0.1.0
+Summary: Call classic COM interfaces through ctypes on Windows, Linux and macOS
+Author-email: Mahmoud Komaiha <mkomaiha@umich.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mkomaiha/portacom
+Project-URL: Repository, https://github.com/mkomaiha/portacom
+Project-URL: Issues, https://github.com/mkomaiha/portacom/issues
+Project-URL: Changelog, https://github.com/mkomaiha/portacom/blob/main/CHANGELOG.md
+Keywords: com,ctypes,winmd,iunknown,ffi,cross-platform
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# portacom
+
+The runtime for bindings generated by
+[winmd2py](https://pypi.org/project/winmd2py/): call classic (IUnknown-based)
+COM interfaces through ctypes on Windows, Linux and macOS, and implement them
+in Python. Pure Python, no dependencies.
+
+```bash
+pip install portacom
+```
+
+Generate bindings from a `.winmd` with `winmd2py`, then (here for MiniCOM's
+example library on Linux, whose `BOOL` and BSTRs differ from Windows'):
+
+```python
+import ctypes, portacom
+
+minicom = portacom.Abi("minicom", typedefs={"BOOL": ctypes.c_long}, allocator=portacom.PlainAllocator())
+portacom.use_abi("my_bindings", minicom)  # before importing the bindings
+import my_bindings.Example as example
+import my_bindings.Registry as api
+
+registry = portacom.co_create_instance(api.Registry, api.IRegistry, library="libExampleLib.so")
+calc = registry.NewCalculator()  # [out] arguments are returned
+print(calc.Add(1, 2))  # 3
+
+
+class Callback(portacom.ComObject):  # implement an interface in Python
+    _interfaces_ = (example.ICalcCb,)
+
+    def Message(self, text):
+        print("C++ says", text)
+
+
+calc.SetCallback(Callback())
+calc.QueryInterface(example.ICalc2).GetValue2()  # 43; C++ calls back: "C++ says GetValue2 called"
+```
+
+A failed HRESULT raises `portacom.COMError`. BSTRs, VARIANTs, SAFEARRAYs,
+GUIDs and enums convert to and from Python values, and `portacom.Dispatch`
+calls automation (IDispatch) objects by name.
+
+For ready-made DirectX Shader Compiler bindings, see
+[portacom-dxc](https://pypi.org/project/portacom-dxc/). Calling conventions,
+ABI profiles and limitations are in the
+[project README](https://github.com/mkomaiha/portacom#readme).
+
+MIT license.

portacom-0.1.0/README.md

@@ -0,0 +1,48 @@
+# portacom
+
+The runtime for bindings generated by
+[winmd2py](https://pypi.org/project/winmd2py/): call classic (IUnknown-based)
+COM interfaces through ctypes on Windows, Linux and macOS, and implement them
+in Python. Pure Python, no dependencies.
+
+```bash
+pip install portacom
+```
+
+Generate bindings from a `.winmd` with `winmd2py`, then (here for MiniCOM's
+example library on Linux, whose `BOOL` and BSTRs differ from Windows'):
+
+```python
+import ctypes, portacom
+
+minicom = portacom.Abi("minicom", typedefs={"BOOL": ctypes.c_long}, allocator=portacom.PlainAllocator())
+portacom.use_abi("my_bindings", minicom)  # before importing the bindings
+import my_bindings.Example as example
+import my_bindings.Registry as api
+
+registry = portacom.co_create_instance(api.Registry, api.IRegistry, library="libExampleLib.so")
+calc = registry.NewCalculator()  # [out] arguments are returned
+print(calc.Add(1, 2))  # 3
+
+
+class Callback(portacom.ComObject):  # implement an interface in Python
+    _interfaces_ = (example.ICalcCb,)
+
+    def Message(self, text):
+        print("C++ says", text)
+
+
+calc.SetCallback(Callback())
+calc.QueryInterface(example.ICalc2).GetValue2()  # 43; C++ calls back: "C++ says GetValue2 called"
+```
+
+A failed HRESULT raises `portacom.COMError`. BSTRs, VARIANTs, SAFEARRAYs,
+GUIDs and enums convert to and from Python values, and `portacom.Dispatch`
+calls automation (IDispatch) objects by name.
+
+For ready-made DirectX Shader Compiler bindings, see
+[portacom-dxc](https://pypi.org/project/portacom-dxc/). Calling conventions,
+ABI profiles and limitations are in the
+[project README](https://github.com/mkomaiha/portacom#readme).
+
+MIT license.

portacom-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portacom"
+version = "0.1.0"
+description = "Call classic COM interfaces through ctypes on Windows, Linux and macOS"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mahmoud Komaiha", email = "mkomaiha@umich.edu" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["com", "ctypes", "winmd", "iunknown", "ffi", "cross-platform"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/mkomaiha/portacom"
+Repository = "https://github.com/mkomaiha/portacom"
+Issues = "https://github.com/mkomaiha/portacom/issues"
+Changelog = "https://github.com/mkomaiha/portacom/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

portacom-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portacom-0.1.0/src/portacom/__init__.py

@@ -0,0 +1,244 @@
+"""portacom: classic COM from Python, through ctypes, on Windows, Linux and macOS.
+
+Bindings generated by winmd2py import this runtime.  Using them:
+
+    import ctypes, portacom
+    import my_bindings.My.Namespace as api
+
+    obj = api.CreateThing(api.CLSID_Thing, api.IThing)   # riid/ppv: pass the class
+    value = obj.GetValue()                               # [out] arguments are returned
+    other = obj.query(api.IOther)                        # None if not implemented
+
+    class Callback(portacom.ComObject):                  # implementing an interface
+        _interfaces_ = (api.ICallback,)
+
+        def Notify(self, message):
+            print(message)
+
+Errors raise portacom.COMError.
+
+A .winmd describes the Windows ABI.  Where a library built for Linux or macOS
+differs (BOOL or LONG width, BSTR allocation), declare it in the bindings'
+__init__.py, before their modules are imported (Windows keeps the metadata's):
+
+    portacom.use_abi(__name__, portacom.Abi("mylib", library="mylib.dll", typedefs={"BOOL": ctypes.c_long}))
+"""
+
+from __future__ import annotations
+
+from ._abi import WINDOWS, Abi, abi_for, use_abi
+from ._activation import (
+    CLSCTX_ALL,
+    CLSCTX_INPROC_SERVER,
+    CoClass,
+    clsid_from_progid,
+    co_create_instance,
+    co_initialize,
+    create_instance,
+    exported_factory,
+)
+from ._dispatch import (
+    DISPATCH_METHOD,
+    DISPATCH_PROPERTYGET,
+    DISPATCH_PROPERTYPUT,
+    DISPATCH_PROPERTYPUTREF,
+    DISPID_NEWENUM,
+    DISPID_PROPERTYPUT,
+    DISPID_UNKNOWN,
+    DISPID_VALUE,
+    DISPPARAMS,
+    EXCEPINFO,
+    Dispatch,
+    DispatchObject,
+    EnumVARIANT,
+    IDispatch,
+    IEnumVARIANT,
+)
+from ._errors import (
+    E_ABORT,
+    E_ACCESSDENIED,
+    E_BOUNDS,
+    E_FAIL,
+    E_INVALIDARG,
+    E_NOINTERFACE,
+    E_NOT_SET,
+    E_NOTIMPL,
+    E_OUTOFMEMORY,
+    E_POINTER,
+    E_UNEXPECTED,
+    REGDB_E_CLASSNOTREG,
+    S_FALSE,
+    S_OK,
+    COMError,
+    check,
+    failed,
+    hresult_text,
+    set_callback_error_handler,
+    succeeded,
+)
+from ._interface import Function, IUnknown
+from ._loader import library_candidates, load_library, register_library
+from ._marshal import COMOUTPTR, CONST, IN, OPTIONAL, OUT, RETVAL, Param, Unsupported
+from ._memory import (
+    Allocator,
+    LibraryAllocator,
+    OleAllocator,
+    PlainAllocator,
+    WindowsLayoutAllocator,
+    default_allocator,
+    free_task_memory,
+)
+from ._platform import ARCH, FUNCTYPE, NATIVE_COM, WCHAR_SIZE, by_arch, wchar_count
+from ._safearray import SAFEARRAY, SafeArray
+from ._server import ComObject
+from ._types import (
+    GUID,
+    HRESULT,
+    PSTR,
+    PWSTR,
+    VARIANT_BOOL,
+    Array,
+    BSTRBase,
+    Enum,
+    Flags,
+    LazyModule,
+    Ptr,
+    Structure,
+    Union,
+    bitfields,
+    finish_layouts,
+    layout,
+    set_fields,
+)
+from ._variant import (
+    VARIANT,
+    VT_ARRAY,
+    VT_BOOL,
+    VT_BSTR,
+    VT_CY,
+    VT_DATE,
+    VT_DISPATCH,
+    VT_EMPTY,
+    VT_ERROR,
+    VT_I1,
+    VT_I2,
+    VT_I4,
+    VT_I8,
+    VT_INT,
+    VT_NULL,
+    VT_R4,
+    VT_R8,
+    VT_UI1,
+    VT_UI2,
+    VT_UI4,
+    VT_UI8,
+    VT_UINT,
+    VT_UNKNOWN,
+    VT_VARIANT,
+)
+
+__version__ = "0.1.0"
+
+
+# The API for using bindings.  What generated code needs is in portacom.codegen;
+# its names are still importable from here (portacom.layout, ...) for one
+# release, but not part of the API.
+__all__ = [
+    # using bindings
+    "IUnknown",
+    "ComObject",
+    "Dispatch",
+    "DispatchObject",
+    "EnumVARIANT",
+    "IDispatch",
+    "IEnumVARIANT",
+    "DISPPARAMS",
+    "EXCEPINFO",
+    "DISPATCH_METHOD",
+    "DISPATCH_PROPERTYGET",
+    "DISPATCH_PROPERTYPUT",
+    "DISPATCH_PROPERTYPUTREF",
+    "DISPID_VALUE",
+    "DISPID_UNKNOWN",
+    "DISPID_PROPERTYPUT",
+    "DISPID_NEWENUM",
+    "COMError",
+    "GUID",
+    "VARIANT",
+    "SafeArray",
+    "SAFEARRAY",
+    "PWSTR",
+    "PSTR",
+    "BSTRBase",
+    "CoClass",
+    "create_instance",
+    "exported_factory",
+    "co_create_instance",
+    "co_initialize",
+    "clsid_from_progid",
+    "CLSCTX_ALL",
+    "CLSCTX_INPROC_SERVER",
+    "free_task_memory",
+    "set_callback_error_handler",
+    "check",
+    "succeeded",
+    "failed",
+    "hresult_text",
+    "S_OK",
+    "S_FALSE",
+    "E_ABORT",
+    "E_ACCESSDENIED",
+    "E_BOUNDS",
+    "E_FAIL",
+    "E_INVALIDARG",
+    "E_NOINTERFACE",
+    "E_NOTIMPL",
+    "E_NOT_SET",
+    "E_OUTOFMEMORY",
+    "E_POINTER",
+    "E_UNEXPECTED",
+    "REGDB_E_CLASSNOTREG",
+    "VT_EMPTY",
+    "VT_NULL",
+    "VT_I1",
+    "VT_I2",
+    "VT_I4",
+    "VT_I8",
+    "VT_UI1",
+    "VT_UI2",
+    "VT_UI4",
+    "VT_UI8",
+    "VT_INT",
+    "VT_UINT",
+    "VT_R4",
+    "VT_R8",
+    "VT_CY",
+    "VT_DATE",
+    "VT_BSTR",
+    "VT_DISPATCH",
+    "VT_ERROR",
+    "VT_BOOL",
+    "VT_VARIANT",
+    "VT_UNKNOWN",
+    "VT_ARRAY",
+    # libraries and their ABI
+    "register_library",
+    "load_library",
+    "Abi",
+    "use_abi",
+    "WINDOWS",
+    "Ptr",  # for Abi overrides of pointer types
+    "Array",
+    "Allocator",
+    "OleAllocator",
+    "WindowsLayoutAllocator",
+    "PlainAllocator",
+    "LibraryAllocator",
+    "default_allocator",
+    # the platform
+    "NATIVE_COM",
+    "WCHAR_SIZE",
+    "ARCH",
+    "by_arch",
+    "wchar_count",
+]

portacom-0.1.0/src/portacom/_abi.py

@@ -0,0 +1,196 @@
+"""ABI profiles: what a library was compiled with that the .winmd cannot say.
+
+A .winmd describes the Windows ABI, and the format has no way to say that a
+library built for Linux or macOS differs.  So winmd2py generates ABI-neutral
+bindings, and whoever knows the library declares its differences with an Abi
+before importing them (in the bindings' own __init__.py, which winmd2py
+creates once for this):
+
+    typedefs   {typedef name: ctypes type}, for every use of a named typedef
+               from the metadata (BOOL, BSTR, ...)
+    overrides  {"Interface.Method": restype, "Interface.Method.param": type,
+               "Function.param": type, "Struct.field": type}, for uses that
+               the metadata does not name (LONG, and an IDL "long", are just
+               Int32)
+    allocator  how BSTRs, VARIANTs, task memory and SAFEARRAYs are allocated
+               and freed
+    library    the shared library behind the bindings ("Foo.dll"): where
+               co_create_instance() finds CoCreateInstance, and whose own
+               exported SysAllocStringLen & co. are used where it has them
+
+An Abi describes the library as built for Linux and macOS.  On Windows the
+metadata is the truth, so use_abi() binds WINDOWS there, unless the Abi was
+made with on_windows=True.  Each generated module asks abi_for() for its Abi
+when it is imported; see use_abi() for how the registration is chosen.
+Without one it is WINDOWS.
+"""
+
+from ._memory import Allocator, LazyAllocator, LibraryAllocator, default_allocator
+from ._platform import NATIVE_COM
+from ._types import HRESULT, PSTR, PWSTR, VARIANT_BOOL, BSTRBase
+
+
+class Abi:
+    """How a library built for Linux and macOS differs from the Windows ABI
+    that its .winmd describes.
+
+    On Windows the library follows the metadata, so use_abi() binds WINDOWS
+    instead; on_windows=True is for the rare library that deviates on
+    Windows too, and makes use_abi() bind this Abi there as well.
+
+    library: the shared library behind the bindings, named as the metadata
+    names it ("Foo.dll", which is libFoo.so or libFoo.dylib off Windows; see
+    load_library), or a path or a loaded ctypes.CDLL.  co_create_instance()
+    calls its exported CoCreateInstance when not given a library (off
+    Windows; on Windows OLE32's is used), and its own exported
+    SysAllocStringLen, SysFreeString, SysStringLen, CoTaskMemAlloc,
+    CoTaskMemFree and SafeArray* functions allocate the BSTRs and memory, in
+    each family that it exports whole (a LibraryAllocator).  It is loaded on
+    first use, so making an Abi loads nothing.
+
+    allocator: how BSTRs, task memory and SAFEARRAYs are allocated.  With
+    library too, it is the fallback for what the library does not export;
+    alone, it is used outright.  Without either, the default allocator (OLE
+    on Windows, the Windows layout on malloc/free elsewhere).
+    """
+
+    def __init__(self, name, typedefs=None, overrides=None, allocator=None, library=None, on_windows=False):
+        self.name = name
+        self.typedefs = dict(typedefs or {})
+        self.overrides = dict(overrides or {})
+        if allocator is not None and not isinstance(allocator, Allocator):
+            raise TypeError("allocator must be a portacom.Allocator")
+        self.library = library
+        self.on_windows = on_windows
+        self._fallback = allocator
+        self._allocator = allocator if library is None else None
+        self._default_allocator = allocator is None and library is None
+        # what this ABI's types allocate with, resolved on first use
+        self._lazy = LazyAllocator(lambda: self.allocator)
+        self._bstr = None
+        self._safearray = None
+        self._variant = None
+
+    @property
+    def allocator(self):
+        if self._allocator is None:
+            if self.library is not None:
+                self._allocator = LibraryAllocator(self.library, fallback=self._fallback)
+            else:
+                self._allocator = default_allocator()
+        return self._allocator
+
+    @property
+    def BSTR(self):
+        """The BSTR type of this ABI, which allocates with its allocator."""
+        if self._bstr is None:
+            self._bstr = type("BSTR", (BSTRBase,), {"_allocator_": self._lazy, "__qualname__": f"BSTR[{self.name}]"})
+        return self._bstr
+
+    @property
+    def SAFEARRAY(self):
+        """The SAFEARRAY type of this ABI, which allocates with its allocator."""
+        if self._safearray is None:
+            from ._safearray import SAFEARRAY
+
+            self._safearray = type(f"SAFEARRAY[{self.name}]", (SAFEARRAY,), {"_allocator_": self._lazy})
+        return self._safearray
+
+    @property
+    def VARIANT(self):
+        """The VARIANT type of this ABI, whose BSTRs and arrays use its allocator."""
+        if self._variant is None:
+            from ._variant import VARIANT, variant_type
+
+            if self._default_allocator:
+                self._variant = VARIANT  # the default allocator, as portacom.VARIANT has
+            else:
+                self._variant = variant_type(self._lazy, self.name)
+        return self._variant
+
+    def typedef(self, name, default):
+        """The type for a use of the named typedef."""
+        if name in self.typedefs:
+            return self.typedefs[name]
+        special = _SPECIAL.get(name)
+        if special is not None:
+            return special(self)
+        return default
+
+    def override(self, key, default):
+        return self.overrides.get(key, default)
+
+    def __repr__(self):
+        return f"<Abi {self.name!r}>"
+
+
+_SPECIAL = {
+    "BSTR": lambda abi: abi.BSTR,
+    "SAFEARRAY": lambda abi: abi.SAFEARRAY,
+    "PWSTR": lambda abi: PWSTR,
+    "PCWSTR": lambda abi: PWSTR,
+    "PSTR": lambda abi: PSTR,
+    "PCSTR": lambda abi: PSTR,
+    "HRESULT": lambda abi: HRESULT,
+    "VARIANT_BOOL": lambda abi: VARIANT_BOOL,
+}
+
+# The Windows ABI, as the metadata describes it
+WINDOWS = Abi("windows")
+
+_registered = {}  # key (module path or namespace) -> Abi
+_bound = {}  # (module path, namespace) -> Abi, for modules already imported
+
+
+def _matches(key, name):
+    return name == key or name.startswith(key + ".")
+
+
+def _longest(registry, name):
+    keys = [key for key in registry if _matches(key, name)]
+    return registry[max(keys, key=len)] if keys else None
+
+
+def _resolve(registry, namespace, module):
+    """A key matching the module path wins; then a key matching the namespace."""
+    found = _longest(registry, module) if module else None
+    if found is None:
+        found = _longest(registry, namespace)
+    return found or WINDOWS
+
+
+def use_abi(key, abi):
+    """Use abi for the generated bindings that key names.  Call it before
+    importing them (in the bindings' __init__.py): a module's Abi is fixed
+    when it is imported.
+
+    An Abi describes the library as built for Linux and macOS.  On Windows
+    the metadata is the truth, so there the bindings get WINDOWS, unless abi
+    was made with on_windows=True.
+
+    key is a generated package's import path ("my_bindings", or
+    "my_bindings.Windows.Win32"), or a metadata namespace ("Windows.Win32").
+    For a module, the longest key that matches its import path wins; only if
+    none does, the longest key that matches its namespace.  So a package that
+    ships bindings (portacom_dxc registers "portacom_dxc._bindings") is not
+    affected by a namespace registered for other bindings of that namespace.
+    """
+    if not isinstance(abi, Abi):
+        raise TypeError(f"use_abi() takes a portacom.Abi, not {type(abi).__name__}")
+    if NATIVE_COM and not abi.on_windows:
+        abi = WINDOWS
+    trial = {**_registered, key: abi}
+    for (module, namespace), used in _bound.items():
+        if _resolve(trial, namespace, module) is not used:
+            raise RuntimeError(
+                f"{module} was already imported with {used!r}; call portacom.use_abi({key!r}, ...) "
+                f"before importing {module}"
+            )
+    _registered[key] = abi
+
+
+def abi_for(namespace, module=None):
+    """The Abi for a generated module, called by the module when imported."""
+    abi = _resolve(_registered, namespace, module)
+    _bound[(module or namespace, namespace)] = abi
+    return abi