Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/docs/docstring.py: 66%

1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"). You 

4# may not use this file except in compliance with the License. A copy of 

5# the License is located at 

6# 

7# http://aws.amazon.com/apache2.0/ 

8# 

9# or in the "license" file accompanying this file. This file is 

10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF 

11# ANY KIND, either express or implied. See the License for the specific 

12# language governing permissions and limitations under the License. 

13from botocore.docs.bcdoc.restdoc import DocumentStructure 

14from botocore.docs.method import document_model_driven_method 

15from botocore.docs.paginator import document_paginate_method 

16from botocore.docs.waiter import document_wait_method 

17 

18 

19class LazyLoadedDocstring(str): 

20 """Used for lazily loading docstrings 

21 

22 You can instantiate this class and assign it to a __doc__ value. 

23 The docstring will not be generated till accessed via __doc__ or 

24 help(). Note that all docstring classes **must** subclass from 

25 this class. It cannot be used directly as a docstring. 

26 """ 

27 

28 def __init__(self, *args, **kwargs): 

29 """ 

30 The args and kwargs are the same as the underlying document 

31 generation function. These just get proxied to the underlying 

32 function. 

33 """ 

34 super().__init__() 

35 self._gen_args = args 

36 self._gen_kwargs = kwargs 

37 self._docstring = None 

38 

39 def __new__(cls, *args, **kwargs): 

40 # Needed in order to sub class from str with args and kwargs 

41 return super().__new__(cls) 

42 

43 def _write_docstring(self, *args, **kwargs): 

44 raise NotImplementedError( 

45 '_write_docstring is not implemented. Please subclass from ' 

46 'this class and provide your own _write_docstring method' 

47 ) 

48 

49 def expandtabs(self, tabsize=8): 

50 """Expands tabs to spaces 

51 

52 So this is a big hack in order to get lazy loaded docstring work 

53 for the ``help()``. In the ``help()`` function, ``pydoc`` and 

54 ``inspect`` are used. At some point the ``inspect.cleandoc`` 

55 method is called. To clean the docs ``expandtabs`` is called 

56 and that is where we override the method to generate and return the 

57 docstrings. 

58 """ 

59 if self._docstring is None: 

60 self._generate() 

61 return self._docstring.expandtabs(tabsize) 

62 

63 def __str__(self): 

64 return self._generate() 

65 

66 # __doc__ of target will use either __repr__ or __str__ of this class. 

67 __repr__ = __str__ 

68 

69 def _generate(self): 

70 # Generate the docstring if it is not already cached. 

71 if self._docstring is None: 

72 self._docstring = self._create_docstring() 

73 return self._docstring 

74 

75 def _create_docstring(self): 

76 docstring_structure = DocumentStructure('docstring', target='html') 

77 # Call the document method function with the args and kwargs 

78 # passed to the class. 

79 self._write_docstring( 

80 docstring_structure, *self._gen_args, **self._gen_kwargs 

81 ) 

82 return docstring_structure.flush_structure().decode('utf-8') 

83 

84 

85class ClientMethodDocstring(LazyLoadedDocstring): 

86 def _write_docstring(self, *args, **kwargs): 

87 document_model_driven_method(*args, **kwargs) 

88 

89 

90class WaiterDocstring(LazyLoadedDocstring): 

91 def _write_docstring(self, *args, **kwargs): 

92 document_wait_method(*args, **kwargs) 

93 

94 

95class PaginatorDocstring(LazyLoadedDocstring): 

96 def _write_docstring(self, *args, **kwargs): 

97 document_paginate_method(*args, **kwargs)