aioapcaccess

An async implementation of apcaccess. This library provides programmatic access to the status information provided by apcupsd over its Network Information Server (NIS) which usually listens on TCP port 3551.

This project is a re-implementation of the synchronous version flyte/apcaccess using asyncio, where a lot of the logic is borrowed and improved.

Install

Install with pip:

$ pip install aioapcaccess

Usage

The primary API for getting the status from APCUPS is aioapcaccess.request_status. It returns a dict mapping from field names (e.g., "SERIALNO") to their values in string format. What fields are available will depend on the model of your APC UPS, see APCUPSD manual for details.

The following example shows a typical usage of aioapcaccess

import asyncio
import aioapcaccess

async def main():
    result = await aioapcaccess.request_status(host='localhost', port=3551)
    print(result)

if __name__ == '__main__':
    asyncio.run(main())

The example above will print the following (prettified and simplified):

OrderedDict([
  ('APC', '001,036,0879'),
  ...,
  ('BATTV', '13.7 Volts'),
  ('CUMONBATT', '0 Seconds')
))])

In addition to request_status, we offer the following functions for advanced uses:

• aioapcaccess.request_raw_status for getting raw (unparsed) status in bytes.
• aioapcaccess.parse_raw_status for parsing the bytes to the dict shown above.
• aioapcaccess.split_unit for splitting the supported unit suffix from the value strings, returning a tuple (value, unit). You can check aioapcaccess.UNITS for the set of supported units. Note that units are also in the forms of strings (e.g., "Seconds", "Volts"). If no valid units are found in the value strings, unit will be None.

Development

We use prek for running the linting and security hooks defined in .pre-commit-config.yaml. After cloning the repository, install the development dependencies and set up the git hook via:

python -m pip install --upgrade pip
pip install '.[dev]'
prek install

To run all hooks manually (which is also what CI does), run:

prek run --all-files

Support

This library supports all Python versions that are not EOL at the time of release.