jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1183264?usp=email )

Change subject: doc: Refactor docstrings of category.py script ......................................................................

doc: Refactor docstrings of category.py script

Change-Id: Ifd9dbdb9b5e4ac93341447311f4eecb981f8fe34 --- M scripts/category.py 1 file changed, 80 insertions(+), 31 deletions(-)

Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified

diff --git a/scripts/category.py b/scripts/category.py index 99f918b..8794727 100755 --- a/scripts/category.py +++ b/scripts/category.py @@ -472,16 +472,25 @@ self.comment = comment

@staticmethod - def sorted_by_last_name(catlink, pagelink) -> pywikibot.Page: - """Return a Category with key that sorts persons by their last name. + def sorted_by_last_name(catlink: pywikibot.Page, + pagelink: pywikibot.Page) -> pywikibot.Page: + """Return a category entry for a person, sorted by last name.

- Parameters: catlink - The Category to be linked. - pagelink - the Page to be placed in the category. + If the page title contains a disambiguation suffix in brackets, + it will be removed. The last word of the (cleaned) title is + treated as the surname and moved to the front, separated by a + comma.

- Trailing words in brackets will be removed. Example: If - category_name is 'Author' and pl is a Page to [[Alexandre Dumas - (senior)]], this function will return this Category: - [[Category:Author|Dumas, Alexandre]]. + Example: + If *catlink* is ``Category:Author`` and *pagelink* points to + ``[[Alexandre Dumas (senior)]]``, this method returns:: + + [[Category:Author|Dumas, Alexandre]] + + :param catlink: Category page where the entry should be added. + :param pagelink: Page of the person to be categorized. + :return: A page object representing the category entry with the + correct sort key. """ page_name = pagelink.title() site = pagelink.site @@ -1323,49 +1332,89 @@

"""Robot to create tree overviews of the category structure.

- Parameters: - * cat_title - The category which will be the tree's root. - * cat_db - A CategoryDatabase object. - * max_depth - The limit beyond which no subcategories will be listed. - This also guarantees that loops in the category structure - won't be a problem. - * filename - The textfile where the tree should be saved; None to print - the tree to stdout. + This class generates a hierarchical overview of categories starting + from a given root category. The tree can be printed to stdout or + written to a file. Cycles in the category structure are prevented + by limiting the depth. + + Example: + Create a tree view of ``Category:Physics`` up to 5 levels deep + and save it to ``physics_tree.txt``:: + + db = CategoryDatabase() + robot = CategoryTreeRobot( + 'Physics', db, 'physics_tree.txt', max_depth=5) + + .. versionchanged:: 10.4 + *max_depth* is keyword only. + + :param cat_title: The category that serves as the root of the + tree. + :param cat_db: A :class:`CategoryDatabase` object + providing access to category data. + :param filename: Path to the text file where the tree + should be saved. If ``None``, the user will be prompted to enter + a filename. If an empty string is entered, the tree will be + printed to stdout. Relative paths are converted to absolute + paths using :meth:`config.datafilepath`. + :param max_depth: Maximum depth of subcategories to traverse. + Prevents infinite loops. """

def __init__( self, - cat_title, - cat_db, - filename=None, + cat_title: str, + cat_db: CategoryDatabase, + filename: str | None = None, + *, max_depth: int = 10 ) -> None: """Initializer.""" - self.cat_title = cat_title or \ - pywikibot.input( + self.cat_title = cat_title \ + or pywikibot.input( 'For which category do you want to create a tree view?') self.cat_db = cat_db if filename is None: filename = pywikibot.input( 'Please enter the name of the file ' 'where the tree should be saved,\n' - 'or press enter to simply show the tree:') + 'or press enter to simply show the tree:' + ) if filename and not os.path.isabs(filename): filename = config.datafilepath(filename) self.filename = filename self.max_depth = max_depth self.site = pywikibot.Site()

- def treeview(self, cat, current_depth: int = 0, parent=None) -> str: - """Return a tree view of all subcategories of cat. + def treeview(self, + cat: pywikibot.Category, + current_depth: int = 0, + *, + parent: pywikibot.Category | None = None) -> str: + """Return a tree view of subcategories as a multi-line string.

- The multi-line string contains a tree view of all subcategories of cat, - up to level max_depth. Recursively calls itself. + Generates a hierarchical tree view of all subcategories of the + given category *cat*, up to the depth specified by + ``self.max_depth``. This method is recursive.

- Parameters: - * cat - the Category of the node we're currently opening. - * current_depth - the current level in the tree (for recursion). - * parent - the Category of the category we're coming from. + .. versionchanged:: 10.4 + *parent* is keyword only. + + Example: + To get a tree view of ``Category:Physics`` starting at depth 0:: + + cat = pywikibot.Category(site, 'Physics') + tree = robot.treeview(cat) + + :param cat: The Category object currently being expanded in the + tree. + :param current_depth: Current depth level in the tree (used for + recursion). + :param parent: The parent Category from which we descended (to + avoid cycles). + :return: A multi-line string representing the tree structure, + including the number of pages in each category and links to + supercategories. """ result = '#' * current_depth if current_depth > 0: @@ -1680,7 +1729,7 @@ gen_factory.namespaces, summary) elif action == 'tree': bot = CategoryTreeRobot(options.get('from'), cat_db, - options.get('to'), depth) + options.get('to'), max_depth=depth) elif action == 'listify': bot = CategoryListifyRobot(options.get('from'), options.get('to'), summary,