Coverage for sources/frigid/__/docstrings.py: 100%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Docstring utilities. ''' 

22 

23# pylint: disable=unused-wildcard-import,wildcard-import 

24# ruff: noqa: F403,F405 

25 

26 

27from __future__ import annotations 

28 

29from . import doctab 

30from .imports import * 

31 

32 

33class Docstring( str ): 

34 ''' Dedicated docstring container. ''' 

35 

36 

37def generate_docstring( 

38 *fragment_ids: type | Docstring | str, 

39 table: cabc.Mapping[ str, str ] = doctab.TABLE, 

40) -> str: 

41 ''' Sews together docstring fragments into clean docstring. ''' 

42 from inspect import cleandoc, getdoc, isclass 

43 fragments: list[ str ] = [ ] 

44 for fragment_id in fragment_ids: 

45 if isclass( fragment_id ): fragment = getdoc( fragment_id ) or '' 

46 elif isinstance( fragment_id, Docstring ): fragment = fragment_id 

47 else: fragment = table[ fragment_id ] 

48 fragments.append( cleandoc( fragment ) ) 

49 return '\n\n'.join( fragments )