Metadata-Version: 2.1
Name: aioapcaccess
Version: 0.2.0
Summary: Async version of apcaccess library implemented in python.
Author-email: Yuxin Wang <yuxinwang.dev@gmail.com>
License: MIT License
        
        Copyright (c) 2022 Yuxin Wang
        
        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.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-asyncio ; extra == 'dev'

# aioapcaccess

[![build](https://github.com/yuxincs/aioapcaccess/actions/workflows/build.yaml/badge.svg)](https://github.com/yuxincs/aioapcaccess/actions/workflows/build.yaml?query=branch%3Amain)
[![codecov](https://codecov.io/github/yuxincs/aioapcaccess/branch/main/graph/badge.svg?token=8zhys5YAk9)](https://codecov.io/github/yuxincs/aioapcaccess)
[![PyPI](https://img.shields.io/pypi/v/aioapcaccess)](https://pypi.org/project/aioapcaccess/)
[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![GitHub](https://img.shields.io/github/license/yuxincs/aioapcaccess)](https://github.com/yuxincs/aioapcaccess/blob/main/LICENSE)

An async implementation of [apcaccess](https://linux.die.net/man/8/apcaccess). This
library provides programmatic access to the status information provided by
[apcupsd](http://www.apcupsd.org/) 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](https://github.com/flyte/apcaccess) using
[asyncio](https://docs.python.org/3/library/asyncio.html), where a lot of the logic is
borrowed and improved.

# Usage

The primary API for getting the status from APCUPS is `aioapcaccess.request_status`.
It returns a `collections.OrderedDict` 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](http://www.apcupsd.org/manual/) for details.

The following example shows a typical usage of `aioapcaccess`

```python
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`.
