From 14ea845aa3155c002e86886878b6c2d3f5a95adf Mon Sep 17 00:00:00 2001
From: Ross Scroggs <ross.scroggs@gmail.com>
Date: Wed, 10 Jul 2024 17:11:06 -0700
Subject: [PATCH] Added option `convertmbtogb` to gam report

---
 docs/Calendars-Events.md                 |  2 +-
 docs/GamUpdates.md                       |  6 ++++
 docs/How-to-Upgrade-from-Standard-GAM.md |  4 +--
 docs/Reports.md                          | 16 +++++++++++
 docs/Users-Calendars-Events.md           |  2 +-
 docs/Users-Drive-Files-Display.md        |  3 ++
 docs/Version-and-Help.md                 | 12 ++++----
 src/GamCommands.txt                      |  6 ++++
 src/GamUpdate.txt                        |  6 ++++
 src/gam/__init__.py                      | 36 ++++++++++++++++++++++--
 10 files changed, 80 insertions(+), 13 deletions(-)

diff --git a/docs/Calendars-Events.md b/docs/Calendars-Events.md
index 4e4f87a4..0dfb049b 100644
--- a/docs/Calendars-Events.md
+++ b/docs/Calendars-Events.md
@@ -347,7 +347,7 @@ If none of the following options are selected, all events are selected.
 * `<EventSelectProperty>* <EventMatchProperty>*` - Properties used to select events
 
 The Google Calendar API processes `<EventSelectProperty>*`; you may specify none or multiple properties.
