# PyUAC - Python User Access Control for Windows
This package provides a way to invoke User Access Control (UAC) in Windows from Python.
This allows a Python process to re-spawn a new process with Administrator level rights using
the UAC prompt. Note that the original process is not elevated; a new process is created.
The main purpose of pyuac is to allow command line Python scripts to ensure they are run
as Administrator on Windows. There is no ability to execute only parts of a program
as Administrator - the entire script is re-launched with the same command line. You can
also override the command line used for the admin process.
See also [pyuac on the Python Package Index (PyPI)](https://pypi.org/project/pyuac)
## Usage and examples
There are two basic ways to use this library. Perhaps the simplest way is to decorate your
Python command line script's main function. The other is to directly use the `isUserAdmin`
and `runAsAdmin` functions yourself. The decorator allows you to automatically capture
the output of the Admin process and return that output string to the non-admin parent process.
See also [tests/example_usage.py](tests/example_usage.py)
### Decorator
The decorator is an easy way to ensure your script's main() function will respawn itself
as Admin if necessary. Note that the decorator has no effect unless on the Windows platform.
It does NOT currently relaunch the script with 'sudo' on Linux or other POSIX platforms.
On non-Windows platforms, it's a no-op.
#### Decorator usage example
```python
from pyuac import main_requires_admin
@main_requires_admin
def main():
print("Do stuff here that requires being run as an admin.")
# The window will disappear as soon as the program exits!
input("Press enter to close the window. >")
if __name__ == "__main__":
main()
```
#### Capture stdout from admin process
You can also capture the stdout and stderr of your Admin sub-process if you need to check
it for errors from the non-admin parent. By default, unless you set scan_for_error=False on
the decorator, it will check the last line of both stdout and stderr for the words 'error'
or 'exception', and if it finds those, will raise RuntimeError on the parent non-admin side.
```python
from pyuac import main_requires_admin
@main_requires_admin(return_output=True)
def main():
print("Do stuff here that requires being run as an admin.")
# The window will disappear as soon as the program exits!
input("Press enter to close the window. >")
if __name__ == "__main__":
rv = main()
if not rv:
print("I must have already been Admin!")
else:
admin_stdout_str, admin_stderr_str, *_ = rv
if "Do stuff" in admin_stdout_str:
print("It worked.")
```
### Direct usage
There are two main direct usage functions provided:
isUserAdmin()
This returns a boolean to indicate whether the current user has elevated Administrator status.
runAsAdmin()
Re-launch the current process (or the given command line) as an Administrator.
This will trigger the UAC (User Access Control) prompt if necessary.
#### Direct usage example
This shows a typical usage pattern:
```python
import pyuac
def main():
print("Do stuff here that requires being run as an admin.")
# The window will disappear as soon as the program exits!
input("Press enter to close the window. >")
if __name__ == "__main__":
if not pyuac.isUserAdmin():
print("Re-launching as admin!")
pyuac.runAsAdmin()
else:
main() # Already an admin here.
```
## Requirements
* This package only supports Windows at the moment. The isUserAdmin function will work under
Linux / Posix, but the runAsAdmin functionality is currently Windows only. Using the
`@main_requires_admin` decorator will be a no-op on non-Windows platforms.
* This requires Python 2.7, or Python 3.3 or higher.
* This requires the [PyWin32](https://pypi.org/project/pywin32/) package to be installed.
https://pypi.org/project/pywin32/
https://github.com/mhammond/pywin32
* It also depends on the packages [decorator](https://pypi.org/project/decorator/)
and [tee](https://pypi.org/project/tee/)
## PyWin32 problems
The PyWin32 package is required by this library (pyuac).
If you get ImportError or ModuleNotFoundError when you run this, usually that means
PyWin32 is either not installed at all, or else the installation is incomplete; see below.
PyWin32 can be installed via pip, but sometimes there are problems completing the installation
scripts which install the COM object support required by pyuac.
Typically, this can be fixed doing the following:
* Launching a command prompt as Administrator
* Activate your Python virtual environment, if needed.
* `pip install pywin32`
* `python venv\Scripts\pywin32_postinstall.py -install`
Replace `venv` above with the path to your Python installation.
* Then, in a regular non-admin command prompt, activate your Python and try this:
* `python -c "from win32com.shell import shellcon"`
If that throws an error, the PyWin32 installation was not successful. Try removing it from pip
and reinstalling it under the Admin command prompt, and then run the postinstall script again.
If all else fails, and you are using a system-installed Python (not a virtualenv) then you
can try downloading the PyWin32 .exe installer.
## Changelog
See [CHANGELOG.md](CHANGELOG.md)
## Credits
This program was originally written by Preston Landers and is provided courtesy of
[Journyx, Inc.](https://www.journyx.com)
## License
See the [LICENSE file](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/Preston-Landers/pyuac",
"name": "pyuac",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*",
"maintainer_email": "",
"keywords": "",
"author": "Preston Landers",
"author_email": "planders@utexas.edu",
"download_url": "https://files.pythonhosted.org/packages/d1/b4/b4d82bea65a5c8cd0cdcf285821481e25eba21578e29c667d90d28007808/pyuac-0.0.3.tar.gz",
"platform": "",
"description": "# PyUAC - Python User Access Control for Windows\n\nThis package provides a way to invoke User Access Control (UAC) in Windows from Python.\n\nThis allows a Python process to re-spawn a new process with Administrator level rights using\nthe UAC prompt. Note that the original process is not elevated; a new process is created.\n\nThe main purpose of pyuac is to allow command line Python scripts to ensure they are run\nas Administrator on Windows. There is no ability to execute only parts of a program \nas Administrator - the entire script is re-launched with the same command line. You can\nalso override the command line used for the admin process.\n\nSee also [pyuac on the Python Package Index (PyPI)](https://pypi.org/project/pyuac)\n\n## Usage and examples\n\nThere are two basic ways to use this library. Perhaps the simplest way is to decorate your \nPython command line script's main function. The other is to directly use the `isUserAdmin`\nand `runAsAdmin` functions yourself. The decorator allows you to automatically capture\nthe output of the Admin process and return that output string to the non-admin parent process.\n\nSee also [tests/example_usage.py](tests/example_usage.py)\n\n### Decorator\n\nThe decorator is an easy way to ensure your script's main() function will respawn itself\nas Admin if necessary. Note that the decorator has no effect unless on the Windows platform.\nIt does NOT currently relaunch the script with 'sudo' on Linux or other POSIX platforms.\nOn non-Windows platforms, it's a no-op.\n\n#### Decorator usage example\n\n```python\nfrom pyuac import main_requires_admin\n\n@main_requires_admin\ndef main():\n print(\"Do stuff here that requires being run as an admin.\")\n # The window will disappear as soon as the program exits!\n input(\"Press enter to close the window. >\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n#### Capture stdout from admin process\n\nYou can also capture the stdout and stderr of your Admin sub-process if you need to check\nit for errors from the non-admin parent. By default, unless you set scan_for_error=False on\nthe decorator, it will check the last line of both stdout and stderr for the words 'error'\nor 'exception', and if it finds those, will raise RuntimeError on the parent non-admin side.\n\n```python\nfrom pyuac import main_requires_admin\n\n@main_requires_admin(return_output=True)\ndef main():\n print(\"Do stuff here that requires being run as an admin.\")\n # The window will disappear as soon as the program exits!\n input(\"Press enter to close the window. >\")\n\nif __name__ == \"__main__\":\n rv = main()\n if not rv:\n print(\"I must have already been Admin!\")\n else:\n admin_stdout_str, admin_stderr_str, *_ = rv\n if \"Do stuff\" in admin_stdout_str:\n print(\"It worked.\")\n```\n\n### Direct usage\n\nThere are two main direct usage functions provided:\n\n isUserAdmin()\nThis returns a boolean to indicate whether the current user has elevated Administrator status.\n\n runAsAdmin()\nRe-launch the current process (or the given command line) as an Administrator. \nThis will trigger the UAC (User Access Control) prompt if necessary.\n\n#### Direct usage example\n\nThis shows a typical usage pattern:\n\n```python\nimport pyuac\n\ndef main():\n print(\"Do stuff here that requires being run as an admin.\")\n # The window will disappear as soon as the program exits!\n input(\"Press enter to close the window. >\")\n\nif __name__ == \"__main__\":\n if not pyuac.isUserAdmin():\n print(\"Re-launching as admin!\")\n pyuac.runAsAdmin()\n else: \n main() # Already an admin here.\n```\n\n## Requirements\n\n* This package only supports Windows at the moment. The isUserAdmin function will work under\n Linux / Posix, but the runAsAdmin functionality is currently Windows only. Using the\n `@main_requires_admin` decorator will be a no-op on non-Windows platforms.\n\n* This requires Python 2.7, or Python 3.3 or higher.\n\n* This requires the [PyWin32](https://pypi.org/project/pywin32/) package to be installed.\n\nhttps://pypi.org/project/pywin32/\nhttps://github.com/mhammond/pywin32\n\n* It also depends on the packages [decorator](https://pypi.org/project/decorator/) \nand [tee](https://pypi.org/project/tee/)\n\n## PyWin32 problems\n\nThe PyWin32 package is required by this library (pyuac).\n\nIf you get ImportError or ModuleNotFoundError when you run this, usually that means\nPyWin32 is either not installed at all, or else the installation is incomplete; see below.\n\nPyWin32 can be installed via pip, but sometimes there are problems completing the installation\nscripts which install the COM object support required by pyuac.\n\nTypically, this can be fixed doing the following:\n\n* Launching a command prompt as Administrator\n* Activate your Python virtual environment, if needed.\n* `pip install pywin32`\n* `python venv\\Scripts\\pywin32_postinstall.py -install`\n\nReplace `venv` above with the path to your Python installation. \n\n* Then, in a regular non-admin command prompt, activate your Python and try this:\n* `python -c \"from win32com.shell import shellcon\"`\n\nIf that throws an error, the PyWin32 installation was not successful. Try removing it from pip\nand reinstalling it under the Admin command prompt, and then run the postinstall script again.\n\nIf all else fails, and you are using a system-installed Python (not a virtualenv) then you\ncan try downloading the PyWin32 .exe installer.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## Credits\n\nThis program was originally written by Preston Landers and is provided courtesy of \n[Journyx, Inc.](https://www.journyx.com)\n\n## License\n\nSee the [LICENSE file](LICENSE)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for Windows User Access Control (UAC)",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/Preston-Landers/pyuac",
"Source": "https://github.com/Preston-Landers/pyuac"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6654cc39101176508733f644b1fdff183f60ff25c35e1e3e0eac9740233b4aa",
"md5": "1cd22802f90f16065d91c55fa7627f37",
"sha256": "cf0e1de597388744daa308e4f83019885caa0c646246a7e94713a77652701600"
},
"downloads": -1,
"filename": "pyuac-0.0.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cd22802f90f16065d91c55fa7627f37",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*",
"size": 11703,
"upload_time": "2020-11-09T01:25:14",
"upload_time_iso_8601": "2020-11-09T01:25:14.646960Z",
"url": "https://files.pythonhosted.org/packages/b6/65/4cc39101176508733f644b1fdff183f60ff25c35e1e3e0eac9740233b4aa/pyuac-0.0.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1b4b4d82bea65a5c8cd0cdcf285821481e25eba21578e29c667d90d28007808",
"md5": "1175c5c4769263c7164d69c53ed6ec71",
"sha256": "fd11caf47246e0a5149284ced014c346439ae3a28c6bad0b622b239fe30d2d5b"
},
"downloads": -1,
"filename": "pyuac-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "1175c5c4769263c7164d69c53ed6ec71",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*",
"size": 8747,
"upload_time": "2020-11-09T01:25:16",
"upload_time_iso_8601": "2020-11-09T01:25:16.643219Z",
"url": "https://files.pythonhosted.org/packages/d1/b4/b4d82bea65a5c8cd0cdcf285821481e25eba21578e29c667d90d28007808/pyuac-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-11-09 01:25:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Preston-Landers",
"github_project": "pyuac",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyuac"
}
JSON
