From 4c357d52818e65f9f1dce98c1c6698b45a916827 Mon Sep 17 00:00:00 2001
From: Ross Scroggs <ross.scroggs@gmail.com>
Date: Mon, 8 Jan 2024 12:08:50 -0800
Subject: [PATCH] Added option `maxevents <Number>` to `gam report
 <ActivityApplictionName>`

---
 docs/GamUpdates.md                       |  7 +++++++
 docs/How-to-Upgrade-from-Standard-GAM.md |  4 ++--
 docs/Reports.md                          |  8 +++++++-
 docs/Version-and-Help.md                 | 12 ++++++------
 src/GamCommands.txt                      |  2 +-
 src/GamUpdate.txt                        |  7 +++++++
 src/gam/__init__.py                      | 10 ++++++++--
 7 files changed, 38 insertions(+), 12 deletions(-)

diff --git a/docs/GamUpdates.md b/docs/GamUpdates.md
index cafeafe1..0fc14c1f 100644
--- a/docs/GamUpdates.md
+++ b/docs/GamUpdates.md
@@ -11,6 +11,13 @@ Add the `-s` option to the end of the above commands to suppress creating the `g
 
 See [Downloads](https://github.com/taers232c/GAMADV-XTD3/wiki/Downloads) for Windows or other options, including manual installation
 
+### 6.67.09
+
+Added option `maxevents <Number>` to `gam report <ActivityApplictionName>` that limits
+the number of events displayed for each activity; the default is 0, no limit.
+Setting options `maxactivities 1 maxevents 1 maxresults 1` can be used to as efficiently as possible
+show the most recent activity/event; this can be useful when reporting drive activity for individual drive files.
+
 ### 6.67.08
 
 Added optional argument `charset <Charset>` to `emlfile <FileName>` in `gam <UserTypeEntity> draft|import|insert message`;
diff --git a/docs/How-to-Upgrade-from-Standard-GAM.md b/docs/How-to-Upgrade-from-Standard-GAM.md
index 1e494f47..07a79aa5 100644
--- a/docs/How-to-Upgrade-from-Standard-GAM.md
+++ b/docs/How-to-Upgrade-from-Standard-GAM.md
@@ -334,7 +334,7 @@ writes the credentials into the file oauth2.txt.
 admin@server:/Users/admin/bin/gamadv-xtd3$ rm -f /Users/admin/GAMConfig/oauth2.txt
 admin@server:/Users/admin/bin/gamadv-xtd3$ ./gam version
 WARNING: Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: /Users/admin/GAMConfig/oauth2.txt, Not Found
-GAMADV-XTD3 6.67.08 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.67.09 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.10.8 64-bit final
 MacOS High Sierra 10.13.6 x86_64
@@ -1002,7 +1002,7 @@ writes the credentials into the file oauth2.txt.
 C:\GAMADV-XTD3>del C:\GAMConfig\oauth2.txt
 C:\GAMADV-XTD3>gam version
 WARNING: Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: C:\GAMConfig\oauth2.txt, Not Found
-GAMADV-XTD3 6.67.08 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.67.09 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.0 64-bit final
 Windows-10-10.0.17134 AMD64
diff --git a/docs/Reports.md b/docs/Reports.md
index 14cea66c..4025f6fb 100644
--- a/docs/Reports.md
+++ b/docs/Reports.md
@@ -58,7 +58,7 @@ gam report <ActivityApplicationName> [todrive <ToDriveAttributes>*]
         [filtertime.* <Time>] [filter|filters <String>]
         [event|events <EventNameList>] [ip <String>]
         [groupidfilter <String>]
-        [maxactivities <Number>] [maxresults <Number>]
+        [maxactivities <Number>] [maxevents <Number>] [maxresults <Number>]
         [countsonly [summary] [eventrowfilter]]
         (addcsvdata <FieldName> <String>)* [shownoactivities]
 ```
@@ -100,9 +100,15 @@ Limit to those users that are a member of at least one of a list of groups.
 Limit the total number of activites.
 * `maxactivities <Number>`
 
+Limit the  number of events per activity; this only applies when `countsonly` is False.
+* `maxevents <Number>`
+
 Limit the number of activities downloaded per API call; infrequently used.
 * `maxresults <Number>`
 
+Setting options `maxactivities 1 maxevents 1 maxresults 1` can be used to as efficiently as possible
+show the most recent activity/event; this can be useful when reporting drive activity for individual drive files.
+
 Add additional columns of data from the command line to the output.
 * `addcsvdata <FieldName> <String>`
 
diff --git a/docs/Version-and-Help.md b/docs/Version-and-Help.md
index 488d6130..aeb25e6d 100644
--- a/docs/Version-and-Help.md
+++ b/docs/Version-and-Help.md
@@ -4,7 +4,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAMADV-XTD3 6.67.08 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.67.09 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.0 64-bit final
 MacOS Monterey 12.7 x86_64
@@ -16,7 +16,7 @@ Time: 2023-06-02T21:10:00-07:00
 Print the current version of Gam with details and time offset information
 ```
 gam version timeoffset
-GAMADV-XTD3 6.67.08 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.67.09 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.0 64-bit final
 MacOS Monterey 12.7 x86_64
@@ -28,7 +28,7 @@ Your system time differs from www.googleapis.com by less than 1 second
 Print the current version of Gam with extended details and SSL information
 ```
 gam version extended
