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

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

2

3 from __future__ import annotations

4

5 from lice2.api.exceptions import (

6 HeaderNotFoundError,

7 InvalidYearError,

8 LanguageNotFoundError,

9 LicenseNotFoundError,

10)

11 from lice2.constants import LANGS, LICENSES

12 from lice2.helpers import (

13 format_license,

14 generate_license,

15 get_local_year,

16 load_package_template,

17)

18

19

20 class 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()