Update documentation

docs/index.md

@@ -119,17 +119,17 @@ Optional configuration values ends with *.
   * plugins/display/top_pages_diff.py
   * plugins/display/top_pages.py
   * plugins/display/top_visitors.py
-  * plugins/display/track_users.py
   * plugins/post_analysis/browsers.py
   * plugins/post_analysis/feeds.py
   * plugins/post_analysis/filter_users.py
+  * plugins/post_analysis/google_console_api.py
   * plugins/post_analysis/hours_stats.py
   * plugins/post_analysis/ip_to_geo.py
   * plugins/post_analysis/iptogeo.py
-  * plugins/post_analysis/iptogeo.reset.py
   * plugins/post_analysis/operating_systems.py
   * plugins/post_analysis/referers.py
   * plugins/post_analysis/reverse_dns.py
+  * plugins/post_analysis/search_analytics_api_sample.py
   * plugins/post_analysis/top_downloads.py
   * plugins/post_analysis/top_hits.py
   * plugins/post_analysis/top_pages.py
@@ -688,34 +688,6 @@ plugins.display.top_visitors
         None
 
 
-plugins.display.track_users
----------------------------
-
-    Display hook
-    
-    Track users
-    
-    Plugin requirements :
-        None
-    
-    Conf values needed :
-        tracked_ip
-        create_tracked_page*
-    
-    Output files :
-        OUTPUT_ROOT/year/month/index.html
-        OUTPUT_ROOT/year/month/tracked_users.html
-    
-    Statistics creation :
-        None
-    
-    Statistics update :
-        None
-    
-    Statistics deletion :
-        None
-
-
 plugins.post_analysis.browsers
 ------------------------------
 
@@ -794,8 +766,8 @@ plugins.post_analysis.filter_users
         filtered_ip : list of ip (string)
         create_filtered_page*
     
-    Filter is a list of filter description combined by AND operator
+    Filter can be a function or a list of filter description combined by AND operator
-    Filter description is a list of 3 elements :
+    Filter description can be a function or a list of 3 elements :
     
       * Field to match in visits
       * Operator '=', '==', '!=', '>', '>=', '<', '<=' for int value
@@ -804,6 +776,19 @@ plugins.post_analysis.filter_users
     
     For easiest config, you can indicate both 'remote_addr' or 'ip' in field element
     
+    function prototype is func(iwla, hit) and must return True or False
+    
+    Example :
+    
+    def my_filter(iwla, hit):
+        return True
+    
+    filtered_users = [
+        [['viewed_pages', '>=', '5'], ['viewed_hits', '>=', '5']],
+        [['viewed_hits', '>=', '5'], my_filter],
+        my_filter,
+    ]
+    
     Output files :
         None
     
@@ -811,6 +796,7 @@ plugins.post_analysis.filter_users
     visits :
        remote_addr =>
            filtered
+           geo_location
     
     Statistics update :
     visits :
@@ -821,6 +807,34 @@ plugins.post_analysis.filter_users
         None
 
 
+plugins.post_analysis.google_console_api
+----------------------------------------
+
+    Post analysis hook
+    
+    Extract key phrases from Google console API
+    
+    Plugin requirements :
+        None
+    
+    Conf values needed :
+        domain_name
+    
+    Output files :
+        None
+    
+    Statistics creation :
+        None
+    
+    Statistics update :
+    month_stats :
+       key_phrases =>
+           phrase => count
+    
+    Statistics deletion :
+        None
+
+
 plugins.post_analysis.hours_stats
 ---------------------------------
 
@@ -893,11 +907,6 @@ plugins.post_analysis.iptogeo
 
 
 
-plugins.post_analysis.iptogeo.reset
------------------------------------
-
-
-
 plugins.post_analysis.operating_systems
 ---------------------------------------
 
@@ -999,6 +1008,141 @@ plugins.post_analysis.reverse_dns
         None
 
 