-GAMADV-XTD3 6.67.08 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.67.09 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.0 64-bit final
 MacOS Monterey 12.7 x86_64
@@ -65,7 +65,7 @@ MacOS High Sierra 10.13.6 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
 Version Check:
   Current: 5.35.08
-   Latest: 6.67.08
+   Latest: 6.67.09
 echo $?
 1
 ```
@@ -73,7 +73,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-6.67.08
+6.67.09
 ```
 In Linux/MacOS you can do:
 ```
@@ -83,7 +83,7 @@ echo $VER
 Print the current version of Gam and address of this Wiki
 ```
 gam help
-GAM 6.67.08 - https://github.com/taers232c/GAMADV-XTD3
+GAM 6.67.09 - https://github.com/taers232c/GAMADV-XTD3
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.0 64-bit final
 MacOS Monterey 12.7 x86_64
diff --git a/src/GamCommands.txt b/src/GamCommands.txt
index cf465a4b..5d12b8c5 100644
--- a/src/GamCommands.txt
+++ b/src/GamCommands.txt
@@ -4166,7 +4166,7 @@ gam report <ActivityApplicationName> [todrive <ToDriveAttribute>*]
         [filtertime.* <Time>] [filter|filters <String>]
         [event|events <EventNameList>] [ip <String>]
         [groupidfilter <String>]
-        [maxactivities <Number>] [maxresults <Number>]
+        [maxactivities <Number>] [maxevents <Number>] [maxresults <Number>]
         [countsonly [summary] [eventrowfilter]]
         (addcsvdata <FieldName> <String>)* [shownoactivities]
 
diff --git a/src/GamUpdate.txt b/src/GamUpdate.txt
index 2dfad572..ffc81a53 100644
--- a/src/GamUpdate.txt
+++ b/src/GamUpdate.txt
@@ -2,6 +2,13 @@
 
 Merged GAM-Team version
 
+6.67.09
+
+Added option `maxevents <Number>` to `gam report <ActivityApplictionName>` that limits
+the number of events displayed for each activity; the default is 0, no limit.
+Setting options `maxactivities 1 maxevents 1 maxresults 1` can be used to as efficiently as possible
+show the most recent activity/event; this can be useful when reporting drive activity for individual drive files.
+
 6.67.08
 
 Added optional argument `charset <Charset>` to `emlfile <FileName>` in `gam <UserTypeEntity> draft|import|insert message`;
diff --git a/src/gam/__init__.py b/src/gam/__init__.py
index 70c4a38f..0c7ac1bf 100755
--- a/src/gam/__init__.py
+++ b/src/gam/__init__.py
@@ -13090,7 +13090,7 @@ REPORT_ACTIVITIES_TIME_OBJECTS = {'time'}
 #	[filtertime.* <Time>] [filter|filters <String>]
 #	[event|events <EventNameList>] [ip <String>]
 #	[groupidfilter <String>]
-#	[maxactivities <Number>] [maxresults <Number>]
+#	[maxactivities <Number>] [maxevents <Number>] [maxresults <Number>]
 #	[countsonly [summary] [eventrowfilter]]
 #	(addcsvdata <FieldName> <String>)* [shownoactivities]
 # gam report users|user [todrive <ToDriveAttribute>*]
@@ -13350,7 +13350,7 @@ def doReport():
   startEndTime = StartEndTime('start', 'end')
   oneDay = datetime.timedelta(days=1)
   filterTimes = {}
-  maxActivities = 0
+  maxActivities = maxEvents = 0
   maxResults = 1000
   aggregateByDate = aggregateByUser = countsOnly = eventRowFilter = exitUserLoop = noAuthorizedApps = noDateChange = \
     normalizeUsers = select = summary = userCustomerRange = False
@@ -13432,6 +13432,8 @@ def doReport():
       noAuthorizedApps = True
     elif activityReports and myarg == 'maxactivities':
       maxActivities = getInteger(minVal=0)
+    elif activityReports and myarg == 'maxevents':
+      maxEvents = getInteger(minVal=0)
     elif activityReports and myarg in {'start', 'starttime', 'end', 'endtime', 'yesterday', 'today'}:
       startEndTime.Get(myarg)
     elif activityReports and myarg in {'event', 'events'}:
@@ -13711,7 +13713,9 @@ def doReport():
           if not countsOnly or eventRowFilter:
             activity_row = flattenJSON(activity, timeObjects=REPORT_ACTIVITIES_TIME_OBJECTS)
             purge_parameters = True
+            numEvents = 0
             for event in events:
+              numEvents += 1
               for item in event.get('parameters', []):
                 itemSet = set(item)
                 if not itemSet.symmetric_difference({'name'}):
@@ -13753,6 +13757,8 @@ def doReport():
                 if addCSVData:
                   row.update(addCSVData)
                 csvPF.WriteRowTitles(row)
+                if maxEvents > 0 and numEvents >= maxEvents:
+                  break
               elif csvPF.CheckRowTitles(row):
                 if not summary:
                   eventCounts.setdefault(actor, {})