[Pywikibot-commits] [Gerrit] ...core[master]: [cleanup] Minor add_text documentation revisions

jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/693983 ) Change subject: [cleanup] Minor add_text documentation revisions ...................................................................... [cleanup] Minor add_text documentation revisions To better acquaint myself with the codebase I'm focusing on one of our scripts. This is just some benign adjustments from a first pass... * Add an example that amends the sandbox page so users have a simple, innocuous command to practice with. * Drop the 'put it in one line' warnings. I tried it and multiple lines works just fine. * Minor get_text simplification so we don't indent as much. * The documented behavior of get_text's create argument was incorrect. * Add the page's type hint. * Minor grammatical corrections. Change-Id: I65a05217b2704ba09c6916c694cf28fdd546ed61 --- M scripts/add_text.py 1 file changed, 55 insertions(+), 57 deletions(-) Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified diff --git a/scripts/add_text.py b/scripts/add_text.py index f937434..1cfa980 100755 --- a/scripts/add_text.py +++ b/scripts/add_text.py @@ -1,20 +1,19 @@ #!/usr/bin/python r""" -This is a Bot to add a text at the end of the content of the page. +This is a Bot to add text to the top or bottom of a page. -By default it adds the text above categories and interwiki. +By default this adds the text to the bottom above the categories and interwiki. -Alternatively it may also add a text at the top of the page. These command line parameters can be used to specify which pages to work on: &params; Furthermore, the following command line parameters are supported: --talkpage Put the text onto the talk page instead the generated on +-talkpage Put the text onto the talk page instead -talk --text Define which text to add. "\n" are interpreted as newlines. +-text Define what text to add. "\n" are interpreted as newlines. -textfile Define a texfile name which contains the text to add @@ -25,26 +24,28 @@ -newimages Add text in the new images --always If used, the bot won't ask if it should add the text - specified +-always If used, the bot won't ask if it should add the specified + text -up If used, put the text at the top of the page --noreorder Avoid to reorder cats and interwiki +-noreorder Avoid reordering cats and interwiki Example ------- -1. This is a script to add a template to the top of the pages with -category:catname -Warning! Put it in one line, otherwise it won't work correctly: +1. Append 'hello world' to the bottom of the sandbox: + + python pwb.py add_text -page:Wikipedia:Sandbox \ + -summary:"Bot: pywikibot practice" -text:"hello world" + +2. Add a template to the top of the pages with 'category:catname': python pwb.py add_text -cat:catname -summary:"Bot: Adding a template" \ -text:"{{Something}}" -except:"\{\{([Tt]emplate:|)[Ss]omething" -up -2. Command used on it.wikipedia to put the template in the page without any -category. -Warning! Put it in one line, otherwise it won't work correctly: +3. Command used on it.wikipedia to put the template in the page without any + category: python pwb.py add_text -except:"\{\{([Tt]emplate:|)[Cc]ategorizzare" \ -text:"{{Categorizzare}}" -excepturl:"class='catlinks'>" -uncat \ @@ -81,50 +82,46 @@ docuReplacements = {'&params;': pagegenerators.parameterHelp} # noqa: N816 -def get_text(page, old: str, create: bool) -> str: +def get_text(page: pywikibot.page.BasePage, old: Optional[str], + create: bool) -> str: """ Get text on page. If old is not None, return old. @param page: The page to get text from - @type page: pywikibot.page.BasePage - @param old: If not None, this parameter is returned instead - of fetching text from the page - @param create: Create the page if it doesn't exist - @return: The page's text or old parameter if not None + @param old: If not None, return this rather than the page's text + @param create: Declare that the page will be created if it doesn't exist + @return: The page's text or the old parameter if not None """ - if old is None: - try: - text = page.get() - except NoPageError: - if create: - pywikibot.output( - "{} doesn't exist, creating it!".format(page.title())) - text = '' - else: - pywikibot.output( - "{} doesn't exist, skip!".format(page.title())) - return None - except IsRedirectPageError: - pywikibot.output('{} is a redirect, skip!'.format(page.title())) + if old is not None: + return old + + try: + return page.get() + except NoPageError: + if create: + pywikibot.output("{} doesn't exist, creating it!" + .format(page.title())) + return '' + else: + pywikibot.output("{} doesn't exist, skip!".format(page.title())) return None - else: - text = old - return text + except IsRedirectPageError: + pywikibot.output('{} is a redirect, skip!'.format(page.title())) + return None -def put_text(page, new: str, summary: str, count: int, +def put_text(page: pywikibot.page.BasePage, new: str, summary: str, count: int, asynchronous: bool = False) -> Optional[bool]: """ Save the new text. - @param page: The page to update and save - @type page: pywikibot.page.BasePage + @param page: The page to change the text of @param new: The new text for the page - @param summary: Summary of page changes. - @param count: Maximum num attempts to reach the server - @param asynchronous: Save the page asynchronously - @return: True if successful, False if unsuccessful, None if - waiting for server + @param summary: Summary of the page change + @param count: Maximum number of attempts to reach the server + @param asynchronous: If True, saves the page asynchronously + @return: True if successful, False if unsuccessful, and None if + awaiting the server """ page.text = new try: @@ -152,7 +149,8 @@ return False -def add_text(page, addText: str, summary: Optional[str] = None, +def add_text(page: pywikibot.page.BasePage, addText: str, + summary: Optional[str] = None, regexSkip: Optional[str] = None, regexSkipUrl: Optional[str] = None, always: bool = False, up: bool = False, @@ -163,21 +161,21 @@ Add text to a page. @param page: The page to add text to - @type page: pywikibot.page.BasePage @param addText: Text to add - @param summary: Summary of changes. If None, beginning of addText is used. - @param regexSkip: Abort if text on page matches - @param regexSkipUrl: Abort if full url matches - @param always: Always add text without user confirmation - @param up: If True, add text to top of page, else add at bottom. - @param putText: If True, save changes to the page, else return + @param summary: Change summary, if None this uses the beginning of addText + @param regexSkip: Abort if the text on the page matches this + @param regexSkipUrl: Abort if the url matches this + @param always: Edit without user confirmation + @param up: Append text to the top of the page if True, otherwise the + bottom + @param putText: Save changes to the page if True, otherwise return (text, newtext, always) @param oldTextGiven: If None fetch page text, else use this text @param reorderEnabled: If True place text above categories and interwiki, else place at page bottom. No effect if up = False. - @param create: Create page if it does not exist - @return: If putText=True: (success, success, always) - else: (text, newtext, always) + @param create: Create the page if it does not exist + @return: (success, success, always) if putText is True, otherwise + (text, newtext, always) """ site = page.site if not summary: @@ -282,7 +280,7 @@ If args is an empty list, sys.argv is used. - @param args: command line arguments + @param args: Command line arguments """ # If none, the var is set only for check purpose. summary = None -- To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/693983 To unsubscribe, or for help writing mail filters, visit https://gerrit.wikimedia.org/r/settings Gerrit-Project: pywikibot/core Gerrit-Branch: master Gerrit-Change-Id: I65a05217b2704ba09c6916c694cf28fdd546ed61 Gerrit-Change-Number: 693983 Gerrit-PatchSet: 3 Gerrit-Owner: Damian <atagar1(a)gmail.com> Gerrit-Reviewer: D3r1ck01 <xsavitar.wiki(a)aol.com> Gerrit-Reviewer: Xqt <info(a)gno.de> Gerrit-Reviewer: jenkins-bot Gerrit-MessageType: merged