jCloud/jcloud-docsgen
2
1 Fork 0
generated from jCloud/repository-template
Code Issues 3 Pull Requests Actions Packages Projects 1 Releases 13 Wiki Activity

style: ensure trailing commas in multi-line statements

Browse Source
This commit is contained in:
jakob.scheid committed 2026-09-18 22:18:13 +02:00
1 parent ffcc7404de
commit 475775eb7e
30 files changed
+1778 -1774
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/jcloud_docsgen/core/python/__init__.py
+1 -1
View File
@@ -18,5 +18,5 @@ from . import namespaces
__all__ = [
*_core__all__,
'namespaces'
'namespaces',
]
src/jcloud_docsgen/core/python/_core.py
+34 -34
View File
@@ -20,7 +20,7 @@ from .definitions import (
PythonAsyncFunctionDefinition,
PythonClassDefinition,
PythonDefinition,
PythonFunctionDefinition
PythonFunctionDefinition,
)
from .arguments import PythonArgumentKind, PythonFunctionArgument
from .docstrings import PythonDocstring
@@ -63,11 +63,11 @@ _Arguments: TypeAlias = tuple[
list[PythonFunctionArgument],
Union[PythonFunctionArgument, None],
list[PythonFunctionArgument],
Union[PythonFunctionArgument, None]
Union[PythonFunctionArgument, None],
]
def _group_argument_list(
argument_list: list[PythonFunctionArgument]
argument_list: list[PythonFunctionArgument],
) -> _Arguments:
'''
Groups the argument list into a list of positional-only arguments, a
@@ -86,7 +86,7 @@ def _group_argument_list(
for arg in argument_list
]):
raise PythonArgumentStructureError(
'arguments cannot follow var-keyword argument'
'arguments cannot follow var-keyword argument',
)
positional_only_args = []
@@ -106,7 +106,7 @@ def _group_argument_list(
if vararg is not None:
raise PythonArgumentStructureError(
'* argument may only appear once',
definition = arg
definition = arg,
)
vararg = arg
@@ -121,11 +121,11 @@ def _group_argument_list(
normal_args,
vararg,
keyword_only_args,
kwargs
kwargs,
)
def _signature_argument_list(
argument_list: list[PythonFunctionArgument]
argument_list: list[PythonFunctionArgument],
) -> list[str]:
'''
Returns a list of the arguments as strings for a function signature.
@@ -142,7 +142,7 @@ def _signature_argument_list(
normal_args,
vararg,
keyword_only_args,
kwargs
kwargs,
) = _group_argument_list(argument_list)
args = []
@@ -198,7 +198,7 @@ def _markdown_table(
allow_markdown_table: bool = False,
force_row_lengths: bool = False,
one_line_values: bool = True,
missing_value: str = '--'
missing_value: str = '--',
) -> str:
'''
Generates a table.
@@ -247,7 +247,7 @@ def _markdown_table(
"s"
if header_len > 1
else ""
}, got {len(row)}'
}, got {len(row)}',
)
else:
row = _fit_row_length(header_len, row)
@@ -273,7 +273,7 @@ def _markdown_table(
"s"
if header_len > 1
else ""
}, got {len(row)}'
}, got {len(row)}',
)
else:
row = _fit_row_length(header_len, row)
@@ -358,7 +358,7 @@ def _argument_kind_human_readable(argument_kind: PythonArgumentKind) -> str:
def _function_params_info(
arg_list: list[PythonFunctionArgument],
docstring_arg_list: list[docstring_parser.DocstringParam]
docstring_arg_list: list[docstring_parser.DocstringParam],
) -> dict[str, _FunctionParamInfo]:
'''
Returns a dictionary with the parameter info.
@@ -388,7 +388,7 @@ def _function_params_info(
if arg.arg_name in arg_annotations.keys():
arg_annotations[arg.arg_name] = _FunctionParamInfo(
arg_annotations[arg.arg_name].annotation or arg.type_name,
arg.description
arg.description,
)
return arg_annotations
@@ -427,7 +427,7 @@ class PythonDefinitionDocumentationIncludeSections:
docstring: bool = True,
bases: bool = True,
decorators: bool = True,
class_body: bool = True
class_body: bool = True,
):
self.signature = signature
self.returns = returns
@@ -456,13 +456,13 @@ class PythonDefinitionDocumentationIncludeSections:
[
key + ' = ' + repr(value)
for key, value in self._args.items()
]
],
) + ')'
def __eq__(self, value) -> str:
if not isinstance(
value,
PythonDefinitionDocumentationIncludeSections
PythonDefinitionDocumentationIncludeSections,
):
return False
return self._args == value._args
@@ -505,7 +505,7 @@ class PythonDefinitionDocumentationGenerator:
allow_html: bool = True,
allow_tables: bool = False,
skip_empty_sections: bool = True,
is_method: bool = False
is_method: bool = False,
) -> None:
self.definition = definition
self.include_sections = include_sections
@@ -539,13 +539,13 @@ class PythonDefinitionDocumentationGenerator:
if isinstance(self.definition, PythonClassDefinition):
raise TypeError(
'Cannot generate a signature of a class definition.'
'Cannot generate a signature of a class definition.',
)
signature = self.definition.name + '(' + ', '.join(
_signature_argument_list(
self.definition.args
)
self.definition.args,
),
) + ')'
if self.definition.returns is not None:
@@ -616,7 +616,7 @@ class PythonDefinitionDocumentationGenerator:
params_types = _function_params_info(
self.definition.args,
self._docstring.params
self._docstring.params,
)
if params_types:
@@ -632,11 +632,11 @@ class PythonDefinitionDocumentationGenerator:
('`' + arg.default + '`')
if arg.default is not None
else None,
non_empty_str(params_types.get(arg.name).description)
non_empty_str(params_types.get(arg.name).description),
)
for arg in self.definition.args
],
allow_markdown_table = self.allow_tables
allow_markdown_table = self.allow_tables,
)
md += '\n\n'
@@ -800,7 +800,7 @@ class PythonDefinitionDocumentationGenerator:
allow_html = self.allow_html,
allow_tables = self.allow_tables,
skip_empty_sections = self.skip_empty_sections,
is_method = True
is_method = True,
).generate_documentation() + '\n\n'
if not self.definition.body and not self.skip_empty_sections:
@@ -896,12 +896,12 @@ class PythonModuleDocumentationGenerator:
include_sections: PythonDefinitionDocumentationIncludeSections = (
PythonDefinitionDocumentationIncludeSections()
),
**kwargs
**kwargs,
) -> None:
if module_path.name.count('.') > 1:
raise InvalidNamespaceError(
'namespace identifier cannot contain more than one dot',
namespace_identifier = module_path.name
namespace_identifier = module_path.name,
)
self.module_path = pathlib.Path(str(module_path))
@@ -956,8 +956,8 @@ class PythonModuleDocumentationGenerator:
module_identifier = '.'.join(
get_relative_path_segments(
self.module_path,
self.src_directory
)
self.src_directory,
),
)
if module_identifier.endswith('.py'):
md += module_identifier[:-3]
@@ -977,7 +977,7 @@ class PythonModuleDocumentationGenerator:
definition,
self.include_sections,
2,
**self.kwargs
**self.kwargs,
).generate_documentation() + '\n\n'
return md.strip()
@@ -990,7 +990,7 @@ def _generate_package_namespace_documentation(
include_sections: PythonDefinitionDocumentationIncludeSections = (
PythonDefinitionDocumentationIncludeSections()
),
kwargs: dict = {}
kwargs: dict = {},
) -> None:
'''
Generates the documentation for a package namespace and writes it to
@@ -1021,7 +1021,7 @@ def _generate_package_namespace_documentation(
documentation_directory / sub_namespace.name,
root_directory, dir / sub_namespace.name,
include_sections,
kwargs
kwargs,
)
elif isinstance(sub_namespace, PythonModuleNamespace):
(
@@ -1031,7 +1031,7 @@ def _generate_package_namespace_documentation(
pathlib.Path(str(dir / (sub_namespace.name + '.py'))),
pathlib.Path(str(root_directory)),
include_sections,
**kwargs
**kwargs,
).generate_documentation()
)
@@ -1055,7 +1055,7 @@ class PythonDocumentationGenerator:
include_sections: PythonDefinitionDocumentationIncludeSections = (
PythonDefinitionDocumentationIncludeSections()
),
**kwargs
**kwargs,
) -> None:
self.project_directory = pathlib.Path(str(project_directory))
self.docs_directory = pathlib.Path(str(docs_directory))
@@ -1100,5 +1100,5 @@ class PythonDocumentationGenerator:
self.project_directory / 'src',
self.project_directory / 'src',
self.include_sections,
self.kwargs
self.kwargs,
)
src/jcloud_docsgen/core/python/arguments.py
+29 -27
View File
@@ -20,7 +20,7 @@ from ...utils import assert_that_is_instance
from ...exceptions import (
InvalidPythonAnnotationError,
InvalidPythonIdentifierError,
PythonArgumentStructureError
PythonArgumentStructureError,
)
import keyword
import types
@@ -28,7 +28,7 @@ import types
__all__ = [
'PythonArgumentKind',
'PythonFunctionArgument',
'PythonASTArgumentsListParser'
'PythonASTArgumentsListParser',
]
class PythonArgumentKind(Enum):
@@ -57,7 +57,7 @@ class PythonFunctionArgument:
name: str,
kind: PythonArgumentKind,
default: Union[str, None],
annotation: Union[str, None]
annotation: Union[str, None],
) -> None:
assert_that_is_instance(name, str)
assert_that_is_instance(kind, PythonArgumentKind)
@@ -68,7 +68,7 @@ class PythonFunctionArgument:
if not name or not name.isidentifier() or keyword.iskeyword(name):
raise InvalidPythonIdentifierError(
'invalid identifier',
identifier = name
identifier = name,
)
# check whether the annotation is a valid annotation
@@ -77,7 +77,7 @@ class PythonFunctionArgument:
if annotation is not None and not annotation:
raise InvalidPythonAnnotationError(
'invalid annotation',
annotation = annotation
annotation = annotation,
)
self.name = name
@@ -87,11 +87,11 @@ class PythonFunctionArgument:
if self.kind in (
PythonArgumentKind.VARARG,
PythonArgumentKind.KWARGS
PythonArgumentKind.KWARGS,
) and self.default is not None:
raise PythonArgumentStructureError(
'* or ** arguments cannot have default values',
definition = self.signature_repr()
definition = self.signature_repr(),
)
def __eq__(self, value: PythonFunctionArgument) -> bool:
@@ -109,7 +109,7 @@ class PythonFunctionArgument:
self.name,
self.kind,
self.default,
self.annotation
self.annotation,
))
def signature_repr(self) -> str:
@@ -192,8 +192,8 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.POSITIONAL_ONLY,
defaults[i],
None
)
None,
),
)
else:
arguments.append(
@@ -201,7 +201,9 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.POSITIONAL_ONLY,
defaults[i],
ast.unparse(arg.annotation)))
ast.unparse(arg.annotation),
),
)
i += 1
for arg in self.ast_arguments_list.args:
if arg.annotation is None:
@@ -210,8 +212,8 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.NORMAL,
defaults[i],
None
)
None,
),
)
else:
arguments.append(
@@ -219,8 +221,8 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.NORMAL,
defaults[i],
ast.unparse(arg.annotation)
)
ast.unparse(arg.annotation),
),
)
i += 1
if self.ast_arguments_list.vararg is not None:
@@ -230,8 +232,8 @@ class PythonASTArgumentsListParser:
self.ast_arguments_list.vararg.arg,
PythonArgumentKind.VARARG,
None,
None
)
None,
),
)
else:
arguments.append(
@@ -239,8 +241,8 @@ class PythonASTArgumentsListParser:
self.ast_arguments_list.vararg.arg,
PythonArgumentKind.VARARG,
None,
ast.unparse(self.ast_arguments_list.vararg.annotation)
)
ast.unparse(self.ast_arguments_list.vararg.annotation),
),
)
for arg in self.ast_arguments_list.kwonlyargs:
if arg.annotation is None:
@@ -249,8 +251,8 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.KEYWORD_ONLY,
defaults[i],
None
)
None,
),
)
else:
arguments.append(
@@ -258,8 +260,8 @@ class PythonASTArgumentsListParser:
arg.arg,
PythonArgumentKind.KEYWORD_ONLY,
defaults[i],
ast.unparse(arg.annotation)
)
ast.unparse(arg.annotation),
),
)
i += 1
if self.ast_arguments_list.kwarg is not None:
@@ -269,8 +271,8 @@ class PythonASTArgumentsListParser:
self.ast_arguments_list.kwarg.arg,
PythonArgumentKind.KWARGS,
None,
None
)
None,
),
)
else:
arguments.append(
@@ -278,8 +280,8 @@ class PythonASTArgumentsListParser:
self.ast_arguments_list.kwarg.arg,
PythonArgumentKind.KWARGS,
None,
ast.unparse(self.ast_arguments_list.kwarg.annotation)
)
ast.unparse(self.ast_arguments_list.kwarg.annotation),
),
)
return arguments
src/jcloud_docsgen/core/python/definitions.py
+11 -11
View File
@@ -26,7 +26,7 @@ __all__ = [
'PythonDefinition',
'PythonFunctionDefinition',
'PythonAsyncFunctionDefinition',
'PythonClassDefinition'
'PythonClassDefinition',
]
def _python_docstring(doc: Union[str, None]) -> Union[PythonDocstring, None]:
@@ -63,12 +63,12 @@ class PythonDefinition:
self,
name: str,
doc: Union[PythonDocstring, None],
decorators: list[str]
decorators: list[str],
) -> None:
if keyword.iskeyword(name) or not name.isidentifier() or not name:
raise InvalidPythonIdentifierError(
'invalid identifier',
identifier = name
identifier = name,
)
assert_that_is_instance(doc, (PythonDocstring, types.NoneType))
@@ -81,7 +81,7 @@ class PythonDefinition:
return (
self.name,
self.doc,
self.decorators
self.decorators,
)
def __repr__(self) -> str:
@@ -99,7 +99,7 @@ class PythonDefinition:
return cls(
node.name,
_python_docstring(ast.get_docstring(node)),
[ast.unparse(d) for d in node.decorator_list]
[ast.unparse(d) for d in node.decorator_list],
)
def __eq__(self, value: object) -> bool:
@@ -133,7 +133,7 @@ class PythonFunctionDefinition(PythonDefinition):
args: list[PythonFunctionArgument],
returns: Union[str, None],
doc: Union[PythonDocstring, None],
decorators: list[str]
decorators: list[str],
) -> None:
super().__init__(name, doc, decorators)
self.args = args
@@ -145,7 +145,7 @@ class PythonFunctionDefinition(PythonDefinition):
self.args,
self.returns,
self.doc,
self.decorators
self.decorators,
)
@classmethod
@@ -162,7 +162,7 @@ class PythonFunctionDefinition(PythonDefinition):
PythonASTArgumentsListParser(node.args).to_argument_list(),
ast.unparse(node.returns) if node.returns is not None else None,
_python_docstring(ast.get_docstring(node)),
[ast.unparse(d) for d in node.decorator_list]
[ast.unparse(d) for d in node.decorator_list],
)
class PythonAsyncFunctionDefinition(PythonFunctionDefinition):
@@ -210,7 +210,7 @@ class PythonClassDefinition(PythonDefinition):
bases: list[str],
doc: Union[PythonDocstring, None],
decorators: list[str],
body: list[PythonDefinition]
body: list[PythonDefinition],
) -> None:
super().__init__(name, doc, decorators)
self.bases = bases
@@ -222,7 +222,7 @@ class PythonClassDefinition(PythonDefinition):
self.bases,
self.doc,
self.decorators,
self.body
self.body,
)
@classmethod
@@ -253,5 +253,5 @@ class PythonClassDefinition(PythonDefinition):
expr,
(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
)
]
],
)
src/jcloud_docsgen/core/python/namespaces.py
+9 -9
View File
@@ -16,7 +16,7 @@ from __future__ import annotations
from ...exceptions import (
InvalidNamespaceError,
NamespaceNotFoundError,
NamespaceExistsError
NamespaceExistsError,
)
from ...utils import assert_that_is_instance
from typing import Union, TypeAlias, Dict, List
@@ -24,7 +24,7 @@ from typing import Union, TypeAlias, Dict, List
__all__ = [
'PythonNamespace',
'PythonPackageNamespace',
'PythonModuleNamespace'
'PythonModuleNamespace',
]
class PythonNamespace:
@@ -40,7 +40,7 @@ class PythonNamespace:
if not name.strip():
raise InvalidNamespaceError(
'invalid namespace',
namespace_identifier = name
namespace_identifier = name,
)
self.name = name
@@ -52,8 +52,8 @@ PythonPackageNamespaceDictType: TypeAlias = Dict[
str,
Union[
str,
'PythonPackageNamespaceDictType'
]
'PythonPackageNamespaceDictType',
],
]
class PythonPackageNamespace(PythonNamespace):
@@ -69,7 +69,7 @@ class PythonPackageNamespace(PythonNamespace):
def __init__(
self,
name: str,
sub_namespaces: List[PythonNamespace]
sub_namespaces: List[PythonNamespace],
) -> None:
assert_that_is_instance(sub_namespaces, list)
@@ -113,7 +113,7 @@ class PythonPackageNamespace(PythonNamespace):
def _sub_namespaces_names(
self,
package: PythonPackageNamespace
package: PythonPackageNamespace,
) -> PythonPackageNamespaceDictType:
'''
Returns the names of all sub-namespaces of the specified package
@@ -177,7 +177,7 @@ class PythonPackageNamespace(PythonNamespace):
raise NamespaceNotFoundError(
'no such namespace',
namespace_identifier = name
namespace_identifier = name,
)
def add(self, namespace: PythonNamespace) -> None:
@@ -195,7 +195,7 @@ class PythonPackageNamespace(PythonNamespace):
self.__getitem__(namespace.name)
raise NamespaceExistsError(
'namespace already exists',
namespace_identifier = namespace.name
namespace_identifier = namespace.name,
)
except NamespaceNotFoundError:
self._sub_namespaces.append(namespace)