Skip to content

Commit

Permalink
Harmonize docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
hynek committed Jan 25, 2024
1 parent e4bbf54 commit ab6e825
Show file tree
Hide file tree
Showing 8 changed files with 33 additions and 32 deletions.
2 changes: 1 addition & 1 deletion .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ You will find the built documentation in `docs/_build/html`.
"""
Do something.
Arguments:
Args:
x: A very important argument.
y:
Expand Down
4 changes: 3 additions & 1 deletion docs/integrations/fastapi.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ If you initialize the application with a lifespan as shown above, and use the {f
```{eval-rst}
.. autoclass:: svcs.fastapi.lifespan(lifespan)
.. seealso:: :ref:`fastapi-init`
.. seealso:: :ref:`fastapi-init`
```


Expand All @@ -118,4 +118,6 @@ If you initialize the application with a lifespan as shown above, and use the {f
.. autofunction:: svcs.fastapi.container
.. autoclass:: svcs.fastapi.DepContainer
.. seealso:: :ref:`fastapi-get`
```
24 changes: 11 additions & 13 deletions src/svcs/_core.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ class ServicePing:
is_async: Whether the service needs to be pinged using :meth:`aping`.
See also:
See Also:
:ref:`health`
"""

Expand Down Expand Up @@ -136,7 +136,6 @@ class Registry:
``async with`` is also supported.
Warns:
ResourceWarning:
If a registry with pending cleanups is garbage-collected.
"""
Expand Down Expand Up @@ -211,7 +210,7 @@ def register_factory(
*on_registry_close* callbacks are run all together when the registry is
closed.
Arguments:
Args:
svc_type: The type of the service to register.
factory:
Expand All @@ -227,8 +226,7 @@ def register_factory(
instantiating the service is passed into the factory as the
first positional argument.
.. note::
Note:
Generally speaking, given the churn and edgecases in the
typing ecosystem, we recommend using the name route to
detect the container argument because it's most reliable.
Expand All @@ -242,7 +240,7 @@ def register_factory(
ping:
A callable that marks the service as having a health check.
.. seealso::
See Also:
:meth:`Container.get_pings` and :class:`ServicePing`.
on_registry_close:
Expand Down Expand Up @@ -478,12 +476,10 @@ class Container:
Cleaned up!
Warns:
ResourceWarning:
If a container with pending cleanups is garbage-collected.
Attributes:
registry:
The :class:`Registry` instance that this container uses for service
type lookup.
Expand Down Expand Up @@ -550,7 +546,7 @@ def close(self) -> None:
Errors are logged at warning level, but otherwise ignored.
.. hint::
Hint:
The Container can be used again after this. Closing it is an
idempotent way to reset it.
"""
Expand Down Expand Up @@ -589,8 +585,8 @@ async def aclose(self) -> None:
Also works with synchronous services, so in an async application, just
use this.
.. hint::
The Container can be used again after this. Closing it is an
Hint:
The container can be used again after this. Closing it is an
idempotent way to reset it.
"""
for name, cm in reversed(self._on_close):
Expand Down Expand Up @@ -696,7 +692,8 @@ def register_local_factory(
A temporary :class:`svcs.Registry` is transparently created -- and
closed together with the container it belongs to.
.. seealso:: :ref:`local-registries`
See Also:
:ref:`local-registries`
.. versionadded:: 23.21.0
"""
Expand Down Expand Up @@ -734,7 +731,8 @@ def register_local_value(
Please note that, unlike with :meth:`register_local_factory`, entering
context managers is **disabled** by default.
.. seealso:: :ref:`local-registries`
See Also:
:ref:`local-registries`
.. versionadded:: 23.21.0
"""
Expand Down
6 changes: 4 additions & 2 deletions src/svcs/aiohttp.py
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,8 @@ async def aclose_registry(app: web.Application) -> None:
You probably don't have to call this yourself, because it's registered for
the application as an {attr}`aiohttp.web.Application.on_cleanup` callback.
.. seealso:: :ref:`aiohttp-cleanup`
See Also:
:ref:`aiohttp-cleanup`
"""
with suppress(KeyError):
await get_registry(app).aclose()
Expand All @@ -144,7 +145,8 @@ def get_pings(request: web.Request) -> list[svcs.ServicePing]:
Same as :meth:`svcs.Container.get_pings`, but uses the container from
*request*.
.. seealso:: :ref:`aiohttp-health`
See Also:
:ref:`aiohttp-health`
"""
return svcs_from(request).get_pings()

Expand Down
5 changes: 1 addition & 4 deletions src/svcs/fastapi.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ class lifespan: # noqa: N801
Async generators are automatically wrapped into an async context manager.
Arguments:
Args:
lifespan: The lifespan function to make *svcs*-aware.
"""

Expand Down Expand Up @@ -80,9 +80,6 @@ async def container(request: Request) -> AsyncGenerator[svcs.Container, None]:
Yields:
A :class:`svcs.Container` that is cleaned up after the request.
See also:
:ref:`fastapi-get`
"""
async with svcs.Container(getattr(request.state, _KEY_REGISTRY)) as cont:
yield cont
Expand Down
8 changes: 4 additions & 4 deletions src/svcs/flask.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ def get_registry(app: Flask | None = None) -> Registry:
"""
Get the registry from *app* or :obj:`flask.current_app`.
Arguments:
Args:
app: If None, :obj:`flask.current_app` is used.
.. versionadded:: 23.21.0
Expand Down Expand Up @@ -140,7 +140,7 @@ def overwrite_factory(
Afterwards resets the instantiation cache on ``g``.
See also:
See Also:
- :meth:`svcs.Registry.register_factory()`
- :meth:`svcs.Container.close()`
"""
Expand Down Expand Up @@ -169,7 +169,7 @@ def overwrite_value(
Afterwards resets the instantiation cache on ``g``.
See also:
See Also:
- :meth:`svcs.Registry.register_factory()`
- :meth:`svcs.Container.close()`
"""
Expand All @@ -188,7 +188,7 @@ def get_pings() -> list[ServicePing]:
"""
See :meth:`svcs.Container.get_pings()`.
See also:
See Also:
:ref:`flask-health`
"""
return svcs_from(g).get_pings()
Expand Down
11 changes: 6 additions & 5 deletions src/svcs/pyramid.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ def svcs_from(request: Request | None = None) -> svcs.Container:
"""
Get the current container either from *request* or from thread locals.
Arguments:
Args:
request: If None, thread locals are used.
"""
if request is None:
Expand All @@ -51,7 +51,7 @@ def get_registry(rh: PyramidRegistryHaver | None = None) -> svcs.Registry:
"""
Get the registry from *rh* or thread locals.
Arguments:
Args:
rh: If None, thread locals are used.
"""
registry = rh.registry if rh else get_current_registry()
Expand All @@ -74,7 +74,7 @@ def init(
.. _Tween: https://docs.pylonsproject.org/projects/pyramid/en/main/glossary.html#term-tween
Arguments:
Args:
config: Pyramid configurator object.
registry:
Expand Down Expand Up @@ -165,7 +165,7 @@ def close_registry(rh: PyramidRegistryHaver) -> None:
Ideal for :func:`atexit.register()` handlers.
Arguments:
Args:
rh: An object that carries a :class:`pyramid.registry.Registry`.
"""
with suppress(KeyError):
Expand All @@ -186,7 +186,8 @@ def get_pings(request: Request) -> list[svcs.ServicePing]:
"""
Like :meth:`svcs.Container.get_pings()`, but uses container on *request*.
.. seealso:: :ref:`pyramid-health`
See Also:
:ref:`pyramid-health`
"""
return svcs_from(request).get_pings()

Expand Down
5 changes: 3 additions & 2 deletions src/svcs/starlette.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ class lifespan: # noqa: N801
Async generators are automatically wrapped into an async context manager.
Arguments:
Args:
lifespan: The lifespan function to make *svcs*-aware.
"""

Expand Down Expand Up @@ -114,7 +114,8 @@ def get_pings(request: Request) -> list[svcs.ServicePing]:
Same as :meth:`svcs.Container.get_pings`, but uses the container from
*request*.
.. seealso:: :ref:`aiohttp-health`
See Also:
:ref:`aiohttp-health`
"""
return svcs_from(request).get_pings()

Expand Down

0 comments on commit ab6e825

Please sign in to comment.