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
« 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."""
3from __future__ import annotations
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)
20class Lice:
21 """List or Generate a License from many supported licenses."""
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.
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)
37 Note that not all licenses will use the 'project' field.
39 Example:
40 >>> lice = Lice(organization="Awesome Co.", project="my_project")
41 """
42 self.organization = organization
43 self.project = project
45 try:
46 # make sure the year can be a valid integer
47 _ = int(year)
48 except ValueError:
49 raise InvalidYearError(year) from None
51 self.year = str(year)
52 if len(self.year) != 4: # noqa: PLR2004
53 raise InvalidYearError(year) from None
55 def get_licenses(self) -> list[str]:
56 """Return a list of all licenses in the system.
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.
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
69 def get_languages(self) -> list[str]:
70 """Return a list of all supported languages.
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.
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())
83 def get_license(self, license_name: str, language: str = "") -> str:
84 """Return the text of the given license.
86 Args:
87 license_name: The name of the license to retrieve.
88 language: [OPTIONAL] If set, comment the license for that language.
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
104 content = generate_license(template, args)
106 try:
107 out = format_license(content, language)
108 except KeyError:
109 raise LanguageNotFoundError(language) from None
110 return out.getvalue()
112 def get_header(self, license_name: str, language: str = "") -> str:
113 """Return the header of the given license suitable for source files.
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.
119 Note: Not all licenses have headers, if the license does not have a
120 header, this method will raise a HeaderNotFoundError.
122 Args:
123 license_name: The name of the license to retrieve.
124 language: The language to format the header for.
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
140 content = generate_license(template, args)
142 try:
143 out = format_license(content, language)
144 except KeyError:
145 raise LanguageNotFoundError(language) from None
146 return out.getvalue()