From 1e0e9e3dd8dc6db07c0031e065908a08d2ca8b42 Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Sat, 5 May 2012 22:23:03 -0400 Subject: [PATCH] Cleanup docstrings in Page --- earwigbot/wiki/page.py | 123 +++++++++++++++++++++++++------------------------ 1 file changed, 64 insertions(+), 59 deletions(-) diff --git a/earwigbot/wiki/page.py b/earwigbot/wiki/page.py index 64b40a1..66581e6 100644 --- a/earwigbot/wiki/page.py +++ b/earwigbot/wiki/page.py @@ -184,8 +184,8 @@ class Page(CopyrightMixin): Loads self._title, ._exists, ._is_redirect, ._pageid, ._fullurl, ._protection, ._namespace, ._is_talkpage, ._creator, ._lastrevid, ._token, and ._starttimestamp using the API. It will do a query of - its own unless `result` is provided, in which case we'll pretend - `result` is what the query returned. + its own unless *result* is provided, in which case we'll pretend + *result* is what the query returned. Assuming the API is sound, this should not raise any exceptions. """ @@ -246,11 +246,11 @@ class Page(CopyrightMixin): def _load_content(self, result=None): """Loads current page content from the API. - If `result` is provided, we'll pretend that is the result of an API + If *result* is provided, we'll pretend that is the result of an API query and try to get content from that. Otherwise, we'll do an API query on our own. - Don't call this directly, ever - use reload() followed by get() if you + Don't call this directly, ever; use reload() followed by get() if you want to force content reloading. """ if not result: @@ -274,7 +274,7 @@ class Page(CopyrightMixin): tries=0): """Edit the page! - If `params` is given, we'll use it as our API query parameters. + If *params* is given, we'll use it as our API query parameters. Otherwise, we'll build params using the given kwargs via _build_edit_params(). @@ -464,11 +464,12 @@ class Page(CopyrightMixin): @property def pageid(self): - """Returns an integer ID representing the Page. + """An integer ID representing the Page. - Makes an API query if force is True or if we haven't already made one. + Makes an API query only if we haven't already made one. - Raises InvalidPageError or PageNotFoundError if the page name is + Raises :py:exc:`~earwigbot.exceptions.InvalidPageError` or + :py:exc:`~earwigbot.exceptions.PageNotFoundError` if the page name is invalid or the page does not exist, respectively. """ if self._exists == 0: @@ -478,11 +479,11 @@ class Page(CopyrightMixin): @property def url(self): - """Returns the page's URL. + """The page's URL. - Like title(), this won't do any API queries on its own unless force is - True. If the API was never queried for this page, we will attempt to - determine the URL ourselves based on the title. + Like :py:meth:`title`, this won't do any API queries on its own. If the + API was never queried for this page, we will attempt to determine the + URL ourselves based on the title. """ if self._fullurl: return self._fullurl @@ -493,45 +494,46 @@ class Page(CopyrightMixin): @property def namespace(self): - """Returns the page's namespace ID (an integer). + """The page's namespace ID (an integer). - Like title(), this won't do any API queries on its own unless force is - True. If the API was never queried for this page, we will attempt to - determine the namespace ourselves based on the title. + Like :py:meth:`title`, this won't do any API queries on its own. If the + API was never queried for this page, we will attempt to determine the + namespace ourselves based on the title. """ return self._namespace @property def protection(self): - """Returns the page's current protection status. + """The page's current protection status. - Makes an API query if force is True or if we haven't already made one. + Makes an API query only if we haven't already made one. - Raises InvalidPageError if the page name is invalid. Will not raise an - error if the page is missing because those can still be protected. + Raises :py:exc:`~earwigbot.exceptions.InvalidPageError` if the page + name is invalid. Won't raise an error if the page is missing because + those can still be create-protected. """ if self._exists == 0: self._load() - self._force_validity() # invalid pages cannot be protected + self._force_validity() # Invalid pages cannot be protected return self._protection @property def is_talkpage(self): - """Returns True if the page is a talkpage, else False. + """``True`` if the page is a talkpage, otherwise ``False``. - Like title(), this won't do any API queries on its own unless force is - True. If the API was never queried for this page, we will attempt to - determine the talkpage status ourselves based on its namespace ID. + Like :py:meth:`title`, this won't do any API queries on its own. If the + API was never queried for this page, we will attempt to determine + whether it is a talkpage ourselves based on its namespace. """ return self._is_talkpage @property def is_redirect(self): - """Returns True if the page is a redirect, else False. + """``True`` if the page is a redirect, otherwise ``False``. - Makes an API query if force is True or if we haven't already made one. + Makes an API query only if we haven't already made one. - We will return False even if the page does not exist or is invalid. + We will return ``False`` even if the page does not exist or is invalid. """ if self._exists == 0: self._load() @@ -552,17 +554,17 @@ class Page(CopyrightMixin): """Returns a content page's talk page, or vice versa. The title of the new page is determined by namespace logic, not API - queries. We won't make any API queries on our own unless force is True, - and the only reason then would be to forcibly update the title or - follow redirects if we haven't already made an API query. + queries. We won't make any API queries on our own. - If `follow_redirects` is anything other than None (the default), it - will be passed to the new Page's __init__(). Otherwise, we'll use the - value passed to our own __init__(). + If *follow_redirects* is anything other than ``None`` (the default), it + will be passed to the new :py:class:`~earwigbot.wiki.page.Page` + object's :py:meth:`__init__`. Otherwise, we'll use the value passed to + our own :py:meth:`__init__`. - Will raise InvalidPageError if we try to get the talk page of a special - page (in the Special: or Media: namespaces), but we won't raise an - exception if our page is otherwise missing or invalid. + Will raise :py:exc:`~earwigbot.exceptions.InvalidPageError` if we try + to get the talk page of a special page (in the ``Special:`` or + ``Media:`` namespaces), but we won't raise an exception if our page is + otherwise missing or invalid. """ if self._namespace < 0: ns = self._site.namespace_id_to_name(self._namespace) @@ -584,7 +586,7 @@ class Page(CopyrightMixin): # If the new page is in namespace 0, don't do ":Title" (it's correct, # but unnecessary), just do "Title": if new_prefix: - new_title = ':'.join((new_prefix, body)) + new_title = u":".join((new_prefix, body)) else: new_title = body @@ -629,11 +631,13 @@ class Page(CopyrightMixin): return self._content def get_redirect_target(self): - """If the page is a redirect, returns its destination. + """If the page is a redirect, return its destination. - Raises InvalidPageError or PageNotFoundError if the page name is - invalid or the page does not exist, respectively. Raises RedirectError - if the page is not a redirect. + Raises :py:exc:`~earwigbot.exceptions.InvalidPageError` or + :py:exc:`~earwigbot.exceptions.PageNotFoundError` if the page name is + invalid or the page does not exist, respectively. Raises + :py:exc:`~earwigbot.exceptions.RedirectError` if the page is not a + redirect. """ content = self.get() try: @@ -643,16 +647,17 @@ class Page(CopyrightMixin): raise exceptions.RedirectError(e) def get_creator(self): - """Returns the page's creator (i.e., the first user to edit the page). + """Return the User object for the first person to edit the page. - Makes an API query if force is True or if we haven't already made one. - Normally, we can get the creator along with everything else (except - content) in self._load_attributes(). However, due to a limitation in - the API (can't get the editor of one revision and the content of - another at both ends of the history), if our other attributes were only - loaded from get(), we'll have to do another API query. + Makes an API query only if we haven't already made one. Normally, we + can get the creator along with everything else (except content) in + :py:meth:`_load_attributes`. However, due to a limitation in the API + (can't get the editor of one revision and the content of another at + both ends of the history), if our other attributes were only loaded + through :py:meth:`get`, we'll have to do another API query. - Raises InvalidPageError or PageNotFoundError if the page name is + Raises :py:exc:`~earwigbot.exceptions.InvalidPageError` or + :py:exc:`~earwigbot.exceptions.PageNotFoundError` if the page name is invalid or the page does not exist, respectively. """ if self._exists == 0: @@ -661,17 +666,17 @@ class Page(CopyrightMixin): if not self._creator: self._load() self._force_existence() - return self._creator + return self._site.get_user(self._creator) def edit(self, text, summary, minor=False, bot=True, force=False): """Replaces the page's content or creates a new page. - `text` is the new page content, with `summary` as the edit summary. - If `minor` is True, the edit will be marked as minor. If `bot` is true, - the edit will be marked as a bot edit, but only if we actually have a - bot flag. + *text* is the new page content, with *summary* as the edit summary. + If *minor* is ``True``, the edit will be marked as minor. If *bot* is + ``True``, the edit will be marked as a bot edit, but only if we + actually have a bot flag. - Use `force` to push the new content even if there's an edit conflict or + Use *force* to push the new content even if there's an edit conflict or the page was deleted/recreated between getting our edit token and editing our page. Be careful with this! """ @@ -681,10 +686,10 @@ class Page(CopyrightMixin): def add_section(self, text, title, minor=False, bot=True, force=False): """Adds a new section to the bottom of the page. - The arguments for this are the same as those for edit(), but instead of - providing a summary, you provide a section title. + The arguments for this are the same as those for :py:meth:`edit`, but + instead of providing a summary, you provide a section title. - Likewise, raised exceptions are the same as edit()'s. + Likewise, raised exceptions are the same as :py:meth:`edit`'s. This should create the page if it does not already exist, with just the new section as content.