# Services (pyzed.services)

> API reference for pyzed.services: timers, shortcuts, file watchers, processes, background workers, web requests, the clipboard, settings, file dialogs, notifications and tray icons for Python desktop apps.

Source: https://albakore.github.io/pyzed/reference/services/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

Services raise events but draw nothing: they are the non-visual components of Pyzed Design
([the tray under the form](https://albakore.github.io/pyzed/editor/non-visual-components/)) and work the same in a
`pz.App` or a script. Handlers go in `on_<event>=`; events raised by a background thread reach
them on the app's thread. See the [Services guide](https://albakore.github.io/pyzed/guides/services/).

```python
watcher = pz.FileWatcher("inbox", pattern="*.csv", on_created=self.import_file)
watcher.start()
```

## Time and keys

### `Timer`

```python
class Timer
```

Raises `tick` (with the count) every `interval` milliseconds while it is running; `repeat=False` ticks once. Return `subscriptions()` from your app's `subscriptions`.

### `Shortcut`

```python
class Shortcut
```

Raises `activate` when one of its `keys` is pressed (`"ctrl-s"`, `"Ctrl+S"`, several separated by commas; `mod-` is Cmd on macOS and Ctrl elsewhere). Call `handle(combo)` from `on_key`.

## Files and programs

### `FileWatcher`

```python
class FileWatcher
```

Watches a folder or a file and raises `created`, `modified` and `deleted` (a path) and `change` (the changed paths), checking every `interval` milliseconds. `start()`, `stop()`, `running`.

### `Process`

```python
class Process
```

Runs a program and raises `output` and `error_output` for every line it prints, `finished` with its exit code, `started` and `failed`. `start()`, `write()`, `kill()`, `wait()`.

### `Worker`

```python
class Worker
```

Runs `work(value)` in a background thread with `run(value)`; `report()` raises `progress`, the result arrives in `done` and an exception in `failed`. `cancel()` sets `cancelled`.

## Network

### `HttpRequest`

```python
class HttpRequest
```

Calls a web address in the background: `send()` raises `response` with an `HttpResponse` (error statuses included) or `failed` when there was no answer. `json=` sends JSON.

### `HttpResponse`

```python
@dataclass
class HttpResponse(status, content=b'', headers={}, url='')
```

A web server's answer: `status`, `ok`, `headers`, `content` (bytes), `text` and `json()`.

## System

### `Clipboard`

```python
class Clipboard
```

The system clipboard: `copy(text)` and `paste()` return commands; with `watch=True` it raises `change` when something new is copied.

### `Settings`

```python
class Settings
```

Values kept between runs: a dict saved as JSON in the user's settings folder at every change, with `defaults`; raises `change` with `(key, value)`.

### `FileDialog`

```python
class FileDialog
```

The system's file dialog: `show()` returns the command that opens it in `mode` `"open"`, `"open_many"`, `"save"` or `"folder"`; raises `chosen` or `cancelled`.

### `Notification`

```python
class Notification
```

A desktop notification: `show(text)` shows it and returns whether it could; raises `shown` or `failed`.

### `TrayIcon`

```python
class TrayIcon
```

An icon in the system tray with a `tooltip` and a `menu` (a list, or text with one item per line: `-` separator, `[x]` check, indented submenu): `show()` returns whether it could, `hide()`, `checked(item)`; raises `click`, `double_click` (Windows), `menu` and `failed`. On Linux it is a StatusNotifierItem, without GTK.

### `TrayItem`

```python
@dataclass
class TrayItem(text, id=None, enabled=True, checked=None, items=[])
```

An entry of a `TrayIcon` menu: `text`, `id` (what `menu` receives), `enabled`, `checked` and `items` for a submenu.

## Operating system (pyzed.system)

### `SystemInfo`

```python
class SystemInfo
```

What the computer is: `os` (`"Windows"`, `"macOS"`, `"Linux"`), `os_version`, `machine`, `hostname`, `user`, `home`, `language`, `cpu_count`, `python_version`, `memory_total`, plus `memory_available`, `disk_free` and `disk_total` read when asked. `env(name)` reads a variable, `folder("documents")` finds the user's folders. With `interval` above 0, `start()` raises `update` with `snapshot()` every so often.

### `Launcher`

```python
class Launcher
```

Opens files, folders and links with the app the system uses for them: `open(target)`, `reveal(path)` (selected in the file manager) and `email(to, subject, body)`; raises `opened` or `failed`.

### `NetworkMonitor`

```python
class NetworkMonitor
```

Notices when the computer goes online or offline by reaching `host` every `interval` milliseconds in the background: `online`, `check()`, `start()`, `stop()`; raises `change`, `online` and `offline`.

### `PowerMonitor`

```python
class PowerMonitor
```

The battery: `percent`, `plugged` and `has_battery`; every `interval` milliseconds raises `change`, `low` (under `low_level` while unplugged), `plugged` and `unplugged`.