Coverage for python/lsst/utils/inheritDoc.py: 29%
12 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-07-25 09:27 +0000
« prev ^ index » next coverage.py v7.2.7, created at 2023-07-25 09:27 +0000
1# This file is part of utils.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (https://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# Use of this source code is governed by a 3-clause BSD-style
10# license that can be found in the LICENSE file.
12from __future__ import annotations
14__all__ = ("inheritDoc",)
16from collections.abc import Callable
19def inheritDoc(klass: type) -> Callable:
20 """Extend existing documentation for a method that exists in another
21 class and extend it with any additional documentation defined.
23 This decorator takes a class from which to draw documentation from as an
24 argument. This is so that any class may be used as a source of
25 documentation and not just the immediate parent of a class. This is useful
26 when there may be a long inheritance chain, or in the case of mixins.
28 Parameters
29 ----------
30 klass : object
31 The class to inherit documentation from.
33 Returns
34 -------
35 decorator : callable
36 Intermediate decorator used in the documentation process.
37 """
39 def tmpDecorator(method: type) -> Callable:
40 """Update the documentation from a class with the same method."""
41 methodName = method.__name__
42 if not hasattr(klass, methodName):
43 raise AttributeError(f"{klass} has no method named {methodName} to inherit from")
44 appendText = method.__doc__ or ""
45 method.__doc__ = getattr(klass, methodName).__doc__ + appendText
46 return method
48 return tmpDecorator