Coverage for lice2/api/api.py: 100%

43 statements  

« prev     ^ index     » next       coverage.py v7.6.4, created at 2024-11-13 11:13 +0000

1"""This defines an API that other Python code can use to interact with LICE2.""" 

2 

3from __future__ import annotations 

4 

5from lice2.api.exceptions import ( 

6 HeaderNotFoundError, 

7 InvalidYearError, 

8 LanguageNotFoundError, 

9 LicenseNotFoundError, 

10) 

11from lice2.constants import LANGS, LICENSES 

12from lice2.helpers import ( 

13 format_license, 

14 generate_license, 

15 get_local_year, 

16 load_package_template, 

17) 

18 

19 

20class Lice: 

21 """List or Generate a License from many supported licenses.""" 

22 

23 def __init__( 

24 self, 

25 organization: str, 

26 project: str, 

27 year: str | int = get_local_year(), 

28 ) -> None: 

29 """Initialize the Lice object. 

30 

31 Args: 

32 organization: The name of the organization that owns the project. 

33 project: The name of the project. 

34 year: The year to use in the license. Defaults to the current year. 

35 (can be a string or an integer) 

36 

37 Note that not all licenses will use the 'project' field. 

38 

39 Example: 

40 >>> lice = Lice(organization="Awesome Co.", project="my_project") 

41 """ 

42 self.organization = organization 

43 self.project = project 

44 

45 try: 

46 # make sure the year can be a valid integer 

47 _ = int(year) 

48 except ValueError: 

49 raise InvalidYearError(year) from None 

50 

51 self.year = str(year) 

52 if len(self.year) != 4: # noqa: PLR2004 

53 raise InvalidYearError(year) from None 

54 

55 def get_licenses(self) -> list[str]: 

56 """Return a list of all licenses in the system. 

57 

58 This returns a list of strings, where each string is the name of a 

59 license that can then be used to generate or retrieve the text of that 

60 license. 

61 

62 Example: 

63 >>> lice = Lice(organization="Awesome Co.", project="my_project") 

64 >>> lice.get_licenses() 

65 ['apache', 'bsd2', 'bsd3', 'gpl2', 'gpl3', ...] 

66 """ 

67 return LICENSES 

68 

69 def get_languages(self) -> list[str]: 

70 """Return a list of all supported languages. 

71 

72 This returns a list of strings, where each string is the name of a 

73 language EXTENSION that can be used to generate a license in that 

74 language format. 

75 

76 Example: 

77 >>> lice = Lice(organization="Awesome Co.", project="my_project") 

78 >>> lice.get_languages() 

79 ['py', 'js', 'c', 'cpp', 'java', 'rs', 'rb', 'sh', 'html', ...] 

80 """ 

81 return list(LANGS.keys()) 

82 

83 def get_license(self, license_name: str, language: str = "") -> str: 

84 """Return the text of the given license. 

85 

86 Args: 

87 license_name: The name of the license to retrieve. 

88 language: [OPTIONAL] If set, comment the license for that language. 

89 

90 Examples: 

91 >>> lice = Lice(organization="Awesome Co.", project="my_project") 

92 >>> licence_txt = Lice.get_license("mit") 

93 """ 

94 args = { 

95 "year": self.year, 

96 "organization": self.organization, 

97 "project": self.project, 

98 } 

99 try: 

100 template = load_package_template(license_name) 

101 except FileNotFoundError: 

102 raise LicenseNotFoundError(license_name) from None 

103 

104 content = generate_license(template, args) 

105 

106 try: 

107 out = format_license(content, language) 

108 except KeyError: 

109 raise LanguageNotFoundError(language) from None 

110 return out.getvalue() 

111 

112 def get_header(self, license_name: str, language: str = "") -> str: 

113 """Return the header of the given license suitable for source files. 

114 

115 If the language is specified, the header will be formatted as a 

116 commented block for that language. If not, the header will be returned 

117 as a plain text block. 

118 

119 Note: Not all licenses have headers, if the license does not have a 

120 header, this method will raise a HeaderNotFoundError. 

121 

122 Args: 

123 license_name: The name of the license to retrieve. 

124 language: The language to format the header for. 

125 

126 Example: 

127 >>> lice = Lice(organization="Awesome Co.", project="my_project") 

128 >>> header_txt = Lice.get_header("mit", "py") 

129 """ 

130 args = { 

131 "year": self.year, 

132 "organization": self.organization, 

133 "project": self.project, 

134 } 

135 try: 

136 template = load_package_template(license_name, header=True) 

137 except FileNotFoundError: 

138 raise HeaderNotFoundError(license_name) from None 

139 

140 content = generate_license(template, args) 

141 

142 try: 

143 out = format_license(content, language) 

144 except KeyError: 

145 raise LanguageNotFoundError(language) from None 

146 return out.getvalue()