Add append/prepend setting in save & use this to add touch

.gitignore

@@ -7,3 +7,4 @@ dist
 *.egg-info
 .eggs
 .tox
+.idea/*

docs/source/user/page-ops.rst

@@ -28,7 +28,7 @@ page, use `page.exists`:
 
 Edit the text as you like before saving it back to the wiki:
 
-    >>> page.save(text, 'Edit summary')
+    >>> page.edit(text, 'Edit summary')
 
 If the page didn't exist, this operation will create it.
 

examples/basic_edit.py

@@ -60,12 +60,12 @@
     image.delete('Testing history deletion', oldimage=archivename)
     print('History:', list(image.imagehistory()))
 
-text = page.edit()
+text = page.text()
 text += u'\n[[Image:%s-test-image.png]]' % prefix
-page.save(text, 'Adding image')
+page.edit(text, 'Adding image')
 print('Images:', list(page.images(generator=False)))
-
 print('Cleaning up')
+
 image.delete('Cleanup')
 page.delete('Cleanup')
 

mwclient/page.py

@@ -113,7 +113,7 @@ def can(self, action):
             True
 
         """
-        level = self.protection.get(action, (action, ))[0]
+        level = self.protection.get(action, (action,))[0]
         if level == 'sysop':
             level = 'editprotected'
 
@@ -171,9 +171,28 @@ def text(self, section=None, expandtemplates=False, cache=True, slot='main'):
             self._textcache[key] = text
         return text
 
-    def save(self, text, summary=u'', minor=False, bot=True, section=None, **kwargs):
+    def save(self, *args, **kwargs):
+        """Alias for edit, for maintaining backwards compatibility."""
+        return self.edit(*args, **kwargs)
+
+    def edit(self, text, summary=u'', minor=False, bot=True, section=None, **kwargs):
         """Update the text of a section or the whole page by performing an edit operation.
         """
+        return self._edit(summary, minor, bot, section, text=text, **kwargs)
+
+    def append(self, text, summary=u'', minor=False, bot=True, section=None,
+               **kwargs):
+        """Append text to a section or the whole page by performing an edit operation.
+        """
+        return self._edit(summary, minor, bot, section, appendtext=text, **kwargs)
+
+    def prepend(self, text, summary=u'', minor=False, bot=True, section=None,
+                **kwargs):
+        """Prepend text to a section or the whole page by performing an edit operation.
+        """
+        return self._edit(summary, minor, bot, section, prependtext=text, **kwargs)
+
+    def _edit(self, summary, minor, bot, section, **kwargs):
         if not self.site.logged_in and self.site.force_login:
             raise mwclient.errors.AssertUserFailedError()
         if self.site.blocked:
@@ -204,12 +223,13 @@ def save(self, text, summary=u'', minor=False, bot=True, section=None, **kwargs)
             data['assert'] = 'user'
 
         def do_edit():
-            result = self.site.post('edit', title=self.name, text=text,
-                                    summary=summary, token=self.get_token('edit'),
+            result = self.site.post('edit', title=self.name, summary=summary,
+                                    token=self.get_token('edit'),
                                     **data)
             if result['edit'].get('result').lower() == 'failure':
                 raise mwclient.errors.EditError(self, result['edit'])
             return result
+
         try:
             result = do_edit()
         except mwclient.errors.APIError as e:
@@ -251,6 +271,16 @@ def handle_edit_error(self, e, summary):
         else:
             raise e
 
+    def touch(self):
+        """Perform a "null edit" on the page to update the wiki's cached data of it.
+        This is useful in contrast to purge when needing to update stored data on a wiki,
+        for example Semantic MediaWiki properties or Cargo table values, since purge
+        only forces update of a page's displayed values and not its store.
+        """
+        if not self.exists:
+            return
+        self.append('')
+
     def move(self, new_title, reason='', move_talk=True, no_redirect=False):
         """Move (rename) page to new_title.
 

test/test_page.py

@@ -215,7 +215,7 @@ def test_captcha(self, mock_site):
         # For now, mwclient will just raise an EditError.
         # <https://github.com/mwclient/mwclient/issues/33>
         with pytest.raises(mwclient.errors.EditError):
-            page.save('Some text')
+            page.edit('Some text')
 
 
 class TestPageApiArgs(unittest.TestCase):
@@ -303,7 +303,7 @@ def test_assertuser_true(self):
         self.site.api.return_value = {
             'edit': {'result': 'Ok'}
         }
-        self.page.save('Some text')
+        self.page.edit('Some text')
         args = self.get_last_api_call_args()
 
         assert args['assert'] == 'user'
@@ -318,7 +318,7 @@ def test_assertuser_false(self):
         self.site.api.return_value = {
             'edit': {'result': 'Ok'}
         }
-        self.page.save('Some text')
+        self.page.edit('Some text')
         args = self.get_last_api_call_args()
 
         assert 'assert' not in args