Metadata-Version: 2.4
Name: laptop_battery_status
Version: 0.1.0
Summary: Reports the battery charge, time remaining, and AC power status on Windows, macOS, and Linux, using only the standard library.
Author-email: Al Sweigart <asweigart@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/asweigart/laptop_battery_status
Project-URL: Source, https://github.com/asweigart/laptop_battery_status
Project-URL: Bug Tracker, https://github.com/asweigart/laptop_battery_status/issues
Keywords: battery,power,acpi,laptop,charge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: license-file

# laptop_battery_status

Reports the battery charge, the time remaining, and whether the computer is
plugged in. Works on Windows, macOS, and Linux, and uses nothing but the
Python standard library. Runs on Python 3.5 and later.

## Installation

    pip install laptop_battery_status

## Quickstart

```python
>>> import laptop_battery_status as lbs
>>> lbs.is_plugged_in()
True
>>> lbs.is_charging()
True
>>> lbs.battery_level()
87.0
>>> lbs.battery_life()
inf
```

Unplug the laptop and the same calls report the runtime left:

```python
>>> lbs.is_plugged_in()
False
>>> lbs.battery_life()
272.0
```

## Functions

| Function | Returns |
| --- | --- |
| `is_plugged_in()` | `True` if running on AC power, otherwise `False`. |
| `battery_level()` | A `float` from `0.0` to `100.0` for the percent of charge left. |
| `battery_life()` | A `float` of the minutes of runtime left, or `float('inf')` while plugged in. |
| `is_charging()` | `True` if the battery is actively charging, otherwise `False`. |
| `battery_present()` | `True` if a battery is installed, otherwise `False`. |

`battery_life()` returns `float('inf')` whenever the computer is plugged in,
because the runtime isn't limited by the battery then. Note that a plugged-in
computer whose battery is already full is *not* charging, so `is_plugged_in()`
can return `True` while `is_charging()` returns `False`.

## Machines with no battery

The battery functions raise `NoBatteryError` on a desktop computer or in a
virtual machine. Call `battery_present()` first if that's a case your program
needs to handle:

```python
import laptop_battery_status

if laptop_battery_status.battery_present():
    print('Battery at %s%%' % (laptop_battery_status.battery_level(),))
else:
    print('This computer runs on wall power.')
```

`is_plugged_in()` is the exception: it works fine on a desktop, where it
always returns `True`.

## Unknown values

`battery_level()` and `battery_life()` return `None` when a battery is
installed but the operating system reports the value as unknown. This is
common for the first minute or two after unplugging, while the OS is still
working out a time estimate, so check `battery_life()` for `None` before doing
arithmetic on it.

## Exceptions

All exceptions subclass `BatteryStatusError`, which subclasses `RuntimeError`.

* `NoBatteryError` - no battery is installed.
* `UnsupportedPlatformError` - the operating system isn't Windows, macOS, or Linux.
* `BatteryStatusError` - the power information couldn't be read, or the OS
  reported the AC power or charging state as unknown.

## How it works

No third party packages are used.

* **Windows** calls the Win32 `GetSystemPowerStatus()` function through `ctypes`.
* **macOS** calls the IOKit `IOPowerSources` functions through `ctypes`, and
  falls back to parsing the output of `pmset -g batt`.
* **Linux** reads the files under `/sys/class/power_supply`, and falls back to
  parsing the output of `upower` and then `acpi`. The kernel doesn't provide a
  time estimate, so the remaining minutes are calculated from the current
  charge and the rate it's being drawn at, which makes the number jumpier than
  the one in a desktop environment's battery menu.

Machines with more than one battery are reported as a single combined battery.

## License

MIT
