mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-06-28 06:41:43 +00:00
docs: extract version for the manpage
This commit is contained in:
19
tools/__init__.py
Normal file
19
tools/__init__.py
Normal file
@ -0,0 +1,19 @@
|
||||
#
|
||||
# Copyright (c) 2021-2025 ahriman team.
|
||||
#
|
||||
# This file is part of ahriman
|
||||
# (see https://github.com/arcan1s/ahriman).
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
#
|
||||
212
tools/pylint_plugins/definition_order/__init__.py
Normal file
212
tools/pylint_plugins/definition_order/__init__.py
Normal file
@ -0,0 +1,212 @@
|
||||
#
|
||||
# Copyright (c) 2021-2025 ahriman team.
|
||||
#
|
||||
# This file is part of ahriman
|
||||
# (see https://github.com/arcan1s/ahriman).
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
#
|
||||
from astroid import nodes
|
||||
from collections.abc import Iterable
|
||||
from enum import StrEnum
|
||||
from pylint.checkers import BaseRawFileChecker
|
||||
from pylint.lint import PyLinter
|
||||
from typing import Any
|
||||
|
||||
|
||||
class MethodType(StrEnum):
|
||||
"""
|
||||
method type enumeration
|
||||
|
||||
Attributes:
|
||||
Class(MethodType): (class attribute) class method
|
||||
Delete(MethodType): (class attribute) destructor-like methods
|
||||
Init(MethodType): (class attribute) initialization method
|
||||
Magic(MethodType): (class attribute) other magical methods
|
||||
New(MethodType): (class attribute) constructor method
|
||||
Normal(MethodType): (class attribute) usual method
|
||||
Property(MethodType): (class attribute) property method
|
||||
Static(MethodType): (class attribute) static method
|
||||
"""
|
||||
|
||||
Class = "classmethod"
|
||||
Delete = "del"
|
||||
Init = "init"
|
||||
Magic = "magic"
|
||||
New = "new"
|
||||
Normal = "regular"
|
||||
Property = "property"
|
||||
Static = "staticmethod"
|
||||
|
||||
|
||||
class DefinitionOrder(BaseRawFileChecker):
|
||||
"""
|
||||
check if methods are defined in recommended order
|
||||
|
||||
Attributes:
|
||||
DECORATED_METHODS_ORDER(list[str]): (class attribute) predefined list of known function decorators
|
||||
"""
|
||||
|
||||
DECORATED_METHODS_ORDER = {
|
||||
"cached_property": MethodType.Property,
|
||||
"classmethod": MethodType.Class,
|
||||
"property": MethodType.Property,
|
||||
"staticmethod": MethodType.Static,
|
||||
}
|
||||
|
||||
msgs = {
|
||||
"W6001": (
|
||||
"Invalid method order %s, expected %s",
|
||||
"methods-out-of-order",
|
||||
"Methods are defined out of recommended order.",
|
||||
),
|
||||
}
|
||||
name = "method-ordering"
|
||||
options = (
|
||||
(
|
||||
"method-type-order",
|
||||
{
|
||||
"default": [
|
||||
"init",
|
||||
"new",
|
||||
"del",
|
||||
"property",
|
||||
"classmethod",
|
||||
"staticmethod",
|
||||
"regular",
|
||||
"magic",
|
||||
],
|
||||
"type": "csv",
|
||||
"metavar": "<comma-separated types>",
|
||||
"help": "Method types order to check.",
|
||||
},
|
||||
),
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def methods(source: Iterable[Any], start_lineno: int = 0) -> list[nodes.FunctionDef]:
|
||||
"""
|
||||
extract function nodes from list of raw nodes
|
||||
|
||||
Args:
|
||||
source(Iterable[Any]): all available nodes
|
||||
start_lineno(int, optional): minimal allowed line number (Default value = 0)
|
||||
|
||||
Returns:
|
||||
list[nodes.FunctionDef]: list of function nodes
|
||||
"""
|
||||
def is_defined_function(function: Any) -> bool:
|
||||
return isinstance(function, nodes.FunctionDef) \
|
||||
and function.lineno is not None \
|
||||
and function.lineno >= start_lineno
|
||||
|
||||
return list(filter(is_defined_function, source))
|
||||
|
||||
@staticmethod
|
||||
def resolve_type(function: nodes.FunctionDef) -> MethodType:
|
||||
"""
|
||||
resolve type of the function
|
||||
|
||||
Args:
|
||||
function(nodes.FunctionDef): function definition
|
||||
|
||||
Returns:
|
||||
MethodType: resolved function type
|
||||
"""
|
||||
# init methods
|
||||
if function.name in ("__init__", "__post_init__"):
|
||||
return MethodType.Init
|
||||
if function.name in ("__new__",):
|
||||
return MethodType.New
|
||||
if function.name in ("__del__",):
|
||||
return MethodType.Delete
|
||||
|
||||
# decorated methods
|
||||
decorators = []
|
||||
if function.decorators is not None:
|
||||
decorators = [getattr(decorator, "name", None) for decorator in function.decorators.get_children()]
|
||||
for decorator in decorators:
|
||||
if decorator in DefinitionOrder.DECORATED_METHODS_ORDER:
|
||||
return DefinitionOrder.DECORATED_METHODS_ORDER[decorator]
|
||||
|
||||
# magic methods
|
||||
if function.name.startswith("__") and function.name.endswith("__"):
|
||||
return MethodType.Magic
|
||||
|
||||
# normal method
|
||||
return MethodType.Normal
|
||||
|
||||
def check_class(self, clazz: nodes.ClassDef) -> None:
|
||||
"""
|
||||
check class functions ordering
|
||||
|
||||
Args:
|
||||
clazz(nodes.ClassDef): class definition
|
||||
"""
|
||||
methods = self.methods(clazz.values(), clazz.lineno)
|
||||
self.check_functions(methods)
|
||||
|
||||
def check_functions(self, functions: list[nodes.FunctionDef]) -> None:
|
||||
"""
|
||||
check global functions ordering
|
||||
|
||||
Args:
|
||||
functions(list[nodes.FunctionDef]): list of functions in their defined order
|
||||
"""
|
||||
for real, expected in zip(functions, sorted(functions, key=self.comparator)):
|
||||
if real == expected:
|
||||
continue
|
||||
self.add_message("methods-out-of-order", line=real.lineno, args=(real.name, expected.name))
|
||||
break
|
||||
|
||||
def comparator(self, function: nodes.FunctionDef) -> tuple[int, str]:
|
||||
"""
|
||||
compare key for sorting function
|
||||
|
||||
Args:
|
||||
function(nodes.FunctionDef): function definition
|
||||
|
||||
Returns:
|
||||
tuple[int, str]: comparison key for the specified function definition
|
||||
"""
|
||||
function_type = self.resolve_type(function)
|
||||
try:
|
||||
function_type_index = self.linter.config.method_type_order.index(function_type)
|
||||
except ValueError:
|
||||
function_type_index = len(self.linter.config.method_type_order) # not in the list
|
||||
|
||||
return function_type_index, function.name
|
||||
|
||||
def process_module(self, node: nodes.Module) -> None:
|
||||
"""
|
||||
process module
|
||||
|
||||
Args:
|
||||
node(nodes.Module): module node to check
|
||||
"""
|
||||
# check global methods
|
||||
self.check_functions(self.methods(node.values()))
|
||||
# check class definitions
|
||||
for clazz in filter(lambda method: isinstance(method, nodes.ClassDef), node.values()):
|
||||
self.check_class(clazz)
|
||||
|
||||
|
||||
def register(linter: PyLinter) -> None:
|
||||
"""
|
||||
register custom checker
|
||||
|
||||
Args:
|
||||
linter(PyLinter): linter in which checker should be registered
|
||||
"""
|
||||
linter.register_checker(DefinitionOrder(linter))
|
||||
205
tools/pylint_plugins/import_order/__init__.py
Normal file
205
tools/pylint_plugins/import_order/__init__.py
Normal file
@ -0,0 +1,205 @@
|
||||
#
|
||||
# Copyright (c) 2021-2025 ahriman team.
|
||||
#
|
||||
# This file is part of ahriman
|
||||
# (see https://github.com/arcan1s/ahriman).
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
#
|
||||
from astroid import nodes
|
||||
from collections.abc import Iterable
|
||||
from enum import StrEnum
|
||||
from pylint.checkers import BaseRawFileChecker
|
||||
from pylint.lint import PyLinter
|
||||
from typing import Any
|
||||
|
||||
|
||||
class ImportType(StrEnum):
|
||||
"""
|
||||
import type enumeration
|
||||
|
||||
Attributes:
|
||||
Future(MethodTypeOrder): (class attribute) from __future__ import
|
||||
Package(MethodTypeOrder): (class attribute) package import
|
||||
PackageFrom(MethodTypeOrder): (class attribute) package import, from clause
|
||||
System(ImportType): (class attribute) system installed packages
|
||||
SystemFrom(MethodTypeOrder): (class attribute) system installed packages, from clause
|
||||
"""
|
||||
|
||||
Future = "future"
|
||||
Package = "package"
|
||||
PackageFrom = "package-from"
|
||||
System = "system"
|
||||
SystemFrom = "system-from"
|
||||
|
||||
|
||||
class ImportOrder(BaseRawFileChecker):
|
||||
"""
|
||||
check if imports are defined in recommended order
|
||||
"""
|
||||
|
||||
msgs = {
|
||||
"W6002": (
|
||||
"Invalid import order %s, expected before %s",
|
||||
"imports-out-of-order",
|
||||
"Imports are defined out of recommended order.",
|
||||
),
|
||||
"W6003": (
|
||||
"Import contains more than one package: %s",
|
||||
"multiple-package-imports",
|
||||
"Multiple package imports are not allowed.",
|
||||
),
|
||||
"W6004": (
|
||||
"Invalid from import order %s, expected %s",
|
||||
"from-imports-out-of-order",
|
||||
"From imports are defined out of recommended order.",
|
||||
),
|
||||
}
|
||||
name = "import-ordering"
|
||||
options = (
|
||||
(
|
||||
"import-type-order",
|
||||
{
|
||||
"default": [
|
||||
"future",
|
||||
"system",
|
||||
"system-from",
|
||||
"package",
|
||||
"package-from",
|
||||
],
|
||||
"type": "csv",
|
||||
"metavar": "<comma-separated types>",
|
||||
"help": "Import types order to check.",
|
||||
},
|
||||
),
|
||||
(
|
||||
"root-module",
|
||||
{
|
||||
"default": "ahriman",
|
||||
"type": "string",
|
||||
"help": "Root module name",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def imports(source: Iterable[Any], start_lineno: int = 0) -> Iterable[nodes.Import | nodes.ImportFrom]:
|
||||
"""
|
||||
extract import nodes from list of raw nodes
|
||||
|
||||
Args:
|
||||
source(Iterable[Any]): all available nodes
|
||||
start_lineno(int, optional): minimal allowed line number (Default value = 0)
|
||||
|
||||
Returns:
|
||||
Iterable[nodes.Import | nodes.ImportFrom]: list of import nodes
|
||||
"""
|
||||
|
||||
def is_defined_import(imports: Any) -> bool:
|
||||
return isinstance(imports, (nodes.Import, nodes.ImportFrom)) \
|
||||
and imports.lineno is not None \
|
||||
and imports.lineno >= start_lineno
|
||||
|
||||
return sorted(filter(is_defined_import, source), key=lambda imports: imports.lineno)
|
||||
|
||||
def check_from_imports(self, imports: nodes.ImportFrom) -> None:
|
||||
"""
|
||||
check import from statement
|
||||
|
||||
Args:
|
||||
imports(nodes.ImportFrom): import from node
|
||||
"""
|
||||
imported = [names for names, _ in imports.names]
|
||||
for real, expected in zip(imported, sorted(imported)):
|
||||
if real == expected:
|
||||
continue
|
||||
self.add_message("from-imports-out-of-order", line=imports.lineno, args=(real, expected))
|
||||
break
|
||||
|
||||
def check_imports(self, imports: Iterable[nodes.Import | nodes.ImportFrom], root_package: str) -> None:
|
||||
"""
|
||||
check imports
|
||||
|
||||
Args:
|
||||
imports(Iterable[nodes.Import | nodes.ImportFrom]): list of imports in their defined order
|
||||
root_package(str): root package name
|
||||
"""
|
||||
last_statement: tuple[int, str] | None = None
|
||||
|
||||
for statement in imports:
|
||||
# define types and perform specific checks
|
||||
match statement:
|
||||
case nodes.ImportFrom() if statement.modname == "__future__":
|
||||
import_name = statement.modname
|
||||
import_type = ImportType.Future
|
||||
case nodes.ImportFrom():
|
||||
import_name = statement.modname
|
||||
root, *_ = import_name.split(".", maxsplit=1)
|
||||
import_type = ImportType.PackageFrom if root_package == root else ImportType.SystemFrom
|
||||
# check from import itself
|
||||
self.check_from_imports(statement)
|
||||
case nodes.Import():
|
||||
import_name = next(name for name, _ in statement.names)
|
||||
root, *_ = import_name.split(".", maxsplit=1)
|
||||
import_type = ImportType.Package if root_package == root else ImportType.System
|
||||
# check import itself
|
||||
self.check_package_imports(statement)
|
||||
case _:
|
||||
continue
|
||||
|
||||
# extract index
|
||||
try:
|
||||
import_type_index = self.linter.config.import_type_order.index(import_type)
|
||||
except ValueError:
|
||||
import_type_index = len(self.linter.config.import_type_order)
|
||||
|
||||
# check ordering if possible
|
||||
if last_statement is not None:
|
||||
_, last_statement_name = last_statement
|
||||
if last_statement > (import_type_index, import_name):
|
||||
self.add_message("imports-out-of-order", line=statement.lineno,
|
||||
args=(import_name, last_statement_name))
|
||||
|
||||
# update the last value
|
||||
last_statement = import_type_index, import_name
|
||||
|
||||
def check_package_imports(self, imports: nodes.Import) -> None:
|
||||
"""
|
||||
check package import
|
||||
|
||||
Args:
|
||||
imports(nodes.Import): package import node
|
||||
"""
|
||||
if len(imports.names) != 1:
|
||||
self.add_message("multiple-package-imports", line=imports.lineno, args=(imports.names,))
|
||||
|
||||
def process_module(self, node: nodes.Module) -> None:
|
||||
"""
|
||||
process module
|
||||
|
||||
Args:
|
||||
node(nodes.Module): module node to check
|
||||
"""
|
||||
root_module, *_ = node.qname().split(".")
|
||||
self.check_imports(self.imports(node.values()), root_module)
|
||||
|
||||
|
||||
def register(linter: PyLinter) -> None:
|
||||
"""
|
||||
register custom checker
|
||||
|
||||
Args:
|
||||
linter(PyLinter): linter in which checker should be registered
|
||||
"""
|
||||
linter.register_checker(ImportOrder(linter))
|
||||
Reference in New Issue
Block a user