aquaui 0.0.1.post2
Native Mac OS UI elements with python
License: MIT
Requires Python: >=3.7,<4.0

<h1 align="center">
  <img src="https://raw.githubusercontent.com/ninest/aquaui/master/assets/icon.svg" width=155>
  <br>
  aquaui
</h1>

<p align="center">
Display native dialogs, alerts, notifications, color pickers, and more with Python
</p>

<p align="center">
  <img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/ninest/aquaui/Run%20tests?style=flat-square">

  <a href="https://pypi.org/project/aquaui/">
    <img src="https://img.shields.io/pypi/v/aquaui?color=blue&style=flat-square" alt="Version" />
  </a>
  <a href="https://pypi.org/project/aquaui/">
    <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/aquaui?color=red&style=flat-square" />
  </a>

  <img src="https://img.shields.io/github/license/ninest/aquaui?style=flat-square" alt="MIT" />

  <a href="https://www.buymeacoffee.com/ninest">
    <img src="https://img.shields.io/badge/Donate-Buy%20Me%20A%20Coffee-orange.svg?style=flat-square" alt="Buy Me A Coffee">
  </a>
</p>

**💥 This library is still a work in progress.**

## Useful links

- [Documentation](https://github.com/ninest/aquaui/tree/master/docs)
- [Examples](https://github.com/ninest/aquaui#examples)
- [Discussions](https://github.com/ninest/aquaui/discussions)

## Features

- [x] Display dialogs
  - [x] Dialog prompts
  - [x] Icon support
- [x] Alerts
- [x] Choice dialogs
- [ ] Notifications
  - [x] Customize title, subtitle, and informational text
  - [x] Customize icon
  - [x] Schedulable
  - [ ] Callbacks (button pressed, reply text) – [relevant stackoverflow answer](https://stackoverflow.com/a/62248246/8677167)
  - [x] Fallback (AppleScript) notifications
- [ ] Color picker
- [ ] File/folder picker

## Documentation

[**Find the documentation in the `docs/` folder**](https://github.com/ninest/aquaui/tree/master/docs)

## Examples

See the `examples/` directory. Feel free to make a pull request to add more examples.

**Show a dialog with the buttons "Go" (default) and "No" (to cancel) with the caution icon:**

```py
from aquaui import Dialog, Buttons, Icon

buttons = Buttons(["Go", "No"], default_button="Go", cancel_button="No")
result = Dialog("Hello!").with_buttons(buttons).with_icon(Icon.CAUTION).show()
```

**Execute functions based on the button clicked:**

```py
from aquaui import Dialog, Buttons

button_one = "One"
button_two = "Two"
buttons = Buttons([button_one, button_two])

result = Dialog("Press a button").with_buttons(buttons).show()

if result.button_returned == button_one:
  print("Button One was pressed")
elif result.button_returned == button_two:
  print("Button Two was pressed")
```

**Display a choice dialog with the options "Netflix" and "Prime Video"**

```py
from aquaui import Choice

provider = Choice("Choose the streaming platform").with_choices(["Netflix", "Prime Video"]).show()
print(provider)
```

If this example interests you, check out my other library [Flixpy](https://github.com/ninest/flixpy).

**Display a notification:**

Warning: please read the [documentation](./docs/3-notification.md) before using notifications. There are additional dependencies to install.

```py
from aquaui.notification.native_notification import Notification

notification = (
    Notification("Hello!")
    .with_subtitle("This is the subtitle!")
    .with_informative_text("Isn't this informative?")
    .with_identity_image("assets/folder.png")  # the image on the right of the notification
    .send()
)
```

**Schedule a notification:**

```py
from aquaui.notification.native_notification import Notification

notification = Notification("Your pizza is here!").with_delay(15).send()
# 15 seconds delay
```

## Build setup

Clone or fork the repository, then run

```bash
poetry shell

poetry install
pre-commit install
```

Make changes, then run tests with

```bash
pytest tests
```

Ensure that all tests pass.

<details>
<summary>
Recommended editor settings
</summary>

```json
{
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.insertSpaces": true,
    "editor.detectIndentation": false,
    "editor.tabSize": 4
  },
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.pylintEnabled": false,
  "python.pythonPath": "/Users/yourusername/.../aquaui-UIHDsdfS-py3.7"
}
```

</details>

## License

MIT