keep-awake 1.2.0__tar.gz

keep_awake-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kevin Chen
+
+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.

keep_awake-1.2.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+
+recursive-include native_code *.c *.h
+
+exclude AGENTS.md
+exclude .gitignore
+prune .venv
+prune .github
+prune .claude
+prune .vscode
+prune tests
+prune docs
+prune build
+prune dist

keep_awake-1.2.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: keep_awake
+Version: 1.2.0
+Summary: Prevent your computer from going to sleep.
+Author-email: Kevin Chen <1354016594@qq.com>
+License: MIT
+Project-URL: Home-page, https://github.com/czf0613/keep_awake_py
+Keywords: sleep,prevent,awake,idle
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: linux
+Requires-Dist: jeepney>=0.9.0; extra == "linux"
+Dynamic: license
+Dynamic: license-file
+
+# Keep Awake
+
+Prevent idle system sleep and keep the display awake while Python is doing work.
+Supports **CPython 3.8+**, including free-threaded (no-GIL) CPython 3.13/3.14.
+
+## Installation
+
+```sh
+# Windows / macOS
+pip install keep_awake
+
+# Linux desktop
+pip install 'keep_awake[linux]'
+```
+
+Windows and macOS use a C extension. A matching wheel avoids a local compiler;
+otherwise installation builds from source. Linux uses the pure Python
+[Jeepney](https://jeepney.readthedocs.io/en/latest/) D-Bus client and requires no
+project C extension or D-Bus development headers.
+
+## Usage
+
+```python
+from keep_awake import prevent_sleep, allow_sleep
+
+if not prevent_sleep():
+    raise RuntimeError("Could not acquire a sleep inhibitor")
+try:
+    # Do long-running work here.
+    pass
+finally:
+    allow_sleep()
+```
+
+For automatic cleanup:
+
+```python
+from keep_awake import KeepAwakeGuard
+
+with KeepAwakeGuard():
+    # Do long-running work here.
+    pass
+```
+
+- Every successful `prevent_sleep()` adds one reference and returns `True`.
+  Failure returns `False` without adding a reference.
+- Pair each successful acquisition with one `allow_sleep()`, which returns `None`.
+  The OS inhibitor is released only when the shared reference count reaches zero.
+  Calling `allow_sleep()` when the count is already zero does nothing.
+- Calls are synchronized across threads, including no-GIL builds. All callers
+  share **one OS inhibitor with a reference count**. If thread A acquires and
+  thread B acquires then releases, the count changes `1 → 2 → 1`, so sleep remains
+  inhibited until A releases. A release may happen on a different thread.
+- Use the public API only. Calling the private C extension directly bypasses
+  synchronization, reference counting and exit cleanup, and is unsupported.
+- Nested and overlapping `KeepAwakeGuard` scopes are supported, including reuse
+  of the same guard. Each scope releases only its own successful acquisition.
+  Acquisition failure still does not raise; use the boolean-returning API when
+  success is required.
+- On normal interpreter shutdown, one shared `atexit` handler releases the backend
+  even if several references remain. Acquisitions after this cleanup return `False`.
+  Forced termination, interpreter crashes and `os._exit()` bypass this handler;
+  use a guard or `try/finally` for cleanup during normal execution.
+  These requests do not override manual sleep, lid closure, or administrator power
+  policy.
+
+## Platforms
+
+| Platform | Implementation |
+| --- | --- |
+| macOS arm64 / x86_64 | IOKit display-idle assertion, serialized by the Python API |
+| Windows x86_64 / ARM64 | `SetThreadExecutionState` on a dedicated, synchronized worker |
+| Linux desktop | GNOME SessionManager, falling back to `org.freedesktop.ScreenSaver` |
+
+On Linux, run inside a logged-in graphical session with
+`DBUS_SESSION_BUS_ADDRESS` set and a supported inhibition service. GNOME requests
+suspend and idle inhibition; the freedesktop fallback depends on the desktop's
+implementation of idle inhibition. Headless servers and minimal compositors may
+not provide either service. An unavailable bus/service returns `False`; omitting
+the required `linux` extra produces a dependency import error.
+
+The connection opens on first acquisition and closes on release, including when
+release fails. If the desktop/session service restarts, release and reacquire the
+inhibitor. Actual GNOME/KDE power behavior still requires desktop validation.
+
+Native Windows ARM64 wheels are built for Python 3.11–3.14 and 3.13t/3.14t.
+Python 3.8–3.10 remains supported on Windows x86_64. This matches the native ARM64
+interpreters available through uv.
+
+## Migrating from the idempotent API
+
+Repeated successful calls now require matching releases. Code that previously
+called `prevent_sleep()` many times but released only once must balance its calls
+or use a guard around each unit of work. Do not manually release an acquisition
+already owned by a guard, or release after a failed acquisition: the counter is
+shared and cannot identify a mismatched manual release.
+
+## Development and publishing
+
+```sh
+uv sync --frozen
+uv run --frozen pytest -q
+uv build
+```
+
+CI checks Python 3.8–3.14 and free-threaded 3.13t/3.14t on Linux, Windows x86_64 and
+both macOS architectures, plus the six Windows ARM64 configurations above,
+whenever changes reach `master` or a pull request targets it.
+Publishing a GitHub Release runs the checks and builds before uploading the
+sdist and native wheels to PyPI through Trusted Publishing.
+
+See [development and release instructions](https://github.com/czf0613/keep_awake_py/blob/master/docs/DEVELOPMENT.md),
+[compatibility findings and verification limits](https://github.com/czf0613/keep_awake_py/blob/master/docs/COMPATIBILITY.md), and
+[Codex repository guidance](https://github.com/czf0613/keep_awake_py/blob/master/AGENTS.md).
+
+## License
+
+[MIT](https://github.com/czf0613/keep_awake_py/blob/master/LICENSE)

keep_awake-1.2.0/README.md

@@ -0,0 +1,118 @@
+# Keep Awake
+
+Prevent idle system sleep and keep the display awake while Python is doing work.
+Supports **CPython 3.8+**, including free-threaded (no-GIL) CPython 3.13/3.14.
+
+## Installation
+
+```sh
+# Windows / macOS
+pip install keep_awake
+
+# Linux desktop
+pip install 'keep_awake[linux]'
+```
+
+Windows and macOS use a C extension. A matching wheel avoids a local compiler;
+otherwise installation builds from source. Linux uses the pure Python
+[Jeepney](https://jeepney.readthedocs.io/en/latest/) D-Bus client and requires no
+project C extension or D-Bus development headers.
+
+## Usage
+
+```python
+from keep_awake import prevent_sleep, allow_sleep
+
+if not prevent_sleep():
+    raise RuntimeError("Could not acquire a sleep inhibitor")
+try:
+    # Do long-running work here.
+    pass
+finally:
+    allow_sleep()
+```
+
+For automatic cleanup:
+
+```python
+from keep_awake import KeepAwakeGuard
+
+with KeepAwakeGuard():
+    # Do long-running work here.
+    pass
+```
+
+- Every successful `prevent_sleep()` adds one reference and returns `True`.
+  Failure returns `False` without adding a reference.
+- Pair each successful acquisition with one `allow_sleep()`, which returns `None`.
+  The OS inhibitor is released only when the shared reference count reaches zero.
+  Calling `allow_sleep()` when the count is already zero does nothing.
+- Calls are synchronized across threads, including no-GIL builds. All callers
+  share **one OS inhibitor with a reference count**. If thread A acquires and
+  thread B acquires then releases, the count changes `1 → 2 → 1`, so sleep remains
+  inhibited until A releases. A release may happen on a different thread.
+- Use the public API only. Calling the private C extension directly bypasses
+  synchronization, reference counting and exit cleanup, and is unsupported.
+- Nested and overlapping `KeepAwakeGuard` scopes are supported, including reuse
+  of the same guard. Each scope releases only its own successful acquisition.
+  Acquisition failure still does not raise; use the boolean-returning API when
+  success is required.
+- On normal interpreter shutdown, one shared `atexit` handler releases the backend
+  even if several references remain. Acquisitions after this cleanup return `False`.
+  Forced termination, interpreter crashes and `os._exit()` bypass this handler;
+  use a guard or `try/finally` for cleanup during normal execution.
+  These requests do not override manual sleep, lid closure, or administrator power
+  policy.
+
+## Platforms
+
+| Platform | Implementation |
+| --- | --- |
+| macOS arm64 / x86_64 | IOKit display-idle assertion, serialized by the Python API |
+| Windows x86_64 / ARM64 | `SetThreadExecutionState` on a dedicated, synchronized worker |
+| Linux desktop | GNOME SessionManager, falling back to `org.freedesktop.ScreenSaver` |
+
+On Linux, run inside a logged-in graphical session with
+`DBUS_SESSION_BUS_ADDRESS` set and a supported inhibition service. GNOME requests
+suspend and idle inhibition; the freedesktop fallback depends on the desktop's
+implementation of idle inhibition. Headless servers and minimal compositors may
+not provide either service. An unavailable bus/service returns `False`; omitting
+the required `linux` extra produces a dependency import error.
+
+The connection opens on first acquisition and closes on release, including when
+release fails. If the desktop/session service restarts, release and reacquire the
+inhibitor. Actual GNOME/KDE power behavior still requires desktop validation.
+
+Native Windows ARM64 wheels are built for Python 3.11–3.14 and 3.13t/3.14t.
+Python 3.8–3.10 remains supported on Windows x86_64. This matches the native ARM64
+interpreters available through uv.
+
+## Migrating from the idempotent API
+
+Repeated successful calls now require matching releases. Code that previously
+called `prevent_sleep()` many times but released only once must balance its calls
+or use a guard around each unit of work. Do not manually release an acquisition
+already owned by a guard, or release after a failed acquisition: the counter is
+shared and cannot identify a mismatched manual release.
+
+## Development and publishing
+
+```sh
+uv sync --frozen
+uv run --frozen pytest -q
+uv build
+```
+
+CI checks Python 3.8–3.14 and free-threaded 3.13t/3.14t on Linux, Windows x86_64 and
+both macOS architectures, plus the six Windows ARM64 configurations above,
+whenever changes reach `master` or a pull request targets it.
+Publishing a GitHub Release runs the checks and builds before uploading the
+sdist and native wheels to PyPI through Trusted Publishing.
+
+See [development and release instructions](https://github.com/czf0613/keep_awake_py/blob/master/docs/DEVELOPMENT.md),
+[compatibility findings and verification limits](https://github.com/czf0613/keep_awake_py/blob/master/docs/COMPATIBILITY.md), and
+[Codex repository guidance](https://github.com/czf0613/keep_awake_py/blob/master/AGENTS.md).
+
+## License
+
+[MIT](https://github.com/czf0613/keep_awake_py/blob/master/LICENSE)

keep_awake-1.2.0/native_code/include/pm.h

@@ -0,0 +1,11 @@
+#ifndef PM_H
+#define PM_H
+
+#include <Python.h>
+#include <stdbool.h>
+
+PyObject *pm_prevent_sleep(PyObject *self, PyObject *args);
+
+PyObject *pm_allow_sleep(PyObject *self, PyObject *args);
+
+#endif // PM_H

keep_awake-1.2.0/native_code/src/ext.c

@@ -0,0 +1,27 @@
+#include <Python.h>
+#include "pm.h"
+
+static PyMethodDef ModMethods[] = {
+    {"_prevent_sleep", pm_prevent_sleep, METH_NOARGS, NULL},
+    {"_allow_sleep", pm_allow_sleep, METH_NOARGS, NULL},
+    {NULL, NULL, 0, NULL}};
+
+static struct PyModuleDef module = {
+    PyModuleDef_HEAD_INIT,
+    "_native_api",
+    NULL,
+    -1,
+    ModMethods};
+
+PyMODINIT_FUNC PyInit__native_api(void)
+{
+    PyObject *m = PyModule_Create(&module);
+    if (m == NULL)
+    {
+        return NULL;
+    }
+#ifdef Py_GIL_DISABLED
+    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);
+#endif
+    return m;
+}

keep_awake-1.2.0/native_code/src/pm_macos.c

@@ -0,0 +1,47 @@
+#include "pm.h"
+#include <IOKit/pwr_mgt/IOPMLib.h>
+#include <CoreFoundation/CoreFoundation.h>
+
+/* All entry points require the public Python API's lock. */
+static IOPMAssertionID sleepAssertion = kIOPMNullAssertionID;
+#define reasonForActive CFSTR("需要保持系统活动以确保后台任务执行")
+
+static bool prevent_sleep(void)
+{
+    bool success = true;
+    if (sleepAssertion == kIOPMNullAssertionID)
+    {
+        IOReturn status = IOPMAssertionCreateWithName(kIOPMAssertionTypePreventUserIdleDisplaySleep, kIOPMAssertionLevelOn, reasonForActive, &sleepAssertion);
+
+        success &= (status == kIOReturnSuccess);
+    }
+
+    return success;
+}
+
+static void allow_sleep(void)
+{
+    if (sleepAssertion != kIOPMNullAssertionID)
+    {
+        IOPMAssertionRelease(sleepAssertion);
+        sleepAssertion = kIOPMNullAssertionID;
+    }
+}
+
+PyObject *pm_prevent_sleep(PyObject *self, PyObject *args)
+{
+    if (prevent_sleep())
+    {
+        Py_RETURN_TRUE;
+    }
+    else
+    {
+        Py_RETURN_FALSE;
+    }
+}
+
+PyObject *pm_allow_sleep(PyObject *self, PyObject *args)
+{
+    allow_sleep();
+    Py_RETURN_NONE;
+}

keep_awake-1.2.0/native_code/src/pm_windows.c

@@ -0,0 +1,99 @@
+#include "pm.h"
+#include <windows.h>
+
+/* All entry points require the public Python API's lock.
+ * The ready/stop events synchronize communication with the native worker. */
+static HANDLE h_thread = NULL;
+static HANDLE stop_event = NULL;
+static HANDLE ready_event = NULL;
+static bool started = false;
+
+static DWORD WINAPI run_forever(LPVOID args)
+{
+    started = SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_DISPLAY_REQUIRED) != 0;
+    SetEvent(ready_event);
+    if (started)
+    {
+        WaitForSingleObject(stop_event, INFINITE);
+        SetThreadExecutionState(ES_CONTINUOUS);
+    }
+    return 0;
+}
+
+/* Called with the public Python lock held, after any worker has exited. */
+static void close_handles(void)
+{
+    if (h_thread != NULL)
+    {
+        CloseHandle(h_thread);
+        h_thread = NULL;
+    }
+    if (stop_event != NULL)
+    {
+        CloseHandle(stop_event);
+        stop_event = NULL;
+    }
+    if (ready_event != NULL)
+    {
+        CloseHandle(ready_event);
+        ready_event = NULL;
+    }
+}
+
+static bool prevent_sleep(void)
+{
+    if (h_thread != NULL)
+    {
+        return true;
+    }
+    stop_event = CreateEventW(NULL, TRUE, FALSE, NULL);
+    ready_event = CreateEventW(NULL, TRUE, FALSE, NULL);
+    if (stop_event == NULL || ready_event == NULL)
+    {
+        close_handles();
+        return false;
+    }
+    started = false;
+    h_thread = CreateThread(NULL, 0, run_forever, NULL, 0, NULL);
+    if (h_thread == NULL)
+    {
+        close_handles();
+        return false;
+    }
+    WaitForSingleObject(ready_event, INFINITE);
+    bool success = started;
+    if (!success)
+    {
+        WaitForSingleObject(h_thread, INFINITE);
+        close_handles();
+    }
+    return success;
+}
+
+static void allow_sleep(void)
+{
+    if (h_thread != NULL)
+    {
+        SetEvent(stop_event);
+        WaitForSingleObject(h_thread, INFINITE);
+        close_handles();
+    }
+}
+
+PyObject *pm_prevent_sleep(PyObject *self, PyObject *args)
+{
+    if (prevent_sleep())
+    {
+        Py_RETURN_TRUE;
+    }
+    else
+    {
+        Py_RETURN_FALSE;
+    }
+}
+
+PyObject *pm_allow_sleep(PyObject *self, PyObject *args)
+{
+    allow_sleep();
+    Py_RETURN_NONE;
+}

keep_awake-1.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "keep_awake"
+version = "1.2.0"
+description = "Prevent your computer from going to sleep."
+readme = "README.md"
+keywords = ["sleep", "prevent", "awake", "idle"]
+authors = [{ name = "Kevin Chen", email = "1354016594@qq.com" }]
+dynamic = ["license"]
+requires-python = ">=3.8"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = []
+optional-dependencies = { linux = ["jeepney>=0.9.0"] }
+
+[project.urls]
+Home-page = "https://github.com/czf0613/keep_awake_py"
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.1",
+    "setuptools>=64",
+    "jeepney>=0.9.0",
+]
+
+[tool.pytest.ini_options]
+markers = ["desktop: requires a real Linux desktop session (opt in with KEEP_AWAKE_DESKTOP_TEST=1)"]

keep_awake-1.2.0/setup.cfg

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

keep_awake-1.2.0/setup.py

@@ -0,0 +1,37 @@
+from setuptools import setup, Extension
+import sys
+import sysconfig
+
+c_modules = []
+os_platform = sys.platform
+macros = (
+    [("Py_GIL_DISABLED", "1")] if sysconfig.get_config_var("Py_GIL_DISABLED") else []
+)
+
+if os_platform == "win32":
+    c_modules.append(
+        Extension(
+            "keep_awake._native_api",
+            sources=["native_code/src/pm_windows.c", "native_code/src/ext.c"],
+            include_dirs=["native_code/include"],
+            extra_compile_args=["/utf-8"],
+            define_macros=macros,
+        )
+    )
+elif os_platform == "darwin":
+    c_modules.append(
+        Extension(
+            "keep_awake._native_api",
+            sources=["native_code/src/pm_macos.c", "native_code/src/ext.c"],
+            include_dirs=["native_code/include"],
+            extra_link_args=["-framework", "CoreFoundation", "-framework", "IOKit"],
+        )
+    )
+elif os_platform == "linux":
+    # nothing todo, native python implementation
+    pass
+else:
+    raise ValueError("Unsupported platform")
+
+# SPDX project.license strings require setuptools versions unavailable on Python 3.8.
+setup(ext_modules=c_modules, license="MIT")

keep_awake-1.2.0/src/keep_awake/__init__.py

@@ -0,0 +1,109 @@
+import atexit
+import sys
+from threading import Lock, local
+from typing import final
+
+__all__ = ["prevent_sleep", "allow_sleep", "KeepAwakeGuard"]
+os_platform = sys.platform
+_mutex = Lock()
+_references = 0
+_shutting_down = False
+
+
+def prevent_sleep() -> bool:
+    """Acquire one sleep-prevention reference; failed requests are not counted."""
+    global _references
+    with _mutex:
+        if _shutting_down:
+            return False
+        if _references == 0 and not _acquire_backend():
+            return False
+        _references += 1
+        return True
+
+
+def allow_sleep() -> None:
+    """Release one reference, allowing sleep only after the last release."""
+    global _references
+    with _mutex:
+        if _references == 0:
+            return
+        if _references == 1:
+            try:
+                _release_backend()
+            finally:
+                # Backends clean up even if release is interrupted. Never cache
+                # success after the underlying inhibitor may have been removed.
+                _references = 0
+        else:
+            _references -= 1
+
+
+def _shutdown() -> None:
+    """Release all outstanding references and prevent new work during exit."""
+    global _references, _shutting_down
+    with _mutex:
+        _shutting_down = True
+        try:
+            if _references:
+                _release_backend()
+        finally:
+            _references = 0
+
+
+def _acquire_backend() -> bool:
+
+    # in macOS and windows, just call the native api
+    if os_platform in ["darwin", "win32"]:
+        from ._native_api import _prevent_sleep
+
+        return _prevent_sleep()
+    elif os_platform == "linux":
+        # in linux, use dbus to send a message to avoid sleep
+        from .dbus_api import session_on
+
+        return session_on()
+    else:
+        raise NotImplementedError(f"Platform '{os_platform}' is not supported.")
+
+
+def _release_backend() -> None:
+    if os_platform in ["darwin", "win32"]:
+        from ._native_api import _allow_sleep
+
+        _allow_sleep()
+    elif os_platform == "linux":
+        from .dbus_api import session_off
+
+        session_off()
+    else:
+        raise NotImplementedError(f"Platform '{os_platform}' is not supported.")
+
+
+atexit.register(_shutdown)
+
+
+@final
+class KeepAwakeGuard:
+    """Own a reference for each successful entry, including nested scopes."""
+
+    def __init__(self):
+        # One guard may be nested or shared across threads. Failed entries must
+        # never consume another entry's successful acquisition.
+        self._state = local()
+
+    def __enter__(self):
+        if not hasattr(self._state, "entries"):
+            self._state.entries = []
+        entries = self._state.entries
+        entries.append(False)
+        try:
+            entries[-1] = prevent_sleep()
+        except BaseException:
+            entries.pop()
+            raise
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        entries = getattr(self._state, "entries", ())
+        if entries and entries.pop():
+            allow_sleep()

keep_awake-1.2.0/src/keep_awake/_native_api.pyi

@@ -0,0 +1,18 @@
+# Native API for keep_awake module
+
+def _prevent_sleep() -> bool:
+    """Prevent the system from sleeping. Returns True if successful, False otherwise.
+    Now the screen will not turn off and system will not go to sleep.
+    Requires the public Python API's lock, including on free-threaded CPython.
+    Direct calls to this private extension are unsupported and are not synchronized.
+    Repeated calls share one process-wide inhibitor; they are not reference counted.
+    The public Python API manages reference counting around this private backend.
+    """
+    pass
+
+def _allow_sleep() -> None:
+    """Release the inhibitor; requires the public Python API's lock.
+
+    Sequential repeated releases are safe. Direct calls are unsupported.
+    """
+    pass

keep_awake-1.2.0/src/keep_awake/dbus_api.py

@@ -0,0 +1,112 @@
+"""Linux desktop inhibition over a private, lazily opened D-Bus connection."""
+
+import logging
+from threading import Lock
+from typing import Optional
+
+from jeepney import DBusAddress, DBusErrorResponse, MessageType, new_method_call
+from jeepney.io.blocking import DBusConnection, open_dbus_connection
+
+_logger = logging.getLogger(__name__)
+_mutex = Lock()
+_connection: Optional[DBusConnection] = None
+_cookie: Optional[int] = None
+_backend = None
+_timeout = 5.0
+_app_id = "org.python.keep_awake"
+_reason = "Keep system and screen awake"
+
+# GNOME flags: suspend (4) | idle (8). Method capitalization differs by API.
+_backends = (
+    (
+        DBusAddress(
+            "/org/gnome/SessionManager",
+            "org.gnome.SessionManager",
+            "org.gnome.SessionManager",
+        ),
+        "susu",
+        (_app_id, 0, _reason, 12),
+        "Uninhibit",
+    ),
+    (
+        DBusAddress(
+            "/org/freedesktop/ScreenSaver",
+            "org.freedesktop.ScreenSaver",
+            "org.freedesktop.ScreenSaver",
+        ),
+        "ss",
+        (_app_id, _reason),
+        "UnInhibit",
+    ),
+)
+
+
+def _call(connection, address, method, signature, body):
+    message = new_method_call(address, method, signature, body)
+    reply = connection.send_and_get_reply(message, timeout=_timeout)
+    if reply.header.message_type == MessageType.error:
+        raise DBusErrorResponse(reply)
+    return reply.body
+
+
+def _close(connection):
+    try:
+        connection.close()
+    except OSError:
+        _logger.debug("Failed to close the D-Bus connection", exc_info=True)
+
+
+def session_on() -> bool:
+    """Acquire one process-wide inhibitor, returning False if unavailable."""
+    global _connection, _cookie, _backend
+    with _mutex:
+        if _cookie is not None:
+            return True
+        connection = None
+        try:
+            connection = open_dbus_connection(bus="SESSION")
+            for backend in _backends:
+                address, signature, body, _ = backend
+                try:
+                    result = _call(connection, address, "Inhibit", signature, body)
+                except DBusErrorResponse:
+                    continue
+                if (
+                    len(result) != 1
+                    or type(result[0]) is not int
+                    or not 0 <= result[0] <= 0xFFFFFFFF
+                ):
+                    raise ValueError("Inhibit must return a UInt32 cookie")
+                _connection, _cookie, _backend = connection, result[0], backend
+                return True
+        except (
+            DBusErrorResponse,
+            OSError,
+            EOFError,
+            KeyError,
+            ValueError,
+            RuntimeError,
+            StopIteration,
+        ) as exc:
+            _logger.debug("Unable to inhibit the desktop session: %s", exc)
+        finally:
+            if connection is not None and connection is not _connection:
+                # Also releases an inhibitor whose reply was lost, malformed,
+                # or interrupted before ownership transferred to module state.
+                _close(connection)
+        return False
+
+
+def session_off() -> None:
+    """Release the inhibitor; disconnect even when the service cannot reply."""
+    global _connection, _cookie, _backend
+    with _mutex:
+        if _connection is None:
+            return
+        try:
+            _call(_connection, _backend[0], _backend[3], "u", (_cookie,))
+        except (DBusErrorResponse, OSError, EOFError, ValueError) as exc:
+            _logger.debug("Unable to release the desktop inhibitor: %s", exc)
+        finally:
+            _close(_connection)
+            _connection, _cookie, _backend = None, None, None

keep_awake-1.2.0/src/keep_awake/py.typed

@@ -0,0 +1,2 @@
+# This package contains type annotations.
+# See PEP 561 for more information.

keep_awake-1.2.0/src/keep_awake.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: keep_awake
+Version: 1.2.0
+Summary: Prevent your computer from going to sleep.
+Author-email: Kevin Chen <1354016594@qq.com>
+License: MIT
+Project-URL: Home-page, https://github.com/czf0613/keep_awake_py
+Keywords: sleep,prevent,awake,idle
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: linux
+Requires-Dist: jeepney>=0.9.0; extra == "linux"
+Dynamic: license
+Dynamic: license-file
+
+# Keep Awake
+
+Prevent idle system sleep and keep the display awake while Python is doing work.
+Supports **CPython 3.8+**, including free-threaded (no-GIL) CPython 3.13/3.14.
+
+## Installation
+
+```sh
+# Windows / macOS
+pip install keep_awake
+
+# Linux desktop
+pip install 'keep_awake[linux]'
+```
+
+Windows and macOS use a C extension. A matching wheel avoids a local compiler;
+otherwise installation builds from source. Linux uses the pure Python
+[Jeepney](https://jeepney.readthedocs.io/en/latest/) D-Bus client and requires no
+project C extension or D-Bus development headers.
+
+## Usage
+
+```python
+from keep_awake import prevent_sleep, allow_sleep
+
+if not prevent_sleep():
+    raise RuntimeError("Could not acquire a sleep inhibitor")
+try:
+    # Do long-running work here.
+    pass
+finally:
+    allow_sleep()
+```
+
+For automatic cleanup:
+
+```python
+from keep_awake import KeepAwakeGuard
+
+with KeepAwakeGuard():
+    # Do long-running work here.
+    pass
+```
+
+- Every successful `prevent_sleep()` adds one reference and returns `True`.
+  Failure returns `False` without adding a reference.
+- Pair each successful acquisition with one `allow_sleep()`, which returns `None`.
+  The OS inhibitor is released only when the shared reference count reaches zero.
+  Calling `allow_sleep()` when the count is already zero does nothing.
+- Calls are synchronized across threads, including no-GIL builds. All callers
+  share **one OS inhibitor with a reference count**. If thread A acquires and
+  thread B acquires then releases, the count changes `1 → 2 → 1`, so sleep remains
+  inhibited until A releases. A release may happen on a different thread.
+- Use the public API only. Calling the private C extension directly bypasses
+  synchronization, reference counting and exit cleanup, and is unsupported.
+- Nested and overlapping `KeepAwakeGuard` scopes are supported, including reuse
+  of the same guard. Each scope releases only its own successful acquisition.
+  Acquisition failure still does not raise; use the boolean-returning API when
+  success is required.
+- On normal interpreter shutdown, one shared `atexit` handler releases the backend
+  even if several references remain. Acquisitions after this cleanup return `False`.
+  Forced termination, interpreter crashes and `os._exit()` bypass this handler;
+  use a guard or `try/finally` for cleanup during normal execution.
+  These requests do not override manual sleep, lid closure, or administrator power
+  policy.
+
+## Platforms
+
+| Platform | Implementation |
+| --- | --- |
+| macOS arm64 / x86_64 | IOKit display-idle assertion, serialized by the Python API |
+| Windows x86_64 / ARM64 | `SetThreadExecutionState` on a dedicated, synchronized worker |
+| Linux desktop | GNOME SessionManager, falling back to `org.freedesktop.ScreenSaver` |
+
+On Linux, run inside a logged-in graphical session with
+`DBUS_SESSION_BUS_ADDRESS` set and a supported inhibition service. GNOME requests
+suspend and idle inhibition; the freedesktop fallback depends on the desktop's
+implementation of idle inhibition. Headless servers and minimal compositors may
+not provide either service. An unavailable bus/service returns `False`; omitting
+the required `linux` extra produces a dependency import error.
+
+The connection opens on first acquisition and closes on release, including when
+release fails. If the desktop/session service restarts, release and reacquire the
+inhibitor. Actual GNOME/KDE power behavior still requires desktop validation.
+
+Native Windows ARM64 wheels are built for Python 3.11–3.14 and 3.13t/3.14t.
+Python 3.8–3.10 remains supported on Windows x86_64. This matches the native ARM64
+interpreters available through uv.
+
+## Migrating from the idempotent API
+
+Repeated successful calls now require matching releases. Code that previously
+called `prevent_sleep()` many times but released only once must balance its calls
+or use a guard around each unit of work. Do not manually release an acquisition
+already owned by a guard, or release after a failed acquisition: the counter is
+shared and cannot identify a mismatched manual release.
+
+## Development and publishing
+
+```sh
+uv sync --frozen
+uv run --frozen pytest -q
+uv build
+```
+
+CI checks Python 3.8–3.14 and free-threaded 3.13t/3.14t on Linux, Windows x86_64 and
+both macOS architectures, plus the six Windows ARM64 configurations above,
+whenever changes reach `master` or a pull request targets it.
+Publishing a GitHub Release runs the checks and builds before uploading the
+sdist and native wheels to PyPI through Trusted Publishing.
+
+See [development and release instructions](https://github.com/czf0613/keep_awake_py/blob/master/docs/DEVELOPMENT.md),
+[compatibility findings and verification limits](https://github.com/czf0613/keep_awake_py/blob/master/docs/COMPATIBILITY.md), and
+[Codex repository guidance](https://github.com/czf0613/keep_awake_py/blob/master/AGENTS.md).
+
+## License
+
+[MIT](https://github.com/czf0613/keep_awake_py/blob/master/LICENSE)

keep_awake-1.2.0/src/keep_awake.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+native_code/include/pm.h
+native_code/src/ext.c
+native_code/src/pm_macos.c
+native_code/src/pm_windows.c
+src/keep_awake/__init__.py
+src/keep_awake/_native_api.pyi
+src/keep_awake/dbus_api.py
+src/keep_awake/py.typed
+src/keep_awake.egg-info/PKG-INFO
+src/keep_awake.egg-info/SOURCES.txt
+src/keep_awake.egg-info/dependency_links.txt
+src/keep_awake.egg-info/requires.txt
+src/keep_awake.egg-info/top_level.txt

keep_awake-1.2.0/src/keep_awake.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keep_awake-1.2.0/src/keep_awake.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[linux]
+jeepney>=0.9.0

keep_awake-1.2.0/src/keep_awake.egg-info/top_level.txt

@@ -0,0 +1 @@
+keep_awake