+plugins.post_analysis.search_analytics_api_sample
+-------------------------------------------------
+
+    from __future__ import print_function
+    
+    import argparse
+    import sys
+    from googleapiclient import sample_tools
+    
+    # Declare command-line flags.
+    argparser = argparse.ArgumentParser(add_help=False)
+    argparser.add_argument('property_uri', type=str,
+                           help=('Site or app URI to query data for (including '
+                                 'trailing slash).'))
+    argparser.add_argument('start_date', type=str,
+                           help=('Start date of the requested date range in '
+                                 'YYYY-MM-DD format.'))
+    argparser.add_argument('end_date', type=str,
+                           help=('End date of the requested date range in '
+                                 'YYYY-MM-DD format.'))
+    
+    
+    def main(argv):
+      service, flags = sample_tools.init(
+          argv, 'webmasters', 'v3', __doc__, __file__, parents=[argparser],
+          scope='https://www.googleapis.com/auth/webmasters.readonly')
+    
+      # First run a query to learn which dates we have data for. You should always
+      # check which days in a date range have data before running your main query.
+      # This query shows data for the entire range, grouped and sorted by day,
+      # descending; any days without data will be missing from the results.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query']
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Available dates')
+    
+      return
+      # Get totals for the date range.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Totals')
+    
+      # Get top 10 queries for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top Queries')
+    
+      # Get top 11-20 mobile queries for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'dimensionFilterGroups': [{
+              'filters': [{
+                  'dimension': 'device',
+                  'expression': 'mobile'
+              }]
+          }],
+          'rowLimit': 10,
+          'startRow': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top 11-20 Mobile Queries')
+    
+      # Get top 10 pages for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['page'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top Pages')
+    
+      # Get the top 10 queries in India, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'dimensionFilterGroups': [{
+              'filters': [{
+                  'dimension': 'country',
+                  'expression': 'ind'
+              }]
+          }],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top queries in India')
+    
+      # Group by both country and device.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['country', 'device'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Group by country and device')
+    
+      # Group by total number of Search Appearance count.
+      # Note: It is not possible to use searchAppearance with other
+      # dimensions.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['searchAppearance'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Search Appearance Features')
+    
+    def execute_request(service, property_uri, request):
+      """Executes a searchAnalytics.query request.
+    
+      Args:
+        service: The webmasters service to use when executing the query.
+        property_uri: The site or app URI to request data for.
+        request: The request to be executed.
+    
+      Returns:
+        An array of response rows.
+
+
 plugins.post_analysis.top_downloads
 -----------------------------------
 

docs/modules.md

@@ -16,17 +16,17 @@
   * plugins/display/top_pages_diff.py
   * plugins/display/top_pages.py
   * plugins/display/top_visitors.py
-  * plugins/display/track_users.py
   * plugins/post_analysis/browsers.py
   * plugins/post_analysis/feeds.py
   * plugins/post_analysis/filter_users.py
+  * plugins/post_analysis/google_console_api.py
   * plugins/post_analysis/hours_stats.py
   * plugins/post_analysis/ip_to_geo.py
   * plugins/post_analysis/iptogeo.py
-  * plugins/post_analysis/iptogeo.reset.py
   * plugins/post_analysis/operating_systems.py
   * plugins/post_analysis/referers.py
   * plugins/post_analysis/reverse_dns.py
+  * plugins/post_analysis/search_analytics_api_sample.py
   * plugins/post_analysis/top_downloads.py
   * plugins/post_analysis/top_hits.py
   * plugins/post_analysis/top_pages.py
@@ -585,34 +585,6 @@ plugins.display.top_visitors
         None
 
 
-plugins.display.track_users
----------------------------
-
-    Display hook
-    
-    Track users
-    
-    Plugin requirements :
-        None
-    
-    Conf values needed :
-        tracked_ip
-        create_tracked_page*
-    
-    Output files :
-        OUTPUT_ROOT/year/month/index.html
-        OUTPUT_ROOT/year/month/tracked_users.html
-    
-    Statistics creation :
-        None
-    
-    Statistics update :
-        None
-    
-    Statistics deletion :
-        None
-
-
 plugins.post_analysis.browsers
 ------------------------------
 
@@ -691,8 +663,8 @@ plugins.post_analysis.filter_users
         filtered_ip : list of ip (string)
         create_filtered_page*
     
-    Filter is a list of filter description combined by AND operator
+    Filter can be a function or a list of filter description combined by AND operator
-    Filter description is a list of 3 elements :
+    Filter description can be a function or a list of 3 elements :
     
       * Field to match in visits
       * Operator '=', '==', '!=', '>', '>=', '<', '<=' for int value
@@ -701,6 +673,19 @@ plugins.post_analysis.filter_users
     
     For easiest config, you can indicate both 'remote_addr' or 'ip' in field element
     
+    function prototype is func(iwla, hit) and must return True or False
+    
+    Example :
+    
+    def my_filter(iwla, hit):
+        return True
+    
+    filtered_users = [
+        [['viewed_pages', '>=', '5'], ['viewed_hits', '>=', '5']],
+        [['viewed_hits', '>=', '5'], my_filter],
+        my_filter,
+    ]
+    
     Output files :
         None
     
@@ -708,6 +693,7 @@ plugins.post_analysis.filter_users
     visits :
        remote_addr =>
            filtered
+           geo_location
     
     Statistics update :
     visits :
@@ -718,6 +704,34 @@ plugins.post_analysis.filter_users
         None
 
 
+plugins.post_analysis.google_console_api
+----------------------------------------
+
+    Post analysis hook
+    
+    Extract key phrases from Google console API
+    
+    Plugin requirements :
+        None
+    
+    Conf values needed :
+        domain_name
+    
+    Output files :
+        None
+    
+    Statistics creation :
+        None
+    
+    Statistics update :
+    month_stats :
+       key_phrases =>
+           phrase => count
+    
+    Statistics deletion :
+        None
+
+
 plugins.post_analysis.hours_stats
 ---------------------------------
 
@@ -790,11 +804,6 @@ plugins.post_analysis.iptogeo
 
 
 
-plugins.post_analysis.iptogeo.reset
------------------------------------
-
-
-
 plugins.post_analysis.operating_systems
 ---------------------------------------
 
@@ -896,6 +905,141 @@ plugins.post_analysis.reverse_dns
         None
 
 
+plugins.post_analysis.search_analytics_api_sample
+-------------------------------------------------
+
+    from __future__ import print_function
+    
+    import argparse
+    import sys
+    from googleapiclient import sample_tools
+    
+    # Declare command-line flags.
+    argparser = argparse.ArgumentParser(add_help=False)
+    argparser.add_argument('property_uri', type=str,
+                           help=('Site or app URI to query data for (including '
+                                 'trailing slash).'))
+    argparser.add_argument('start_date', type=str,
+                           help=('Start date of the requested date range in '
+                                 'YYYY-MM-DD format.'))
+    argparser.add_argument('end_date', type=str,
+                           help=('End date of the requested date range in '
+                                 'YYYY-MM-DD format.'))
+    
+    
+    def main(argv):
+      service, flags = sample_tools.init(
+          argv, 'webmasters', 'v3', __doc__, __file__, parents=[argparser],
+          scope='https://www.googleapis.com/auth/webmasters.readonly')
+    
+      # First run a query to learn which dates we have data for. You should always
+      # check which days in a date range have data before running your main query.
+      # This query shows data for the entire range, grouped and sorted by day,
+      # descending; any days without data will be missing from the results.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query']
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Available dates')
+    
+      return
+      # Get totals for the date range.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Totals')
+    
+      # Get top 10 queries for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top Queries')
+    
+      # Get top 11-20 mobile queries for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'dimensionFilterGroups': [{
+              'filters': [{
+                  'dimension': 'device',
+                  'expression': 'mobile'
+              }]
+          }],
+          'rowLimit': 10,
+          'startRow': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top 11-20 Mobile Queries')
+    
+      # Get top 10 pages for the date range, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['page'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top Pages')
+    
+      # Get the top 10 queries in India, sorted by click count, descending.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['query'],
+          'dimensionFilterGroups': [{
+              'filters': [{
+                  'dimension': 'country',
+                  'expression': 'ind'
+              }]
+          }],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Top queries in India')
+    
+      # Group by both country and device.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['country', 'device'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Group by country and device')
+    
+      # Group by total number of Search Appearance count.
+      # Note: It is not possible to use searchAppearance with other
+      # dimensions.
+      request = {
+          'startDate': flags.start_date,
+          'endDate': flags.end_date,
+          'dimensions': ['searchAppearance'],
+          'rowLimit': 10
+      }
+      response = execute_request(service, flags.property_uri, request)
+      print_table(response, 'Search Appearance Features')
+    
+    def execute_request(service, property_uri, request):
+      """Executes a searchAnalytics.query request.
+    
+      Args:
+        service: The webmasters service to use when executing the query.
+        property_uri: The site or app URI to request data for.
+        request: The request to be executed.
+    
+      Returns:
+        An array of response rows.
+
+
 plugins.post_analysis.top_downloads
 -----------------------------------