-* `after|starttime|timemin <Time>` - Lower bound (inclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
+* `after|starttime|timemin <Time>` - Lower bound (exclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
 * `before|endtime|timemax <Time>` - Upper bound (exclusive) for an event's start time to filter by. If timeMin is set, timeMax must be greater than timeMin.
 * `eventtypes <EventTypeList>` - Select events based on their type.
 * `query <QueryCalendar>` - Free text search terms to find events that match these terms in any field, except for extended properties
diff --git a/docs/GamUpdates.md b/docs/GamUpdates.md
index 955c34c6..9f995b2d 100644
--- a/docs/GamUpdates.md
+++ b/docs/GamUpdates.md
@@ -10,6 +10,12 @@ 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.77.11
+
+Added option `convertmbtogb` to `gam report usage customer|user` and
+`gam report customer|user` that causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 ### 6.77.10
 
 Fixed bug in `gam <UserTypeEntity> get profilephoto` where data written to stdout, e.g. `> filename`,
diff --git a/docs/How-to-Upgrade-from-Standard-GAM.md b/docs/How-to-Upgrade-from-Standard-GAM.md
index cf36d86d..211e0f5a 100644
--- a/docs/How-to-Upgrade-from-Standard-GAM.md
+++ b/docs/How-to-Upgrade-from-Standard-GAM.md
@@ -335,7 +335,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.77.10 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.11 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -1009,7 +1009,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.77.10 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.11 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 Windows-10-10.0.17134 AMD64
diff --git a/docs/Reports.md b/docs/Reports.md
index def6e4b6..12302f9e 100644
--- a/docs/Reports.md
+++ b/docs/Reports.md
@@ -188,6 +188,7 @@ gam report usage customer [todrive <ToDriveAttribute>*]
          thismonth|(previousmonths <Integer>)]
         [skipdates <Date>[:<Date>](,<Date>[:<Date>])*] [skipdaysofweek <DayOfWeek>(,<DayOfWeek>)*]
         [fields|parameters <String>]
+        [convertmbtogb]
 ```
 Limit the time period.
 * `start <Date>` - Default value is 30 days prior to `end <Date>`
@@ -196,6 +197,9 @@ Limit the time period.
 * `thismonth` - The current calendar month up to the current time
 * `previousmonths <Integer>` - A number in the range 1 to 6 indicating calendar months previous to the current month
 
+Option `convertmbtogb` causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 ### Example
 Jay provided this example.
 ```
@@ -237,6 +241,7 @@ gam report customers|customer|domain [todrive <ToDriveAttributes>*]
         [(nodatechange | limitdatechanges <Integer>) | (fulldatarequired all|<CustomerServiceNameList>)]
         [(fields|parameters <String>)|(services <CustomerServiceNameList>)]
         [noauthorizedapps]
+        [convertmbtogb]
 ```
 Specify the report date; the default is today's date.
 * `date <Date>` - A single date; there is one API call
@@ -246,6 +251,9 @@ Specify the report date; the default is today's date.
 * `thismonth` - The current calendar month up to the current time; there is an API call per date
 * `previousmonths <Integer>` - A number in the range 1 to 6 indicating calendar months previous to the current month; there is an API call per date
 
+Option `convertmbtogb` causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 If no report is available for the specified date, can an earlier date be used?
 * `limitdatechanges -1' - Back up to earlier dates to find report data; this is the default.
 * `limitdatechanges 0 | nodatechange' - Do not report on an earlier date if no report data is available for the specified date.
@@ -298,6 +306,7 @@ gam report usage user [todrive]
          thismonth|(previousmonths <Integer>)]
         [skipdates <Date>[:<Date>](,<Date>[:<Date>])*] [skipdaysofweek <DayOfWeek>(,<DayOfWeek>)*]
         [fields|parameters <String>]
+        [convertmbtogb]
 ```
 Select the users for whom information is desired.
 * `user all` - All users, the default; there is one API call
@@ -313,6 +322,9 @@ Limit the time period.
 * `thismonth` - The current calendar month up to the current time
 * `previousmonths <Integer>` - A number in the range 1 to 6 indicating calendar months previous to the current month
 
+Option `convertmbtogb` causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 ## User reports
 User reports are generally available up to four days before the current date.
 ```
@@ -335,6 +347,7 @@ gam report users|user [todrive <ToDriveAttributes>*]
         [(fields|parameters <String>)|(services <UserServiceNameList>)]
         [aggregatebydate|aggregatebyuser [Boolean]]
         [maxresults <Number>]
+        [convertmbtogb]
 ```
 Select the users for whom information is desired.
 * `user all` - All users, the default; there is one API call
@@ -354,6 +367,9 @@ Specify the report date; the default is today's date.
 * `thismonth` - The current calendar month up to the current time; there is an API call per date
 * `previousmonths <Integer>` - A number in the range 1 to 6 indicating calendar months previous to the current month; there is an API call per date
 
+Option `convertmbtogb` causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 If no report is available for the specified date, can an earlier date be used?
 * `limitdatechanges -1' - Back up to earlier dates to find report data; this is the default.
 * `limitdatechanges 0 | nodatechange' - Do not report on an earlier date if no report data is available for the specified date.
diff --git a/docs/Users-Calendars-Events.md b/docs/Users-Calendars-Events.md
index 92a0060f..65c6d7c9 100644
--- a/docs/Users-Calendars-Events.md
+++ b/docs/Users-Calendars-Events.md
@@ -429,7 +429,7 @@ If none of the following options are selected, all events are selected.
 * `<EventSelectProperty>* <EventMatchProperty>*` - Properties used to select events
 
 The Google Calendar API processes `<EventSelectProperty>*`; you may specify none or multiple properties.
-* `after|starttime|timemin <Time>` - Lower bound (inclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
+* `after|starttime|timemin <Time>` - Lower bound (exclusive) for an event's end time to filter by. If timeMax is set, timeMin must be smaller than timeMax.
 * `before|endtime|timemax <Time>` - Upper bound (exclusive) for an event's start time to filter by. If timeMin is set, timeMax must be greater than timeMin.
 * `eventtypes <EventTypeList>` - Select events based on their type.
 * `query <QueryCalendar>` - Free text search terms to find events that match these terms in any field, except for extended properties
diff --git a/docs/Users-Drive-Files-Display.md b/docs/Users-Drive-Files-Display.md
index f3af9bfb..11cf0eef 100644
--- a/docs/Users-Drive-Files-Display.md
+++ b/docs/Users-Drive-Files-Display.md
@@ -540,6 +540,9 @@ See: [Drive File Selection](Drive-File-Selection) for details of `<DriveFileName
         my_3p_shortcuts |
         my_items |
         my_forms |
+        my_top_files |
+        my_top_folders |
+        my_top_items |
         others_files |
         others_folders |
         others_forms |
diff --git a/docs/Version-and-Help.md b/docs/Version-and-Help.md
index a85b9bd5..2f5f60e4 100644
--- a/docs/Version-and-Help.md
+++ b/docs/Version-and-Help.md
@@ -3,7 +3,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAMADV-XTD3 6.77.10 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.11 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -15,7 +15,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.77.10 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.11 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -27,7 +27,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.77.10 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.77.11 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
@@ -64,7 +64,7 @@ MacOS High Sierra 10.13.6 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
 Version Check:
   Current: 5.35.08
-   Latest: 6.77.10
+   Latest: 6.77.11
 echo $?
 1
 ```
@@ -72,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-6.77.10
+6.77.11
 ```
 In Linux/MacOS you can do:
 ```
@@ -82,7 +82,7 @@ echo $VER
 Print the current version of Gam and address of this Wiki
 ```
 gam help
-GAM 6.77.10 - https://github.com/taers232c/GAMADV-XTD3
+GAM 6.77.11 - https://github.com/taers232c/GAMADV-XTD3
 Ross Scroggs <ross.scroggs@gmail.com>
 Python 3.12.4 64-bit final
 MacOS Sonoma 14.5 x86_64
diff --git a/src/GamCommands.txt b/src/GamCommands.txt
index 16a9565a..074e6e2b 100644
--- a/src/GamCommands.txt
+++ b/src/GamCommands.txt
@@ -1073,6 +1073,7 @@ Specify a collection of items by directly specifying them; the item type is dete
         others_3p_shortcuts |
         others_items |
         writable_files
+
 <DriveFileEntityShortcut> ::=
         alldrives |
         mydrive_any |
@@ -1088,6 +1089,7 @@ Specify a collection of items by directly specifying them; the item type is dete
         sharedwithme_all |
         sharedwithme_mydrive |
         sharedwithme_notmydrive
+
 <DriveFileEntity> ::=
         <DriveFileIDEntity> |
         <DriveFileNameEntity> |
@@ -4269,11 +4271,13 @@ gam report usage user [todrive <ToDriveAttribute>*]
          thismonth|(previousmonths <Integer>)]
         [skipdates <Date>[:<Date>](,<Date>[:<Date>])*] [skipdaysofweek <DayOfWeek>(,<DayOfWeek>)*]
         [fields|parameters <String>]
+        [convertmbtogb]
 gam report usage customer [todrive <ToDriveAttribute>*]
         [([start|startdate <Date>] [end|enddate <Date>])|(range <Date> <Date>)|
          thismonth|(previousmonths <Integer>)]
         [skipdates <Date>[:<Date>](,<Date>[:<Date>])*] [skipdaysofweek <DayOfWeek>(,<DayOfWeek>)*]
         [fields|parameters <String>]
+        [convertmbtogb]
 
 <ActivityApplicationName> ::=
         access|accesstransparency|
@@ -4333,6 +4337,7 @@ gam report customers|customer|domain [todrive <ToDriveAttribute>*]
           yesterday|today|thismonth|(previousmonths <Integer>)]
         [(nodatechange | limitdatechanges <Integer>) | (fulldatarequired all|<CustomerServiceNameList>)]
         [(fields|parameters <String>)|(services <CustomerServiceNameList>)] [noauthorizedapps]
+        [convertmbtogb]
 
 <UserServiceName> ::=
         accounts|
@@ -4353,6 +4358,7 @@ gam report users|user [todrive <ToDriveAttribute>*]
         [(fields|parameters <String>)|(services <UserServiceNameList>)]
         [aggregatebydate|aggregatebyuser [Boolean]]
         [maxresults <Number>]
+        [convertmbtogb]
 
 # Reseller
 
diff --git a/src/GamUpdate.txt b/src/GamUpdate.txt
index 17fcd438..0a3a5315 100644
--- a/src/GamUpdate.txt
+++ b/src/GamUpdate.txt
@@ -2,6 +2,12 @@
 
 Merged GAM-Team version
 
+6.77.11
+
+Added option `convertmbtogb` to `gam report usage customer|user` and
+`gam report customer|user` that causes GAM to convert parameters expressed in megabytes
+(name ends with _in_mb) to gigabytes (name converted to _in_gb) with two decimal places.
+
 6.77.10
 
 Fixed bug in `gam <UserTypeEntity> get profilephoto` where data written to stdout, e.g. `> filename`,
diff --git a/src/gam/__init__.py b/src/gam/__init__.py
index 2dae4552..bdc191e9 100755
--- a/src/gam/__init__.py
+++ b/src/gam/__init__.py
@@ -13063,6 +13063,12 @@ def getUserOrgUnits(cd, orgUnit, orgUnitId):
           GAPI.invalidCustomerId, GAPI.loginRequired, GAPI.resourceNotFound, GAPI.forbidden):
     checkEntityDNEorAccessErrorExit(cd, Ent.ORGANIZATIONAL_UNIT, orgUnit)
 
+# Convert report mb item to gb
+def convertReportMBtoGB(name, item):
+  if item is not None:
+    item['intValue'] = f"{int(item['intValue'])/1024:.2f}"
+  return name.replace('_in_mb', '_in_gb')
+
 REPORTS_PARAMETERS_SIMPLE_TYPES = ['intValue', 'boolValue', 'datetimeValue', 'stringValue']
 
 # gam report usage user [todrive <ToDriveAttribute>*]
@@ -13070,10 +13076,12 @@ REPORTS_PARAMETERS_SIMPLE_TYPES = ['intValue', 'boolValue', 'datetimeValue', 'st
 #	[([start|startdate <Date>] [end|enddate <Date>])|(range <Date> <Date>)|
 #	 thismonth|(previousmonths <Integer>)]
 #	[fields|parameters <String>)]
+#	[convertmbtogb]
 # gam report usage customer [todrive <ToDriveAttribute>*]
 #	[([start|startdate <Date>] [end|enddate <Date>])|(range <Date> <Date>)|
 #	 thismonth|(previousmonths <Integer>)]
 #	[fields|parameters <String>)]
+#	[convertmbtogb]
 def doReportUsage():
   def usageEntitySelectors():
     selectorChoices = Cmd.USER_ENTITY_SELECTORS+Cmd.USER_CSVDATA_ENTITY_SELECTORS
@@ -13118,7 +13126,7 @@ def doReportUsage():
   if customerId == GC.MY_CUSTOMER:
     customerId = None
   parameters = set()
-  select = showOrgUnit = False
+  convertMbToGb = select = showOrgUnit = False
   userKey = 'all'
   cd = orgUnit = orgUnitId = None
   userOrgUnits = {}
@@ -13178,6 +13186,8 @@ def doReportUsage():
       _, users = getEntityToModify(defaultEntityType=Cmd.ENTITY_USERS)
       orgUnit = orgUnitId = None
       select = True
+    elif myarg == 'convertmbtogb':
+      convertMbToGb = True
     else:
       unknownArgumentExit()
   if startEndTime.endDateTime is None:
@@ -13259,6 +13269,8 @@ def doReportUsage():
               for ptype in REPORTS_PARAMETERS_SIMPLE_TYPES:
                 if ptype in item:
                   if ptype != 'datetimeValue':
+                    if convertMbToGb and name.endswith('_in_mb'):
+                      name = convertReportMBtoGB(name, item)
                     row[name] = item[ptype]
                   else:
                     row[name] = formatLocalTime(item[ptype])
@@ -13361,11 +13373,13 @@ REPORT_ACTIVITIES_TIME_OBJECTS = {'time'}
 #	[(fields|parameters <String>)|(services <UserServiceNameList>)]
 #	[aggregatebydate|aggregatebyuser [Boolean]]
 #	[maxresults <Number>]
+#	[convertmbtogb]
 # gam report customers|customer|domain [todrive <ToDriveAttribute>*]
 #	[(date <Date>)|(range <Date> <Date>)|
 #	 yesterday|today|thismonth|(previousmonths <Integer>)]
 #	[nodatechange | (fulldatarequired all|<CustomerServiceNameList>)]
 #	[(fields|parameters <String>)|(services <CustomerServiceNameList>)] [noauthorizedapps]
+#	[convertmbtogb]
 def doReport():
   def processUserUsage(usage, lastDate):
     if not usage:
@@ -13399,6 +13413,8 @@ def doReport():
               csvPF.AddTitles('accounts:disabled_time')
             except ValueError:
               pass
+        elif convertMbToGb and name.endswith('_in_mb'):
+          name = convertReportMBtoGB(name, item)
         csvPF.AddTitles(name)
         for ptype in REPORTS_PARAMETERS_SIMPLE_TYPES:
           if ptype in item:
@@ -13432,6 +13448,8 @@ def doReport():
         if repsvc not in includeServices:
           continue
         if 'intValue' in item:
+          if convertMbToGb and name.endswith('_in_mb'):
+            name = convertReportMBtoGB(name, None)
           csvPF.AddTitles(name)
           eventCounts.setdefault(email, {})
           eventCounts[email].setdefault(name, 0)
@@ -13455,6 +13473,8 @@ def doReport():
         if repsvc not in includeServices:
           continue
         if 'intValue' in item:
+          if convertMbToGb and name.endswith('_in_mb'):
+            name = convertReportMBtoGB(name, None)
           csvPF.AddTitles(name)
           eventCounts.setdefault(lastDate, {})
           eventCounts[lastDate].setdefault(name, 0)
@@ -13477,6 +13497,8 @@ def doReport():
         continue
       for ptype in REPORTS_PARAMETERS_SIMPLE_TYPES:
         if ptype in item:
+          if convertMbToGb and name.endswith('_in_mb'):
+            name = convertReportMBtoGB(name, item)
           csvPF.AddTitles(name)
           if ptype != 'datetimeValue':
             row[name] = item[ptype]
@@ -13541,6 +13563,8 @@ def doReport():
       for ptype in REPORTS_PARAMETERS_SIMPLE_TYPES:
         if ptype in item:
           if ptype != 'datetimeValue':
+            if convertMbToGb and name.endswith('_in_mb'):
+              name = convertReportMBtoGB(name, item)
             csvPF.WriteRow({'date': lastDate, 'name': name, 'value': item[ptype]})
           else:
             csvPF.WriteRow({'date': lastDate, 'name': name, 'value': formatLocalTime(item[ptype])})
@@ -13610,8 +13634,8 @@ def doReport():
   filterTimes = {}
   maxActivities = maxEvents = 0
   maxResults = 1000
-  aggregateByDate = aggregateByUser = countsOnly = eventRowFilter = exitUserLoop = noAuthorizedApps = \
-    normalizeUsers = select = summary = userCustomerRange = False
+  aggregateByDate = aggregateByUser = convertMbToGb = countsOnly = eventRowFilter = exitUserLoop = \
+    noAuthorizedApps = normalizeUsers = select = summary = userCustomerRange = False
   limitDateChanges = -1
   allVerifyUser = userKey = 'all'
   cd = orgUnit = orgUnitId = None
@@ -13690,6 +13714,8 @@ def doReport():
           includeServices.add(repsvc)
         else:
           invalidChoiceExit(repsvc, fullDataServices, True)
+    elif usageReports and myarg == 'convertmbtogb':
+      convertMbToGb = True
     elif customerReports and myarg == 'noauthorizedapps':
       noAuthorizedApps = True
     elif activityReports and myarg == 'maxactivities':
@@ -13861,6 +13887,8 @@ def doReport():
       for usageDate, events in iter(eventCounts.items()):
         row = {'date': usageDate}
         for event, count in iter(events.items()):
+          if convertMbToGb and event.endswith('_in_gb'):
+            count = f'{count/1024:.2f}'
           row[event] = count
         csvPF.WriteRow(row)
       csvPF.SortRows('date', False)
@@ -13871,6 +13899,8 @@ def doReport():
         if showOrgUnit:
           row['orgUnitPath'] = userOrgUnits.get(email, UNKNOWN)
         for event, count in iter(events.items()):
+          if convertMbToGb and event.endswith('_in_gb'):
+            count = f'{count/1024:.2f}'
           row[event] = count
         csvPF.WriteRow(row)
       csvPF.SortRows('email', False)