Skip to content

MkDocs improvements for auto-documented code using mkdocstrings #1409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 25, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions cmd2/ansi.py
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ def clear_screen(clear_type: int = 2) -> str:
2 - clear entire screen
3 - clear entire screen and delete all lines saved in the scrollback buffer
:return: the clear screen string
:raises: ValueError if clear_type is not a valid value
:raises ValueError: if clear_type is not a valid value
"""
if 0 <= clear_type <= 3:
return f"{CSI}{clear_type}J"
Expand All @@ -182,7 +182,7 @@ def clear_line(clear_type: int = 2) -> str:
1 - clear from cursor to beginning of the line
2 - clear entire line
:return: the clear line string
:raises: ValueError if clear_type is not a valid value
:raises ValueError: if clear_type is not a valid value
"""
if 0 <= clear_type <= 2:
return f"{CSI}{clear_type}K"
Expand Down Expand Up @@ -915,7 +915,7 @@ def __init__(self, r: int, g: int, b: int) -> None:
:param r: integer from 0-255 for the red component of the color
:param g: integer from 0-255 for the green component of the color
:param b: integer from 0-255 for the blue component of the color
:raises: ValueError if r, g, or b is not in the range 0-255
:raises ValueError: if r, g, or b is not in the range 0-255
"""
if any(c < 0 or c > 255 for c in [r, g, b]):
raise ValueError("RGB values must be integers in the range of 0 to 255")
Expand Down Expand Up @@ -944,7 +944,7 @@ def __init__(self, r: int, g: int, b: int) -> None:
:param r: integer from 0-255 for the red component of the color
:param g: integer from 0-255 for the green component of the color
:param b: integer from 0-255 for the blue component of the color
:raises: ValueError if r, g, or b is not in the range 0-255
:raises ValueError: if r, g, or b is not in the range 0-255
"""
if any(c < 0 or c > 255 for c in [r, g, b]):
raise ValueError("RGB values must be integers in the range of 0 to 255")
Expand Down Expand Up @@ -988,8 +988,8 @@ def style(
:param overline: apply the overline style if True. Defaults to False.
:param strikethrough: apply the strikethrough style if True. Defaults to False.
:param underline: apply the underline style if True. Defaults to False.
:raises: TypeError if fg isn't None or a subclass of FgColor
:raises: TypeError if bg isn't None or a subclass of BgColor
:raises TypeError: if fg isn't None or a subclass of FgColor
:raises TypeError: if bg isn't None or a subclass of BgColor
:return: the stylized string
"""
# List of strings that add style
Expand Down
6 changes: 3 additions & 3 deletions cmd2/argparse_completer.py
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ def complete(
:param cmd_set: if tab completing a command, the CommandSet the command's function belongs to, if applicable.
Defaults to None.

:raises: CompletionError for various types of tab completion errors
:raises CompletionError: for various types of tab completion errors
"""
if not tokens:
return []
Expand Down Expand Up @@ -264,7 +264,7 @@ def update_mutex_groups(arg_action: argparse.Action) -> None:
Check if an argument belongs to a mutually exclusive group and either mark that group
as complete or print an error if the group has already been completed
:param arg_action: the action of the argument
:raises: CompletionError if the group is already completed
:raises CompletionError: if the group is already completed
"""
# Check if this action is in a mutually exclusive group
for group in self._parser._mutually_exclusive_groups:
Expand Down Expand Up @@ -679,7 +679,7 @@ def _complete_arg(
"""
Tab completion routine for an argparse argument
:return: list of completions
:raises: CompletionError if the completer or choices function this calls raises one
:raises CompletionError: if the completer or choices function this calls raises one
"""
# Check if the arg provides choices to the user
arg_choices: Union[List[str], ChoicesCallable]
Expand Down
9 changes: 4 additions & 5 deletions cmd2/argparse_custom.py
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,6 @@ def __init__(self, value: object, description: str = '', *args: Any) -> None:
:param value: the value being tab completed
:param description: description text to display
:param args: args for str __init__
:param kwargs: kwargs for str __init__
"""
super().__init__(*args)
self.description = description
Expand Down Expand Up @@ -473,7 +472,7 @@ def _action_set_choices_callable(self: argparse.Action, choices_callable: Choice

:param self: action being edited
:param choices_callable: the ChoicesCallable instance to use
:raises: TypeError if used on incompatible action type
:raises TypeError: if used on incompatible action type
"""
# Verify consistent use of parameters
if self.choices is not None:
Expand Down Expand Up @@ -504,7 +503,7 @@ def _action_set_choices_provider(

:param self: action being edited
:param choices_provider: the choices_provider instance to use
:raises: TypeError if used on incompatible action type
:raises TypeError: if used on incompatible action type
"""
self._set_choices_callable(ChoicesCallable(is_completer=False, to_call=choices_provider)) # type: ignore[attr-defined]

Expand All @@ -525,7 +524,7 @@ def _action_set_completer(

:param self: action being edited
:param completer: the completer instance to use
:raises: TypeError if used on incompatible action type
:raises TypeError: if used on incompatible action type
"""
self._set_choices_callable(ChoicesCallable(is_completer=True, to_call=completer)) # type: ignore[attr-defined]

Expand Down Expand Up @@ -758,7 +757,7 @@ def _add_argument_wrapper(
See the header of this file for more information

:return: the created argument action
:raises: ValueError on incorrect parameter usage
:raises ValueError: on incorrect parameter usage
"""
# Verify consistent use of arguments
choices_callables = [choices_provider, completer]
Expand Down
22 changes: 11 additions & 11 deletions cmd2/cmd2.py
Original file line number Diff line number Diff line change
Expand Up @@ -1134,7 +1134,7 @@ def remove_settable(self, name: str) -> None:
Convenience method for removing a settable parameter from ``self.settables``

:param name: name of the settable being removed
:raises: KeyError if the Settable matches this name
:raises KeyError: if the Settable matches this name
"""
try:
del self._settables[name]
Expand Down Expand Up @@ -2701,8 +2701,8 @@ def _complete_statement(self, line: str, *, orig_rl_history_length: Optional[int
This is used to assist in combining multiline readline history entries and is only
populated by cmd2. Defaults to None.
:return: the completed Statement
:raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
:raises: EmptyStatement when the resulting Statement is blank
:raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
:raises EmptyStatement: when the resulting Statement is blank
"""

def combine_rl_history(statement: Statement) -> None:
Expand Down Expand Up @@ -2788,8 +2788,8 @@ def _input_line_to_statement(self, line: str, *, orig_rl_history_length: Optiona
This is used to assist in combining multiline readline history entries and is only
populated by cmd2. Defaults to None.
:return: parsed command line as a Statement
:raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
:raises: EmptyStatement when the resulting Statement is blank
:raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
:raises EmptyStatement: when the resulting Statement is blank
"""
used_macros = []
orig_line = None
Expand Down Expand Up @@ -2879,7 +2879,7 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState:

:param statement: a parsed statement from the user
:return: A bool telling if an error occurred and a utils.RedirectionSavedState object
:raises: RedirectionError if an error occurs trying to pipe or redirect
:raises RedirectionError: if an error occurs trying to pipe or redirect
"""
import io
import subprocess
Expand Down Expand Up @@ -3135,7 +3135,7 @@ def read_input(
:param parser: an argument parser which supports the tab completion of multiple arguments

:return: the line read from stdin with all trailing new lines removed
:raises: any exceptions raised by input() and stdin.readline()
:raises Exception: any exceptions raised by input() and stdin.readline()
"""
readline_configured = False
saved_completer: Optional[CompleterFunc] = None
Expand Down Expand Up @@ -3260,7 +3260,7 @@ def _read_command_line(self, prompt: str) -> str:

:param prompt: prompt to display to user
:return: command line text of 'eof' if an EOFError was caught
:raises: whatever exceptions are raised by input() except for EOFError
:raises Exception: whatever exceptions are raised by input() except for EOFError
"""
try:
# Wrap in try since terminal_lock may not be locked
Expand Down Expand Up @@ -5080,7 +5080,7 @@ def run_editor(self, file_path: Optional[str] = None) -> None:
Run a text editor and optionally open a file with it

:param file_path: optional path of the file to edit. Defaults to None.
:raises: EnvironmentError if self.editor is not set
:raises EnvironmentError: if self.editor is not set
"""
if not self.editor:
raise EnvironmentError("Please use 'set editor' to specify your text editing program of choice.")
Expand Down Expand Up @@ -5515,9 +5515,9 @@ def _report_disabled_command_usage(self, *_args: Any, message_to_print: str, **_
"""
Report when a disabled command has been run or had help called on it

:param args: not used
:param _args: not used
:param message_to_print: the message reporting that the command is disabled
:param kwargs: not used
:param _kwargs: not used
"""
# Set apply_style to False so message_to_print's style is not overridden
self.perror(message_to_print, apply_style=False)
Expand Down
6 changes: 3 additions & 3 deletions cmd2/command_definition.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ def _cmd(self) -> 'cmd2.Cmd':
Override this property if you need to change its return type to a
child class of Cmd.

:raises: CommandSetRegistrationError if CommandSet is not registered.
:raises CommandSetRegistrationError: if CommandSet is not registered.
"""
if self.__cmd_internal is None:
raise CommandSetRegistrationError('This CommandSet is not registered')
Expand All @@ -127,7 +127,7 @@ def on_register(self, cmd: 'cmd2.Cmd') -> None:
requiring access to the Cmd object (e.g. configure commands and their parsers based on CLI state data).

:param cmd: The cmd2 main application
:raises: CommandSetRegistrationError if CommandSet is already registered.
:raises CommandSetRegistrationError: if CommandSet is already registered.
"""
if self.__cmd_internal is None:
self.__cmd_internal = cmd
Expand Down Expand Up @@ -185,7 +185,7 @@ def remove_settable(self, name: str) -> None:
Convenience method for removing a settable parameter from the CommandSet

:param name: name of the settable being removed
:raises: KeyError if the Settable matches this name
:raises KeyError: if the Settable matches this name
"""
try:
del self._settables[name]
Expand Down
2 changes: 1 addition & 1 deletion cmd2/decorators.py
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,7 @@ def cmd_wrapper(*args: Any, **kwargs: Dict[str, Any]) -> Optional[bool]:
contiguously somewhere in the list
:param kwargs: any keyword arguments being passed to command function
:return: return value of command function
:raises: Cmd2ArgparseError if argparse has error parsing command line
:raises Cmd2ArgparseError: if argparse has error parsing command line
"""
cmd2_app, statement_arg = _parse_positionals(args)
statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
Expand Down
4 changes: 2 additions & 2 deletions cmd2/parsing.py
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,7 @@ def tokenize(self, line: str) -> List[str]:

:param line: the command line being lexed
:return: A list of tokens
:raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
:raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
"""

# expand shortcuts and aliases
Expand Down Expand Up @@ -404,7 +404,7 @@ def parse(self, line: str) -> Statement:

:param line: the command line being parsed
:return: a new [cmd2.parsing.Statement][] object
:raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
:raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
"""

# handle the special case/hardcoded terminator of a blank line
Expand Down
40 changes: 20 additions & 20 deletions cmd2/table_creator.py
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,8 @@ def __init__(
(defaults to True)
:param max_data_lines: maximum lines allowed in a data cell. If line count exceeds this, then the final
line displayed will be truncated with an ellipsis. (defaults to INFINITY)
:raises: ValueError if width is less than 1
:raises: ValueError if max_data_lines is less than 1
:raises ValueError: if width is less than 1
:raises ValueError: if max_data_lines is less than 1
"""
self.header = header

Expand Down Expand Up @@ -138,7 +138,7 @@ def __init__(self, cols: Sequence[Column], *, tab_width: int = 4) -> None:
:param cols: column definitions for this table
:param tab_width: all tabs will be replaced with this many spaces. If a row's fill_char is a tab,
then it will be converted to one space.
:raises: ValueError if tab_width is less than 1
:raises ValueError: if tab_width is less than 1
"""
if tab_width < 1:
raise ValueError("Tab width cannot be less than 1")
Expand Down Expand Up @@ -443,9 +443,9 @@ def generate_row(
:param post_line: string to print after each line of a row. This can be used for padding after
the last cell's text and a right row border. (Defaults to blank)
:return: row string
:raises: ValueError if row_data isn't the same length as self.cols
:raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
:raises: ValueError if fill_char, pre_line, inter_cell, or post_line contains an unprintable
:raises ValueError: if row_data isn't the same length as self.cols
:raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
:raises ValueError: if fill_char, pre_line, inter_cell, or post_line contains an unprintable
character like a newline
"""

Expand Down Expand Up @@ -570,10 +570,10 @@ def __init__(
want a divider row. Defaults to dash. (Cannot be a line breaking character)
:param header_bg: optional background color for header cells (defaults to None)
:param data_bg: optional background color for data cells (defaults to None)
:raises: ValueError if tab_width is less than 1
:raises: ValueError if column_spacing is less than 0
:raises: TypeError if divider_char is longer than one character
:raises: ValueError if divider_char is an unprintable character
:raises ValueError: if tab_width is less than 1
:raises ValueError: if column_spacing is less than 0
:raises TypeError: if divider_char is longer than one character
:raises ValueError: if divider_char is an unprintable character
"""
super().__init__(cols, tab_width=tab_width)

Expand Down Expand Up @@ -626,8 +626,8 @@ def base_width(cls, num_cols: int, *, column_spacing: int = 2) -> int:
:param num_cols: how many columns the table will have
:param column_spacing: how many spaces to place between columns. Defaults to 2.
:return: base width
:raises: ValueError if column_spacing is less than 0
:raises: ValueError if num_cols is less than 1
:raises ValueError: if column_spacing is less than 0
:raises ValueError: if num_cols is less than 1
"""
if num_cols < 1:
raise ValueError("Column count cannot be less than 1")
Expand Down Expand Up @@ -685,7 +685,7 @@ def generate_data_row(self, row_data: Sequence[Any]) -> str:

:param row_data: data with an entry for each column in the row
:return: data row string
:raises: ValueError if row_data isn't the same length as self.cols
:raises ValueError: if row_data isn't the same length as self.cols
"""
if len(row_data) != len(self.cols):
raise ValueError("Length of row_data must match length of cols")
Expand All @@ -712,7 +712,7 @@ def generate_table(self, table_data: Sequence[Sequence[Any]], *, include_header:
:param include_header: If True, then a header will be included at top of table. (Defaults to True)
:param row_spacing: A number 0 or greater specifying how many blank lines to place between
each row (Defaults to 1)
:raises: ValueError if row_spacing is less than 0
:raises ValueError: if row_spacing is less than 0
"""
if row_spacing < 0:
raise ValueError("Row spacing cannot be less than 0")
Expand Down Expand Up @@ -771,8 +771,8 @@ def __init__(
:param border_bg: optional background color for borders (defaults to None)
:param header_bg: optional background color for header cells (defaults to None)
:param data_bg: optional background color for data cells (defaults to None)
:raises: ValueError if tab_width is less than 1
:raises: ValueError if padding is less than 0
:raises ValueError: if tab_width is less than 1
:raises ValueError: if padding is less than 0
"""
super().__init__(cols, tab_width=tab_width)
self.empty_data = [EMPTY] * len(self.cols)
Expand Down Expand Up @@ -827,7 +827,7 @@ def base_width(cls, num_cols: int, *, column_borders: bool = True, padding: int
:param column_borders: if True, borders between columns will be included in the calculation (Defaults to True)
:param padding: number of spaces between text and left/right borders of cell
:return: base width
:raises: ValueError if num_cols is less than 1
:raises ValueError: if num_cols is less than 1
"""
if num_cols < 1:
raise ValueError("Column count cannot be less than 1")
Expand Down Expand Up @@ -976,7 +976,7 @@ def generate_data_row(self, row_data: Sequence[Any]) -> str:

:param row_data: data with an entry for each column in the row
:return: data row string
:raises: ValueError if row_data isn't the same length as self.cols
:raises ValueError: if row_data isn't the same length as self.cols
"""
if len(row_data) != len(self.cols):
raise ValueError("Length of row_data must match length of cols")
Expand Down Expand Up @@ -1077,8 +1077,8 @@ def __init__(
:param header_bg: optional background color for header cells (defaults to None)
:param odd_bg: optional background color for odd numbered data rows (defaults to None)
:param even_bg: optional background color for even numbered data rows (defaults to StdBg.DARK_GRAY)
:raises: ValueError if tab_width is less than 1
:raises: ValueError if padding is less than 0
:raises ValueError: if tab_width is less than 1
:raises ValueError: if padding is less than 0
"""
super().__init__(
cols,
Expand Down
Loading
Loading