@@ -329,55 +329,52 @@ def wrapper(*args, **kwargs) -> Callable[..., Any]:
329
329
return decorate
330
330
331
331
332
- def doc (* args : Union [str , Callable ], ** kwargs ) -> Callable [[F ], F ]:
332
+ def doc (* docstrings : Union [str , Callable ], ** params ) -> Callable [[F ], F ]:
333
333
"""
334
334
A decorator take docstring templates, concatenate them and perform string
335
335
substitution on it.
336
336
337
337
This decorator will add a variable "_docstring_components" to the wrapped
338
- function to keep track the original docstring template for potential usage.
338
+ callable to keep track the original docstring template for potential usage.
339
339
If it should be consider as a template, it will be saved as a string.
340
340
Otherwise, it will be saved as callable, and later user __doc__ and dedent
341
341
to get docstring.
342
342
343
343
Parameters
344
344
----------
345
- *args : str or callable
345
+ *docstrings : str or callable
346
346
The string / docstring / docstring template to be appended in order
347
- after default docstring under function .
348
- **kwargs
349
- The objects which would be used to format docstring template.
347
+ after default docstring under callable .
348
+ **params
349
+ The string which would be used to format docstring template.
350
350
"""
351
351
352
- def decorator (func : F ) -> F :
353
- @wraps (func )
354
- def wrapper (* args , ** kwargs ) -> Callable :
355
- return func (* args , ** kwargs )
356
-
352
+ def decorator (decorated : F ) -> F :
357
353
# collecting docstring and docstring templates
358
354
docstring_components : List [Union [str , Callable ]] = []
359
- if func .__doc__ :
360
- docstring_components .append (dedent (func .__doc__ ))
355
+ if decorated .__doc__ :
356
+ docstring_components .append (dedent (decorated .__doc__ ))
361
357
362
- for arg in args :
363
- if hasattr (arg , "_docstring_components" ):
364
- docstring_components .extend (arg ._docstring_components ) # type: ignore
365
- elif isinstance (arg , str ) or arg .__doc__ :
366
- docstring_components .append (arg )
358
+ for docstring in docstrings :
359
+ if hasattr (docstring , "_docstring_components" ):
360
+ docstring_components .extend (
361
+ docstring ._docstring_components # type: ignore
362
+ )
363
+ elif isinstance (docstring , str ) or docstring .__doc__ :
364
+ docstring_components .append (docstring )
367
365
368
366
# formatting templates and concatenating docstring
369
- wrapper .__doc__ = "" .join (
367
+ decorated .__doc__ = "" .join (
370
368
[
371
- arg .format (** kwargs )
372
- if isinstance (arg , str )
373
- else dedent (arg .__doc__ or "" )
374
- for arg in docstring_components
369
+ component .format (** params )
370
+ if isinstance (component , str )
371
+ else dedent (component .__doc__ or "" )
372
+ for component in docstring_components
375
373
]
376
374
)
377
375
378
- wrapper ._docstring_components = docstring_components # type: ignore
379
-
380
- return cast (F , wrapper )
376
+ decorated ._docstring_components = docstring_components # type: ignore
377
+ return decorated
381
378
382
379
return decorator
383
380
0 commit comments