Merge pull request #10 from kmaehashi/improve-readme

Improve documentation

Author: kmaehashi

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2016-2019 Kenichi Maehashi
+Copyright (C) 2016-2022 Kenichi Maehashi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.rst

@@ -31,8 +31,8 @@ Requirements
 Usage
 -----
 
-``atwiki-dump`` Tool
-~~~~~~~~~~~~~~~~~~~~
+``atwiki-dump`` Command
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Dump source and page name for each page in the wiki site.
 
@@ -53,15 +53,15 @@ Python API provides access to @wiki features.
 
   # Show list of tags.
   for tag in api.get_tags():
-    print(tag['name'])
+    print(tag)
 
   # Show list of pages.
   for page in api.get_list():
-    print(page['name'])
+    print(page)
 
   # Show list of pages tagged with 'tag01'.
   for page in api.get_list('tag01'):
-    print(page['name'])
+    print(page)
 
   # Show source of page ID 14.
   print(api.get_source(14))
@@ -70,6 +70,16 @@ Python API provides access to @wiki features.
   for result in api.search('test'):
     print(result)
 
+Hints
+-----
+
+* Always use an appropraite interval between requests, or your IP address may get banned.
+  Empirically, 10 seconds of sleep between API call is sufficient.
+* Your application must expect that entries returned from APIs may be duplicate/missing when pages/tags are added/removed during API call.
+  This is because listing requests are internally pagerized and it is costly to guarantee consistency.
+* AtWiki's specification may change anytime.
+  If you are going to build an automated system, it is encouraged to run test suites included with the installation of this library (``python -m unittest discover atwiki``) everytime before running your application.
+
 License
 -------