gam7 7.20.1__tar.gz → 7.20.2__tar.gz

{gam7-7.20.1 → gam7-7.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gam7
-Version: 7.20.1
+Version: 7.20.2
 Summary: CLI tool to manage Google Workspace
 Project-URL: Homepage, https://github.com/GAM-team/GAM
 Project-URL: Issues, https://github.com/GAM-team/GAM/issues

{gam7-7.20.1 → gam7-7.20.2}/src/GamCommands.txt

@@ -1246,6 +1246,8 @@ Specify a collection of items by directly specifying them; the item type is dete
         <SiteACLScopeList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>
 <SiteEntity> ::=
         <SiteList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector> | <CSVDataSelector>
+<StringEntity> ::=
+        <StringList> | <FileSelector> | <CSVFileSelector>
 <StudentGroupEntity> ::=
         <StudentGroupIDList> | <FileSelector> | <CSVFileSelector> | <CSVkmdSelector>
 <TagManagerAccountPathEntity> ::=
@@ -3396,7 +3398,7 @@ gam print course-works [todrive <ToDriveAttribute>*]
 
 gam create course-studentgroups
         (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
-        title <String>
+        ((title <String>)|(select <StringEntity))+
         [csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]]
 gam update course-studentgroups <CourseID> <StudentGroupID> title <String>
 gam delete course-studentgroups <CourseID> <StudentGroupIDEntity>

{gam7-7.20.1 → gam7-7.20.2}/src/GamUpdate.txt

@@ -1,3 +1,9 @@
+7.20.02
+
+Upgraded `gam create course-studentgroups` to allow specification of multiple student group titles;
+multiple student groups can be created in a single command.
+* `((title <String>)|(select <StringEntity))+`
+
 7.20.01
 
 Added option `showaccesssettings` to `gam [<UserTypeEntity>] print|show chatspaces`. When listing

{gam7-7.20.1 → gam7-7.20.2}/src/gam/__init__.py

@@ -25,7 +25,7 @@ https://github.com/GAM-team/GAM/wiki
 """
 
 __author__ = 'GAM Team <google-apps-manager@googlegroups.com>'
-__version__ = '7.20.01'
+__version__ = '7.20.02'
 __license__ = 'Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0)'
 
 #pylint: disable=wrong-import-position
@@ -51233,7 +51233,7 @@ def printShowClassroomProfile(users):
 
 # gam create course-studentgroups
 #	(course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
-#	title <String>
+#	((title <String>)|(select <StringEntity))+
 #	[csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]]
 def doCreateCourseStudentGroups():
   croom = buildGAPIObject(API.CLASSROOM)
@@ -51243,10 +51243,13 @@ def doCreateCourseStudentGroups():
   courseShowProperties = _initCourseShowProperties(['name'])
   useOwnerAccess = GC.Values[GC.USE_COURSE_OWNER_ACCESS]
   kwargs  = {'courseId': None, 'body': {}}
+  titles = []
   while Cmd.ArgumentsRemaining():
     myarg = getArgument()
     if myarg == 'title':
-      kwargs['body']['title'] = getString(Cmd.OB_STRING)
+      titles.append(getString(Cmd.OB_STRING))
+    elif myarg == 'select':
+      titles.extend(getEntityList(Cmd.OB_STRING_ENTITY, shlexSplit=True))
     elif _getCourseSelectionParameters(myarg, courseSelectionParameters):
       pass
     elif myarg == 'csv':
@@ -51256,8 +51259,9 @@ def doCreateCourseStudentGroups():
       csvPF.GetTodriveParameters()
     else:
       FJQC.GetFormatJSONQuoteChar(myarg, True)
-  if 'title' not in kwargs['body']:
+  if not titles:
     missingArgumentExit('title')
+  jcount = len(titles)
   if csvPF and FJQC.formatJSON:
     csvPF.SetJSONTitles(['courseId', 'courseName', 'JSON'])
   coursesInfo = _getCoursesInfo(croom, courseSelectionParameters, courseShowProperties, useOwnerAccess)
@@ -51272,29 +51276,36 @@ def doCreateCourseStudentGroups():
     if not ocroom:
       continue
     kwargs['courseId'] = courseId
-    kvList = [Ent.COURSE, courseId, Ent.COURSE_STUDENTGROUP, None]
-    try:
-      studentGroup = callGAPI(ocroom.courses().studentGroups(), 'create',
-                              throwReasons=[GAPI.NOT_FOUND, GAPI.SERVICE_NOT_AVAILABLE, GAPI.NOT_IMPLEMENTED,
-                                            GAPI.FORBIDDEN, GAPI.PERMISSION_DENIED],
-                              retryReasons=GAPI.SERVICE_NOT_AVAILABLE_RETRY_REASONS,
-                              previewVersion='V1_20250630_PREVIEW',
-                              **kwargs)
-      kvList[-1] = f"{studentGroup['title']}({studentGroup['id']})"
-      if not csvPF:
-        entityActionPerformed(kvList, i, count)
-      elif not  FJQC.formatJSON:
-        csvPF.WriteRow({'courseId': courseId, 'courseName': course['name'],
-                        'studentGroupId': studentGroup['id'], 'studentGroupTitle': studentGroup['title']})
-      else:
-        csvPF.WriteRowNoFilter({'courseId': courseId, 'courseName': course['name'],
-                                'JSON': json.dumps(cleanJSON(studentGroup), ensure_ascii=False, sort_keys=True)})
-    except GAPI.notFound as e:
-      entityActionFailedWarning(kvList, str(e), i, count)
-    except (GAPI.serviceNotAvailable, GAPI.notImplemented) as e:
-      entityActionFailedExit([Ent.COURSE, courseId], str(e), i, count)
-    except (GAPI.forbidden, GAPI.permissionDenied) as e:
-      ClientAPIAccessDeniedExit(str(e))
+    entityPerformActionNumItems([Ent.COURSE, courseId], jcount, Ent.COURSE_STUDENTGROUP, i, count)
+    Ind.Increment()
+    j = 0
+    for title in titles:
+      j += 1
+      kwargs['body']['title'] = title
+      kvList = [Ent.COURSE, courseId, Ent.COURSE_STUDENTGROUP, None]
+      try:
+        studentGroup = callGAPI(ocroom.courses().studentGroups(), 'create',
+                                throwReasons=[GAPI.NOT_FOUND, GAPI.SERVICE_NOT_AVAILABLE, GAPI.NOT_IMPLEMENTED,
+                                              GAPI.FORBIDDEN, GAPI.PERMISSION_DENIED],
+                                retryReasons=GAPI.SERVICE_NOT_AVAILABLE_RETRY_REASONS,
+                                previewVersion='V1_20250630_PREVIEW',
+                                **kwargs)
+        kvList[-1] = f"{studentGroup['title']}({studentGroup['id']})"
+        if not csvPF:
+          entityActionPerformed(kvList, j, jcount)
+        elif not  FJQC.formatJSON:
+          csvPF.WriteRow({'courseId': courseId, 'courseName': course['name'],
+                          'studentGroupId': studentGroup['id'], 'studentGroupTitle': studentGroup['title']})
+        else:
+          csvPF.WriteRowNoFilter({'courseId': courseId, 'courseName': course['name'],
+                                  'JSON': json.dumps(cleanJSON(studentGroup), ensure_ascii=False, sort_keys=True)})
+      except GAPI.notFound as e:
+        entityActionFailedWarning(kvList, str(e), j, jcount)
+      except (GAPI.serviceNotAvailable, GAPI.notImplemented) as e:
+        entityActionFailedExit([Ent.COURSE, courseId], str(e), j, jcount)
+      except (GAPI.forbidden, GAPI.permissionDenied) as e:
+        ClientAPIAccessDeniedExit(str(e))
+    Ind.Decrement()
   if csvPF:
     csvPF.writeCSVfile('Course Student Groups')
 

{gam7-7.20.1 → gam7-7.20.2}/src/gam/gamlib/glclargs.py

@@ -1057,6 +1057,7 @@ class GamCLArgs():
   OB_SPREADSHEET_RANGE_LIST = 'SpreadsheetRangeList'
   OB_STATE_NAME_LIST = "StateNameList"
   OB_STRING = 'String'
+  OB_STRING_ENTITY = 'StringEntity'
   OB_STRING_LIST = 'StringList'
   OB_STUDENTGROUP_ID = 'StudentGroupID'
   OB_STUDENTGROUP_ID_ENTITY = 'StudentGroupIDEntity'

{gam7-7.20.1 → gam7-7.20.2}/wiki/Classroom-StudentGroups.md

@@ -3,6 +3,7 @@
 - [API documentation](#api-documentation)
 - [Definitions](#definitions)
 - [Special quoting for course aliases](#special-quoting-for-course-aliases)
+- [Special quoting for lists of titles](#special-quoting-for-lists-of-titles)
 - [Manage student groups](#manage-student-groups)
 - [Display student groups](#display-student-groups)
 - [Display student group counts](#display-student-group-counts)
@@ -60,6 +61,11 @@ Once you get an email from Google saying that your project has been registered y
 <CourseState> ::= active|archived|provisioned|declined|suspended
 <CourseStateList> ::= all|"<CourseState>(,<CourseState>)*"
 
+<StringList> ::= "<String>(,<String>)*"
+<StringEntity> ::=
+        <StringList> | <FileSelector> | <CSVFileSelector>
+        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
+
 <StudentGroupID> ::= <Number>
 <StudentGroupIDList> ::= "<StudentGroupID>(,<StudentGroupID>)*"
 <StudentGroupEntity> ::=
@@ -82,6 +88,25 @@ The shell strips the `"` leaving a single argument `'d:Math Class'`; as gam is e
 
 For multiple aliases you must enter: `gam info courses "'d:Math Class','d:Science Class'"`
 
+## Special quoting for lists of titles
+As student group titles can contain spaces, some care must be used when entering `selevct <StringList>`.
+
+Suppose you want to create a student group `Advanced Students`. `gam create course-studentgroups course <CourseID> title "Advanced Students"`
+
+The shell strips the `"` leaving a single argument `Advanced Math`; gam correctly processes the argument as it is expecting a single title.
+
+Suppose you enter the command: `gam create course-studentgroups course <CourseID> select "Advanced Students"`
+
+The shell strips the `"` leaving a single argument `Advanced Students`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `Advanced` and `Students`, not what you want.
+
+You must enter: `gam create course-studentgroups course <CourseID> select "'Advanced Students'"`
+
+The shell strips the `"` leaving a single argument `'Advanced Students'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `Advanced Students` and correctly processes the item.
+
+For multiple titles you can enter either of the following:
+* `gam create course-studentgroups course <CourseID> select "'Advanced Students','Beginner Students'"`
+* `gam create course-studentgroups course <CourseID> title"Advanced Students" title "Beginner Students"`
+
 See: [Lists and Collections](Lists-and-Collections)
 
 ## Manage student groups
@@ -89,7 +114,7 @@ See: [Lists and Collections](Lists-and-Collections)
 ```
 gam create course-studentgroups
         (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
-        title <String>
+        ((title <String>)|(select <StringEntity))+
         [csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]]
 gam update course-studentgroups <CourseID> <StudentGroupID> title <String>
 gam delete course-studentgroups <CourseID> <StudentGroupIDEntity>
@@ -97,6 +122,9 @@ gam clear course-studentgroups
         (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
 ```
 
+When creating student groups, the API does not check for duplicate titles; you can have multiple student grpups
+with the same title; they will have unique `<StudentGroupID>s`.
+
 The `update|delete course-studentgroups` commands manage a specific course.
 
 By default, the `create|clear course-studentgroups` commands manage student group information about all courses.
@@ -112,6 +140,34 @@ To manage student group information for courses based on their state, use the fo
 By default, all course states are selected.
 * `states <CourseStateList>` - Display courses with any of the specified states.
 
+By default, when a student group is created, you will get output like this:
+```
+Course: <CourseID>, Course Student Group: <Title>(<StudentGroupId>), Added
+```
+If you use the `csv` option, you will get output like this:
+```
+courseId,courseName,studentGroupId,studentGroupTitle
+<CourseID>,<CourseName>,<StudentGroupID>,<Title>
+```
+This gives you a record the the student group IDs.
+
+### Example
+```
+$ more titles.csv
+title
+Advanced Students
+Middle Students
+Beginner Students
+
+$ gam redirect csv ./StudentGroups.csv add coursestudentgroups course <CourseID> select csvfile titles.csv:title csv
+
+$ more StudentGroups.csv 
+courseId,courseName,studentGroupId,studentGroupTitle
+<CourseID>,<CourseName>,796177544247,Advanced Students
+<CourseID>,<CourseName>,796177718666,Middle Students
+<CourseID>,<CourseName>,796177727901,Beginner Students
+```
+
 ## Display student groups
 ```
 gam print course-studentgroups [todrive <ToDriveAttribute>*]

{gam7-7.20.1 → gam7-7.20.2}/wiki/GamUpdates.md

@@ -10,6 +10,13 @@ Add the `-s` option to the end of the above commands to suppress creating the `g
 
 See [Downloads-Installs-GAM7](https://github.com/GAM-team/GAM/wiki/Downloads-Installs) for Windows or other options, including manual installation
 
+### 7.20.01
+
+Added option `showaccesssettings` to `gam [<UserTypeEntity>] print|show chatspaces`. When listing
+Chat Spaces, the Chat API does not return the `accessSettings` field; if you need to see this field,
+add `showaccesssettings` to the command. This requires an additional Chat API call per chat space of type `SPACE`
+to get the `accessSettings` field.
+
 ### 7.20.00
 
 Added initial support for student groups in Google Classroom. This is a work in progress and requires Developer Preview membership.

{gam7-7.20.1 → gam7-7.20.2}/wiki/How-to-Upgrade-Legacy-GAM-to-GAM7.md

@@ -252,7 +252,7 @@ writes the credentials into the file oauth2.txt.
 admin@server:/Users/admin$ rm -f /Users/admin/GAMConfig/oauth2.txt
 admin@server:/Users/admin$ gam version
 WARNING: Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: /Users/admin/GAMConfig/oauth2.txt, Not Found
-GAM 7.20.00 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.20.01 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 MacOS Sequoia 15.6.1 x86_64
@@ -990,7 +990,7 @@ writes the credentials into the file oauth2.txt.
 C:\>del C:\GAMConfig\oauth2.txt
 C:\>gam version
 WARNING: Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, Item: oauth2_txt, Value: C:\GAMConfig\oauth2.txt, Not Found
-GAM 7.20.00 - https://github.com/GAM-team/GAM - pythonsource
+GAM 7.20.01 - https://github.com/GAM-team/GAM - pythonsource
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 Windows-10-10.0.17134 AMD64

{gam7-7.20.1 → gam7-7.20.2}/wiki/Users-Chat.md

@@ -320,24 +320,32 @@ By default, Gam displays the information as an indented list of keys and values.
 ```
 gam <UserTypeEntity> show chatspaces
         [types <ChatSpaceTypeList>]
-        [fields <ChatSpaceFieldNameList>]
+        [fields <ChatSpaceFieldNameList>] [showaccessssettings]
         [formatjson]
 ```
 By default, chat spaces of all types are displayed.
 * `types <ChatSpaceTypeList>` - Display specific types of spaces.
 
+When listing Chat Spaces, the Chat API does not return the `accessSettings` field; if you need to see this fieldf,
+add `showaccesssettings` to the command. This requires an additional Chat API call per chat space of type `SPACE`
+to get the `accessSettings` field.
+
 By default, Gam displays the information as an indented list of keys and values.
 * `formatjson` - Display the fields in JSON format.
 
 ```
 gam <UserTypeEntity> print chatspaces [todrive <ToDriveAttribute>*]
         [types <ChatSpaceTypeList>]
-        [fields <ChatSpaceFieldNameList>]
+        [fields <ChatSpaceFieldNameList>] [showaccessssettings]
         [formatjson [quotechar <Character>]]
 ```
 By default, chat spaces of all types are displayed.
 * `types <ChatSpaceTypeList>` - Display specific types of spaces.
 
+When listing Chat Spaces, the Chat API does not return the `accessSettings` field; if you need to see this fieldf,
+add `showaccesssettings` to the command. This requires an additional Chat API call per chat space of type `SPACE`
+to get the `accessSettings` field.
+
 By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,
 * `formatjson` - Display the fields in JSON format.
 
@@ -385,13 +393,17 @@ Only spaces of `<ChatSpaceType>` `space` are displayed; spaces of `<ChatSpaceTyp
 gam <UserItem> show chatspaces asadmin
         [query <String>] [querytime<String> <Time>]
         [orderby <ChatSpaceAdminOrderByFieldName> [ascending|descending]]
-        [fields <ChatSpaceFieldNameList>]
+        [fields <ChatSpaceFieldNameList>] [showaccessssettings]
         [formatjson]
 ```
 By default, all chat spaces of type SPACE are displayed.
 * `query <String> [querytime<String> <Time>]` - Display selected chat spaces
   * See: https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search
 
+When listing Chat Spaces, the Chat API does not return the `accessSettings` field; if you need to see this fieldf,
+add `showaccesssettings` to the command. This requires an additional Chat API call per chat space of type `SPACE`
+to get the `accessSettings` field.
+
 By default, Gam displays the information as an indented list of keys and values.
 * `formatjson` - Display the fields in JSON format.
 
@@ -399,13 +411,17 @@ By default, Gam displays the information as an indented list of keys and values.
 gam <UserItem> print chatspaces asadmin [todrive <ToDriveAttribute>*]
         [query <String>] [querytime<String> <Time>]
         [orderby <ChatSpaceAdminOrderByFieldName> [ascending|descending]]
-        [fields <ChatSpaceFieldNameList>]
+        [fields <ChatSpaceFieldNameList>] [showaccessssettings]
         [formatjson [quotechar <Character>]]
 ```
 By default, all chat spaces of type SPACE are displayed.
 * `query <String> [querytime<String> <Time>]` - Display selected chat spaces
   * See: https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search
 
+When listing Chat Spaces, the Chat API does not return the `accessSettings` field; if you need to see this fieldf,
+add `showaccesssettings` to the command. This requires an additional Chat API call per chat space of type `SPACE`
+to get the `accessSettings` field.
+
 By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,
 * `formatjson` - Display the fields in JSON format.
 
@@ -975,8 +991,9 @@ The `quotechar <Character>` option allows you to choose an alternate quote chara
 ## Bulk Operations
 ### Display information about all chat spaces for a collection of users
 ```
-gam config auto_batch_min 1 redirect csv ./ChatSpaces.csv multiprocess [todrive <ToDriveAttribute>*] redirect stdout - multiprocess redirect stderr <UserTypeEntity> print chatspaces
+gam config auto_batch_min 1 redirect csv ./ChatSpaces.csv multiprocess [todrive <ToDriveAttribute>*] redirect stdout - multiprocess redirect stderr <UserTypeEntity> print chatsacesp
         [types <ChatSpaceTypeList>]
+        [fields <ChatSpaceFieldNameList>] [showaccessssettings]
         [formatjson [quotechar <Character>]]
 ```
 

{gam7-7.20.1 → gam7-7.20.2}/wiki/Version-and-Help.md

@@ -3,7 +3,7 @@
 Print the current version of Gam with details
 ```
 gam version
-GAM 7.20.00 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.20.01 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 MacOS Sequoia 15.6.1 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
-GAM 7.20.00 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.20.01 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 MacOS Sequoia 15.6.1 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
-GAM 7.20.00 - https://github.com/GAM-team/GAM - pyinstaller
+GAM 7.20.01 - https://github.com/GAM-team/GAM - pyinstaller
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 MacOS Sequoia 15.6.1 x86_64
@@ -64,7 +64,7 @@ MacOS High Sierra 10.13.6 x86_64
 Path: /Users/Admin/bin/gam7
 Version Check:
   Current: 5.35.08
-   Latest: 7.20.00
+   Latest: 7.20.01
 echo $?
 1
 ```
@@ -72,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-7.20.00
+7.20.01
 ```
 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 7.20.00 - https://github.com/GAM-team/GAM
+GAM 7.20.01 - https://github.com/GAM-team/GAM
 GAM Team <google-apps-manager@googlegroups.com>
 Python 3.13.7 64-bit final
 MacOS Sequoia 15.6.1 x86_64