# EnergyMon Python Bindings
[](https://energymon-py.readthedocs.io/en/latest/?badge=latest)
This project provides Python bindings to [energymon](https://github.com/energymon/energymon) libraries.
If using this project for other scientific works or publications, please reference:
* Connor Imes, Lars Bergstrom, and Henry Hoffmann. "A Portable Interface for Runtime Energy Monitoring". In: FSE. 2016. DOI: https://doi.org/10.1145/2950290.2983956
<details>
<summary>[BibTex]</summary>
```BibTex
@inproceedings{imes2016energymon,
author = {Imes, Connor and Bergstrom, Lars and Hoffmann, Henry},
title = {A Portable Interface for Runtime Energy Monitoring},
year = {2016},
isbn = {9781450342186},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/2950290.2983956},
doi = {10.1145/2950290.2983956},
booktitle = {Proceedings of the 2016 24th ACM SIGSOFT International Symposium on Foundations of Software Engineering},
pages = {968–974},
numpages = {7},
keywords = {portable energy measurement},
location = {Seattle, WA, USA},
series = {FSE 2016}
}
```
## Dependencies
The `energymon` libraries should be installed to the system and on the library search path (e.g., `LD_LIBRARY_PATH` on Linux/POSIX systems or `DYLD_LIBRARY_PATH` on macOS systems).
The latest `energymon` C libraries can be found at https://github.com/energymon/energymon.
## Installing
Versioned releases of the `energymon` package are published in the Python Package Index and installable with pip:
```sh
pip install energymon
```
and through Conda Forge:
```sh
conda install energymon
```
To install from source:
```sh
pip install .
```
## Usage
The following subsections document usage with increasing levels of abstraction.
### Direct Bindings
At the lowest level, the `energymon` package exposes an `energymon` class, which is a binding to the `energymon` C struct.
To directly use the energymon API, first load the library, create and "get" the struct to populate its function pointers, then initialize, do work, and cleanup when finished.
For example:
```Python
from ctypes import CDLL, byref, create_string_buffer, sizeof, set_errno, get_errno
from ctypes.util import find_library
from energymon import energymon
# try to find the library by name:
lib_path = find_library('energymon-default')
if lib_path is None:
# maybe fall back on a relative or absolute path
lib_path = 'libenergymon-default.so'
lib = CDLL(lib_path, use_errno=True)
em = energymon()
if lib.energymon_get_default(byref(em)) != 0:
# handle error...
exit(1)
name = create_string_buffer(256)
if not em.fsource(name, sizeof(name)):
# handle error
exit(1)
print(name.value.decode())
if em.finit(byref(em)) != 0:
# handle error
exit(1)
set_errno(0)
uj = em.fread(byref(em))
if uj == 0 and get_errno() != 0:
# handle error (but don't skip cleanup!)
pass
if em.ffinish(byref(em)) != 0:
# handle error
exit(1)
```
### Utility Functions
Utility functions work with the direct bindings, but simplify their usage by (1) abstracting the user from the Python `ctypes` (including pointers) and (2) raising exceptions when errors are reported by the native library.
For example, to load the `energymon-default` library, "get" the energymon, and report the energy source and current value:
```Python
from energymon import util
lib = util.load_energymon_library()
em = util.get_energymon(lib)
print(util.get_source(em))
util.init(em)
try:
print(util.get_uj(em))
finally:
util.finish(em)
```
### Context Management
The `context` submodule provides the `EnergyMon` class, which is both a wrapper around `energymon` bindings and a Python context manager.
As a context manager, the class handles the `energymon` lifecycle, and is both reentrant and reusable.
For example, to use as a context manager:
```Python
from energymon.context import EnergyMon
with EnergyMon() as em:
print('source:', em.get_source())
print('reading (uJ):', em.get_uj())
```
Alternatively, you can manage the lifecycle yourself with `em.init()` and `em.finish()` (instead of using `with ...`).
Take care to handle exceptions, including correct lifecycle management if not using the automatic context management.
## Project Source
Find this and related project sources at the [energymon organization on GitHub](https://github.com/energymon).
This project originates at: https://github.com/energymon/energymon-py
Bug reports and pull requests for bug fixes and enhancements are welcome.
Raw data
{
"_id": null,
"home_page": "https://github.com/energymon/energymon-py",
"name": "energymon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "energymon,energy,monitoring,bindings",
"author": "Connor Imes",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/33/4c/6ebf05d1fe7e839aac9367c48606bb0bff9d8b5d6774cc6674ea15b2e03a/energymon-0.1.2.tar.gz",
"platform": null,
"description": "# EnergyMon Python Bindings\n\n[](https://energymon-py.readthedocs.io/en/latest/?badge=latest)\n\nThis project provides Python bindings to [energymon](https://github.com/energymon/energymon) libraries.\n\nIf using this project for other scientific works or publications, please reference:\n\n* Connor Imes, Lars Bergstrom, and Henry Hoffmann. \"A Portable Interface for Runtime Energy Monitoring\". In: FSE. 2016. DOI: https://doi.org/10.1145/2950290.2983956\n <details>\n <summary>[BibTex]</summary>\n\n ```BibTex\n @inproceedings{imes2016energymon,\n author = {Imes, Connor and Bergstrom, Lars and Hoffmann, Henry},\n title = {A Portable Interface for Runtime Energy Monitoring},\n year = {2016},\n isbn = {9781450342186},\n publisher = {Association for Computing Machinery},\n address = {New York, NY, USA},\n url = {https://doi.org/10.1145/2950290.2983956},\n doi = {10.1145/2950290.2983956},\n booktitle = {Proceedings of the 2016 24th ACM SIGSOFT International Symposium on Foundations of Software Engineering},\n pages = {968\u2013974},\n numpages = {7},\n keywords = {portable energy measurement},\n location = {Seattle, WA, USA},\n series = {FSE 2016}\n }\n ```\n\n\n## Dependencies\n\nThe `energymon` libraries should be installed to the system and on the library search path (e.g., `LD_LIBRARY_PATH` on Linux/POSIX systems or `DYLD_LIBRARY_PATH` on macOS systems).\n\nThe latest `energymon` C libraries can be found at https://github.com/energymon/energymon.\n\n\n## Installing\n\nVersioned releases of the `energymon` package are published in the Python Package Index and installable with pip:\n\n```sh\npip install energymon\n```\n\nand through Conda Forge:\n\n```sh\nconda install energymon\n```\n\nTo install from source:\n\n```sh\npip install .\n```\n\n\n## Usage\n\nThe following subsections document usage with increasing levels of abstraction.\n\n### Direct Bindings\n\nAt the lowest level, the `energymon` package exposes an `energymon` class, which is a binding to the `energymon` C struct.\n\nTo directly use the energymon API, first load the library, create and \"get\" the struct to populate its function pointers, then initialize, do work, and cleanup when finished.\nFor example:\n\n```Python\nfrom ctypes import CDLL, byref, create_string_buffer, sizeof, set_errno, get_errno\nfrom ctypes.util import find_library\nfrom energymon import energymon\n\n# try to find the library by name:\nlib_path = find_library('energymon-default')\nif lib_path is None:\n # maybe fall back on a relative or absolute path\n lib_path = 'libenergymon-default.so'\n\nlib = CDLL(lib_path, use_errno=True)\nem = energymon()\nif lib.energymon_get_default(byref(em)) != 0:\n # handle error...\n exit(1)\n\nname = create_string_buffer(256)\nif not em.fsource(name, sizeof(name)):\n # handle error\n exit(1)\n\nprint(name.value.decode())\nif em.finit(byref(em)) != 0:\n # handle error\n exit(1)\n\nset_errno(0)\nuj = em.fread(byref(em))\nif uj == 0 and get_errno() != 0:\n # handle error (but don't skip cleanup!)\n pass\n\nif em.ffinish(byref(em)) != 0:\n # handle error\n exit(1)\n```\n\n### Utility Functions\n\nUtility functions work with the direct bindings, but simplify their usage by (1) abstracting the user from the Python `ctypes` (including pointers) and (2) raising exceptions when errors are reported by the native library.\nFor example, to load the `energymon-default` library, \"get\" the energymon, and report the energy source and current value:\n\n```Python\nfrom energymon import util\n\nlib = util.load_energymon_library()\nem = util.get_energymon(lib)\nprint(util.get_source(em))\nutil.init(em)\ntry:\n print(util.get_uj(em))\nfinally:\n util.finish(em)\n```\n\n### Context Management\n\nThe `context` submodule provides the `EnergyMon` class, which is both a wrapper around `energymon` bindings and a Python context manager.\nAs a context manager, the class handles the `energymon` lifecycle, and is both reentrant and reusable.\nFor example, to use as a context manager:\n\n```Python\nfrom energymon.context import EnergyMon\n\nwith EnergyMon() as em:\n print('source:', em.get_source())\n print('reading (uJ):', em.get_uj())\n```\n\nAlternatively, you can manage the lifecycle yourself with `em.init()` and `em.finish()` (instead of using `with ...`).\nTake care to handle exceptions, including correct lifecycle management if not using the automatic context management.\n\n\n## Project Source\n\nFind this and related project sources at the [energymon organization on GitHub](https://github.com/energymon). \nThis project originates at: https://github.com/energymon/energymon-py\n\nBug reports and pull requests for bug fixes and enhancements are welcome.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python bindings to native energymon libraries",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/energymon/energymon-py"
},
"split_keywords": [
"energymon",
"energy",
"monitoring",
"bindings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "98156ca337004330ee0401163fafb93becdce515ce876fc490baa7f99dac572c",
"md5": "28ea97f5fe31fe7d482ac06e7fa52fd9",
"sha256": "5f551760d45f86ba2589d95f9707b5a713a3710b1dd1c9d705fe72b0f9bbf794"
},
"downloads": -1,
"filename": "energymon-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28ea97f5fe31fe7d482ac06e7fa52fd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 12977,
"upload_time": "2023-06-19T19:46:14",
"upload_time_iso_8601": "2023-06-19T19:46:14.951779Z",
"url": "https://files.pythonhosted.org/packages/98/15/6ca337004330ee0401163fafb93becdce515ce876fc490baa7f99dac572c/energymon-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "334c6ebf05d1fe7e839aac9367c48606bb0bff9d8b5d6774cc6674ea15b2e03a",
"md5": "3ed0e453560b20d9dfb12b893c95443d",
"sha256": "b5fbf1369ee01f60cfef0f1488fa61093ee3751f6facb7b0ef087f46ce931820"
},
"downloads": -1,
"filename": "energymon-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "3ed0e453560b20d9dfb12b893c95443d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 14641,
"upload_time": "2023-06-19T19:46:16",
"upload_time_iso_8601": "2023-06-19T19:46:16.145128Z",
"url": "https://files.pythonhosted.org/packages/33/4c/6ebf05d1fe7e839aac9367c48606bb0bff9d8b5d6774cc6674ea15b2e03a/energymon-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 19:46:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "energymon",
"github_project": "energymon-py",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "energymon"
}
JSON
