@@ -0,0 +1,62 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "bindings/python/**"
+      - "core"
+      - "examples/python_*/**"
+      - ".github/workflows/python-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "bindings/python/**"
+      - "core"
+      - "examples/python_*/**"
+      - ".github/workflows/python-ci.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test:
+    name: Build & Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Checkout core
+        run: git submodule update --init core
+      - uses: astral-sh/setup-uv@v6
+      - name: Install Linux dependencies
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y cmake pkg-config libgtk-3-dev libx11-dev libxi-dev xvfb
+      - name: Lint
+        working-directory: bindings/python
+        run: uvx ruff check nativeapi tests --select E,F,W,B,UP,I
+      - name: Build the library
+        working-directory: bindings/python
+        run: |
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+          cmake --build build --config Release
+      - name: Test
+        working-directory: bindings/python
+        shell: bash
+        env:
+          PYTHONPATH: .
+        run: |
+          cmd="uvx --with pytest pytest"
+          if [ "$RUNNER_OS" = "Linux" ]; then xvfb-run -a $cmd; else $cmd; fi
+      - name: Build the wheel
+        working-directory: bindings/python
+        run: uv build --wheel
@@ -1,6 +1,6 @@
 # libnativeapi workspace
 
-This is the workspace repo (`nativeapi-workspace`, formerly `nativeapi-flutter`) for the [libnativeapi](https://github.com/libnativeapi) project family. All three bindings (`bindings/dart/`, `bindings/rust/`, `bindings/csharp/`), the code generator (`tools/codegen/`), the `./codegen` script, the specs and the shared tooling live directly in this repo (the Rust and C# histories were merged in from `nativeapi-rust` and `nativeapi-csharp`); only `core/` is a git submodule of an independent repository. Work inside `core/` is committed and pushed from that subdirectory; everything else is committed here.
+This is the workspace repo (`nativeapi-workspace`, formerly `nativeapi-flutter`) for the [libnativeapi](https://github.com/libnativeapi) project family. Every binding (`bindings/dart/`, `bindings/rust/`, `bindings/csharp/`, `bindings/js/`, `bindings/python/`), the code generator (`tools/codegen/`), the `./codegen` script, the specs and the shared tooling live directly in this repo (the Rust and C# histories were merged in from `nativeapi-rust` and `nativeapi-csharp`); only `core/` is a git submodule of an independent repository. Work inside `core/` is committed and pushed from that subdirectory; everything else is committed here.
 
 ## Layout
 
@@ -9,8 +9,10 @@ core/               # submodule: nativeapi-core — the C++ core library
 bindings/
 ├── dart/           # the Dart binding: nativeapi/, cnativeapi/, nativeapi_flutter/
 ├── rust/           # the Rust binding: crates/{nativeapi,cnativeapi}
-└── csharp/         # the C# binding: src/, tests/, NativeAPI.slnx
-examples/           # every binding's example apps, prefixed flutter_*, rust_*, csharp_*
+├── csharp/         # the C# binding: src/, tests/, NativeAPI.slnx
+├── js/             # the JS/TS binding: a Node-API addon (src/) + TypeScript (lib/)
+└── python/         # the Python binding: ctypes package (nativeapi/) + native shim (src/)
+examples/           # every binding's example apps, prefixed flutter_*, rust_*, csharp_*, js_*, python_*
 pubspec.yaml        # pub workspace + melos root: Dart packages and Flutter examples
 Cargo.toml          # cargo workspace root: Rust crates and examples
 tools/codegen/      # in-repo Rust workspace: the code generator
@@ -23,8 +25,8 @@ codegen             # Python entry point orchestrating the generators
 ## Architecture
 
 - `core` — the C++ core library (repo: `nativeapi-core`). The source of truth for the native API surface (windows, tray icons, menus, displays, keyboard, dialogs, storage, etc.) with per-platform implementations (macOS/Windows/Linux).
-- `tools/codegen` — three crates: `shared` (libclang parser, IR, naming), `capi` (C ABI + umbrella header), `bindings` (Rust/Dart/C# generators, consuming the IR JSON emitted by `capi`). Only `capi` depends on libclang. See tools/codegen/README.md.
-- `bindings/*` — language bindings wrapping the core library. All live in this repo and build against the `core/` submodule directly (Rust `build.rs`, the Dart `cnativeapi` package's build hook, the C# native CMake). Only a published package carries its own copy of core, in `cxx_impl/`, which the release workflows vendor and never commit. The Rust binding layers `nativeapi` (safe API) over `cnativeapi` (FFI).
+- `tools/codegen` — three crates: `shared` (libclang parser, IR, naming), `capi` (C ABI + umbrella header), `bindings` (Rust/Dart/C#/JS/Python generators, consuming the IR JSON emitted by `capi`). Only `capi` depends on libclang. See tools/codegen/README.md.
+- `bindings/*` — language bindings wrapping the core library. All live in this repo and build against the `core/` submodule directly (Rust `build.rs`, the Dart `cnativeapi` package's build hook, the C# native CMake, the JS addon's and the Python binding's `CMakeLists.txt`). Only a published package carries its own copy of core, in `cxx_impl/`, which the release workflows vendor and never commit. The Rust binding layers `nativeapi` (safe API) over `cnativeapi` (FFI). The Python binding has no compiled extension: generated `ctypes` code (`nativeapi/_capi.py` plus one module per header) calls a shared library built from core and a small event loop shim, which `Application.run_async()` pumps from asyncio.
 
 ## Design specs
 
@@ -48,12 +50,12 @@ breaks). When one is resolved, edit the spec text itself.
 Always drive the generators through `./codegen` at the workspace root:
 
 - `./codegen` — full run: C ABI, then all bindings
-- `./codegen capi` / `./codegen bindings [--lang rust,dart,csharp]`
+- `./codegen capi` / `./codegen bindings [--lang rust,dart,csharp,js,python]`
 - `./codegen check` — read-only verification, non-zero exit when stale (CI mode)
 - `./codegen readme` — copy the shared README sections (`tools/readme/*.md`, e.g. Contributing) into core and every binding; `check` flags drift, `sync` runs it. Edit the snippet, never the copies.
 - `./codegen sync [-m "msg"] [--push]` — full downstream propagation, see below
 
-Generated files start with `// AUTO-GENERATED. DO NOT EDIT.` — change the C++ headers in `core/src/` and regenerate instead of editing outputs. Files without that banner are hand-written and never overwritten. The header list (`API_HEADERS`) lives in `tools/codegen/shared/src/lib.rs`.
+Generated files start with `// AUTO-GENERATED. DO NOT EDIT.` (`#` in Python) — change the C++ headers in `core/src/` and regenerate instead of editing outputs. Files without that banner are hand-written and never overwritten. The header list (`API_HEADERS`) lives in `tools/codegen/shared/src/lib.rs`.
 
 ## Changing the core API
 
@@ -68,7 +70,7 @@ It regenerates everything, reruns `bindgen` (Rust raw FFI) and `ffigen` (Dart ra
 Manual follow-ups sync cannot do (details in tools/codegen/README.md):
 
 - New handle types need an `IdTypeTag<T>` entry in `core/src/foundation/id_allocator.h` (append only; a miss is a compile error, not silent).
-- Hand-written files in the bindings (exports, re-exports, changelogs, examples) are never touched by the generators. Rust's `pub mod` list is generated (`modules.rs`), and so is Dart's (`nativeapi/lib/src/generated.dart`); `nativeapi_flutter`'s exports are not.
+- Hand-written files in the bindings (exports, re-exports, changelogs, examples) are never touched by the generators. Rust's `pub mod` list is generated (`modules.rs`), and so is Dart's (`nativeapi/lib/src/generated.dart`) and Python's (`nativeapi/__init__.py`); `nativeapi_flutter`'s exports are not.
 
 The `core-api-change` skill walks the whole flow, including what to check before `sync` commits.
 
@@ -93,8 +95,8 @@ scenarios for *this project's* examples live in [tools/gui/](tools/gui/README.md
 - `core` tracks `branch = main`. Use `make sync` to fast-forward it; `make status` to see dirty state everywhere; `make bump` to stage its pointer.
 - The leanflutter packages built on nativeapi (`tray_manager`, `window_manager`, `launch_at_startup`, …) live in their own repos under github.com/leanflutter and depend on the published `nativeapi`; they are not part of this repo. To try one against local changes, point a `dependency_overrides` entry in that package at `bindings/dart/nativeapi_flutter` (and `nativeapi`, `cnativeapi`) and never commit the override.
 - Commit workspace submodule pointer updates only when the combination is compatible (a known-good snapshot).
-- Examples live in `examples/<binding>_<name>_example` (`flutter_`, `rust_`, `csharp_`), not inside the bindings; a new Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`. Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
-- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`); never push a bare `v*` tag for anything but the Dart packages.
+- Examples live in `examples/<binding>_<name>_example` (`flutter_`, `rust_`, `csharp_`, `js_`, `python_`), not inside the bindings; a new Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`, a JS one in the root `package.json`. A Python example is a standalone uv project whose `pyproject.toml` points `nativeapi` at `../../bindings/python` (`uv run main.py` builds the wheel). Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
+- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`, `js-ci.yml`, `python-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`, `examples/js_*`, `examples/python_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`); never push a bare `v*` tag for anything but the Dart packages. The Python package is not published yet.
 - The Dart packages `cnativeapi`, `nativeapi` and `nativeapi_flutter` share one version: a release bumps all three pubspecs and CHANGELOGs, because pub.dev's automated publishing matches the tag `v<version>` against each package's own version. `cnativeapi` and `nativeapi` are plain Dart (no Flutter dependency; a build hook compiles core); `nativeapi_flutter` is the Flutter-facing package, holding the widgets, the `dart:ui` conversions and `windowing.dart`, and re-exporting `nativeapi` minus the names that clash with Flutter's.
 - Never commit in a submodule while on a detached HEAD — check out `main` first (`./codegen sync` enforces this).
 - Do not add Co-Authored-By trailers to commits.
@@ -0,0 +1,5 @@
+/build/
+/dist/
+/cxx_impl/
+*.egg-info/
+.venv/
@@ -0,0 +1,56 @@
+# Builds the shared library the Python binding loads with ctypes: the whole
+# core static archive plus the event loop shim for Application.run_async().
+#
+# Built by scikit-build-core when the wheel is built (`pip install .`), which
+# installs the library into the `nativeapi` package; or by hand for a source
+# checkout (`cmake -S . -B build && cmake --build build`), where
+# nativeapi/_library.py finds it in build/.
+cmake_minimum_required(VERSION 3.24)
+
+project(nativeapi_python LANGUAGES CXX C)
+if(APPLE)
+  enable_language(OBJCXX)
+endif()
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# The published sdist vendors core into cxx_impl/; in this repository the
+# binding builds against the core/ submodule directly.
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/cxx_impl/src/CMakeLists.txt")
+  set(NATIVEAPI_CORE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cxx_impl")
+else()
+  set(NATIVEAPI_CORE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../core")
+endif()
+add_subdirectory("${NATIVEAPI_CORE_DIR}/src" nativeapi_core)
+
+set(SOURCES src/event_loop_common.cc)
+if(APPLE)
+  list(APPEND SOURCES src/event_loop_macos.mm)
+elseif(WIN32)
+  list(APPEND SOURCES src/event_loop_windows.cc)
+else()
+  list(APPEND SOURCES src/event_loop_linux.cc)
+endif()
+
+add_library(nativeapi_python SHARED ${SOURCES})
+target_include_directories(nativeapi_python PRIVATE "${NATIVEAPI_CORE_DIR}/src")
+# Re-export every C ABI symbol of the archive, not just the ones the shim uses.
+target_link_libraries(nativeapi_python PRIVATE
+  $<LINK_LIBRARY:WHOLE_ARCHIVE,nativeapi>)
+if(WIN32)
+  target_link_libraries(nativeapi_python PRIVATE ole32 uuid)
+endif()
+set_target_properties(nativeapi_python PROPERTIES
+  OUTPUT_NAME nativeapi
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+)
+
+if(SKBUILD)
+  install(TARGETS nativeapi_python
+    LIBRARY DESTINATION nativeapi
+    RUNTIME DESTINATION nativeapi
+  )
+endif()
@@ -0,0 +1,98 @@
+# nativeapi (Python)
+
+Native desktop APIs — windows, tray icons, menus, displays, global shortcuts,
+dialogs, preferences and secure storage — for **Python 3.10+**, on macOS,
+Windows and Linux.
+
+Pure `ctypes` over the [libnativeapi](https://github.com/libnativeapi) C ABI:
+no compiled extension module, so one wheel per platform serves every Python 3
+version. The typed Python layer is generated from the C++ headers of core by
+`./codegen`; only `nativeapi/_library.py`, `nativeapi/_runtime.py` and the
+event loop shim in `src/` are hand-written.
+
+> **Status: prototype.** The whole API surface is generated, but it has not
+> been published and the API may still change.
+
+```python
+import asyncio
+
+from nativeapi import Application, Size, Window, WindowClosedEvent, WindowManager
+
+
+async def main() -> int:
+    window = Window()
+    window.set_title("Hello")
+    window.set_size(Size(800, 600), False)
+    window.center()
+
+    def on_event(event):
+        if isinstance(event, WindowClosedEvent):
+            Application.quit()
+
+    WindowManager.add_listener(on_event)
+    return await Application.run_async(window)  # asyncio keeps running
+
+
+asyncio.run(main())
+```
+
+## Model
+
+- **Objects** (`Window`, `Menu`, `TrayIcon`, …) wrap a handle. The default
+  constructor is `Window()`; other constructors are class methods
+  (`Preferences.with_scope("app")`). A failed creation raises
+  `NativeApiError`. The reference is released by `dispose()` / `with`, or when
+  the wrapper is garbage collected. Calls on a released handle fail safely.
+- **Getters** without arguments are properties (`window.title`,
+  `window.bounds`, `window.is_visible`); everything else is a method
+  (`window.set_title(...)`).
+- **Values** (`Point`, `Size`, `Rectangle`, `Color`, …) are dataclasses.
+- **Enums** are `IntEnum`s (`TitleBarStyle.HIDDEN`); bit sets are `IntFlag`s
+  (`ModifierKey.SHIFT | ModifierKey.ALT`).
+- **Events** are frozen dataclasses, one subclass per kind, so they work
+  with `match`: `case WindowMovedEvent(window_id=id, new_position=p)`.
+- **Singletons** (`Application`, `WindowManager`, `DisplayManager`, …) are
+  classes with static methods.
+
+## The event loop
+
+- `Application.run(window=None)` blocks in the platform loop and returns the
+  exit code. Listeners run on the main thread in between. Ctrl+C terminates
+  the process.
+- `await Application.run_async(window=None)` pumps the platform loop from the
+  running asyncio loop instead, so tasks, timers and I/O keep running while
+  windows are up. It resolves with the exit code once `Application.quit(code)`
+  is called. An exception raised in a listener goes to the asyncio loop's
+  exception handler.
+
+Both must be called on the main thread.
+
+## Building
+
+```bash
+cd examples/python_window_example && uv run main.py   # builds the wheel, runs the example
+```
+
+For work on the binding itself, build the library in place and run from the
+source tree; `nativeapi/_library.py` finds it in `build/`:
+
+```bash
+cmake -S bindings/python -B bindings/python/build && cmake --build bindings/python/build
+cd bindings/python && PYTHONPATH=. uvx --with pytest pytest
+```
+
+`NATIVEAPI_LIBRARY=/path/to/libnativeapi.dylib` overrides the lookup.
+
+## Contributing
+
+Development happens in [nativeapi-workspace](https://github.com/libnativeapi/nativeapi-workspace), which holds every binding and the code generator and checks out the core library as a submodule:
+
+```bash
+git clone --recursive https://github.com/libnativeapi/nativeapi-workspace.git
+```
+
+Files marked `AUTO-GENERATED. DO NOT EDIT.` are generated from the C++ headers in [nativeapi](https://github.com/libnativeapi/nativeapi-core). To change the API, send a pull request there; maintainers regenerate the bindings.
+
+- API requests and native behavior bugs → [nativeapi-core issues](https://github.com/libnativeapi/nativeapi-core/issues)
+- Bugs specific to one binding → [nativeapi-workspace issues](https://github.com/libnativeapi/nativeapi-workspace/issues)
+- Not sure → [nativeapi-core issues](https://github.com/libnativeapi/nativeapi-core/issues)
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +/build/
 +/dist/
 +/cxx_impl/
 +*.egg-info/
 +.venv/