feat: add ctypes-based Python bindings

Author: AnmiTaliDev

.gitignore

@@ -91,6 +91,14 @@ compile_commands.json
 # Meson private directory
 .mesonpy-*
 
+# python
+# @detect: bindings/python
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.venv/
+
 # nix
 # @detect: *.nix flake.nix default.nix
 # Nix build outputs

CHANGELOG.md

@@ -9,6 +9,11 @@ All notable changes to this project will be documented in this file.
 - `dep_graph_add_installed()` (`include/apg/graph.h`): identical to `dep_graph_add()`, but marks the node as installed so alias/`provides` resolution can prefer it (see Fixed below). `trans_prepare()` (`src/transaction/prepare.c`) now uses it for the caller's already-installed packages instead of `dep_graph_add()`
 - `trans_prefer_provider(trans, name, pkg_name)` (`include/apg/transaction.h`): forces resolution of a dependency or virtual (`provides`) name to a specific package for a given transaction, for callers that want to prompt the user when a name has multiple providers (pacman-style), rather than rely on `trans_prepare()`'s automatic choice. Must be called before `trans_prepare()`. Backed internally by `dep_graph_prefer()` (`src/graph/graph_priv.h`, not public — the transaction's graph is never exposed to callers)
 - `dep_graph_export_dot()` (`include/apg/graph.h`, `src/graph/dot.c`): renders the graph to Graphviz DOT — every package as a node (installed ones filled green), every dependency as an edge to whatever `dep_graph_lookup()` currently resolves it to (labeled with the version constraint, red/dashed if unresolved), and every virtual/`provides` name as a diamond node with an edge to each of its providers (bold for the one that would currently win, dashed for the rest) — useful for visualizing exactly which provider a multi-provider name resolves to. Wrapped as `DependencyGraph::export_dot()` in the C++ bindings. Output verified against a real `dot` binary (renders to SVG without errors)
+- ctypes-based Python bindings (`bindings/python/apg/`), enabled with `-Dpython_bindings=enabled`. Pure stdlib, no compiled extension: loads the built `.so` directly (`APG_LIBRARY_PATH` env var, else `ctypes.util.find_library`), so there's no separate build step, mirroring the C++ bindings' philosophy. Covers the full public API — `Database`, `Transaction`, `DependencyGraph`, `Keyring`, `Package`/`PackageMetadata`, `version`/`journal`/`audit`/`sign`/`archive`/`install`/`copy`/`scripts` — with RAII-style `close()`/`__del__`/context-manager wrappers. Installable via `bindings/python/pyproject.toml` (hatchling). Covered by `bindings/python/tests/test_bindings.py`, run via `meson test`
+
+### Fixed
+
+- (Python bindings, new in this release, no prior public API affected) `Database.list()`/`Database.search()` could return `Package` objects wrapping garbage pointers: ctypes indexing into a `POINTER(POINTER(package))` array (`raw[i]`) returns a lazy view into that array's backing memory rather than a copied pointer value, so freeing the array (`db_list()`/`db_search()` require the caller to free the returned array) invalidated every `raw[i]` still referenced by the wrapped `Package` objects. Fixed by extracting each pointer's address via `ctypes.cast(raw[i], ctypes.c_void_p).value` and reconstructing an independent pointer object before freeing the array
 
 ### Changed
 

ROADMAP.md

@@ -4,7 +4,7 @@
 
 - [x] ABI stabilization and documentation
 - [x] C++ bindings (header-only, `bindings/cpp/`)
-- [ ] Python bindings
+- [x] Python bindings
 - [x] Correctness tests: installation unit tests, fuzzing (package JSON, dep constraints)
 - [x] pkg-config and CMake find module
 - [x] Drop the gpgme (OpenPGP) signing backend entirely; libsodium (Ed25519) becomes the only one

bindings/python/apg/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: 2026 AnmiTaliDev <anmitalidev@nuros.org>
+
+from . import archive, audit, copy, install, keyring, scripts, sign
+from .config import InstallPolicy
+from .db import Database, DbVerifyIssue
+from .error import ApgError
+from .graph import DependencyGraph
+from .journal import JournalEntry, JournalOp, JournalStatus
+from .package import Package, PackageMetadata, PackageMetadataView
+from .transaction import (
+    Transaction,
+    TransBlockedRemoveView,
+    TransConflictView,
+    TransError,
+    TransFileConflictView,
+    TransHeldPkgView,
+    TransOp,
+    TransStepView,
+)
+from .version import DepConstraint, VerOp, dep_constraint_parse, dep_constraint_to_str, ver_compare, ver_satisfies
+
+__all__ = [
+    "ApgError",
+    "InstallPolicy",
+    "Database",
+    "DbVerifyIssue",
+    "DependencyGraph",
+    "JournalEntry",
+    "JournalOp",
+    "JournalStatus",
+    "Package",
+    "PackageMetadata",
+    "PackageMetadataView",
+    "Transaction",
+    "TransBlockedRemoveView",
+    "TransConflictView",
+    "TransError",
+    "TransFileConflictView",
+    "TransHeldPkgView",
+    "TransOp",
+    "TransStepView",
+    "DepConstraint",
+    "VerOp",
+    "dep_constraint_parse",
+    "dep_constraint_to_str",
+    "ver_compare",
+    "ver_satisfies",
+    "archive",
+    "audit",
+    "copy",
+    "install",
+    "keyring",
+    "scripts",
+    "sign",
+]