From baee33b88f8a2568ff03e880a71b7d0327d427c6 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Sat, 25 May 2024 21:42:51 +0200 Subject: [PATCH] README. - Added/restyled badges. - Added sections on the scripts directory and YAML `include` directive. --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 74 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a861167573..469b615b76 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,22 @@ ![Platypush logo](https://static.platypush.tech/images/platypush-banner.png) [![Build Status](https://ci-cd.platypush.tech/api/badges/platypush/platypush/status.svg)](https://ci-cd.platypush.tech/platypush/platypush) -[![pip version](https://img.shields.io/pypi/v/platypush.svg?style=flat)](https://pypi.python.org/pypi/platypush/) -[![License](https://img.shields.io/github/license/BlackLight/platypush.svg)](https://git.platypush.tech/platypush/platypush/src/branch/master/LICENSE.txt) +[![Issues](https://img.shields.io/gitea/issues/open/platypush/platypush?gitea_url=https://git.platypush.tech)](https://git.platypush.tech/platypush/platypush/issues) +[![Github stars](https://img.shields.io/github/stars/blacklight/platypush?style=flat&logo=Github)](https://github.com/blacklight/platypush) +[![Github forks](https://img.shields.io/github/forks/blacklight/platypush?style=flat&logo=Github)](https://github.com/blacklight/platypush) [![Last Commit](https://img.shields.io/github/last-commit/BlackLight/platypush.svg)](https://git.platypush.tech/platypush/platypush/commits/branch/master) -[![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://git.platypush.tech/platypush/platypush/src/branch/master/CONTRIBUTING.md) -[![Join chat on Matrix](https://img.shields.io/matrix/platypush:matrix.platypush.tech.svg?server_fqdn=matrix.platypush.tech)](https://matrix.to/#/#platypush:matrix.platypush.tech) +[![Ask on Lemmy](https://img.shields.io/lemmy/platypush%40lemmy.platypush.tech?style=flat&logo=lemmy&label=Ask%20on%20Lemmy)](https://lemmy.platypush.tech/c/platypush) +[![Join chat on Matrix](https://img.shields.io/matrix/platypush:matrix.platypush.tech.svg?server_fqdn=matrix.platypush.tech&label=chat&logo=matrix)](https://matrix.to/#/#platypush:matrix.platypush.tech) +[![pip version](https://img.shields.io/pypi/v/platypush.svg?style=flat)](https://pypi.python.org/pypi/platypush/) +[![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://git.platypush.tech/platypush/platypush/src/branch/master/CONTRIBUTING.md) +[![License](https://img.shields.io/github/license/BlackLight/platypush.svg)](https://git.platypush.tech/platypush/platypush/src/branch/master/LICENSE.txt) +[![Sponsor](https://img.shields.io/github/sponsors/blacklight)](https://github.com/sponsors/blacklight) [![Blog](https://img.shields.io/badge/-Blog-9532CA?logo=LiveJournal)](https://blog.platypush.tech) [![Documentation](https://img.shields.io/badge/-Docs-022AC5?logo=GitBook)](https://docs.platypush.tech) [![Wiki](https://img.shields.io/badge/-Wiki-00AA40?logo=Docs.rs)](https://git.platypush.tech/platypush/platypush/wiki) -[![Issues](https://img.shields.io/badge/-Issues-BABA30?logo=TickTick)](https://git.platypush.tech/platypush/platypush/issues) -[![Sponsor](https://img.shields.io/github/sponsors/blacklight)](https://github.com/sponsors/blacklight) -[![PayPal](https://img.shields.io/badge/-PayPal-CACA30?logo=PayPal)](https://paypal.me/fabiomanganiello) [![Join chat on IRC](https://img.shields.io/badge/-IRC-4542CA?logo=LiveChat)](irc://platypush@irc.platypush.tech:6697) -[![Ask on Lemmy](https://img.shields.io/lemmy/platypush%40lemmy.platypush.tech)](https://matrix.to/#/#platypush:matrix.platypush.tech) +[![PayPal](https://img.shields.io/badge/-PayPal-CACA30?logo=PayPal)](https://paypal.me/fabiomanganiello) @@ -52,6 +54,8 @@ * [Manual installation](#manual-installation-1) - [Post-installation](#post-installation) * [Configuration file](#configuration-file) + + [Scripts directory](#scripts-directory) + + [Splitting configuration on multiple files](#splitting-configuration-on-multiple-files) * [systemd service](#systemd-service) * [Redis](#redis) * [nginx](#nginx) @@ -1011,6 +1015,68 @@ in the following way: virtual environment, `$XDG_CONFIG_HOME/platypush/config.yaml` will be used (defaults to `~/.config/platypush/config.yaml`). +#### Scripts directory + +By default, any custom Python scripts will be searched under +`/scripts`, where `` is the path to your `config.yaml`. + +You can override it in your `config.yaml`: + +```yaml +scripts_dir: /path/to/custom/scripts +``` + +Since everything under the scripts directory will be imported as a submodule, +you can create your own libraries of scripts that can import other scripts: + +```python +# Content of scripts/music.py + +from platypush import run + +def music_play(plugin='music.mopidy', resource=None): + run(f'{plugin}.play', resource) + +# Content of scripts/lights.py + +from platypush import run + +def lights_toggle(plugin='light.hue', groups=('Living Room',)): + run(f'{plugin}.toggle', groups=groups) + +# Content of scripts/home.py + +from platypush import procedure + +from scripts.music import music_play +from scripts.lights import lights_toggle + +@procedure +def at_home(): + music_play() + lights_toggle() +``` + +#### Splitting configuration on multiple files + +The `config.yaml` file can become very complex, especially if you embed many +hooks and procedures in it in YAML format. + +To make the configuration more maintainable, and also to isolate modules that +you can reuse across multiple instances, you can leverage the `include` +directive: + +```yaml +# All paths are relative to config.yaml, or to the location of the current file +include: + - assistant.yaml + - db.yaml + - media.yaml + - mqtt.yaml + - sensors.yaml + # ... +``` + ### systemd service If you installed Platypush from a system package manager then you'll also have