From eab35c387ce6f13e28ea3e33bcda0ee796d25ac0 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Sun, 18 Aug 2024 09:09:58 +0200 Subject: [PATCH] docs: clerify ping callables get services as first argument Fixes #99 --- docs/core-concepts.md | 4 ++-- src/svcs/_core.py | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 9915200..4203681 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -101,7 +101,7 @@ For instance, you could free a database connection pool in an {mod}`atexit` hand This liberates you from keeping track of registered services yourself. You can also use a registry as an (async) context manager that (a)closes automatically on exit. -*svcs* will raise a {class}`ResourceWarning` if a registry with pending cleanups is garbage-collected. +*svcs* will raise a {class}`ResourceWarning` when a registry with pending cleanups is garbage-collected. ## Containers @@ -280,7 +280,7 @@ Now the type name expresses the purpose of the object and it doesn't matter if t Each registered service may have a `ping` callable that you can use for health checks. You can request all pingable registered services with {meth}`svcs.Container.get_pings()`. -This returns a list of {class}`svcs.ServicePing` objects that currently have a name property to identify the ping and a {meth}`~svcs.ServicePing.ping()` method that instantiates the service, adds it to the cleanup list, and runs the ping. +This returns a list of {class}`svcs.ServicePing` objects that have a name property to identify the ping and a {meth}`~svcs.ServicePing.ping()` method that acquires the service, adds it to the cleanup list, and runs the ping with the acquired service as its only argument. If you have async services (factory or ping callable), you can use {meth}`~svcs.ServicePing.aping()` instead. `aping()` works with sync services, too, so you can use it universally in async code. diff --git a/src/svcs/_core.py b/src/svcs/_core.py index f7827ea..d0507f6 100644 --- a/src/svcs/_core.py +++ b/src/svcs/_core.py @@ -92,15 +92,15 @@ class ServicePing: def ping(self) -> None: """ - Instantiate the service, schedule its cleanup, and call its ping - method. + Acquire the service, schedule its cleanup, and call its ping callable + with the acquired service as its only argument. """ svc: Any = self._container.get(self._svc_type) self._ping(svc) async def aping(self) -> None: """ - Same as :meth:`ping` but instantiate and/or ping asynchronously, if + Same as :meth:`ping` but acquire and/or ping asynchronously, if necessary. Also works with synchronous services, so in an async application, just