Release 0.13.10a1

.github/workflows/coverage.yml

@@ -12,6 +12,6 @@ jobs:
     with:
       python_version: '3.11'
       coverage_source: 'ovos_utils'
-      test_path: 'test/'
-      install_extras: ''
+      test_path: 'test/unittests'
+      install_extras: '.[extras]'
       min_coverage: 0

CHANGELOG.md

@@ -1,54 +1,172 @@
 # Changelog
 
-## [0.8.5a4](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.5a4) (2026-03-11)
+## [0.13.10a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.10a1) (2026-08-13)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.6a2...0.8.5a4)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.9a2...0.13.10a1)
 
 **Merged pull requests:**
 
-- chore: Add comprehensive test suites and documentation [\#362](https://github.com/OpenVoiceOS/ovos-utils/pull/362) ([JarbasAl](https://github.com/JarbasAl))
-- fix: make the stopwatch test less strict [\#360](https://github.com/OpenVoiceOS/ovos-utils/pull/360) ([PureTryOut](https://github.com/PureTryOut))
+- fix: give FakeBus the intent-topic bridge \(RULE 1/RULE 2 parity with MessageBusClient\) [\#417](https://github.com/OpenVoiceOS/ovos-utils/pull/417) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.8.6a2](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.6a2) (2026-02-02)
+## [0.13.9a2](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.9a2) (2026-08-01)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.6a1...0.8.6a2)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.9a1...0.13.9a2)
 
 **Merged pull requests:**
 
-- chore\(deps\): update actions/setup-python action to v6 [\#353](https://github.com/OpenVoiceOS/ovos-utils/pull/353) ([renovate[bot]](https://github.com/apps/renovate))
-- chore\(deps\): update actions/checkout action to v6 [\#352](https://github.com/OpenVoiceOS/ovos-utils/pull/352) ([renovate[bot]](https://github.com/apps/renovate))
+- docs: rewrite README in Simplified Technical English [\#413](https://github.com/OpenVoiceOS/ovos-utils/pull/413) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.8.6a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.6a1) (2026-02-02)
+## [0.13.9a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.9a1) (2026-07-24)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.5a3...0.8.6a1)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.8a1...0.13.9a1)
 
 **Merged pull requests:**
 
-- fix: prevent handler errors from aborting FakeBus emit [\#358](https://github.com/OpenVoiceOS/ovos-utils/pull/358) ([JarbasAl](https://github.com/JarbasAl))
+- fix: watch files that do not exist yet [\#408](https://github.com/OpenVoiceOS/ovos-utils/pull/408) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.8.5a3](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.5a3) (2025-12-19)
+## [0.13.8a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.8a1) (2026-07-24)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.5a2...0.8.5a3)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.7a2...0.13.8a1)
 
 **Merged pull requests:**
 
-- chore\(deps\): update dependency python to 3.14 [\#348](https://github.com/OpenVoiceOS/ovos-utils/pull/348) ([renovate[bot]](https://github.com/apps/renovate))
+- fix: FileEventHandler must only fire for the file it watches [\#406](https://github.com/OpenVoiceOS/ovos-utils/pull/406) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.8.5a2](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.5a2) (2025-12-18)
+## [0.13.7a2](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.7a2) (2026-07-24)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.5a1...0.8.5a2)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.7a1...0.13.7a2)
 
 **Merged pull requests:**
 
-- chore: Configure Renovate [\#347](https://github.com/OpenVoiceOS/ovos-utils/pull/347) ([renovate[bot]](https://github.com/apps/renovate))
+- refactor: deprecate create\_self\_signed\_cert [\#404](https://github.com/OpenVoiceOS/ovos-utils/pull/404) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.8.5a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.8.5a1) (2025-11-07)
+## [0.13.7a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.7a1) (2026-07-23)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.4...0.8.5a1)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.6a1...0.13.7a1)
 
 **Merged pull requests:**
 
-- fix: use timezone-aware datetime functions and update scheduler event names [\#343](https://github.com/OpenVoiceOS/ovos-utils/pull/343) ([JarbasAl](https://github.com/JarbasAl))
+- fix: replace removed distutils.spawn with shutil.which \(Python 3.12+\) [\#402](https://github.com/OpenVoiceOS/ovos-utils/pull/402) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.6a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.6a1) (2026-07-23)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.5a1...0.13.6a1)
+
+**Merged pull requests:**
+
+- fix: ovos-logs CLI leaves stray file in cwd [\#400](https://github.com/OpenVoiceOS/ovos-utils/pull/400) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.5a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.5a1) (2026-07-16)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.4a1...0.13.5a1)
+
+**Merged pull requests:**
+
+- fix: log each unique deprecation warning only once [\#398](https://github.com/OpenVoiceOS/ovos-utils/pull/398) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.4a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.4a1) (2026-07-02)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.3a1...0.13.4a1)
+
+**Merged pull requests:**
+
+- fix: FakeBus folds the message session BEFORE handlers, not after [\#396](https://github.com/OpenVoiceOS/ovos-utils/pull/396) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.3a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.3a1) (2026-06-29)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.2a1...0.13.3a1)
+
+**Merged pull requests:**
+
+- fix: FakeBus folds the default session like any other \(drop owner-only\) [\#393](https://github.com/OpenVoiceOS/ovos-utils/pull/393) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.2a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.2a1) (2026-06-29)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.1a1...0.13.2a1)
+
+**Merged pull requests:**
+
+- fix: drop deprecated make\_default from FakeBus default-session sync [\#389](https://github.com/OpenVoiceOS/ovos-utils/pull/389) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.1a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.1a1) (2026-06-29)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.13.0a1...0.13.1a1)
+
+**Merged pull requests:**
+
+- fix: target a real shape-changing pair in namespace-migration tests [\#390](https://github.com/OpenVoiceOS/ovos-utils/pull/390) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.13.0a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.13.0a1) (2026-06-27)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.12.2a1...0.13.0a1)
+
+**Merged pull requests:**
+
+- feat: AsyncFakeBus namespace migration + env/config flag parity [\#387](https://github.com/OpenVoiceOS/ovos-utils/pull/387) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.12.2a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.12.2a1) (2026-06-27)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.12.1a1...0.12.2a1)
+
+**Merged pull requests:**
+
+- fix: translate mirrored payload onto counterpart topic in FakeBus [\#385](https://github.com/OpenVoiceOS/ovos-utils/pull/385) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.12.1a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.12.1a1) (2026-06-25)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.12.0a1...0.12.1a1)
+
+**Merged pull requests:**
+
+- fix: raise ovos-spec-tools floor to 0.10.0a1 for NamespaceTranslator [\#383](https://github.com/OpenVoiceOS/ovos-utils/pull/383) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.12.0a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.12.0a1) (2026-06-25)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.11.2a1...0.12.0a1)
+
+**Merged pull requests:**
+
+- feat: FakeBus mirrors the legacy\<-\>ovos.\* namespace migration [\#381](https://github.com/OpenVoiceOS/ovos-utils/pull/381) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.11.2a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.11.2a1) (2026-06-20)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.11.1a1...0.11.2a1)
+
+**Merged pull requests:**
+
+- fix: allow json-database 1.x [\#379](https://github.com/OpenVoiceOS/ovos-utils/pull/379) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.11.1a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.11.1a1) (2026-05-25)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.11.0a1...0.11.1a1)
+
+**Merged pull requests:**
+
+- fix: standardize\_lang\_tag macro=True preserves region \(restore langcodes semantics\) [\#377](https://github.com/OpenVoiceOS/ovos-utils/pull/377) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.11.0a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.11.0a1) (2026-05-25)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.10.0a1...0.11.0a1)
+
+**Merged pull requests:**
+
+- feat: fakebus Message subclasses ovos\_spec\_tools.Message — no API break [\#375](https://github.com/OpenVoiceOS/ovos-utils/pull/375) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.10.0a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.10.0a1) (2026-05-22)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.9.0a1...0.10.0a1)
+
+**Merged pull requests:**
+
+- feat: migrate ovos-utils onto ovos-spec-tools [\#373](https://github.com/OpenVoiceOS/ovos-utils/pull/373) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.9.0a1](https://github.com/OpenVoiceOS/ovos-utils/tree/0.9.0a1) (2026-05-18)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-utils/compare/0.8.5...0.9.0a1)
+
+**Merged pull requests:**
+
+- feat: AsyncFakeBus alongside FakeBus [\#371](https://github.com/OpenVoiceOS/ovos-utils/pull/371) ([JarbasAl](https://github.com/JarbasAl))
 
 
 

README.md

@@ -1,87 +1,107 @@
 # OVOS-utils
 
-collection of simple utilities for use across the mycroft ecosystem
+`ovos-utils` is a shared utility library for the OpenVoiceOS ecosystem. It provides
+logging, process lifecycle management, a testing-friendly fake message bus, event
+scheduling, file utilities, network checks, audio playback, and XDG path helpers.
+Most OVOS packages, including `ovos-bus-client`, `ovos-config`, and `ovos-workshop`,
+depend on it, so most projects get it as a transitive dependency.
 
 ## Install
 
 ```bash
-pip install ovos_utils
+pip install ovos-utils
 ```
 
-## Commandline scripts
-### ovos-logs
- Small helper tool to quickly navigate the logs, create slices and quickview errors  
+## Usage
 
----------------
-- **ovos-logs slice [options]**
+The library exposes many small, independent modules. Import only what you need.
+For example, use `FakeBus` to test skill code without a live message bus:
 
-  **Slice logs of a given time period. Defaults on the last service start (`-s`) until now (`-u`)**
+```python
+from ovos_utils.fakebus import FakeBus, FakeMessage
 
-  _Different logs can be picked using the `-l` option. All logs will be included if not specified._  
-  _Optionally the directory where the logs are stored (`-p`) and the file where the slices should be dumped (`-f`) can be specified._
-
+bus = FakeBus()
 
-  _[ex: `ovos-logs slice`]_  
-  <sup>_Slice all logs from service start up until now._</sup>
-
-  _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25`]_  
-  <sup>_Slice all logs from 17:05:20 until 17:05:25._</sup>    
-  <sup>_**no logs in that timeframe in other present logs_</sup>
-  <img width="1898" alt="Screenshot 2023-12-25 185004" src="https://github.com/emphasize/ovos-utils/assets/25036977/c7918bd6-0e13-46af-8016-55486b9a786e">  
-
-  _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25 -l skills`]_  
-  <sup>_Slice skills.log from 17:05:20 until 17:05:25._</sup>
-
-  _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25 -f ~/testslice.log`]_  
-  <sup>_Slice the logs from 17:05:20 until 17:05:25 on all log files and dump the slices in the file ~/testslice.log (default: `~/slice_<timestamp>.log`)._</sup>
-  <img width="1246" alt="Screenshot 2023-12-25 190732" src="https://github.com/emphasize/ovos-utils/assets/25036977/dda99d8a-2739-4872-b81a-f44902b43d7d">
---------------
+def on_utterance(message):
+    print(message.data["utterances"])
 
-- **ovos-logs list [-e|-w|-d|-x] [options]**
+bus.on("recognizer_loop:utterance", on_utterance)
+bus.emit(FakeMessage("recognizer_loop:utterance", {"utterances": ["hello"]}))
+```
+
+See [docs/index.md](docs/index.md) for the full module overview, with links to
+detailed pages on logging, process utilities, `FakeBus`, and event handling.
+
+## Command line: ovos-logs
+
+`ovos-logs` is a helper tool that slices, lists, and reduces OVOS service logs.
+
+- **`ovos-logs slice [options]`**. Slice logs for a time period. The default
+  period runs from the last service start (`-s`) until now (`-u`). Pick specific
+  logs with `-l` (default: all logs). Set the log directory with `-p` and the
+  output file with `-f`.
+
+  ```bash
+  ovos-logs slice
+  # Slice all logs from the last service start until now.
+
+  ovos-logs slice -s 17:05:20 -u 17:05:25
+  # Slice all logs between 17:05:20 and 17:05:25.
+
+  ovos-logs slice -s 17:05:20 -u 17:05:25 -l skills
+  # Slice only skills.log between 17:05:20 and 17:05:25.
+
+  ovos-logs slice -s 17:05:20 -u 17:05:25 -f ~/testslice.log
+  # Slice logs between 17:05:20 and 17:05:25 into ~/testslice.log.
+  # Default output file: ~/slice_<timestamp>.log
+  ```
+
+- **`ovos-logs list [-e|-w|-d|-x] [options]`**. List log lines by severity
+  (error, warning, debug, exception). Specify at least one level. You can combine
+  several. Set the time range with `-s` and `-u` (default: last service start
+  until now). Pick specific logs with `-l` (default: all logs).
+
+  ```bash
+  ovos-logs list -x
+  # List EXCEPTION-level lines (with tracebacks) from the last service start until now.
 
-  **List logs by severity (error/warning/debug/exception). A log level has to be specified - more than one can be listed**  
+  ovos-logs list -w -e -s 20-12-2023 -l bus -l skills
+  # List WARNING and ERROR lines from bus.log and skills.log since 20 December 2023.
+  ```
 
-  _A start and end date can be specified using the `-s` and `-u` options. Defaults to the last service start until now._  
-  _Different logs can be picked using the `-l` option. All logs will be included if not specified._  
-  _Optionally, the directory where the logs are stored (`-p`) and the file where the slices should be dumped (`-f`) can be passed as arguments._  
+- **`ovos-logs reduce [options]`**. Shrink logs to a target size in bytes, or
+  remove entries before a given date. Pick specific logs with `-l` (default: all
+  logs). Set the log directory with `-p`.
 
-  _[ex: `ovos-logs list -x`]_  
-  <sup>_List the logs with level EXCEPTION (plus tracebacks) from the last service start until now._</sup>
-  <img width="992" alt="Screenshot 2023-12-25 184321" src="https://github.com/emphasize/ovos-utils/assets/25036977/da8be23a-4268-4647-8dd3-32c1a889440c">
-
-  _[ex: `ovos-logs list -w -e -s 20-12-2023 -l bus -l skills`]_  
-  <sup>_List the logs with level WARNING and ERROR from the 20th of December 2023 until now from the logs bus.log and skills.log._</sup>
-  <img width="1898" alt="Screenshot 2023-12-25 173739" src="https://github.com/emphasize/ovos-utils/assets/25036977/c5703195-4393-4989-ae40-b37638438c92">
----------------------
+  ```bash
+  ovos-logs reduce
+  # Shrink all logs to 0 bytes.
 
-- **ovos-logs reduce [options]**
-
-  **Downsize logs to a given size (in bytes) or remove entries before a given date.**  
-
-  _Different logs can be included using the `-l` option. If not specified, all logs will be included._  
-  _Optionally the directory where the logs are stored (`-p`) can be specified._  
-
-  _[ex: `ovos-logs reduce`]_  
-  <sup>_Downsize all logs to 0 bytes_</sup>  
+  ovos-logs reduce -s 1000000
+  # Shrink all logs to about 1 MB, keeping the latest entries.
 
-  _[ex: `ovos-logs reduce -s 1000000`]_  
-  <sup>_Downsize all logs to ~1MB (latest logs)_</sup>  
+  ovos-logs reduce -d "1-12-2023 17:00"
+  # Shrink all logs to entries after the given date and time.
 
-  _[ex: `ovos-logs reduce -d "1-12-2023 17:00"`]_  
-  <sup>_Downsize all logs to entries after the specified date/time_</sup>  
+  ovos-logs reduce -s 1000000 -l skills -l bus
+  # Shrink skills.log and bus.log to about 1 MB each.
+  ```
 
-  _[ex: `ovos-logs reduce -s 1000000 -l skills -l bus`]_  
-  <sup>_Downsize skills.log and bus.log to ~1MB (latest logs)_</sup>  
+- **`ovos-logs show -l <servicelog>`**. Print the contents of a log file.
 
----------------------
+  ```bash
+  ovos-logs show -l bus
+  # Print the contents of bus.log.
+  ```
 
-- **ovos-logs show -l [servicelog]**
+  The logs shown depend on which log files exist in the log folder.
 
-  **Show logs**
+## Related projects
 
-  _[ex: `ovos-logs show -l bus`]_  
-  <sup>_Show the logs from bus.log._</sup>  
+- [OpenVoiceOS/ovos-bus-client](https://github.com/OpenVoiceOS/ovos-bus-client). The real message bus client that `FakeBus` and `FakeMessage` stand in for during testing.
+- [OpenVoiceOS/ovos-config](https://github.com/OpenVoiceOS/ovos-config). Reads and writes `mycroft.conf`, the configuration file used by `LOG`, `PIDLock`, and the network utilities.
+- [OpenVoiceOS/ovos-workshop](https://github.com/OpenVoiceOS/ovos-workshop). The skill framework built on `EventContainer`, `RuntimeRequirements`, and the other utilities in this library.
 
-  _[ex: wrong servicelog]_  
-  <sup>_**logs shown depending on the logs present in the folder_</sup>
+## License
 
+Apache License 2.0. See [LICENSE](LICENSE).

docs/events.md

@@ -85,3 +85,6 @@ from ovos_bus_client.apis.events import EventSchedulerInterface
 | `shutdown()` | Cancel repeating events and clear all registered handlers |
 
 `when` may be a `datetime`, or a positive `int`/`float` representing seconds from now.
+
+---
+[← FakeBus](fakebus.md) · [Home](index.md) · [Utilities →](utilities.md)