Metadata-Version: 2.4
Name: py-admin-launch
Version: 0.1.3
Summary: A cross-platform command launcher for administrator privileges.
Author: GGN_2015
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# py-admin-launch

A cross-platform Python command/helper to launch a specified program with
administrator privileges.

## Strategy

- Linux desktop: `pkexec` for polkit GUI authentication, falling back to `sudo`
  when `pkexec` is not available. GUI session variables such as `DISPLAY`,
  `XAUTHORITY`, `WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR`, and
  `DBUS_SESSION_BUS_ADDRESS` are passed explicitly so desktop apps can still
  reach the current display after elevation.
- Windows: `ShellExecuteW(..., "runas", ...)`.
- macOS: `osascript` + `with administrator privileges`, falling back to `sudo`
  when `osascript` is not available.

If the current process is already administrator/root, the command is launched
directly as the current user.

## CLI

Run from source:

```bash
python -m py_admin_launch -- your-command arg1 arg2
```

After installing the package:

```bash
py-admin-launch -- your-command arg1 arg2
```

Useful options:

```bash
py-admin-launch --cwd /path/to/workdir -- your-command arg1 arg2
py-admin-launch --no-wait -- your-command arg1 arg2
```

The CLI waits by default. On Linux and macOS, that means `py-admin-launch`
returns the elevated command's exit code, including failures such as cancelled
authentication or a failed `pkexec`/`sudo` invocation. This matches the behavior
users usually expect from commands like `sudo your-command`.

Use `--no-wait` only when you intentionally want to start the command in the
background and return after the elevation request is handed off. In that mode,
the launcher cannot report the elevated command's later exit code.

On Windows, elevated launches use `ShellExecuteW(..., "runas", ...)`, which does
not provide a child process handle to this helper. That means the CLI cannot
observe the elevated program's exit code on Windows.

## Python API

```python
from py_admin_launch import launch

launch(["python", "-m", "http.server", "80"])
```

`launch()` accepts a command list plus optional `cwd` and `wait` arguments:

```python
result = launch(["your-command", "arg1"], cwd="/tmp", wait=True)
print(result.elevated, result.returncode)
```

When `wait=True`, `returncode` is the launched command's exit code where the
platform exposes one. When `wait=False`, `returncode` is `None`.
