Added support for Gmail Client Side Encryption

Build universal2 with macos-12, doesn't run with macos-14

.github/workflows/build.yml

@@ -34,11 +34,13 @@ jobs:
             goal: build
             arch: x86_64
             openssl_archs: linux-x86_64
+            fullGamTest: yes
           - os: [self-hosted, linux, arm64]
             jid: 2
             goal: build
             arch: aarch64
             openssl_archs: linux-aarch64
+            fullGamTest: yes
           - os: ubuntu-20.04
             jid: 3
             goal: build
@@ -56,21 +58,24 @@ jobs:
             goal: build
             arch: x86_64
             openssl_archs: darwin64-x86_64
-          - os: [self-hosted, macOS, ARM64]
-            jid: 7
+            fullGamTest: yes
+          - os: macos-14
+            jid: 6
             goal: build
             arch: aarch64
             openssl_archs: darwin64-arm64
-          - os: [self-hosted, macOS, ARM64]
-            jid: 12
+            fullGamTest: yes
+          - os: macos-14
+            jid: 7
             goal: build
             arch: universal2
             openssl_archs: darwin64-arm64 darwin64-x86_64
           - os: windows-2022
-            jid: 6
+            jid: 8
             goal: build
             arch: Win64
             openssl_archs: VC-WIN64A
+            fullGamTest: yes
           - os: ubuntu-22.04
             goal: test
             python: "3.8"
@@ -94,37 +99,36 @@ jobs:
 
     steps:
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - id: auth
         name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@v1
+        uses: google-github-actions/auth@v2
         with:
           workload_identity_provider: projects/297925809119/locations/global/workloadIdentityPools/gha-pool/providers/gha-provider
           service_account: github-actions-testing-for-gam@gam-project-wyo-lub-ivl.iam.gserviceaccount.com
 
       - name: Cache multiple paths
         if: matrix.goal == 'build'
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         id: cache-python-ssl
         with:
           path: |
-            bin.tar.xz
-            src/cpython
-          key: gam-${{ matrix.jid }}-20231212
+            cache.tar.xz
+          key: gam-${{ matrix.jid }}-20240210
 
       - name: Untar Cache archive
         if: matrix.goal == 'build' && steps.cache-python-ssl.outputs.cache-hit == 'true'
         working-directory: ${{ github.workspace }}
         run: |
-          tar xvvf bin.tar.xz
+          tar xvvf cache.tar.xz
 
       - name: Use pre-compiled Python for testing
         if: matrix.python != ''
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
           allow-prereleases: true
@@ -155,19 +159,30 @@ jobs:
           fi
           echo "GAMCFGDIR=${GAMCFGDIR}" >> $GITHUB_ENV
           echo "GAMCFGDIR is: ${GAMCFGDIR}"
+          if [[ "${RUNNER_OS}" == "macOS" ]]; then
+            GAMOS="macos"
+          elif [[ "${RUNNER_OS}" == "Linux" ]]; then
+            GAMOS="linux"
+          elif [[ "${RUNNER_OS}" == "Windows" ]]; then
+            GAMOS="windows"
+          else
+           GAMOS='unknown'
+          fi
+          echo "GAMOS=${GAMOS}" >> $GITHUB_ENV
+          echo "GAMOS is: ${GAMOS}"
 
       - name: Set env variables for test
         if: matrix.goal == 'test'
         run: |
-             export PYTHON=$(which python3)
-             export PIP=$(which pip3)
-             export gam="${PYTHON} -m gam"
-             export gampath="$(readlink -e .)"
-             echo -e "PYTHON: ${PYTHON}\nPIP: ${PIP}\gam: ${gam}\ngampath: ${gampath}"
-             echo "PYTHON=${PYTHON}" >> $GITHUB_ENV
-             echo "PIP=${PIP}" >> $GITHUB_ENV
-             echo "gam=${gam}" >> $GITHUB_ENV
-             echo "gampath=${gampath}" >> $GITHUB_ENV
+          export PYTHON=$(which python3)
+          export PIP=$(which pip3)
+          export gam="${PYTHON} -m gam"
+          export gampath="$(readlink -e .)"
+          echo -e "PYTHON: ${PYTHON}\nPIP: ${PIP}\gam: ${gam}\ngampath: ${gampath}"
+          echo "PYTHON=${PYTHON}" >> $GITHUB_ENV
+          echo "PIP=${PIP}" >> $GITHUB_ENV
+          echo "gam=${gam}" >> $GITHUB_ENV
+          echo "gampath=${gampath}" >> $GITHUB_ENV
 
       - name: Install necessary Github-hosted Linux packages
         if: runner.os == 'Linux' && runner.arch == 'X64'
@@ -177,15 +192,15 @@ jobs:
           sudo apt-get -qq --yes install swig libpcsclite-dev libxslt1-dev
 
       - name: MacOS install tools
-        if: runner.os == 'macOS' && runner.arch == 'x86_64'
+        if: runner.os == 'macOS'
         run: |
           # Install latest Rust
           curl $curl_retry -fsS -o rust.sh https://sh.rustup.rs
           bash ./rust.sh -y
           source $HOME/.cargo/env
-          # needed for Rust to compile cryptography Python package for universal2
-          # not needed since MacOS ARM and universal will be on self-hosted
-          #rustup target add aarch64-apple-darwin
+          # Install needed packages
+          brew update
+          brew install gpg swig
 
       - name: Windows Configure VCode
         uses: ilammy/msvc-dev-cmd@v1
@@ -215,14 +230,11 @@ jobs:
             CHOC_OPS="--forcex86"
           fi
           if [[ "${RUNNER_OS}" == "macOS" ]]; then
-            #brew install coreutils
-            #brew install bash
             MAKE=make
             MAKEOPT="-j$(sysctl -n hw.logicalcpu)"
             PERL=perl
             echo "MACOSX_DEPLOYMENT_TARGET=10.15" >> $GITHUB_ENV
             echo "PYTHON=${PYTHON_INSTALL_PATH}/bin/python3" >> $GITHUB_ENV
-            #echo "PIP_ARGS=--no-binary=:all:" >> $GITHUB_ENV
           elif [[ "${RUNNER_OS}" == "Linux" ]]; then
             MAKE=make
             MAKEOPT="-j$(nproc)"
@@ -444,39 +456,39 @@ jobs:
 
       - name: Install pip requirements
         run: |
-             echo "before anything..."
-             "${PYTHON}" -m pip list
-             if ([ "${RUNNER_OS}" == "macOS" ] && [ "$arch" == "universal2" ]); then
-               # cffi is a dep of cryptography and doesn't ship
-               # a universal2 wheel so we must build one ourself :-/
-               export CFLAGS="-arch x86_64 -arch arm64"
-               export ARCHFLAGS="-arch x86_64 -arch arm64"
-               "${PYTHON}" -m pip install --upgrade --force-reinstall --no-binary :all: \
-                                 --no-cache-dir --no-deps --use-pep517 \
-                                 --use-feature=no-binary-enable-wheel-cache \
-                                 cffi 
-               echo "before cryptography..."
-               "${PYTHON}" -m pip list
-               # cryptography has a universal2 wheel but getting it installed
-               # on x86-64 MacOS is a royal pain in the keester.
-               "${PYTHON}" -m pip download --only-binary :all: \
-                                             --dest . \
-                                             --no-cache \
-                                             --no-deps \
-                                             --platform macosx_10_15_universal2 \
-                                             cryptography
-               "${PYTHON}" -m pip install --force-reinstall --no-deps cryptography*.whl
-               echo "after cryptography..."
-               "${PYTHON}" -m pip list
-               "${PYTHON}" -m pip install --upgrade --no-binary :all: -r requirements.txt
-             else
-               "${PYTHON}" -m pip install --upgrade -r requirements.txt
-               echo "after requirements..."
-               "${PYTHON}" -m pip list
-               "${PYTHON}" -m pip install --force-reinstall --no-deps --upgrade cryptography
-             fi
-             echo "after everything..."
-             "${PYTHON}" -m pip list
+          echo "before anything..."
+          "${PYTHON}" -m pip list
+          if ([ "${RUNNER_OS}" == "macOS" ] && [ "$arch" == "universal2" ]); then
+            # cffi is a dep of cryptography and doesn't ship
+            # a universal2 wheel so we must build one ourself :-/
+            export CFLAGS="-arch x86_64 -arch arm64"
+            export ARCHFLAGS="-arch x86_64 -arch arm64"
+            "${PYTHON}" -m pip install --upgrade --force-reinstall --no-binary :all: \
+                              --no-cache-dir --no-deps --use-pep517 \
+                              --use-feature=no-binary-enable-wheel-cache \
+                              cffi 
+            echo "before cryptography..."
+            "${PYTHON}" -m pip list
+            # cryptography has a universal2 wheel but getting it installed
+            # on x86-64 MacOS is a royal pain in the keester.
+            "${PYTHON}" -m pip download --only-binary :all: \
+                                          --dest . \
+                                          --no-cache \
+                                          --no-deps \
+                                          --platform macosx_10_15_universal2 \
+                                          cryptography
+            "${PYTHON}" -m pip install --force-reinstall --no-deps cryptography*.whl
+            echo "after cryptography..."
+            "${PYTHON}" -m pip list
+            "${PYTHON}" -m pip install --upgrade --no-binary :all: -r requirements.txt
+          else
+            "${PYTHON}" -m pip install --upgrade -r requirements.txt
+            echo "after requirements..."
+            "${PYTHON}" -m pip list
+            "${PYTHON}" -m pip install --force-reinstall --no-deps --upgrade cryptography
+          fi
+          echo "after everything..."
+          "${PYTHON}" -m pip list
 
       - name: Install PyInstaller
         if: matrix.goal == 'build'
@@ -514,34 +526,34 @@ jobs:
       - name: Build GAM with PyInstaller
         if: matrix.goal != 'test'
         run: |
-             if [[ "${staticx}" == "yes" ]]; then
-               export distpath="./dist/gam"
-               export gampath="${distpath}"
-             else
-               export distpath="./dist"
-               export gampath="${distpath}/gam"
-             fi
-             mkdir -p -v "${gampath}"
-             if [[ "${RUNNER_OS}" == "macOS" ]]; then
-               export gampath=$($PYTHON -c "import os; print(os.path.realpath('$gampath'))")
-             elif [[ "${RUNNER_OS}" == "Windows" ]]; then
-               # Work around issue where PyInstaller picks up python3.dll from other Python versions
-               # https://github.com/pyinstaller/pyinstaller/issues/7102
-               export PATH="/usr/bin"
-             else
-               export gampath=$(realpath "${gampath}")
-             fi
-             export gam="${gampath}/gam"
-             echo "gampath=${gampath}" >> $GITHUB_ENV
-             echo "gam=${gam}" >> $GITHUB_ENV
-             echo -e "GAM: ${gam}\nGAMPATH: ${gampath}"
-             # TEMP force everything back to one file.
-             export PYINSTALLER_BUILD_ONEFILE="yes"
-             export distpath="./dist/gam"
-             export gampath="${distpath}"
-             "${PYTHON}" -m PyInstaller --clean --noconfirm --distpath="${distpath}" gam.spec
-             cat build/gam/warn-gam.txt
- 
+          if [[ "${staticx}" == "yes" ]]; then
+            export distpath="./dist/gam"
+            export gampath="${distpath}"
+          else
+            export distpath="./dist"
+            export gampath="${distpath}/gam"
+          fi
+          mkdir -p -v "${gampath}"
+          if [[ "${RUNNER_OS}" == "macOS" ]]; then
+            export gampath=$($PYTHON -c "import os; print(os.path.realpath('$gampath'))")
+          elif [[ "${RUNNER_OS}" == "Windows" ]]; then
+            # Work around issue where PyInstaller picks up python3.dll from other Python versions
+            # https://github.com/pyinstaller/pyinstaller/issues/7102
+            export PATH="/usr/bin"
+          else
+            export gampath=$(realpath "${gampath}")
+          fi
+          export gam="${gampath}/gam"
+          echo "gampath=${gampath}" >> $GITHUB_ENV
+          echo "gam=${gam}" >> $GITHUB_ENV
+          echo -e "GAM: ${gam}\nGAMPATH: ${gampath}"
+          # TEMP force everything back to one file.
+          export PYINSTALLER_BUILD_ONEFILE="yes"
+          export distpath="./dist/gam"
+          export gampath="${distpath}"
+          "${PYTHON}" -m PyInstaller --clean --noconfirm --distpath="${distpath}" gam.spec
+          cat build/gam/warn-gam.txt
+
       - name: Copy extra package files
         if: matrix.goal == 'build'
         run: |
@@ -578,11 +590,11 @@ jobs:
       - name: Basic Tests all jobs
         id: basictests
         run: |
-             $PYTHON -m unittest discover --start-directory ./ --pattern "*_test.py" --buffer || if [ $? != 5 ]; then exit $?; fi # exit 5 is no tests
-             $gam version extended nooffseterror
-             export GAMVERSION=$($gam version simple)
-             echo "GAM Version ${GAMVERSION}"
-             echo "GAMVERSION=${GAMVERSION}" >> $GITHUB_ENV
+          $PYTHON -m unittest discover --start-directory ./ --pattern "*_test.py" --buffer || if [ $? != 5 ]; then exit $?; fi # exit 5 is no tests
+          $gam version extended nooffseterror
+          export GAMVERSION=$($gam version simple)
+          echo "GAM Version ${GAMVERSION}"
+          echo "GAMVERSION=${GAMVERSION}" >> $GITHUB_ENV
 
       - name: Linux/MacOS package
         if: runner.os != 'Windows' && matrix.goal == 'build'
@@ -595,7 +607,7 @@ jobs:
               else
                 libver="glibc$(ldd --version | awk '/ldd/{print $NF}')"
               fi
-              GAM_ARCHIVE="gam-${GAMVERSION}-linux-$(arch)-$libver}.tar.xz"
+              GAM_ARCHIVE="gam-${GAMVERSION}-linux-$(arch)-${libver}.tar.xz"
           fi
           tar -C dist/ --create --verbose --exclude-from "${GITHUB_WORKSPACE}/.github/actions/package_exclusions.txt" --file $GAM_ARCHIVE --xz gam
 
@@ -631,227 +643,248 @@ jobs:
           echo "We successfully compiled Python ${this_python} and OpenSSL ${this_openssl}"
 
       - name: Live API tests push only
-        if: github.event_name == 'push' || github.event_name == 'schedule'
+        if: (github.event_name == 'push' || github.event_name == 'schedule') && matrix.fullGamTest == 'yes'
         env:
           PASSCODE: ${{ secrets.PASSCODE }}
         run: |
-             if ([ "${RUNNER_OS}" == "macOS" ] && which gpg > /dev/null); then
-               brew install gnupg
-             fi
-             source ../.github/actions/decrypt.sh ../.github/actions/creds.tar.xz.gpg creds.tar.xz "${GAMCFGDIR}"
-             mv -v "${GAMCFGDIR}/oauth2.txt-gam-gha-${JID}" "${GAMCFGDIR}/oauth2.txt"
-             rm -v $GAMCFGDIR/oauth2.txt-gam*
-             export gam_user="gam-gha-${JID}@pdl.jaylee.us"
-             echo "gam_user=${gam_user}" >> $GITHUB_ENV
-             $gam config customer_id "C03uzfv2s" save
-             $gam config domain "pdl.jaylee.us" save
-             $gam config admin_email "${gam_user}" save
-             $gam config enable_dasa false save
-             $gam oauth info
-             $gam oauth refresh
-             $gam config enable_dasa true save 
-             $gam create signjwtserviceaccount
-             $gam checkconn
-             $gam user "$gam_user" check serviceaccount
-             $gam info domain
-             $gam info user
-             export tstamp=$($PYTHON -c "import time; print(time.time_ns())")
-             export newbase="gha_test_${JID}_${tstamp}"
-             export newuser="${newbase}@pdl.jaylee.us"
-             export newgroup="${newbase}-group@pdl.jaylee.us"
-             export newalias="${newbase}-alias@pdl.jaylee.us"
-             export newbuilding="${newbase}-building"
-             export newresource="${newbase}-resource"
-             export newou="aaaGithub Actions/${newbase}"
-             
-             # cleanup old runs
-             $gam config enable_dasa false save
-             $gam config csv_output_row_filter "name:regex:gha_test_${JID}_" print vaultholds || if [ $? != 55 ]; then exit $?; fi | $gam csv - gam delete vaulthold "id:~~holdId~~" matter "id:~~matterId~~"
-             $gam config enable_dasa true save
-             $gam config csv_output_row_filter "name:regex:gha_test_${JID}_" print features | $gam csv - gam delete feature ~name
-             $gam config csv_output_row_filter "name:regex:^gha_test_${JID}_" user $gam_user print shareddrives asadmin | $gam csv - gam user $gam_user delete shareddrive ~id nukefromorbit
-             $gam print users query "gha.jid=$JID" | $gam csv - gam delete user ~primaryEmail
-             $gam config csv_output_row_filter "name:regex:^gha_test_${JID}_" print ous fromparent "aaaGithub Actions" | $gam csv - gam delete ou ~orgUnitId
-             $gam config csv_output_row_filter "email:regex:^gha_test_${JID}_" print cigroups | $gam csv - gam delete cigroup ~email
-             $gam config csv_output_row_filter "resourceId:regex:^gha_test_${JID}_" print resources | $gam csv - gam delete resource ~resourceId
-             $gam config csv_output_row_filter "buildingId:regex:^gha_test_${JID}_" print buildings | $gam csv - gam delete building ~buildingId
-             $gam config csv_output_row_filter "Emails.1.address:regex:^gha_test-${JID}_" print contacts | $gam csv - gam delete contact ~ContactID
+          source ../.github/actions/decrypt.sh ../.github/actions/creds.tar.xz.gpg creds.tar.xz "${GAMCFGDIR}"
+          mv -v "${GAMCFGDIR}/oauth2.txt-gam-gha-${JID}" "${GAMCFGDIR}/oauth2.txt"
+          rm -v $GAMCFGDIR/oauth2.txt-gam*
+          export gam_user="gam-gha-${JID}@pdl.jaylee.us"
+          echo "gam_user=${gam_user}" >> $GITHUB_ENV
+          $gam config customer_id "C03uzfv2s" save
+          $gam config domain "pdl.jaylee.us" save
+          $gam config admin_email "${gam_user}" save
+          $gam config enable_dasa false save
+          $gam oauth info
+          $gam oauth refresh
+          $gam config enable_dasa true save 
+          $gam create signjwtserviceaccount
+          $gam checkconn
+          $gam user "$gam_user" check serviceaccount
+          $gam info domain
+          $gam info user
+          export tstamp=$($PYTHON -c "import time; print(time.time_ns())")
+          export newbase="gha_test_${JID}_${tstamp}"
+          export newuser="${newbase}@pdl.jaylee.us"
+          export newgroup="${newbase}-group@pdl.jaylee.us"
+          export newalias="${newbase}-alias@pdl.jaylee.us"
+          export newbuilding="${newbase}-building"
+          export newresource="${newbase}-resource"
+          export newou="aaaGithub Actions/${newbase}"
+          
+          # cleanup old runs
+          $gam config enable_dasa false save
+          $gam config csv_output_row_filter "name:regex:gha_test_${JID}_" print vaultholds || if [ $? != 55 ]; then exit $?; fi | $gam csv - gam delete vaulthold "id:~~holdId~~" matter "id:~~matterId~~"
+          $gam config enable_dasa true save
+          $gam config csv_output_row_filter "name:regex:gha_test_${JID}_" print features | $gam csv - gam delete feature ~name
+          $gam config csv_output_row_filter "name:regex:^gha_test_${JID}_" user $gam_user print shareddrives asadmin | $gam csv - gam user $gam_user delete shareddrive ~id nukefromorbit
+          $gam print users query "gha.jid=$JID" | $gam csv - gam delete user ~primaryEmail
+          $gam config csv_output_row_filter "name:regex:^gha_test_${JID}_" print ous fromparent "aaaGithub Actions" | $gam csv - gam delete ou ~orgUnitId
+          $gam config csv_output_row_filter "email:regex:^gha_test_${JID}_" print cigroups | $gam csv - gam delete cigroup ~email
+          $gam config csv_output_row_filter "resourceId:regex:^gha_test_${JID}_" print resources | $gam csv - gam delete resource ~resourceId
+          $gam config csv_output_row_filter "buildingId:regex:^gha_test_${JID}_" print buildings | $gam csv - gam delete building ~buildingId
+          $gam config csv_output_row_filter "Emails.1.address:regex:^gha_test-${JID}_" print contacts | $gam csv - gam delete contact ~ContactID
 
-             echo "Creating OrgUnit ${newou}"
-             $gam create ou "${newou}"
-             export GAM_THREADS=5
-             echo email > sample.csv;
-             for i in {1..10}; do
-               echo "${newbase}-bulkuser-$i" >> sample.csv;
-             done
-             driveid=$($gam user $gam_user add shareddrive "${newbase}" returnidonly)
-             echo "Created shared drive ${driveid}"
-             $gam create user $newuser firstname GHA lastname $JID displayname "Github Actions ${JID}" password random ou "${newou}" recoveryphone 12125121110 recoveryemail jay0lee@gmail.com gha.jid $JID languages en+,en-GB-
-             $gam user $newuser update photo https://dummyimage.com/400x600/000/fff
-             $gam user $newuser get photo
-             $gam user $newuser delete photo
-             $gam create alias $newalias user $newuser
-             $gam create group $newgroup name "GHA $JID group" description "This is a description" isarchived true
-             $gam user $gam_user sendemail recipient $newuser subject "test message $newbase" message "GHA test message"
-             $gam user $gam_user sendemail recipient exchange@pdl.jaylee.us subject "test ${tstamp}" message "test message"
-             $gam config enable_dasa false save
-             $gam create contact firstname GHA lastname "$JID" email work "${newbase}@example.com" primary
-             $gam print contacts
-             $gam user $newuser add license workspaceenterpriseplus
-             $gam print privileges
-             $gam config enable_dasa true save
-             $gam update cigroup $newgroup security memberrestriction 'member.type == 1 || member.customer_id == groupCustomerId()'
-             $gam info cigroup $newgroup
-             $gam update group $newgroup add owner $gam_user
-             $gam update group $newgroup add member $newuser
-             $gam config enable_dasa false save
-             $gam create admin $newuser _GROUPS_EDITOR_ROLE CUSTOMER # condition nonsecuritygroup
-             $gam create admin $newgroup _HELP_DESK_ADMIN_ROLE org_unit "${newou}"
-             $gam config csv_output_row_filter "assignedToUser:regex:${newuser}" print admins | $gam csv - gam delete admin "~roleAssignmentId"
-             $gam config csv_output_row_filter "assignedToGroup:regex:${newgroup}" print admins | $gam csv - gam delete admin "~roleAssignmentId"
-             $gam config enable_dasa false save
-             $gam csv sample.csv gam create user ~~email~~ firstname "GHA Bulk" lastname ~~email~~ gha.jid $JID ou "${newou}"
-             $gam csv sample.csv gam update user ~~email~~ recoveryphone 12125121110 recoveryemail jay0lee@gmail.com password random displayname "GitHub Actions Bulk ${JID}"
-             $gam csv sample.csv gam update user ~~email~~ recoveryphone "" recoveryemail ""
-             $gam config enable_dasa false save
-             $gam csv sample.csv gam user ~email add license workspaceenterpriseplus
-             $gam config enable_dasa true save
-             $gam csv sample.csv gam user $gam_user sendemail recipient ~~email~~@pdl.jaylee.us subject "test message $newbase" message "GHA test message"
-             $gam csv sample.csv gam update group $newgroup add member ~email
-             $gam info group $newgroup
-             $gam info cigroup $newgroup membertree
-             # confirm mailbox is provisoned before continuing
-             $gam user $newuser waitformailbox
-             $gam user $newuser imap on
-             $gam user $newuser show imap
-             $gam user $newuser show delegates
-             #$gam user $newuser add contactdelegate "${newbase}-bulkuser-1"
-             #$gam user $newuser print contactdelegates
-             export biohazard=$(echo -e '\xe2\x98\xa3')
-             $gam user $newuser label "$biohazard unicode biohazard $biohazard"
-             $gam user $newuser show labels
-             $gam user $newuser show labels > labels.txt
-             $gam user $gam_user importemail subject "GHA import $newbase" message "This is a test import" labels IMPORTANT,UNREAD,INBOX,STARRED
-             $gam user $gam_user insertemail subject "GHA insert $newbase" file gam.py labels INBOX,UNREAD # yep body is gam code
-             $gam user $gam_user sendemail subject "GHA send $gam_user $newbase" file gam.py recipient admin@pdl.jaylee.us
-             $gam user $gam_user draftemail subject "GHA draft $newbase" message "Draft message test"
-             $gam csvfile sample.csv:email waitformailbox
-             $gam user $newuser delegate to "${newbase}-bulkuser-1" || if [ $? != 50 ]; then exit $?; fi # expect a 50 return code (delegation failed)
-             $gam users "$gam_user $newbase-bulkuser-1 $newbase-bulkuser-2 $newbase-bulkuser-3" delete messages query in:anywhere maxtodelete 99999 doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
-             $gam users "$newbase-bulkuser-4 $newbase-bulkuser-5 $newbase-bulkuser-6" trash messages query in:anywhere maxtotrash 99999 doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
-             $gam users "$newbase-bulkuser-7 $newbase-bulkuser-8 $newbase-bulkuser-9" modify messages query in:anywhere maxtomodify 99999 addlabel IMPORTANT addlabel STARRED doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
-             $gam user $newuser delete label --ALL_LABELS--
-             $gam config csv_output_row_filter "name:regex:gha-test-${JID}" print features | $gam csv - gam delete feature ~name
-             $gam create feature name VC-$newbase
-             $gam create feature name Whiteboard-$newbase
-             $gam create building "My Building - $newbase" id $newbuilding floors 1,2,3,4,5,6,7,8,9,10,11,12,14,15 description "No 13th floor here..."
-             $gam create resource $newresource "Resource Calendar $tstamp" capacity 25 features Whiteboard-$newbase,VC-$newbase building $newbuilding floor 15 type Room
-             $gam info resource $newresource
-             $gam user $newuser add drivefile drivefilename "TPS Reports" mimetype gfolder
-             $gam user $newuser show filelist
-             $gam calendar $gam_user printacl | $gam csv - gam calendar $gam_user delete ~id # clear ACLs
-             $gam calendar $gam_user add read domain
-             $gam calendar $gam_user add freebusy default
-             $gam calendar $gam_user add editor $newuser
-             $gam calendar $gam_user showacl
-             $gam calendar $gam_user printacl | $gam csv - gam calendar $gam_user delete ~id
-             $gam calendar $gam_user addevent summary "GHA test event" start +1h end +2h attendee $newgroup hangoutsmeet guestscanmodify true sendupdates all
-             $gam calendar $gam_user printevents after -0d
-             $gam config enable_dasa false save
-             matterid=uid:$($gam create vaultmatter name "GHA matter $newbase" description "test matter" collaborators $newuser returnidonly)
-             $gam create vaulthold matter $matterid name "GHA hold $newbase" corpus mail accounts $newuser
-             $gam print vaultmatters matterstate open
-             $gam print vaultholds matter $matterid
-             $gam print vaultcount matter $matterid corpus mail everyone todrive tdnobrowser
-             $gam create vaultexport matter $matterid name "GHA export $newbase" corpus mail accounts $newuser
-             $gam print exports matter $matterid | $gam csv - gam info export $matterid id:~~id~~
-             $gam config enable_dasa true save
-             $gam csv sample.csv gam user ~email add calendar id:$newresource
-             $gam delete resource $newresource
-             $gam delete feature Whiteboard-$newbase
-             $gam delete feature VC-$newbase
-             $gam delete building $newbuilding
-             $gam delete group $newgroup
-             $gam config enable_dasa false save
-             echo start
-             $gam user $newuser delete license workspaceenterpriseplus
-             echo finish
-             $gam config enable_dasa true save
-             $gam whatis $newuser || if [ $? != 20 ]; then exit $?; fi # expect a 20 return code (is a user)
-             $gam user $gam_user show tokens
-             $gam config enable_dasa false save
-             download_dir="${RUNNER_TEMP}/TEMP_DELETE_ME"
-             mkdir -v "$download_dir"
-             $gam print exports matter $matterid | $gam csv - gam download export $matterid id:~~id~~ targetfolder "$download_dir"
-             rm -rvf "$download_dir"
-             $gam delete hold "GHA hold $newbase" matter $matterid
-             $gam update matter $matterid action close
-             $gam update matter $matterid action delete
-             # shakes off vault hold on user so we can delete
-             $gam print users query "email:${newuser}" orgunitpath | $gam csv - gam update user ~primaryEmail ou ~orgUnitPath
-             $gam user $newuser show holds || if [ $? != 55 ]; then exit $?; fi # expect a 55 return code
-             export sn="$JID$JID$JID$JID-$(openssl rand -base64 32 | sed 's/[^a-zA-Z0-9]//g')"
-             $gam create device serialnumber $sn devicetype android
-             $gam config enable_dasa true save
-             $gam print users query "gha.jid=$JID" | $gam csv - gam delete user ~primaryEmail  || if [ $? != 50 ]; then exit $?; fi # expect a 50 return code (vault hold on user)
-             $gam delete contacts emailmatchpattern "^${newbase}@example.com$"
-             $gam print mobile
-             $gam print devices
-             $gam print browsers
-             $gam print cros allfields orderby serialnumber
-             $gam show crostelemetry storagepercentonly
-             $gam report usageparameters customer
-             $gam report usage customer parameters gmail:num_emails_sent,accounts:num_1day_logins
-             $gam report customer todrive tdnobrowser
-             #$gam report users fields accounts:is_less_secure_apps_access_allowed,gmail:last_imap_time,gmail:last_pop_time filters "accounts:last_login_time>2019-01-01T00:00:00.000Z" todrive tdnobrowser
-             $gam report users todrive tdnobrowser
-             $gam report admin start -3d todrive tdnobrowser
-             $gam print devices nopersonaldevices nodeviceusers filter "serial:$JID$JID$JID$JID-" | $gam csv - gam delete device id ~name
-             $gam config enable_dasa false save
-             $gam print userinvitations
-             $gam print userinvitations | $gam csv - gam send userinvitation ~name
-             $gam config enable_dasa false save
-             $gam create caalevel "zzz_${newbase}" basic condition ipsubnetworks 1.1.1.1/32,2.2.2.2/32 endcondition
-             $gam print caalevels
-             $gam delete caalevel "zzz_${newbase}"
-             $gam user $gam_user add drivefile localfile gam.py parentid "${driveid}"
-             $gam user $gam_user update shareddrive "${driveid}" ou "${newou}"
-             $gam user $gam_user show shareddrives asadmin
-             $gam user $gam_user update shareddrive "${driveid}" ou "aaaGithub Actions" # so we can delete our OU...
-             $gam user $gam_user delete shareddrive "${driveid}" nukefromorbit
-             echo "printer model count:"
-             ssoprofile=$($gam create inboundssoprofile name "El Goog ${newbase}" loginurl https://www.google.com logouturl https://www.google.com changepasswordurl https://www.google.com entityid ElGoog return_name_only)
-             $gam create inboundssocredential profile "id:${ssoprofile}" generate_key
-             #$gam create inboundssoassignment profile "id:${ssoprofile}" orgunit "${newou}" mode SAML_SSO
-             #$gam delete inboundssoassignment "orgunit:${newou}"
-             $gam delete inboundssoprofile "id:${ssoprofile}"
-             $gam print printermodels | wc -l
-             $gam print printers
-             printerid=$($gam create printer displayname "${newbase}" uri ipp://localhost:631 driverless description "made by $(gam_user)" ou "${newou}" nodetails | awk '{print substr($2, 1, length($2)-1)}')
-             $gam info printer "$printerid"
-             $gam delete printer "$printerid"
-             $gam delete ou "${newou}"
-
-      - name: Archive production artifacts
-        uses: actions/upload-artifact@v3
-        if: (github.event_name == 'push' || github.event_name == 'schedule') && matrix.goal != 'test'
-        with:
-          name: gam-binaries
-          path: |
-            src/*.tar.xz
-            src/*.zip
-            src/*.msi
+          echo "Creating OrgUnit ${newou}"
+          $gam create ou "${newou}"
+          export GAM_THREADS=5
+          echo email > sample.csv;
+          for i in {1..10}; do
+            echo "${newbase}-bulkuser-$i" >> sample.csv;
+          done
+          driveid=$($gam user $gam_user add shareddrive "${newbase}" returnidonly)
+          echo "Created shared drive ${driveid}"
+          $gam create user $newuser firstname GHA lastname $JID displayname "Github Actions ${JID}" password random ou "${newou}" recoveryphone 12125121110 recoveryemail jay0lee@gmail.com gha.jid $JID languages en+,en-GB-
+          $gam user $newuser update photo https://dummyimage.com/400x600/000/fff
+          $gam user $newuser get photo
+          $gam user $newuser delete photo
+          $gam create alias $newalias user $newuser
+          $gam create group $newgroup name "GHA $JID group" description "This is a description" isarchived true
+          $gam user $gam_user sendemail recipient $newuser subject "test message $newbase" message "GHA test message"
+          $gam user $gam_user sendemail recipient exchange@pdl.jaylee.us subject "test ${tstamp}" message "test message"
+          $gam config enable_dasa false save
+          $gam create contact firstname GHA lastname "$JID" email work "${newbase}@example.com" primary
+          $gam print contacts
+          $gam user $newuser add license workspaceenterpriseplus
+          $gam print privileges
+          $gam config enable_dasa true save
+          $gam update cigroup $newgroup security memberrestriction 'member.type == 1 || member.customer_id == groupCustomerId()'
+          $gam info cigroup $newgroup
+          $gam update group $newgroup add owner $gam_user
+          $gam update group $newgroup add member $newuser
+          $gam config enable_dasa false save
+          $gam create admin $newuser _GROUPS_EDITOR_ROLE CUSTOMER # condition nonsecuritygroup
+          $gam create admin $newgroup _HELP_DESK_ADMIN_ROLE org_unit "${newou}"
+          $gam config csv_output_row_filter "assignedToUser:regex:${newuser}" print admins | $gam csv - gam delete admin "~roleAssignmentId"
+          $gam config csv_output_row_filter "assignedToGroup:regex:${newgroup}" print admins | $gam csv - gam delete admin "~roleAssignmentId"
+          $gam config enable_dasa false save
+          $gam csv sample.csv gam create user ~~email~~ firstname "GHA Bulk" lastname ~~email~~ gha.jid $JID ou "${newou}"
+          $gam csv sample.csv gam update user ~~email~~ recoveryphone 12125121110 recoveryemail jay0lee@gmail.com password random displayname "GitHub Actions Bulk ${JID}"
+          $gam csv sample.csv gam update user ~~email~~ recoveryphone "" recoveryemail ""
+          $gam config enable_dasa false save
+          $gam csv sample.csv gam user ~email add license workspaceenterpriseplus
+          $gam config enable_dasa true save
+          $gam csv sample.csv gam user $gam_user sendemail recipient ~~email~~@pdl.jaylee.us subject "test message $newbase" message "GHA test message"
+          $gam csv sample.csv gam update group $newgroup add member ~email
+          $gam info group $newgroup
+          $gam info cigroup $newgroup membertree
+          # confirm mailbox is provisoned before continuing
+          $gam user $newuser waitformailbox
+          $gam user $newuser imap on
+          $gam user $newuser show imap
+          $gam user $newuser show delegates
+          #$gam user $newuser add contactdelegate "${newbase}-bulkuser-1"
+          #$gam user $newuser print contactdelegates
+          export biohazard=$(echo -e '\xe2\x98\xa3')
+          $gam user $newuser label "$biohazard unicode biohazard $biohazard"
+          $gam user $newuser show labels
+          $gam user $newuser show labels > labels.txt
+          $gam user $gam_user importemail subject "GHA import $newbase" message "This is a test import" labels IMPORTANT,UNREAD,INBOX,STARRED
+          $gam user $gam_user insertemail subject "GHA insert $newbase" file gam.py labels INBOX,UNREAD # yep body is gam code
+          $gam user $gam_user sendemail subject "GHA send $gam_user $newbase" file gam.py recipient admin@pdl.jaylee.us
+          $gam user $gam_user draftemail subject "GHA draft $newbase" message "Draft message test"
+          $gam csvfile sample.csv:email waitformailbox
+          $gam user $newuser delegate to "${newbase}-bulkuser-1" || if [ $? != 50 ]; then exit $?; fi # expect a 50 return code (delegation failed)
+          $gam users "$gam_user $newbase-bulkuser-1 $newbase-bulkuser-2 $newbase-bulkuser-3" delete messages query in:anywhere maxtodelete 99999 doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
+          $gam users "$newbase-bulkuser-4 $newbase-bulkuser-5 $newbase-bulkuser-6" trash messages query in:anywhere maxtotrash 99999 doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
+          $gam users "$newbase-bulkuser-7 $newbase-bulkuser-8 $newbase-bulkuser-9" modify messages query in:anywhere maxtomodify 99999 addlabel IMPORTANT addlabel STARRED doit || if [ $? != 60 ]; then exit $?; fi # expect a 60 return code (no messages)
+          $gam user $newuser delete label --ALL_LABELS--
+          $gam config csv_output_row_filter "name:regex:gha-test-${JID}" print features | $gam csv - gam delete feature ~name
+          $gam create feature name VC-$newbase
+          $gam create feature name Whiteboard-$newbase
+          $gam create building "My Building - $newbase" id $newbuilding floors 1,2,3,4,5,6,7,8,9,10,11,12,14,15 description "No 13th floor here..."
+          $gam create resource $newresource "Resource Calendar $tstamp" capacity 25 features Whiteboard-$newbase,VC-$newbase building $newbuilding floor 15 type Room
+          $gam info resource $newresource
+          $gam user $newuser add drivefile drivefilename "TPS Reports" mimetype gfolder
+          $gam user $newuser show filelist
+          $gam calendar $gam_user printacl | $gam csv - gam calendar $gam_user delete ~id # clear ACLs
+          $gam calendar $gam_user add read domain
+          $gam calendar $gam_user add freebusy default
+          $gam calendar $gam_user add editor $newuser
+          $gam calendar $gam_user showacl
+          $gam calendar $gam_user printacl | $gam csv - gam calendar $gam_user delete ~id
+          $gam calendar $gam_user addevent summary "GHA test event" start +1h end +2h attendee $newgroup hangoutsmeet guestscanmodify true sendupdates all
+          $gam calendar $gam_user printevents after -0d
+          $gam config enable_dasa false save
+          matterid=uid:$($gam create vaultmatter name "GHA matter $newbase" description "test matter" collaborators $newuser returnidonly)
+          $gam create vaulthold matter $matterid name "GHA hold $newbase" corpus mail accounts $newuser
+          $gam print vaultmatters matterstate open
+          $gam print vaultholds matter $matterid
+          $gam print vaultcount matter $matterid corpus mail everyone todrive tdnobrowser
+          $gam create vaultexport matter $matterid name "GHA export $newbase" corpus mail accounts $newuser
+          $gam print exports matter $matterid | $gam csv - gam info export $matterid id:~~id~~
+          $gam config enable_dasa true save
+          $gam csv sample.csv gam user ~email add calendar id:$newresource
+          $gam delete resource $newresource
+          $gam delete feature Whiteboard-$newbase
+          $gam delete feature VC-$newbase
+          $gam delete building $newbuilding
+          $gam delete group $newgroup
+          $gam config enable_dasa false save
+          echo start
+          $gam user $newuser delete license workspaceenterpriseplus
+          echo finish
+          $gam config enable_dasa true save
+          $gam whatis $newuser || if [ $? != 20 ]; then exit $?; fi # expect a 20 return code (is a user)
+          $gam user $gam_user show tokens
+          $gam config enable_dasa false save
+          download_dir="${RUNNER_TEMP}/TEMP_DELETE_ME"
+          mkdir -v "$download_dir"
+          $gam print exports matter $matterid | $gam csv - gam download export $matterid id:~~id~~ targetfolder "$download_dir"
+          rm -rvf "$download_dir"
+          $gam delete hold "GHA hold $newbase" matter $matterid
+          $gam update matter $matterid action close
+          $gam update matter $matterid action delete
+          # shakes off vault hold on user so we can delete
+          $gam print users query "email:${newuser}" orgunitpath | $gam csv - gam update user ~primaryEmail ou ~orgUnitPath
+          $gam user $newuser show holds || if [ $? != 55 ]; then exit $?; fi # expect a 55 return code
+          export sn="$JID$JID$JID$JID-$(openssl rand -base64 32 | sed 's/[^a-zA-Z0-9]//g')"
+          $gam create device serialnumber $sn devicetype android
+          $gam config enable_dasa true save
+          $gam print users query "gha.jid=$JID" | $gam csv - gam delete user ~primaryEmail  || if [ $? != 50 ]; then exit $?; fi # expect a 50 return code (vault hold on user)
+          $gam delete contacts emailmatchpattern "^${newbase}@example.com$"
+          $gam print mobile
+          $gam print devices
+          $gam print browsers
+          $gam print cros allfields orderby serialnumber
+          $gam show crostelemetry storagepercentonly
+          $gam report usageparameters customer
+          $gam report usage customer parameters gmail:num_emails_sent,accounts:num_1day_logins
+          $gam report customer todrive tdnobrowser
+          #$gam report users fields accounts:is_less_secure_apps_access_allowed,gmail:last_imap_time,gmail:last_pop_time filters "accounts:last_login_time>2019-01-01T00:00:00.000Z" todrive tdnobrowser
+          $gam report users todrive tdnobrowser
+          $gam report admin start -3d todrive tdnobrowser
+          $gam print devices nopersonaldevices nodeviceusers filter "serial:$JID$JID$JID$JID-" | $gam csv - gam delete device id ~name
+          $gam config enable_dasa false save
+          $gam print userinvitations
+          $gam print userinvitations | $gam csv - gam send userinvitation ~name
+          $gam config enable_dasa false save
+          $gam create caalevel "zzz_${newbase}" basic condition ipsubnetworks 1.1.1.1/32,2.2.2.2/32 endcondition
+          $gam print caalevels
+          $gam delete caalevel "zzz_${newbase}"
+          $gam user $gam_user add drivefile localfile gam.py parentid "${driveid}"
+          $gam user $gam_user update shareddrive "${driveid}" ou "${newou}"
+          $gam user $gam_user show shareddrives asadmin
+          $gam user $gam_user update shareddrive "${driveid}" ou "aaaGithub Actions" # so we can delete our OU...
+          $gam user $gam_user delete shareddrive "${driveid}" nukefromorbit
+          echo "printer model count:"
+          ssoprofile=$($gam create inboundssoprofile name "El Goog ${newbase}" loginurl https://www.google.com logouturl https://www.google.com changepasswordurl https://www.google.com entityid ElGoog return_name_only)
+          $gam create inboundssocredential profile "id:${ssoprofile}" generate_key
+          #$gam create inboundssoassignment profile "id:${ssoprofile}" orgunit "${newou}" mode SAML_SSO
+          #$gam delete inboundssoassignment "orgunit:${newou}"
+          $gam delete inboundssoprofile "id:${ssoprofile}"
+          $gam print printermodels | wc -l
+          $gam print printers
+          printerid=$($gam create printer displayname "${newbase}" uri ipp://localhost:631 driverless description "made by $(gam_user)" ou "${newou}" nodetails | awk '{print substr($2, 1, length($2)-1)}')
+          $gam info printer "$printerid"
+          $gam delete printer "$printerid"
+          $gam delete ou "${newou}"
 
       - name: Tar Cache archive
         if: matrix.goal == 'build' && steps.cache-python-ssl.outputs.cache-hit != 'true'
         working-directory: ${{ github.workspace }}
         run: |
-          tar cJvvf bin.tar.xz bin/
+          if [[ "${RUNNER_OS}" == "Windows" ]]; then
+            tar_folders="src/cpython/ bin/ssl"
+          else
+            tar_folders="bin/"
+          fi
+          tar cJvvf cache.tar.xz $tar_folders
+
+      - name: Archive production artifacts
+        uses: actions/upload-artifact@v4
+        if: (github.event_name == 'push' || github.event_name == 'schedule') && matrix.goal != 'test'
+        with:
+          name: gam-binaries-${{ env.GAMOS }}-${{ env.arch }}-${{ matrix.jid }}
+          path: |
+            src/*.tar.xz
+            src/*.zip
+            src/*.msi
+
+  merge:
+    if: (github.event_name == 'push' || github.event_name == 'schedule')
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          name: gam-binaries
+          pattern: gam-binaries-*
+
+#      - name: Delete Artifacts
+#        uses: geekyeggo/delete-artifact@v4
+#        with:
+#          name: gam-binaries-*
 
   publish:
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
-    needs: build
+    needs: merge
     permissions:
       contents: write
       packages: write
@@ -859,16 +892,16 @@ jobs:
 
     steps:
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           persist-credentials: false
           fetch-depth: 0
 
       - name: Download artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
 
       - name: VirusTotal Scan
-        uses: crazy-max/ghaction-virustotal@v3
+        uses: crazy-max/ghaction-virustotal@v4
         with:
           vt_api_key: ${{ secrets.VT_API_KEY }}
           files: |

docs/Aliases.md

@@ -85,7 +85,7 @@ gam <UserTypeEntity> delete aliases
 ```
 
 ## Display aliases
-Display a specific alise.
+Display a specific alias.
 ```
 gam info alias|aliases <EmailAddressEntity>
 ```

docs/Bulk-Processing.md

@@ -41,6 +41,7 @@ Batch files can contain the following types of lines:
   * GAM waits for all running GAM commands to complete
   * GAM prints \<String\> and waits for the user to press any key
   * GAM continues
+* sleep \<Integer\> - Batch processing will suspend for \<Integer\> seconds before the next command line is processed
 * print \<String\> - Print \<String\> on stderr
 * set \<KeywordString\> \<ValueString\>
   * Subsequent lines will have %\<KeywordString\>% replaced with \<ValueString\>
@@ -71,13 +72,13 @@ gam redirect stdout ./NewStudents.out redirect stderr ./NewStudents.err tbatch N
 gam csv <FileName>|-|(gsheet <UserGoogleSheet>)|(gdoc <UserGoogleDoc>) [charset <Charset>] [warnifnodata]
         [columndelimiter <Character>] [noescapechar <Boolean>] [quotechar <Character>] [fields <FieldNameList>]
         (matchfield|skipfield <FieldName> <RegularExpression>)* [showcmds [<Boolean>]]
-        [maxrows <Integer>]
+        [skiprows <Integer>] [maxrows <Integer>]
         gam <GAMArgumentList>
 
 gam loop <FileName>|-|(gsheet <UserGoogleSheet>)|(gdoc <UserGoogleDoc>) [charset <Charset>] [warnifnodata]
         [columndelimiter <Character>] [noescapechar <Boolean>] [quotechar <Character>] [fields <FieldNameList>]
         (matchfield|skipfield <FieldName> <RegularExpression>)* [showcmds [<Boolean>]]
-        [maxrows <Integer>]
+        [skiprows <Integer>] [maxrows <Integer>]
         gam <GAMArgumentList>
 ```
 * `gam csv` - Use parallel processing
@@ -92,7 +93,10 @@ gam loop <FileName>|-|(gsheet <UserGoogleSheet>)|(gdoc <UserGoogleDoc>) [charset
 * `fields <FieldNameList>` - The column headings of a CSV file that does not contain column headings.
 * `(matchfield|skipfield <FieldName> <RegularExpression>)*` - The criteria to select rows from the CSV file; can be used multiple times; if not specified, all rows are selected
 * `showcmds` - Write `timestamp,command number/number of commands,command` to stderr when each command starts; write `timestamp, command number/numberof commands,complete` to stderr when command completes
-* `maxrows <Integer>` - Limit the number of filtered rows processed from the CSV file/Google Sheet.
+* `skiprows <Integer>` - Skip filtered rows from the CSV file/Google Sheet.
+  * `skiprows 0` - All rows are processed, this is the default
+  * `skiprows N` - The first N filtered rows are skipped
+* `maxrows <Integer>` - Limit the number of filtered rows processed from the CSV file/Google Sheet after any skipped rows.
   * `maxrows 0` - All rows are processed, this is the default
   * `maxrows N` - N filtered rows are processed
 

docs/ChromeOS-Devices.md

@@ -695,6 +695,23 @@ gam print cros
           (cros_ous <OrgUnitList>)|(cros_ous_and_children <OrgUnitList>)]]
         showitemcountonly
 ```
+Example
+```
+$ gam print cros query "sync:..2020-01-01" showitemcountonly
+Getting all CrOS Devices that match query (sync:..2020-01-01) for /, may take some time on a large Organizational Unit...
+Got 77 CrOS Devices that matched query (sync:..2020-01-01) for /...
+Got 77 CrOS Devices that matched query (sync:..2020-01-01)
+77
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print cros query "sync:..2020-01-01" showitemcountonly)
+Windows PowerShell
+count = & gam print cros query "sync:..2020-01-01" showitemcountonly
+```
 
 ## Print ChromeOS device activity
 

docs/Classroom-Courses.md

@@ -441,6 +441,24 @@ gam print courses
         [owneremailmatchpattern <RegularExpression>]
         showitemcountonly
 ```
+Example
+```
+$ gam print courses states active showitemcountonly
+Getting all Courses that match query (Course State: ACTIVE), may take some time on a large Google Workspace Account...
+Got 268 Courses...
+Got 272 Courses...
+Got 272 Courses...
+272
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print courses states active showitemcountonly)
+Windows PowerShell
+count = & gam print courses states active showitemcountonly
+```
 
 ## Display course announcements
 ```

docs/Classroom-Invitations.md

@@ -3,9 +3,10 @@
 - [Notes](#notes)
 - [Definitions](#definitions)
 - [Create classroom invitations](#create-classroom-invitations)
-- [Accept classroom invitations](#accept-classroom-invitations)
-- [Delete classroom invitations](#delete-classroom-invitations)
+- [Accept classroom invitations by user](#accept-classroom-invitations-by-user)
+- [Delete classroom invitations by user](#delete-classroom-invitations-by-user)
 - [Display classroom invitations by user](#display-classroom-invitations-by-user)
+- [Delete classroom invitations by course](#delete-classroom-invitations-by-course)
 - [Display classroom invitations by course](#display-classroom-invitations-by-course)
 
 ## API documentation
@@ -24,8 +25,6 @@ Scope: https://www.googleapis.com/auth/classroom.rosters           , Checked: FA
 ```
 Follow the directions to authorize the Service Account scopes.
 
-The Classroom API does not support inviting users from outside your domain.
-
 ## Definitions
 ```
 <DomainName> ::= <String>(.<String>)+
@@ -49,12 +48,18 @@ The Classroom API does not support inviting users from outside your domain.
 Invite users to classes.
 ```
 gam <UserTypeEntity> create classroominvitation courses <CourseEntity> [role owner|student|teacher]
-        [adminaccess|asadmin] [csvformat] [todrive <ToDriveAttributes>*] [formatjson [quotechar <Character>]]
+        [adminaccess|asadmin]
+        [csv|csvformat] [todrive <ToDriveAttributes>*] [formatjson [quotechar <Character>]]
 ```
 If `role` is not specified, `student` will be used.
 
+You can only invite a co-teacher to be an owner of a course.
+
 By default, classroom invitations are issued by the owner of the course, the `adminaccess` option causes the invitations to be issued by the admin named in `oauth2.txt`.
 
+By default, when an invitation is created, GAM outputs details of the invitation as indented keywords and values.
+* `csv|csvformat [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]` - Output the details in CSV format.
+
 ### Example
 
 Suppose you have a CSV file CourseStudent.csv  with two columns: Course,Student.
@@ -66,11 +71,13 @@ This command will invite all students to their courses in parallel
 ```
 gam redirect stdout ./Invites.out multiprocess redirect stderr stdout multiprocess csv CourseStudent.csv gam user ~Student create classroominvitation role student course ~Course
 ```
-## Accept classroom invitations
-Accept classroom invitations for users. You can only invite a co-teacher to be an owner of a course.
+## Accept classroom invitations by user
+Accept classroom invitations for users.
 ```
 gam <UserTypeEntity> accept classroominvitation (ids <ClassroomInvitationIDEntity>)|([courses <CourseEntity>] [role all|owner|student|teacher])
 ```
+`<UserTypeEntity>` must specify users in your domain.
+
 By default, all invitations for the specified users will be accepted.
 
 Select specific invitations to accept:
@@ -81,11 +88,13 @@ Select courses and accept invitations for those courses.
 
 By default, invitations for all roles will be accepted; you can limit the acceptances to invitations of a specific role.
 
-## Delete classroom invitations
+## Delete classroom invitations by user
 Delete classroom invitations for users.
 ```
 gam <UserTypeEntity> delete classroominvitation (ids <ClassroomInvitationIDEntity>)|([courses <CourseEntity>] [role all|owner|student|teacher])
 ```
+`<UserTypeEntity>` must specify users in your domain.
+
 By default, all invitations for the specified users will be deleted.
 
 Select specific invitations to delete:
@@ -104,8 +113,23 @@ gam <UserTypeEntity> show classroominvitations [role all|owner|student|teacher]
 gam <UserTypeEntity> print classroominvitations [todrive <ToDriveAttributes>*] [role all|owner|student|teacher]
         [formatjson [quotechar <Character>]]
 ```
+`<UserTypeEntity>` must specify users in your domain.
+
 By default, invitations for all roles will be displayed; you can limit the display to invitations of a specific role.
 
+## Delete classroom invitations by course
+Delete classroom invitations for courses. This command must be used to delete non-domain member invitations.
+```
+gam delete classroominvitation courses <CourseEntity> (ids <ClassroomInvitationIDEntity>)|(role all|owner|student|teacher)
+```
+Select courses and delete invitations for those courses.
+* `courses <CourseEntity>` - Specify courses
+
+Select specific invitations to delete:
+* `ids <ClassroomInvitationIDEntity>` - Specify invitation IDs
+
+Select invitations to delete by role. By default, invitations for all roles will be deleted; you can limit the deletions to invitations of a specific role.
+
 ## Display classroom invitations by course
 ```
 gam show classroominvitations (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])

docs/Classroom-Membership.md

@@ -141,3 +141,26 @@ gam print course-participants
         [show all|students|teachers]
         showitemcountonly
 ```
+Example
+```
+$ gam print course-participants teacher asmith states active show students showitemcountonly
+Getting all Courses that match query (Teacher: asmith@domain.com, Course State: ACTIVE), may take some time on a large Google Workspace Account...
+Got 3 Courses...
+Getting Students for Course: 636981507234 (1/3)
+Got 30 Students...
+Got 43 Students...
+Getting Students for Course: 589346784341 (2/3)
+Got 22 Students...
+Getting Students for Course: 589345535881 (3/3)
+Got 23 Students...
+88
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print course-participants teacher asmith states active show students showitemcountonly)
+Windows PowerShell
+count = & gam print course-participants teacher asmith states active show students showitemcountonly
+```

docs/Cloud-Identity-Devices.md

@@ -235,6 +235,28 @@ gam print devices
         [all|company|personal|nocompanydevices|nopersonaldevices]
         showitemcountonly
 ```
+Example
+```
+$ gam print devices queries "'model:Mac'" showitemcountonly
+Getting all Devices that match query (model:Mac), may take some time on a large Google Workspace Account...
+Got 100 Devices...
+Got 200 Devices...
+Got 300 Devices...
+...
+Got 900 Devices...
+Got 995 Devices...
+Got 995 Devices...
+995
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print devices queries "'model:Mac'" showitemcountonly)
+Windows PowerShell
+count = & gam print devices queries "'model:Mac'" showitemcountonly
+```
 
 ## Approve or block device users
 Approve or block user profiles on a device.
@@ -304,6 +326,29 @@ gam print deviceusers [todrive <ToDriveAttribute>*]
         [(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime<String> <Time>)*]
         showitemcountonly
 ```
+Example
+```
+$ gam print deviceusers queries "'model:Mac'" showitemcountonly
+Getting all Device Users that match query (model:Mac), may take some time on a large Google Workspace Account...
+Got 20 Device Users...
+Got 40 Device Users...
+Got 60 Device Users...
+...
+Got 980 Device Users...
+Got 995 Device Users...
+Got 995 Device Users...
+995
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print deviceusers queries "'model:Mac'" showitemcountonly)
+Windows PowerShell
+count = & gam print deviceusers queries "'model:Mac'" showitemcountonly
+```
+
 
 ## Display device user client state
 ```

docs/Cloud-Identity-Groups.md

@@ -387,4 +387,19 @@ gam print cigroups
         [descriptionmatchpattern [not] <RegularExpression>]
         showitemcountonly
 ```
+Example
+```
+$ gam print cigroups showitemcountonly
+Getting all Cloud Identity Groups, may take some time on a large Google Workspace Account...
+Got 242 Cloud Identity Groups: td.current@domain.com - postmaster@domain.com
+242
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
 
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print cigroups showitemcountonly)
+Windows PowerShell
+count = & gam print cidgroups showitemcountonly
+```

docs/Domain-People-Contacts-Profiles.md

@@ -133,7 +133,7 @@ The `quotechar <Character>` option allows you to choose an alternate quote chara
 ## Display Domain Profiles
 ### Display as an indented list of keys and values.
 ```
-gam info people|domainprofiles <PeopleResourceNameEntity>
+gam info domainprofiles|people|peopleprofiles <PeopleResourceNameEntity>
         [allfields|(fields <PeopleFieldNameList>)]
         [formatjson]
 ```
@@ -143,7 +143,7 @@ By default, Gam displays the fields `names,emailaddresses`.
 By default, Gam displays the information as an indented list of keys and values.
 * `formatjson` - Display the fields in JSON format.
 ```
-gam show people|domainprofiles
+gam show domainprofiles|people|peopleprofiles
         [query <String>]
         [mergesources <PeopleMergeSourceName>]
         [allfields|(fields <PeopleFieldNameList>)]
@@ -163,7 +163,7 @@ By default, Gam displays the information as an indented list of keys and values.
 
 ### Display as a CSV file.
 ```
-gam print people|domainprofiles [todrive <ToDriveAttribute>*]
+gam print domainprofiles|people|peopleprofiles [todrive <ToDriveAttribute>*]
         [query <String>]
         [mergesources <PeopleMergeSourceName>]
         [allfields|(fields <PeopleFieldNameList>)]

docs/Find-File-Owner.md

@@ -48,10 +48,7 @@ The `quotechar <Character>` option allows you to choose an alternate quote chara
 ## Display File Ownership for Old files
 If the above commands fail, you can try to loop through all accounts, however this might take a long time if you are on a large Google Workspace Account.
 
-```
-gam config auto_batch_min 1 redirect csv - multiprocess redirect stderr null multiprocess all users print filelist select id <DriveFileID> fields id,name,owners.emailaddress norecursion showownedby any
-```
-Starting with version 6.07.26, this can be made more efficient by terminating processing after the owner is identified.
 ```
 gam config auto_batch_min 1 multiprocessexit rc=0 redirect csv - multiprocess redirect stderr null multiprocess all users print filelist select id <DriveFileID> fields id,name,owners.emailaddress norecursion showownedby any
+gam config auto_batch_min 1 multiprocessexit rc=0 redirect csv - multiprocess redirect stderr null multiprocess all users print filelist select name <DriveFileName> fields id,name,owners.emailaddress norecursion showownedby any
 ```

docs/GamUpdates.md

@@ -1,4 +1,3 @@
-
 # Update GAMADV-XTD3 to latest version
 Automatic update to the latest version on Linux/Mac OS/Google Cloud Shell/Raspberry Pi/ChromeOS:
 - Do not create project or authorizations, default path `$HOME/bin`
@@ -11,6 +10,257 @@ 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.70.01
+
+Added `gmail_cse_incert_dir` and `gmail_cse_inkey_dir` path variables to `gam.cfg` that provide
+default values for the `incertdir <FilePath>` and `inkeydir <FilePath>` options in `gam <UserTypeEntity> create csekeypair`.
+
+### 6.70.00
+
+Added support for Gmail Client Side Encryption.
+
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Gmail-CSE
+
+This is an initial, minimally tested release; proceed with care and report all issues.
+
+### 6.69.00
+
+Added `use_classroom_owner_access` Boolean variable to `gam.cfg` that controls how GAM gets
+classroom member information and removes students/teachers. Client access does not provide
+complete information about non-domain students/teachers.
+* `False` - Use client access; this is the default. Use if you don't have non-domain members in your courses.
+* `True` - Use service account access as the classroom owner. An extra API call is required per course to authenticate the owner; this will affect performance
+
+Added the following command which must be used to delete classroom invitations for non-domain students/teachers.
+```
+gam delete classroominvitation courses <CourseEntity> (ids <ClassroomInvitationIDEntity>)|(role all|owner|student|teacher)
+```
+You can obtain the classroom invitation IDs with these commands:
+```
+gam show classroominvitations (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
+        [role all|owner|student|teacher] [formatjson]
+gam print classroominvitations [todrive <ToDriveAttribute>*] (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
+        [role all|owner|student|teacher] [formatjson [quotechar <Character>]]
+```
+
+### 6.68.08
+
+Updated `gam <UserTypeEntity> print filelist|drivefileacls|shareddriveacls ... oneitemperrow` to print
+ACLs with multiple permission details on separate rows for each basic permission/permission detail combination.
+This case occurs when a member of a Shared Drive has access to a file and also has explicitly granted access to the same file.
+
+Added `pmtype member|file` to `<PermissionMatch>` that allows determining whether an ACL on a Shared Drive file was
+derived from membership or explicitly granted.
+
+### 6.68.07
+
+Updated `gam info user ... locations formatjson` to include the `buildingName` field in the
+`locations` entries. If `gam.cfg` contains `quick_info_user = true` or the `quick` option
+is included on the command line, add the option `buildingnames` to the command line.
+
+### 6.68.06
+
+Fixed bug in `gam <UserTypeEntity> copy drivefile <DriveFileID> ... mergewithparent` that incorrectly named
+the copied file with the name of the parent folder.
+
+Updated `gam <UserTypeEntity> copy|move drivefile` to avoid copying/moving the same file twice.
+
+### 6.68.05
+
+Updated `gam print groups ... ciallfields|(cifields <CIGroupFieldNameList>)` to account for an
+API shortcoming that failed to get all of the Cloud Identity fields.
+
+### 6.68.04
+
+Added option `skiprows <Integer>` to `gam csv|loop` that causes GAM to skip processing the first `<Integer>` filtered rows.
+
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Bulk-Processing#csv-files
+
+### 6.68.03
+
+Fixed bug in `gam <UserTypeEntity> create drivefileacl` that caused a trap.
+
+### 6.68.02
+
+Upgraded to Python 3.12.2 where possible.
+
+Added options `restricted|(audience <String>)` to `gam <UserTypeEntity> create|update chatspace` that
+sets the access options for the chat space. These options are in Developer Preview and will not be generally available.
+
+### 6.68.01
+
+Fixed `<PermissionMatch>` bug for real.
+
+### 6.68.00
+
+Fixed `<PermissionMatch>` bug introduced in 6.67.35 that caused a command error like the following or would
+not properly match `type|nottype <DriveFileACLType>` and `role|notrole <DriveFileACLRole>`.
+
+```
+ERROR: permission attribute allowfilediscovery/withlink not allowed with type {'a', 'y', 'e', 'o', 'n'}
+```
+
+My sincere apologies.
+
+### 6.67.39
+
+Added option `wait <Integer> <Integer>` to `gam create datatransfer` that causes GAM to wait
+for the transfer to complete. The first `<Integer>` must be in the range 5-60 and is the number
+of seconds between checks to see if the transfer has completed. The second `<Integer>` is the maximum
+number of checks to perform. By default, GAM does not wait for the transfer to complete.
+
+### 6.67.38
+
+Added option `tdnotify [<Boolean>]` to `<ToDriveAttribute>` that causes GAM to send notification
+emails to all `tdshare <EmailAddress>` users when the file is uploaded/updated.
+
+### 6.67.37
+
+Fixed bug in `gam <UserTypeEntity> show messages ... showattachments` to avoid a trap when `text/plain` attachments
+in character sets other than `UTF-8` are displayed.
+
+### 6.67.36
+
+Updated `gam batch <BatchContent>` and `gam tbatch <BatchContent>` commands to accept lines with the following form:
+```
+sleep <Integer>
+```
+Batch processing will suspend for `<Integer>` seconds before the next command line is processed.
+
+### 6.67.35
+
+Added the following options to `<PermissionMatch>` that allow more powerful matching.
+```
+nottype	<DriveFileACLType>
+typelist <DriveFileACLTypeList>
+nottypelist <DriveFileACLTypeList>
+rolelist <DriveFileACLRoleList>
+notrolelist <DriveFileACLRoleList>
+```
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Permission-Matches#define-a-match
+
+### 6.67.34
+
+Added option `movetoorgunitdelay <Integer>` to `gam <UserTypeEntity> create shareddrive <Name> ... ou|org|orgunit <OrgUnitItem>`.
+GAM creates the Shared Drive, verifies that it has been created and then tries to move it to `<OrgUnitItem>`. Google seems to
+require a delay or the following error is generated.
+```
+ERROR: 409: 409 - The operation was aborted.
+```
+`movetoorgunitdelay` defaults to 20 seconds which seems to work; `<Integer>` can range from 0 to 60.
+
+### 6.67.33
+
+Upgraded to OpenSSL 3.2.1 where possible.
+
+Fixed bug in `gam <UserTypeEntity> print shareddrives` where `role` was improperly displayed as `fileOrganizer`
+rather than `writer`.
+
+Added option `guiroles [<Boolean>]` to `gam <UserTypeEntity> info|print|show shareddrive` that maps
+the Drive API role names to the Google Drive GUI role names.
+```
+API: GUI
+commenter: Commenter
+fileOrganizer: Content manager
+organizer: Manager
+reader: Viewer
+writer: Contributor
+```
+
+### 6.67.32
+
+Updated `<ToDriveAttribute>` to allow multiple `tdshare <EmailAddress> commenter|reader|writer` options.
+
+Fixed bug in `gam <UserTypeEntity> print shareddrives` where `role` was improperly displayed as `unknown`
+rather than `reader` when `Allow viewers and commenters to download, print, and copy files` was unchecked for the Shared Drive.
+
+### 6.67.31
+
+Updated `gam <UserTypeEntity> claim|transfer ownership <DriveFileEntity>` to properly
+handle the case where `<DriveFileEntity>` referencess a Drive shortcut.
+
+### 6.67.30
+
+Fixed bug where the `fullpath` option in various commands was not converting the generic shared drive name `Drive` to the drive's actual name.
+
+### 6.67.29
+
+Added optional argument `owneraccess` to `gam courses <CourseEntity> remove teachers|students [owneracccess] <UserTypeEntity` and
+`gam course <CourseID> remove teacher|student [owneraccess] <EmailAddress>` in order to test a possible API change.
+
+Updated code to avoid a trap when `gam config auto_batch_min 1 csv file.csv gam ...` was entered.
+The `config auto_batch_min 1` is not appropriate in this context and will be ignored.
+
+### 6.67.28
+
+Improved handling of `Bad Request` error in `gam <UserTypeEntity> collect orphans`.
+
+### 6.67.27
+
+Updated `gam <UserTypeEntity> collect orphans` to handle the following error:
+```
+ERROR: 400: badRequest - Bad Request
+```
+
+### 6.67.26
+
+Fixed bug in `gam print vaultexports ... formatjson` that caused a trap.
+
+### 6.67.25
+
+Added option `owneraccess` to `gam info courses <CourseEntity>` and `gam info course <CourseID>` in order
+to test a possible API change.
+
+### 6.67.24
+
+Fixed bug that caused HTML password notification email messages to be displayed in raw form.
+
+### 6.67.23
+
+Use local copy of `googleapiclient` to remove static discovery documents to improve performance.
+
+### 6.67.22
+
+Added `permissionidlist <PermissionIDList>` to `<PermissionMatch>` that allows matching any permission ID in a list.
+
+Added option `exportlinkeddrivefiles <Boolean>` to `gam create vaultexport` that is used with `corpus mail`.
+
+### 6.67.21
+
+Updated `gam remove aliases <EmailAddress> user|group <EmailAddressEntity>` to give a more informative
+error message when the target/alias combination does not exist.
+```
+Old: User: testsimple@rdschool.org, User Alias: tsalias@rdschool.org, Remove Failed: Invalid Input: resource_id
+New: User: testsimple@rdschool.org, User Alias: tsalias@rdschool.org, Remove Failed: Does not exist
+```
+
+### 6.67.20
+
+Added option `onelicenseperrow|onelicenceperrow` to `gam print users ... licenses` that causes GAM to print
+a seperate user information row for each license a user is assigned. This makes processing
+the licenses in a script possible and allows better sorting in a CSV File.
+
+By default, all licenses for a user are displayed in a list on one row:
+```
+primaryEmail,LicensesCount,Licenses,LicensesDisplay
+user@domain.com,2,1010020020 1010330004,Google Workspace Enterprise Plus Google Voice Standard
+```
+With `onelicenseperrow|onelicenceperrow`, each license is on a separate row:
+```
+primaryEmail,License,LicenseDisplay
+user@domain.com,1010020020,Google Workspace Enterprise Plus
+user@domain.com 1010330004,Google Voice Standard
+```
+
+### 6.67.19
+
+Updated `gam create|update user ... notify` to encode the characters `<>&` in the password
+so that they display correctly when the notify message content is HTML.
+
+### 6.67.18
+
+Cleaned up `Getting/Got` messages for `gam print courses|course-participants`.
+
 ### 6.67.17
 
 Added option `showitemcountonly` to various commands that causes GAM to display the
@@ -21,7 +271,7 @@ item count on stdout; no CSV file is written.
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Classroom-Membership#display-course-membership-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/ChromeOS-Devices#display-cros-device-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-counts
-* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-counts
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-user-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Groups#display-group-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Mobile-Devices#display-mobile-device-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Organizational-Units#display-organizational-unit-counts

docs/Google-Data-Transfers.md

@@ -15,7 +15,7 @@
 <DataTransferService> ::=
         calendar|
         currents|
-        datastudio|"google data studio"|
+        datastudio|lookerstudio|"google data studio"|
         drive|gdrive|googledrive|"drive and docs"
 <DataTransferServiceList> ::= "<DataTransferService>(,<DataTransferService>)*"
 
@@ -37,6 +37,7 @@ gam create|add datatransfer|transfer <OldOwnerID> <DataTransferServiceList> <New
         [private|shared|all] [privacy_level private|shared|private,shared]
         [releaseresources [<Boolean>]]
         (<ParameterKey> <ParameterValue>)*
+        [wait <Integer> <Integer>]
 ```
 For`datastudio` and `drive`, there are options to control the privacy level of the files to be transferred.
 * `private` or `privacy_level private` - Transfer files that are not shared with anyone
@@ -54,6 +55,10 @@ As of 2020-06-10, background transfers only transfer future non-private events w
 
 The option `<ParameterKey> <ParameterValue>` is for future expansion.
 
+By default, GAM does not wait for the transfer to complete. The option `wait <Integer> <Integer>` causes GAM to wait
+for the transfer to complete. The first `<Integer>` must be in the range 5-60 and is the number
+of seconds between checks to see if the transfer has completed. The second `<Integer>` is the maximum number of checks to perform.
+
 ## Display transfers
 ```
 gam info datatransfer|transfer <TransferID>

docs/Groups.md

@@ -575,3 +575,20 @@ gam print groups
         [admincreatedmatch <Boolean>]
         showitemcountonly
 ```
+Example
+```
+$ gam print groups showitemcountonly
+Getting all Groups, may take some time on a large Google Workspace Account...
+Got 200 Groups: 1aparents@domain.com - students-genderfood@domain.com
+Got 238 Groups: students-worldculture@domain.com - xcarestaff@domain.com
+238
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print groups showitemcountonly)
+Windows PowerShell
+count = & gam print groups showitemcountonly
+```

docs/How-to-Upgrade-from-Standard-GAM.md

@@ -334,12 +334,12 @@ 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.17 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.70.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 MacOS Sonoma 14.2.1 x86_64
 Path: /Users/admin/bin/gamadv-xtd3
-Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 
 admin@server:/Users/admin/bin/gamadv-xtd3$ ./gam oauth create
 
@@ -1002,12 +1002,12 @@ 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.17 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.70.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 Windows-10-10.0.17134 AMD64
 Path: C:\GAMADV-XTD3
-Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: C:\GAMConfig\gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 
 C:\GAMADV-XTD3>gam oauth create
 

docs/List-Items.md

@@ -34,6 +34,7 @@
 <DeviceUserList> ::= "<DeviceUserID>(,<DeviceUserID>)*"
 <DomainNameList> ::= "<DomainName>(,<DomainName>)*"
 <DriveFileACLRoleList> ::= "<DriveFileACLRole>(,<DriveFileACLRole>)*"
+<DriveFileACLTypeList> ::= "<DriveFileACLType>(,<DriveFileACLType>)*"
 <DriveFileList> ::= "<DriveFileItem>(,<DriveFileItem>)*"
 <DriveFilePermissionList> ::= "<DriveFilePermission>(,<DriveFilePermission>)*"
 <DriveFilePermissionIDList> ::= "<DriveFilePermissionID>(,<DriveFilePermissionID>)*"

docs/Mobile-Devices.md

@@ -158,3 +158,20 @@ gam print mobile
         [(query <QueryMobile>)|(queries <QueryMobileList>) (querytime<String> <Time>)*]
         showitemcountonly
 ```
+Example
+```
+$ gam print mobile showitemcountonly
+Getting all Mobile Devices, may take some time on a large Google Workspace Account...
+Got 100 Mobile Devices...
+Got 115 Mobile Devices
+115
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print mobile showitemcountonly)
+Windows PowerShell
+count = & gam print mobile showitemcountonly
+```

docs/Organizational-Units.md

@@ -13,7 +13,7 @@
 - [Synchronize ChromeOS devices with an organizational unit](#synchronize-chromeos-devices-with-an-organizational-unit)
 - [Display organizational units](#display-organizational-units)
 - [Print organizational units](#print-organizational-units)
-- [Display orgamizational unit counts](#display-organizational-unit-counts)
+- [Display organizational unit counts](#display-organizational-unit-counts)
 - [Display indented organizational unit tree](#display-indented-organizational-unit-tree)
 - [Special case handling for large number of organizational units](#special-case-handling-for-large-number-of-organizational-units)
 
@@ -245,6 +245,22 @@ gam print orgs|ous
         [fromparent <OrgUnitItem>] [showparent [Boolean>]] [toplevelonly]
         showitemcountonly
 ```
+Example
+```
+$ gam print orgs showitemcountonly     
+Getting all Organizational Units, may take some time on a large Google Workspace Account...
+Got 98 Organizational Units
+98
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print orgs showitemcountonly)
+Windows PowerShell
+count = & gam print orgs showitemcountonly
+```
 
 ## Display indented organizational unit tree
 ```

docs/Other-Resources.md

@@ -13,3 +13,4 @@ Thank you.
 * Goldy Arora - https://www.goldyarora.com/license-notifier/
 * Paul Ogier (Taming.Tech) - GAMADV-XTD3 Tutorials https://www.youtube.com/watch?v=g9LDeyXQNLI&list=PL_dLiK09pJVhKJxZHNk9CHK0q5hkZ856w
 * Paul Ogier (Taming.Tech) - GAMADV-XTD3 Course on Udemy https://taming.tech/GAMCourse
+* Paul Ogier (Taming.Tech) - https://taming.tech/taming-gam-a-practical-guide-to-gam-and-gamadv-xtd3/

docs/Permission-Matches.md

@@ -18,7 +18,10 @@
         contributor|editor|writer|
         manager|organizer|owner|
         reader|viewer
+<DriveFileACLRoleList> ::= "<DriveFileACLRole>(,<DriveFileACLRole>)*"
+
 <DriveFileACLType> ::= anyone|domain|group|user
+<DriveFileACLTypeList> ::= "<DriveFileACLType>(,<DriveFileACLType>)*"
 
 <EmailAddress> ::= <String>@<DomainName>
 <EmailAddressList> ::= "<EmailAddress>(,<EmailAddress>)*"
@@ -31,13 +34,15 @@
 
 <PermissionMatch> ::=
         pm|permissionmatch [not]
-            [type <DriveFileACLType>] [role|notrole <DriveFileACLRole>]
+            [type|nottype <DriveFileACLType>] [role|notrole <DriveFileACLRole>]
+            [typelist|nottypelist <DriveFileACLTypeList>] [rolelist|notrolelist <DriveFileACLRoleList>]
             [allowfilediscovery|withlink <Boolean>]
             [emailaddress <RegularExpression>] [emailaddressList <EmailAddressList>]
+            [permissionidlist <PermissionIDList>
             [name|displayname <String>]
             [domain|notdomain <RegularExpression>] [domainlist|notdomainlist <DomainNameList>]
             [expirationstart <Time>] [expirationend <Time>]
-            [deleted <Boolean>] [inherited <Boolean>]
+            [deleted <Boolean>] [inherited <Boolean>] [pmtype member|file]
         em|endmatch
 <PermissionMatchMode> ::=
         pmm|permissionmatchmode or|and
@@ -71,12 +76,18 @@ In the `print/show drivefileacls` and `create/delete permissions` commands you c
 ## Define a Match
 * `pm|permissionmatch` - Start of permission match definition.
 * `not` - Negate the match.
-* `type <DriveFileACLType>` - The type of the grantee.
-* `role <DriveFileACLRole>` - The role granted by this permission.
-* `notrole <DriveFileACLRole>` - The role granted by this permission.
+* `type <DriveFileACLType>` - The type of the grantee must match.
+* `nottype <DriveFileACLType>` - The type of the grantee must not match.
+* `typelist <DriveFileACLTypeList>` - The type of the grantee must match any value in the list.
+* `nottypelist <DriveFileACLTypeList>` - The type of the grantee must not match any value in the list.
+* `role <DriveFileACLRole>` - The role granted by this permission must match.
+* `notrole <DriveFileACLRole>` - The role granted by this permission must not match.
+* `rolelist <DriveFileACLRoleList>` - The role granted by this permission must match any value in the list..
+* `notrolelist <DriveFileACLRoleList>` - The role granted by this permission must not match any value in the list..
 * `allowfilediscovery|withlink <Boolean>` - Whether a link is required or whether the file can be discovered through search.
 * `emailaddress <RegularExpression>` - For types user and group, the required email address.
 * `emailaddresslist <EmailAddressList>` - For types user and group, a list of required email addresses; any one of which must match.
+* `permissionidlist <PermissionIDListList>` - A list of required permission IDs; any one of which must match.
 * `name|displayname <RegularExpression>` - For types domain, user and group, the displayable name.
 * `domain <RegularExpression>` - For type domain, the required domain name. For types user and group, the required domain name in the email address.
 * `notdomain <RegularExpression>` - For type domain, any domain name that doesn't match. For types user and group, any domain name that doesn't match in the email address.
@@ -86,6 +97,7 @@ In the `print/show drivefileacls` and `create/delete permissions` commands you c
 * `expirationend <Time>` - For types user and group, will the permission expire before or on <Time>.
 * `deleted <Boolean>` - For types user and groups, has the user or group been deleted.
 * `inherited <Boolean>` - For Shared Drive files/folders, is the permission inherited
+* `pmtype member|file` - For Shared Drive files/folders, is the permission derived from  membership or explicitly granted.
 * `em|endmatch` - End of permission match definition
 
 ## File Selection Examples

docs/Reseller.md

@@ -1,6 +1,7 @@
 # Reseller
 - [API documentation](#api-documentation)
 - [Notes](#notes)
+- [Manage Multiple Domains](#manage-multiple-domains)
 - [Definitions](#definitions)
 - [Manage Resold Customers](#manage-resold-customers)
 - [Display Resold Customers](#display-resold-customers)
@@ -25,6 +26,11 @@ Prior to version 6.50.00, this is how the `seats <NumberOfSeats> <MaximumNumberO
 
 Now, you can still use the above option which has been corrected or you can specify `seats <Number>` which will be properly passed in the correct form to the API based on plan name.
 
+## Manage Multiple Domains
+Thanks to Duncan Isaksen-Loxton for a script to help manage multiple domains.
+
+* See: https://gist.github.com/65/b5e9cee9b5812b487b8ae3e8256e262b
+
 ## Definitions
 ```
 <CustomerID> ::= <String>

docs/Resources.md

@@ -253,6 +253,22 @@ gam print resources
         [query <String>]
         showitemcountonly
 ```
+Example
+```
+$ gam print resources showitemcountonly
+Getting all Resource Calendars, may take some time on a large Google Workspace Account...
+Got 32 Resource Calendars: Back 50 - Video Cameras Class Set
+32
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print resources showitemcountonly)
+Windows PowerShell
+count = & gam print resources showitemcountonly
+```
 
 ## Manage resource calendar ACLs
 These commands operate on a single resource calendar.

docs/Send-Email.md

@@ -241,7 +241,7 @@ Your HTML message will contain lines like this:
 <img src="cid:image2"/>
 ```
 
-Your command line will have: `embedimage file1.jpg image1` embedimage file2.jpg image2`
+Your command line will have: `embedimage file1.jpg image1 embedimage file2.jpg image2`
 
 ## Send an email from a user sendas
 You want to send an email from a user's sendas address.
@@ -312,7 +312,7 @@ Your HTML message will contain lines like this:
 <img src="cid:image2"/>
 ```
 
-Your command line will have: `embedimage file1.jpg image1` embedimage file2.jpg image2`
+Your command line will have: `embedimage file1.jpg image1 embedimage file2.jpg image2`
 
 ### Examples
 Send an email to a user's personal address notifying them of their new Google Workspace account;
@@ -376,7 +376,7 @@ Your HTML message will contain lines like this:
 <img src="cid:image2"/>
 ```
 
-Your command line will have: `embedimage file1.jpg image1` embedimage file2.jpg image2`
+Your command line will have: `embedimage file1.jpg image1 embedimage file2.jpg image2`
 
 ## Send an email to users
 ```
@@ -418,7 +418,7 @@ Your HTML message will contain lines like this:
 <img src="cid:image2"/>
 ```
 
-Your command line will have: `embedimage file1.jpg image1` embedimage file2.jpg image2`
+Your command line will have: `embedimage file1.jpg image1 embedimage file2.jpg image2`
 
 ## Example
 Send a message to a user, save the Message-ID so that a later reminder message can be sent

docs/Shared-Drives.md

@@ -68,6 +68,10 @@
 ```
 <JSONData> ::= (json [charset <Charset>] <String>) | (json file <FileName> [charset <Charset>]) |
 
+<OrgUnitID> ::= id:<String>
+<OrgUnitPath> ::= /|(/<String>)+
+<OrgUnitItem> ::= <OrgUnitID>|<OrgUnitPath>
+
 <DriveFileACLRole> ::=
         manager|organizer|owner|
         contentmanager|fileorganizer|

docs/Todrive.md

@@ -184,9 +184,10 @@ direct the uploaded file to a particular user and location and add a timestamp t
         (tdnobrowser [<Boolean>])|
         (tdnoemail [<Boolean>])|
         (tdnoescapechar [<Boolean>])|
+        (tdnotify [<Boolean>])|
         (tdparent (id:<DriveFolderID>)|<DriveFolderName>)|
         (tdretaintitle [<Boolean>])|
-        (tdshare <EmailAddress> commenter|reader|writer)|
+        (tdshare <EmailAddress> commenter|reader|writer)*|
         (tdsheet (id:<Number>)|<String>)|
         (tdsheettimestamp [<Boolean>] [tdsheettimeformat <String>])
         (tdsheettitle <String>)|
@@ -213,7 +214,7 @@ It is uploaded to the root folder of the admin user named in `oauth2.txt`.
 ## Create new file
 If `tdfileid <DriveFileID>` is not specified, a new file is created.
 * `tdparent` - An existing/writable parent folder for the uploaded file; if not specified, the `todrive_parent` value from gam.cfg is used; that value defaults to the root folder.
-* `tdshare <EmailAddress> commenter|reader|writer` - Share the new file with `<EmailAddress>` with the specified role. `<EmailAddress>` must be valid within your Google Workspace.
+* `tdshare <EmailAddress> commenter|reader|writer` - Share the new file with `<EmailAddress>` with the specified role. `<EmailAddress>` must be valid within your Google Workspace. You can specify multiple shares.
 
 ## File name, file description and sheet name
 * `tdtitle` - The title for the uploaded file, if not specified, the Gam default title is used.
@@ -236,6 +237,7 @@ If `tdfileid <DriveFileID>` is not specified, a new file is created.
 ## Open browser and send email
 * `tdnobrowser` - If False, a browser is opened to view the file uploaded to Google Drive; if not specified, the `todrive_nobrowser` value from gam.cfg is used.
 * `tdnoemail` - If False, an email is sent to `tduser` informing them of name and URL of the uploaded file; if not specified, the `todrive_noemail` value from gam.cfg is used.
+* `tdnotify` - If True, an email is sent to all `tdshare <EmailAddress>` users informing them of name and URL of the uploaded/updated file.
 
 ## Escape character
 * `tdnoescapechar <Boolean>` - Should `\` be ignored as an escape character; if not specified, the value of `todrive_no_escape_char` from `gam.cfg` will be used

docs/Users-Calendars-Events.md

@@ -713,12 +713,14 @@ The attendee changes are displayed but not processed unless `doit` is specified.
 
 ## Manage focus time events
 You can create and delete focus time events; they can not be updated.
-To update a working location event, delete the working location event and recreate it.
+To update a focus time event, delete the focus time event and recreate it.
 ```
 gam <UserTypeEntity> create focustime
         [chatstatus available|donotdisturb]|
         [declinemode none|all|new] [declinemessage <String>]|
-        (timerange <Time> <Time>)+
+        [summary <String>]
+        (timerange <Time> <Time>
+        (recurrence <RRULE, EXRULE, RDATE and EXDATE line>)*
 
 gam <UserTypeEntity> delete focustime
         (timerange <Time> <Time>)+
@@ -762,17 +764,20 @@ The `quotechar <Character>` option allows you to choose an alternate quote chara
 
 ## Manage out of office events
 You can create and delete out of office events; they can not be updated.
-To update a working location event, delete the working location event and recreate it.
+To update an out of office event, delete the out of office event and recreate it.
 ```
 gam <UserTypeEntity> create outofoffice
-        [declinemode none|all|new] [declinemessage <String>]|
-        (timerange <Time> <Time>)+
+        [declinemode none|all|new]
+        [declinemessage <String>]
+        [summary <String>]
+        (timerange <Time> <Time>
+        (recurrence <RRULE, EXRULE, RDATE and EXDATE line>)*
 
 gam <UserTypeEntity> delete outofoffice
         (timerange <Time> <Time>)+
 ```
 
-out of office events span a time range:
+Out of office events span a time range:
 * `timerange <Time> <Time>` - A time range, may span multiple days
 
 ## Display out of office events

docs/Users-Chat.md

@@ -82,6 +82,7 @@ Google requires that you have a Chat Bot configured in order to use the Chat API
 ```
 gam <UserTypeEntity> create chatspace
         [type <ChatSpaceType>]
+        [restricted|(audience <String>)]
         [externalusersallowed <Boolean>]
         [members <UserTypeEntity>]
         [displayname <String>]
@@ -117,20 +118,26 @@ By default, Gam displays the information about the created chatspace as an inden
 
 Use the `<ChatContent>` option to send an initial message to the created chatspace.
 
+The `restricted|audience` options are in Developer Preview and will not be generally available.
+
 By default, details about the chatmessage are displayed.
 * `returnidonly` - Display the chatmessage name only
 
 ### Update a chat space
 ```
 gam <UserTypeEntity> update chatspace <ChatSpace>
-        [type space]
-        [displayname <String>]
-        [description <String>] [guidelines <String>]
-        [history <Boolean>]
+        [restricted|(audience <String>)]|
+        ([displayname <String>]
+         [type space]
+         [description <String>] [guidelines|rules <String>]
+         [history <Boolean>])
         [formatjson]
 ```
 A groupchat space can be upgraded to a space by specifying `type space` and `displayname <String>`.
 
+The `restricted|audience` options can not be combined with options `displayname,type,description,guidelines,history`.
+They are in Developer Preview and will not be generally available.
+
 By default, Gam displays the information about the created chatspace as an indented list of keys and values.
 * `formatjson` - Display the fields in JSON format.
 

docs/Users-Drive-Files-Display.md

@@ -267,9 +267,10 @@
         <DriveOwnersSubfieldName>|
         parents|
         <DriveParentsSubfieldName>|
+        permissionids|
+        permissiondetails|
         permissions|
         <DrivePermissionsSubfieldName>|
-        permissionids|
         properties|
         quotabytesused|quotaused|
         resourcekey|
@@ -572,7 +573,7 @@ The `querytime<String> <Time>` value replaces the string `#querytime<String>#` i
 The characters following `querytime` can be any combination of lowercase letters and numbers. This is most useful in scripts
 where you can specify a relative date without having to change the script.
 
-For example, query for files last modified me than 5 years ago:
+For example, query for files last modified more than 5 years ago:
 ```
 querytime5years -5y query "modifiedTime<'#querytime5years#'"
 ```
@@ -1005,7 +1006,7 @@ gam <UserTypeEntity> print|show filelist [todrive <ToDriveAttribute>*]
         [excludetrashed]
         [maxfiles <Integer>] [nodataheaders <String>]
         [countsonly [summary none|only|plus] [summaryuser <String>]
-	            [showsource] [showsize] [showmimetypesize]] [countsrowfilter]
+                    [showsource] [showsize] [showmimetypesize]] [countsrowfilter]
         [filepath|fullpath [pathdelimiter <Character>] [addpathstojson] [showdepth]] [buildtree]
         [allfields|<DriveFieldName>*|(fields <DriveFieldNameList>)]
         [showdrivename] [showshareddrivepermissions]

docs/Users-Gmail-CSE.md

@@ -0,0 +1,197 @@
+# Users - Gmail - Client Side Encryption
+- [API documentation](#api-documentation)
+- [Notes](#notes)
+- [Definitions](#definitions)
+- [Create Gmail CSE Identity](#create-gmail-cse-identity)
+- [Update Gmail CSE Identity](#update-gmail-cse-identity)
+- [Delete Gmail CSE Identity](#delete-gmail-cse-identity)
+- [Display Gmail CSE Identities](#display-gmail-cse-identities)
+- [Create Gmail CSE Key Pair](#create-gmail-cse-key-pair)
+- [Action Gmail CSE Key Pairs](#action-gmail-cse-key-pairs)
+- [Display Gmail CSE Key Pairs](#display-gmail-cse-key-pairs)
+
+## API documentation
+* https://developers.google.com/gmail/api/reference/rest/v1/users.settings.cse.identities
+* https://developers.google.com/gmail/api/reference/rest/v1/users.settings.cse.keypairs
+
+## Notes
+
+This is an initial, minimally tested release; proceed with care and report all issues.
+
+Setting up Client Side Encryption is not for the faint of heart; here is a start.
+* https://support.google.com/a/answer/10741897?hl=en&ref_topic=10742486&sjid=10342493441460488213-NA
+
+Do I personally understand what's going on here? No, I just added the API calls to GAM.
+
+Two sets of files are required for Gmail CSE, these two variables in `gam.cfg` control where GAM looks for these files.
+You must edit `gam.cfg` to set the paths you currently use.
+```
+gmail_cse_incert_dir
+        Directory for the S/MIME certificate files used by Gmail Client Side Encryption.
+        Default: Blank
+gmail_cse_inkey_dir
+        Directory for the Key Access Control List (KACL) wrapped private key data files used by Gmail Client Side Encryption.
+        Default: Blank
+```
+
+## Definitions
+* [`<UserTypeEntity>`](Collections-of-Users)
+
+```
+<DomainName> ::= <String>(.<String>)+
+<EmailAddress> ::= <String>@<DomainName>
+<FilePath> ::= <String>
+<Password> ::= <String>
+<KeyPairID> ::= <String>
+```
+## Create Gmail CSE Identity
+Creates and configures a client-side encryption identity that's authorized to send mail from the user account.
+Google publishes the S/MIME certificate to a shared domain-wide directory so that people within a Google Workspace organization can encrypt and send mail to the identity.
+
+```
+gam <UserTypeEntity> create cseidentity <KeyPairID> [kpemail <EmailAddress>]
+        [formatjson]
+```
+If `kpemail <EmailAddress>` is not specified, the user's primary email address is used for the identity.
+
+By default, Gam displays the identity as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+## Update Gmail CSE Identity
+Associates a different key pair with an existing client-side encryption identity. The updated key pair must validate against Google's S/MIME certificate profiles.
+```
+gam <UserTypeEntity> update cseidentity <KeyPairID> [kpemail <EmailAddress>]
+        [formatjson]
+```
+If `kpemail <EmailAddress>` is not specified, the key pair for the user's primary email address is identity updated.
+
+By default, Gam displays the identity as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+## Delete Gmail CSE Identity
+Deletes a client-side encryption identity. The authenticated user can no longer use the identity to send encrypted messages.
+You cannot restore the identity after you delete it. Instead, use the `create cseidentity`  to create another identity with the same configuration.
+
+```
+gam <UserTypeEntity> delete cseidentity [kpemail <EmailAddress>]
+```
+If `kpemail <EmailAddress>` is not specified, the identity for the user's primary email address is deleted.
+
+## Display Gmail CSE Identities
+### Display a client-side encryption identity configuration.
+```
+gam <UserTypeEntity> info cseidentity [kpemail <EmailAddress>]
+        [formatjson]
+```
+If `kpemail <EmailAddress>` is not specified, the user's primary email address is used for the identity.
+
+
+### Display all of the client-side encrypted identities for an authenticated user.
+```
+gam <UserTypeEntity> show cseidentities
+        [formatjson]
+```
+By default, Gam displays the identity as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+```
+gam <UserTypeEntity> print cseidentities [todrive <ToDriveAttribute>*]
+        [formatjson [quotechar <Character>]]
+```
+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.
+
+By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain
+the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
+The `quotechar <Character>` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
+`quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used.
+
+## Create Gmail CSE Key Pair
+Create a CSE Key Pair for the primary address of a user.
+```
+gam <UserTypeEntity> create csekeypair
+        [incertdir <FilePath>] [inkeydir <FilePath>]
+        [addidentity [<Boolean>]] [kpemail <EmailAddress>]
+        [formatjson|returnidonly]
+```
+* The S/MIME certificate files for the users are in the `incertdir <FilePath>` folder/directory.
+* If this option is not specified, the directory is taken from `gam.cfg/gmail_cse_incert_dir`.
+* The files must be named `user@domain.com.p7pem`.
+* The certificate contains the public key and its certificate chain. The chain must be in PKCS#7 format and use PEM encoding and ASCII armor.
+
+* The Key Access Control List (KACL) wrapped private key data files are in the `inkeydir <FilePath>` folder/directory.
+* If this option is not specified, the directory is taken from `gam.cfg/gmail_cse_inkey_dir`.
+* The files must be named `user@domain.com.wrap`.
+* The files are in JSON format with two keys:
+    * `kacls_url` - The URI of the key access control list service that manages the private key.
+    * `wrapped_private_key` - Opaque data generated and used by the key access control list service.
+
+By default, Gam displays the new key pair as an indented list of keys and values; the following options cause the output to be displayed in alternate forms.
+* `formatjson` - Display the fields in JSON format.
+* `returnidonly` - Display just the new `<KeyPairID>`.
+
+If 'addidentity` or `addidentity true` is specified, a client-side encryption identity is created with the new key pair.
+If `kpemail <EmailAddress>` is not specified, the user's primary email address is used for the identity.
+
+By default, Gam displays the identity as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+* `returnidonly` - Display just the new `<KeyPairID>-<EmailAddress>`.
+
+
+## Action Gmail CSE Key Pairs
+### Disable
+Turns off a client-side encryption key pair. The authenticated user can no longer use the key pair to decrypt incoming CSE message texts or sign outgoing CSE mail.
+```
+gam <UserTypeEntity> disable csekeypair <KeyPairID>
+        [formatjson]
+```
+By default, Gam displays the disabled key pair as an indented list of keys and values; the following option causes the output to be displayed in alternate forms.
+* `formatjson` - Display the fields in JSON format.
+
+### Enable
+Turn on a client-side encryption key pair that was turned off. The key pair becomes active again for any associated client-side encryption identities.
+```
+gam <UserTypeEntity> ensable csekeypair <KeyPairID>
+        [formatjson]
+```
+By default, Gam displays the enabled key pair as an indented list of keys and values; the following option causes the output to be displayed in alternate forms.
+* `formatjson` - Display the fields in JSON format.
+
+### Obliterate
+Delete a client-side encryption key pair permanently and immediately. You can only permanently delete key pairs that have been turned off for more than 30 days.
+To turn off a key pair, use `disable csekeypair`.
+```
+gam <UserTypeEntity> obliterate csekeypair <KeyPairID>
+```
+
+Gmail can't restore or decrypt any messages that were encrypted by an obliterated key. Authenticated users and Google Workspace administrators lose access to reading the encrypted messages.
+
+## Display Gmail CSE Key Pairs
+### Display an existing client-side encryption key pair.
+```
+gam <UserTypeEntity> info csekeypair <KeyPairID>
+        [formatjson]
+```
+By default, Gam displays the key pairs as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+
+### Display all client-side encryption key pairs for an authenticated user.
+```
+gam <UserTypeEntity> show csekeypairs
+        [formatjson]
+```
+By default, Gam displays the key pairs as an indented list of keys and values; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+```
+gam <UserTypeEntity> print csekeypairs [todrive <ToDriveAttribute>*]
+        [formatjson [quotechar <Character>]]
+```
+By default, Gam displays the key pairs as columns of fields; the following option causes the output to be in JSON format:
+* `formatjson` - Display the fields in JSON format.
+
+By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain
+the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
+The `quotechar <Character>` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
+`quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used.

docs/Users-Gmail-Delegates.md

@@ -10,7 +10,8 @@
 
 ## API documentation
 * https://developers.google.com/gmail/api/v1/reference/users/settings/delegates
-* https://support.google.com/a/answer/7223765?hl=en
+* https://support.google.com/a/answer/7223765
+* https://support.google.com/a/answer/11946994
 
 ## Definitions
 * [`<UserTypeEntity>`](Collections-of-Users)

docs/Users-Shared-Drives.md

@@ -69,6 +69,10 @@
 ```
 <JSONData> ::= (json [charset <Charset>] <String>) | (json file <FileName> [charset <Charset>]) |
 
+<OrgUnitID> ::= id:<String>
+<OrgUnitPath> ::= /|(/<String>)+
+<OrgUnitItem> ::= <OrgUnitID>|<OrgUnitPath>
+
 <DriveFileACLRole> ::=
         manager|organizer|owner|
         contentmanager|fileorganizer|
@@ -277,12 +281,15 @@ gam <UserTypeEntity> unhide teamdrive <SharedDriveEntity>
 ```
 gam <UserTypeEntity> show teamdriveinfo <SharedDriveEntity>
 gam <UserTypeEntity> info teamdrive <SharedDriveEntity>
-        [fields <SharedDriveFieldNameList>] [formatjson]
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>] [formatjson]
 gam <UserTypeEntity> show teamdriveinfo <SharedDriveEntity>
-        [fields <SharedDriveFieldNameList>] [formatjson]
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>] [formatjson]
 gam <UserTypeEntity> show teamdrives
         [matchname <RegularExpression>] (role|roles <SharedDriveACLRoleList>)*
-        [fields <SharedDriveFieldNameList>] [formatjson]
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>] [formatjson]
 ```
 By default, Gam displays all Teams Drives accessible by the user.
 * `matchname <RegularExpression>` - Display Shared Drives with names that match a pattern.
@@ -301,10 +308,20 @@ By default, Gam displays all Teams Drives accessible by the user.
 
 The Google Drive API does not list roles for Shared Drives so GAM generates a role from the capabilities:
 * `commenter - canComment: True, canEdit: False`
-* `fileOrganizer - canAddChildren: True, canManageMembers: False`
+* `reader - canComment: False, canEdit: False`
+* `writer - canEdit: True, canTrashChildren: False`
+* `fileOrganizer - canTrashChildren: True, canManageMembers: False`
 * `organizer - canManageMembers: True`
-* `reader - canCopy': True, canComment: False`
-* `writer - canEdit: True, canManageMembers: False`
+
+By default, the Drive API role names are displayed, use `guiroles` to display the Google Drive GUI role names.
+```
+API: GUI
+commenter: Commenter
+fileOrganizer: Content manager
+organizer: Manager
+reader: Viewer
+writer: Contributor
+```
 
 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.

docs/Users.md

@@ -980,7 +980,9 @@ gam print users [todrive <ToDriveAttribute>*]
         ([domain|domains <DomainNameEntity>] [(query <QueryUser>)|(queries <QueryUserList>)]
          [limittoou <OrgUnitItem>] [deleted_only|only_deleted])
         [orderby <UserOrderByFieldName> [ascending|descending]]
-        [groups|groupsincolumns] [license|licenses|licence|licences]
+        [groups|groupsincolumns]
+        [license|licenses|licence|licences]
+        [onelicenseperrow|onelicenceperrow]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username]
         [userview] [allfields|basic|full|(<UserFieldName>*|fields <UserFieldNameList>)]
@@ -1003,6 +1005,7 @@ gam print users [todrive <ToDriveAttribute>*] select <UserTypeEntity>
         [orderby <UserOrderByFieldName> [ascending|descending]]
         [groups|groupsincolumns]
         [license|licenses|licence|licences|licensebyuser|licensesbyuser|licencebyuser|licencesbyuser]
+        [onelicenseperrow|onelicenceperrow]
         [(products|product <ProductIDList>)|(skus|sku <SKUIDList>)]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username][schemas|custom all|<SchemaNameList>]
@@ -1014,6 +1017,7 @@ gam <UserTypeEntity> print users [todrive <ToDriveAttribute>*]
         [orderby <UserOrderByFieldName> [ascending|descending]]
         [groups|groupsincolumns]
         [license|licenses|licence|licences|licensebyuser|licensesbyuser|licencebyuser|licencesbyuser]
+        [onelicenseperrow|onelicenceperrow]
         [(products|product <ProductIDList>)|(skus|sku <SKUIDList>)]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username]
@@ -1058,6 +1062,17 @@ to limit the display of aliases to those that match `<RegularExpression>`.
 By default, the entries in lists of groups and licenses are separated by the `csv_output_field_delimiter` from `gam.cfg`.
 * `delimiter <Character>` - Separate list items with `<Character>`
 
+By default, all licenses for a user are displayed in a list on one row:
+```
+primaryEmail,LicensesCount,Licenses,LicensesDisplay
+user@domain.com,2,1010020020 1010330004,Google Workspace Enterprise Plus Google Voice Standard
+```
+With `onelicenseperrow|onelicenceperrow`, each license is on a separate row:
+```
+primaryEmail,License,LicenseDisplay
+user@domain.com,1010020020,Google Workspace Enterprise Plus
+user@domain.com 1010330004,Google Voice Standard
+```
 In the output, primaryEmail is the always the first column; these options control the sorting of the remaining columns.
 * `allfields|basic|full` - All other columns are sorted by name.
 * `sortheaders [true]` - All other columns are sorted by name.
@@ -1218,3 +1233,19 @@ gam print users
         [issuspended <Boolean>]
         showitemcountonly
 ```
+Example
+```
+$ gam print users query "orgUnitPath='/Students/Middle School'" showitemcountonly
+Getting all Users that match query (query="orgUnitPath='/Students/Middle School'"), may take some time on a large Google Workspace Account...
+Got 221 Users: aaron-first@domain.com - zoe-last@domain.com
+221
+```
+The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
+
+To retrieve the count with `showitemcountonly`:
+```
+Linux/MacOS
+count=$(gam print users query "orgUnitPath='/Students/Middle School'" showitemcountonly)
+Windows PowerShell
+count = & gam print users query "orgUnitPath='/Students/Middle School'" showitemcountonly
+```

docs/Vault-Takeout.md

@@ -219,7 +219,7 @@ gam create vaultexport|export matter <MatterItem> [name <String>] corpus calenda
         [includeshareddrives <Boolean>] [driveversiondate <Date>|<Time>] [includeaccessinfo <Boolean>]
         [includerooms <Boolean>]
         [excludedrafts <Boolean>] [format mbox|pst]
-        [showconfidentialmodecontent <Boolean>] [usenewexport <Boolean>]
+        [showconfidentialmodecontent <Boolean>] [usenewexport <Boolean>] [exportlinkeddrivefiles <Boolean>]
         [covereddata calllogs|textmessages|voicemails]
         [region any|europe|us] [showdetails|returnidonly]
 ```
@@ -305,6 +305,10 @@ For `corpus mail`, you can specify whether to use the new export system:
 * `usenewexport false` - Do not use the new export system
 * `usenewexport true` - Use the new export system
 
+For `corpus mail`, you can specify whether to enable exporting linked Drive files:
+* `exportlinkeddrivefiles false` - Do not export linked Drive files
+* `exportlinkeddrivefiles true` - Export linked Drive files
+
 See: https://support.google.com/vault/answer/4388708#new_gmail_export&zippy=%2Cfebruary-new-gmail-export-system-available
 
 For `corpus mail`, `corpus groups`, `corpus hangouts_chat`and `corpus voice`, you can specify the format of the exported data:

docs/Version-and-Help.md

@@ -1,44 +1,43 @@
-\
 # Version and Help
 
 Print the current version of Gam with details
 ```
 gam version
-GAMADV-XTD3 6.67.17 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.70.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 MacOS Sonoma 14.2.1 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
-Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 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.17 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.70.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 MacOS Sonoma 14.2.1 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
-Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 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.17 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
+GAMADV-XTD3 6.70.00 - https://github.com/taers232c/GAMADV-XTD3 - pythonsource
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 MacOS Sonoma 14.2.1 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
-Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 Time: 2023-06-02T21:10:00-07:00
 Your system time differs from admin.googleapis.com by less than 1 second
 OpenSSL 3.1.1 30 May 2023
 cryptography 41.0.1
-filelock 3.12.1
+filelock 3.12.2
 google-api-python-client 2.88.0
 google-auth-httplib2 0.1.0
 google-auth-oauthlib 1.0.0
@@ -65,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.67.17
+   Latest: 6.70.00
 echo $?
 1
 ```
@@ -73,7 +72,7 @@ echo $?
 Print the current version number without details
 ```
 gam version simple
-6.67.17
+6.70.00
 ```
 In Linux/MacOS you can do:
 ```
@@ -83,12 +82,12 @@ echo $VER
 Print the current version of Gam and address of this Wiki
 ```
 gam help
-GAM 6.67.17 - https://github.com/taers232c/GAMADV-XTD3
+GAM 6.70.00 - https://github.com/taers232c/GAMADV-XTD3
 Ross Scroggs <ross.scroggs@gmail.com>
-Python 3.12.1 64-bit final
+Python 3.12.2 64-bit final
 MacOS Sonoma 14.2.1 x86_64
 Path: /Users/Admin/bin/gamadv-xtd3
-Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain.com
+Config File: /Users/admin/GAMConfig/gam.cfg, Section: DEFAULT, customer_id: my_customer, domain: domain.com
 Time: 2023-06-02T21:10:00-07:00
 Help: Syntax in file /Users/Admin/bin/gamadv-xtd3/GamCommands.txt
 Help: Documentation is at https://github.com/taers232c/GAMADV-XTD3/wiki

docs/_Sidebar.md

@@ -141,6 +141,7 @@ Service Account Access
 * [Users - Drive - Shortcuts](Users-Drive-Shortcuts)
 * [Users - Drive - Transfer](Users-Drive-Transfer)
 * [Users - Forms](Users-Forms)
+* [Users - Gmail - Client Side Encryption](Users-Gmail-CSE)
 * [Users - Gmail - Delegates](Users-Gmail-Delegates)
 * [Users - Gmail - Filters](Users-Gmail-Filters)
 * [Users - Gmail - Forwarding](Users-Gmail-Forwarding)

docs/gam.cfg.md

@@ -150,7 +150,7 @@ csv_input_column_delimiter
         Default: ','
 csv_input_no_escape_char
         When reading a CSV file, should `\` be ignored as an escape character.
-	Set this to False if the input file data was written using `\` as an escape character.
+        Set this to False if the input file data was written using `\` as an escape character.
         Default: True
 csv_input_quote_char
         A one-character string used to quote fields containing special characters,
@@ -213,14 +213,14 @@ csv_output_header_force
         for inclusion in the CSV file written by a gam print command
         Default: ''
 csv_output_line_terminator
-p        Allowed values: cr, lf, crlf
+        Allowed values: cr, lf, crlf
         Designates character(s) used to terminate the lines of a CSV file.
         For Linux and Mac OS, this would typically be lf.
         For Windows, this would typically be crlf.
         Default: lf
 csv_output_no_escape_char
         When writing a CSV file, should `\` be ignored as an escape character.
-	Set this to True if the output file data is to be read by a non-Python program.
+        Set this to True if the output file data is to be read by a non-Python program.
         Default: False
 csv_output_quote_char
         A one-character string used to quote fields containing special characters,
@@ -322,6 +322,12 @@ extra_args
         Path to extra_args.txt
         Default: Blank
         Data file: extra_args.txt
+gmail_cse_incert_dir
+        Directory for the S/MIME certificate files used by Gmail Client Side Encryption.
+        Default: Blank
+gmail_cse_inkey_dir
+        Directory for the Key Access Control List (KACL) wrapped private key data files used by Gmail Client Side Encryption.
+        Default: Blank
 inter_batch_wait
         When processing items in batches, how many seconds should GAM wait between batches
         Default: 0
@@ -420,23 +426,23 @@ print_agu_domains
           gam print groups
           gam print|show group-members
           gam print users
-	This allows predefining the list of domains so they don't have to be specified in each command.
+        This allows predefining the list of domains so they don't have to be specified in each command.
         Default: Blank
 print_cros_ous
         A comma separated list of org unit that are used in these commands:
           gam print cros
           gam print crosactivity
-	This allows predefining the list of org units so they don't have to be specified in each command.
+        This allows predefining the list of org units so they don't have to be specified in each command.
         Default: Blank
 print_cros_ous_and_children
         A comma separated list of org unit names that are used in these commands:
           gam print cros
           gam print crosactivity
-	This allows predefining the list of org units so they don't have to be specified in each command.
+        This allows predefining the list of org units so they don't have to be specified in each command.
         Default: Blank
 process_wait_limit
-	When processing batch/CSV files, how long (in seconds) GAM should wait for all batch|csv processes to complete
-	after all have been started. If the limit is reached, GAM terminates any remaining processes.
+        When processing batch/CSV files, how long (in seconds) GAM should wait for all batch|csv processes to complete
+        after all have been started. If the limit is reached, GAM terminates any remaining processes.
         Default: 0: no limit
         Range: 0 - Unlimited
 quick_cros_move
@@ -573,6 +579,13 @@ update_cros_ou_with_id
         Set to true if you are getting the following error:
         `400: invalidInput - Invalid Input: Inconsistent Orgunit id and path in request`
         Default: False
+use_classroom_owner_access
+        How is classroom member information obtained and how are classroom members deleted.
+        Client access does not provide complete information about non-domain students/teachers.
+        When False, GAM uses client access to get classroom member information and to delete members
+        When True, GAM uses service account access as the classroom owner.
+        An extra API call is required per course to authenticate the owner
+        Default: False
 use_projectid_as_name
         When False, new projects have a default project name of "GAM Project"
         and a default app name of "GAM".

src/GamCommands.txt

@@ -611,7 +611,7 @@ If an item contains spaces, it should be surrounded by ".
         (tdnoescapechar [<Boolean>])|
         (tdparent (id:<DriveFolderID>)|<DriveFolderName>)|
         (tdretaintitle [<Boolean>])|
-        (tdshare <EmailAddress> commenter|reader|writer)|
+        (tdshare <EmailAddress> commenter|reader|writer)*|
         (tdsheet (id:<Number>)|<String>)|
         (tdsheettimestamp [<Boolean>] [tdsheettimeformat <String>])
         (tdsheettitle <String>)|
@@ -664,6 +664,7 @@ If an item contains spaces, it should be surrounded by ".
 <DeviceUserList> ::= "<DeviceUserID>(,<DeviceUserID>)*"
 <DomainNameList> ::= "<DomainName>(,<DomainName>)*"
 <DriveFileACLRoleList> ::= "<DriveFileACLRole>(,<DriveFileACLRole>)*"
+<DriveFileACLTypeList> ::= "<DriveFileACLType>(,<DriveFileACLType>)*"
 <DriveFileList> ::= "<DriveFileItem>(,<DriveFileItem>)*"
 <DriveFilePermissionList> ::= "<DriveFilePermission>(,<DriveFilePermission>)*"
 <DriveFilePermissionIDList> ::= "<DriveFilePermissionID>(,<DriveFilePermissionID>)*"
@@ -1287,13 +1288,13 @@ gam tbatch <BatchContent> [showcmds [<Boolean>]]
 gam csv <CSVLoopContent> [warnifnodata]
         [columndelimiter <Character>] [noescapechar <Boolean>] [quotechar <Character>] [fields <FieldNameList>]
         (matchfield|skipfield <FieldName> <RegularExpression>)* [showcmds [<Boolean>]]
-        [maxrows <Integer>]
+        [skiprows <Integer>] [maxrows <Integer>]
         gam <GAMArgumentList>
 
 gam loop <CSVLoopContent> [warnifnodata]
         [columndelimiter <Character>] [noescapechar <Boolean>] [quotechar <Character>] [fields <FieldNameList>]
         (matchfield|skipfield <FieldName> <RegularExpression>)* [showcmds [<Boolean>]]
-        [maxrows <Integer>]
+        [skiprows <Integer>] [maxrows <Integer>]
         gam <GAMArgumentList>
 
 You can make substitutions in <GAMArgumentList> with values from the CSV file.
@@ -2875,7 +2876,7 @@ gam course <CourseID> delete topic <CourseTopicID>
 
 gam course <CourseID> create|add teachers [makefirstteacherowner] <UserItem>
 gam course <CourseID> create|add students <UserItem>
-gam course <CourseID> delete|remove teachers|students <UserItem>
+gam course <CourseID> delete|remove teachers|students [owneraccess] <UserItem>
 gam course <CourseID> clear teachers|students
 gam course <CourseID> sync teachers [addonly|removeonly] [makefirstteacherowner] <UserTypeEntity>
 gam course <CourseID> sync students [addonly|removeonly] <UserTypeEntity>
@@ -2888,15 +2889,17 @@ gam courses <CourseEntity> delete topic <CourseTopicIDEntity>
 
 gam courses <CourseEntity> create|add teachers [makefirstteacherowner] <UserTypeEntity>
 gam courses <CourseEntity> create|add students <UserTypeEntity>
-gam courses <CourseEntity> delete|remove teachers|students <UserTypeEntity>
+gam courses <CourseEntity> delete|remove teachers|students [owneraccess] <UserTypeEntity>
 gam courses <CourseEntity> clear teachers|students
 gam courses <CourseEntity> sync teachers [addonly|removeonly] [makefirstteacherowner] <UserTypeEntity>
 gam courses <CourseEntity> sync students [addonly|removeonly] <UserTypeEntity>
 
-gam info course <CourseID> [owneremail] [alias|aliases] [show all|students|teachers] [countsonly]
+gam info course <CourseID> [owneraccess]
+        [owneremail] [alias|aliases] [show all|students|teachers] [countsonly]
         [fields <CourseFieldNameList>] [skipfields <CourseFieldNameList>]
         [formatjson]
-gam info courses <CourseEntity> [owneremail] [alias|aliases] [show all|students|teachers] [countsonly]
+gam info courses <CourseEntity> [owneraccess]
+        [owneremail] [alias|aliases] [show all|students|teachers] [countsonly]
         [fields <CourseFieldNameList>] [skipfields <CourseFieldNameList>]
         [formatjson]
 gam print courses [todrive <ToDriveAttribute>*]
@@ -3040,8 +3043,8 @@ gam print course-works [todrive <ToDriveAttribute>*]
 # Classroom - Invitations
 
 gam <UserTypeEntity> create classroominvitation courses <CourseEntity> [role owner|student|teacher]
-        [adminaccess|asadmin] [csv|csvformat] [todrive <ToDriveAttribute>*]
-        [formatjson [quotechar <Character>]]
+        [adminaccess|asadmin]
+        [csv|csvformat] [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]
 gam <UserTypeEntity> accept classroominvitation (ids <ClassroomInvitationIDEntity>)|([courses <CourseEntity>] [role all|owner|student|teacher])
 gam <UserTypeEntity> delete classroominvitation (ids <ClassroomInvitationIDEntity>)|([courses <CourseEntity>] [role all|owner|student|teacher])
 gam <UserTypeEntity> show classroominvitations [role all|owner|student|teacher]
@@ -3049,6 +3052,7 @@ gam <UserTypeEntity> show classroominvitations [role all|owner|student|teacher]
 gam <UserTypeEntity> print classroominvitations [todrive <ToDriveAttribute>*] [role all|owner|student|teacher]
         [formatjson [quotechar <Character>]]
 
+gam delete classroominvitation courses <CourseEntity> (ids <ClassroomInvitationIDEntity>)|(role all|owner|student|teacher)
 gam show classroominvitations (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
         [role all|owner|student|teacher]
         [formatjson]
@@ -3141,7 +3145,7 @@ gam print|show transferapps
 gam create|add datatransfer|transfer <OldOwnerID> <DataTransferServiceList> <NewOwnerID>
         [private|shared|all] [release_resources]
         (<ParameterKey> <ParameterValue>)*
-
+        [wait <Integer> <Integer>]
 gam info datatransfer|transfer <TransferID>
 gam print datatransfers|transfers [todrive <ToDriveAttribute>*]
         [olduser|oldowner <UserItem>] [newuser|newowner <UserItem>]
@@ -3362,16 +3366,16 @@ gam show peoplecontacts
         [allfields|(fields <PeopleFieldNameList>)] [showmetadata]
         [formatjson]
 
-gam info people <PeopleResourceNameEntity>
+gam info people|peopleprofile <PeopleResourceNameEntity>
         [allfields|(fields <PeopleFieldNameList>)] [showmetadata]
         [formatjson]
-gam print people [todrive <ToDriveAttribute>*]
+gam print people|peopleprofile [todrive <ToDriveAttribute>*]
         [query <String>]
         [mergesources <PeopleMergeSourceName>]
         [coountsonly]
         [allfields|(fields <PeopleFieldNameList>)] [showmetadata]
         [formatjson [quotechar <Character>]]
-gam show people
+gam show people|peopleprofile
         [query <String>]
         [mergesources <PeopleMergeSourceName>]
         [coountsonly]
@@ -4533,6 +4537,7 @@ gam create shareddrive <Name>
         (<SharedDriveRestrictionsSubfieldName> <Boolean>)*
         [hide|hidden <Boolean>] [ou|org|orgunit <OrgUnitItem>]
         [errorretries <Integer>] [updateinitialdelay <Integer>] [updateretrydelay <Integer>]
+        [movetoorgunitdelay <Integer>]
         [(csv [todrive <ToDriveAttribute>*] (addcsvdata <FieldName> <String>)*) | returnidonly]
 gam update shareddrive <SharedDriveEntity> [name <Name>]
         [(theme|themeid <String>) | ([customtheme <DriveFileID> <Float> <Float> <Float>] [color <ColorValue>])]
@@ -4542,9 +4547,11 @@ gam delete shareddrive <SharedDriveEntity>
        [adminaccess|asadmin] [allowitemdeletion]
 gam hide shareddrive <SharedDriveEntity>
 gam unhide shareddrive <SharedDriveEntity>
-gam info shareddrive <SharedDriveEntity> [fields <SharedDriveFieldNameList>]
+gam info shareddrive <SharedDriveEntity>
+        [fields <SharedDriveFieldNameList>]
         [formatjson]
-gam show shareddriveinfo <SharedDriveEntity> [fields <SharedDriveFieldNameList>]
+gam show shareddriveinfo <SharedDriveEntity>
+        [fields <SharedDriveFieldNameList>]
         [formatjson]
 gam print shareddrives [todrive <ToDriveAttribute>*]
         [teamdriveadminquery|query <QueryTeamDrive>]
@@ -4571,16 +4578,19 @@ gam <UserTypeEntity> create shareddrive <Name> adminaccess
         (<SharedDriveRestrictionsSubfieldName> <Boolean>)*
         [hide|hidden <Boolean>] [ou|org|orgunit <OrgUnitItem>]
         [errorretries <Integer>] [updateinitialdelay <Integer>] [updateretrydelay <Integer>]
+        [movetoorgunitdelay <Integer>]
         [(csv [todrive <ToDriveAttribute>*] (addcsvdata <FieldName> <String>)*) | returnidonly]
-gam update shareddrive <SharedDriveEntity> asadmin [name <Name>]
+gam <UserTypeEntity> update shareddrive <SharedDriveEntity> adminaccess [name <Name>]
         [(theme|themeid <String>) | ([customtheme <DriveFileID> <Float> <Float> <Float>] [color <ColorValue>])]
         (<SharedDriveRestrictionsFieldName> <Boolean>)*
         [hide|hidden <Boolean>] [ou|org|orgunit <OrgUnitItem>]
 gam <UserTypeEntity> delete shareddrive <SharedDriveEntity>
         adminaccess [allowitemdeletion]
-gam <UserTypeEntity> info shareddrive <SharedDriveEntity> adminaccess [fields <SharedDriveFieldNameList>]
+gam <UserTypeEntity> info shareddrive <SharedDriveEntity>
+        adminaccess [fields <SharedDriveFieldNameList>]
         [formatjson]
-gam <UserTypeEntity> show shareddriveinfo <SharedDriveEntity> adminaccess [fields <SharedDriveFieldNameList>]
+gam <UserTypeEntity> show shareddriveinfo <SharedDriveEntity>
+        adminaccess [fields <SharedDriveFieldNameList>]
         [formatjson]
 gam <UserTypeEntity> print shareddrives [todrive <ToDriveAttribute>*]
         adminaccess [teamdriveadminquery|query <QueryTeamDrive>]
@@ -4595,6 +4605,57 @@ gam <UserTypeEntity> show shareddrives
         [fields <SharedDriveFieldNameList>]
         [formatjson]
 
+In these commands, you specify a user, administrator access is not used.
+
+gam <UserTypeEntity> create shareddrive <Name>
+        [(theme|themeid <String>) | ([customtheme <DriveFileID> <Float> <Float> <Float>] [color <ColorValue>])]
+        (<SharedDriveRestrictionsSubfieldName> <Boolean>)*
+        [hide|hidden <Boolean>] [ou|org|orgunit <OrgUnitItem>]
+        [errorretries <Integer>] [updateinitialdelay <Integer>] [updateretrydelay <Integer>]
+        [movetoorgunitdelay <Integer>]
+        [(csv [todrive <ToDriveAttribute>*] (addcsvdata <FieldName> <String>)*) | returnidonly]
+gam <UserTypeEntity> update shareddrive <SharedDriveEntity> [name <Name>]
+        [(theme|themeid <String>) | ([customtheme <DriveFileID> <Float> <Float> <Float>] [color <ColorValue>])]
+        (<SharedDriveRestrictionsFieldName> <Boolean>)*
+        [hide|hidden <Boolean>] [ou|org|orgunit <OrgUnitItem>]
+gam <UserTypeEntity> delete shareddrive <SharedDriveEntity>
+        [allowitemdeletion]
+gam <UserTypeEntity> info shareddrive <SharedDriveEntity>
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>]] [formatjson]
+gam <UserTypeEntity> show shareddriveinfo <SharedDriveEntity>
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>]] [formatjson]
+gam <UserTypeEntity> print shareddrives [todrive <ToDriveAttribute>*]
+        [teamdriveadminquery|query <QueryTeamDrive>]
+        [matchname <RegularExpression>] [orgunit|org|ou <OrgUnitPath>]
+        (role|roles <SharedDriveACLRoleList>)*
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>]] [formatjson [quotechar <Character>]]
+gam <UserTypeEntity> show shareddrives
+        [teamdriveadminquery|query <QueryTeamDrive>]
+        [matchname <RegularExpression>] [orgunit|org|ou <OrgUnitPath>]
+        (role|roles <SharedDriveACLRoleList>)*
+        [fields <SharedDriveFieldNameList>]
+        [guiroles [<Boolean>]] [formatjson]
+
+<PermissionMatch> ::=
+        pm|permissionmatch [not]
+            [type|nottype <DriveFileACLType>] [role|notrole <DriveFileACLRole>]
+            [typelist|nottypelist <DriveFileACLTypeList>] [rolelist|notrolelist <DriveFileACLRoleList>]
+            [allowfilediscovery|withlink <Boolean>]
+            [emailaddress <RegularExpression>] [emailaddressList <EmailAddressList>]
+            [permissionidlist <PermissionIDList>
+            [name|displayname <String>]
+            [domain|notdomain <RegularExpression>] [domainlist|notdomainlist <DomainNameList>]
+            [expirationstart <Time>] [expirationend <Time>]
+            [deleted <Boolean>] [inherited <Boolean>] [permtype member|file]
+        em|endmatch
+<PermissionMatchMode> ::=
+        pmm|permissionmatchmode or|and
+<PermissionMatchAction> ::=
+        pma|permissionmatchaction process|skip
+
 These commands are used to manage the ACLs on the Team Drives themselves, not the files/folders on the Team Drives.
 
 <DrivePermissionsFieldName> ::=
@@ -4939,7 +5000,7 @@ gam create vaultexport|export matter <MatterItem> [name <String>] corpus calenda
         [includeshareddrives <Boolean>] [driveversiondate <Date>|<Time>] [includeaccessinfo <Boolean>]
         [includerooms <Boolean>]
         [excludedrafts <Boolean>] [format mbox|pst]
-        [showconfidentialmodecontent <Boolean>] [usenewexport <Boolean>]
+        [showconfidentialmodecontent <Boolean>] [usenewexport <Boolean>] [exportlinkeddrivefiles <Boolean>]
         [covereddata calllogs|textmessages|voicemails]
         [region any|europe|us] [showdetails|returnidonly]
 gam delete vaultexport|export <ExportItem> matter <MatterItem>
@@ -5348,6 +5409,7 @@ gam print users [todrive <ToDriveAttribute>*]
         [orderby <UserOrderByFieldName> [ascending|descending]]
         [groups|groupsincolumns]
         [license|licenses|licence|licences|licensebyuser|licensesbyuser|licencebyuser|licencesbyuser]
+        [onelicenseperrow|onelicenceperrow]
         [(products|product <ProductIDList>)|(skus|sku <SKUIDList>)]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username]
@@ -5363,6 +5425,7 @@ gam print users [todrive <ToDriveAttribute>*] select <UserTypeEntity>
         [orderby <UserOrderByFieldName> [ascending|descending]]
         [groups|groupsincolumns]
         [license|licenses|licence|licences|licensebyuser|licensesbyuser|licencebyuser|licencesbyuser]
+        [onelicenseperrow|onelicenceperrow]
         [(products|product <ProductIDList>)|(skus|sku <SKUIDList>)]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username]
@@ -5376,6 +5439,7 @@ gam <UserTypeEntity> print users [todrive <ToDriveAttribute>*]
         [orderby <UserOrderByFieldName> [ascending|descending]]
         [groups|groupsincolumns]
         [license|licenses|licence|licences|licensebyuser|licensesbyuser|licencebyuser|licencesbyuser]
+        [onelicenseperrow|onelicenceperrow]
         [(products|product <ProductIDList>)|(skus|sku <SKUIDList>)]
         [schemas|custom|customschemas all|<SchemaNameList>]
         [emailpart|emailparts|username]
@@ -5767,18 +5831,19 @@ gam <UserTypeEntity> create focustime
         [declinemessage <String>]
         [summary <String>]
         (timerange <Time> <Time> [recurrence <String>])+
-        [timezone <String>]
+
 gam <UserTypeEntity> create outofoffice
         [declinemode none|all|new]
         [declinemessage <String>]
         [summary <String>]
         (timerange <Time> <Time> [recurrence <String>])+
         [timezone <String>]
+
 gam <UserTypeEntity> create workinglocation
         (home|
          (custom <String>)|
          (office <String> [building|buildingid <String>] [floor|floorname <String>]
-           		  [section|floorsection <String>] [desk|deskcode <String>]))
+                          [section|floorsection <String>] [desk|deskcode <String>]))
         ((date yyyy-mm-dd)|
          (range yyyy-mm-dd yyyy-mm-dd)|
          (daily yyyy-mm-dd N)|
@@ -5833,6 +5898,7 @@ gam <UserTypeEntity> print focustime|outofoffice|workinglocation
 
 gam <UserTypeEntity> create chatspace
         [type <ChatSpaceType>]
+        [restricted|(audience <String>)]
         [externalusersrallowed <Boolean>]
         [members <UserTypeEntity>]
         [displayname <String>]
@@ -5841,10 +5907,11 @@ gam <UserTypeEntity> create chatspace
         [<ChatContent>]
         [formatjson|returnidonly]
 gam <UserTypeEntity> update chatspace <ChatSpace>
-        [type space]
-        [displayname <String>]
-        [description <String>] [guidelines <String>]
-        [history <Boolean>]
+        [restricted|(audience <String>)]|
+        ([displayname <String>]
+         [type space]
+         [description <String>] [guidelines|rules <String>]
+         [history <Boolean>])
         [formatjson]
 gam <UserTypeEntity> delete chatspace <ChatSpace>
 
@@ -6503,9 +6570,10 @@ gam <UserTypeEntity> collect orphans
         <DriveOwnersSubfieldName>|
         parents|
         <DriveParentsSubfieldName>|
+        permissionids|
+        permissiondetails|
         permissions|
         <DrivePermissionsSubfieldName>|
-        permissionids|
         properties|
         quotabytesused|quotaused|
         resourcekey|
@@ -6542,19 +6610,6 @@ gam <UserTypeEntity> collect orphans
         writerscanshare
 <DriveFieldNameList> ::= "<DriveFieldName>(,<DriveFieldName>)*"
 
-<PermissionMatch> ::=
-        permissionmatch|pm [not]
-            [type anyone|user|group|domain] [role|notrole <DriveFileACLRole>] [allowfilediscovery|withlink <Boolean>]
-            [emailaddress <RegularExpression>] [name|displayname <String>]
-            [domain|notdomain <RegularExpression>] [domainlist|notdomainlist <DomainNameList>]
-            [expirationstart <Time>] [expirationend <Time>]
-            [deleted <Boolean>] [inherited <Boolean>]
-        endmatch|em
-<PermissionMatchMode> ::=
-        permissionmatchmode|pmm or|and
-<PermissionMatchAction> ::=
-        permissionmatchaction|pma process|skip
-
 gam <UserTypeEntity> show fileinfo <DriveFileEntity>
         [returnidonly]
         [filepath|fullpath] [pathdelimiter <Character>]
@@ -7071,6 +7126,15 @@ gam <UserTypeEntity> show signature|sig [compact|format|html]
 gam <UserTypeEntity> print signature [compact]
         [primary|default] [verifyonly] [todrive <ToDriveAttribute>*]
 
+gam <UserTypeEntity> vacation <Boolean> subject <String>
+        [<VacationMessageContent> (replace <Tag> <UserReplacement>)*]
+        [html [<Boolean>]] [contactsonly [<Boolean>]] [domainonly [<Boolean>]]
+        [start|startdate <Date>|Started] [end|enddate <Date>|NotSpecified]
+gam <UserTypeEntity> show vacation [compact|format|html] [enabledonly]
+gam <UserTypeEntity> print vacation [compact] [enabledonly] [todrive <ToDriveAttribute>*]
+
+# Users - Gmail - S/MIME
+
 gam <UserTypeEntity> create|add smime file <FileName> [password <Password>]
         [sendas|sendasemail <EmailAddress>] [default]
 gam <UserTypeEntity> update smime default
@@ -7082,12 +7146,37 @@ gam <UserTypeEntity> show smimes
 gam <UserTypeEntity> print smimes [todrive <ToDriveAttribute>*]
         [primary|default|(sendas|sendasemail <EmailAddress>)]
 
-gam <UserTypeEntity> vacation <Boolean> subject <String>
-        [<VacationMessageContent> (replace <Tag> <UserReplacement>)*]
-        [html [<Boolean>]] [contactsonly [<Boolean>]] [domainonly [<Boolean>]]
-        [start|startdate <Date>|Started] [end|enddate <Date>|NotSpecified]
-gam <UserTypeEntity> show vacation [compact|format|html] [enabledonly]
-gam <UserTypeEntity> print vacation [compact] [enabledonly] [todrive <ToDriveAttribute>*]
+# Users - Gmail Client Side Encryption
+
+gam <UserTypeEntity> create cseidentity <KeyPairID> [kpemail <EmailAddress>]
+        [formatjson]
+gam <UserTypeEntity> update cseidentity <KeyPairID> [kpemail <EmailAddress>]
+        [formatjson]
+gam <UserTypeEntity> delete cseidentity [kpemail <EmailAddress>]
+
+gam <UserTypeEntity> info cseidentity [kpemail <EmailAddress>]
+        [formatjson]
+gam <UserTypeEntity> show cseidentities
+        [formatjson]
+gam <UserTypeEntity> print cseidentities [todrive <ToDriveAttribute>*]
+        [formatjson [quotechar <Character>]]
+
+gam <UserTypeEntity> create csekeypair
+        [incertdir <FilePath>] [inkeydir <FilePath>]
+        [addidentity [<Boolean>]] [kpemail <EmailAddress>]
+        [formatjson|returnidonly]
+gam <UserTypeEntity> disable csekeypair <KeyPairID>
+        [formatjson]
+gam <UserTypeEntity> enable csekeypair <KeyPairID>
+        [formatjson]
+gam <UserTypeEntity> obliterate csekeypair <KeyPairID>
+
+gam <UserTypeEntity> info csekeypair <KeyPairID>
+        [formatjson]
+gam <UserTypeEntity> show csekeypairs
+        [formatjson]
+gam <UserTypeEntity> print csekeypairs [todrive <ToDriveAttribute>*]
+        [formatjson [quotechar <Character>]]
 
 # Users - Gmail - Settings
 

src/GamUpdate.txt

@@ -2,6 +2,257 @@
 
 Merged GAM-Team version
 
+6.70.01
+
+Added `gmail_cse_incert_dir` and `gmail_cse_inkey_dir` path variables to `gam.cfg` that provide
+default values for the `incertdir <FilePath>` and `inkeydir <FilePath>` options in `gam <UserTypeEntity> create csekeypair`.
+
+6.70.00
+
+Added support for Gmail Client Side Encryption.
+
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Users-Gmail-CSE
+
+This is an initial, minimally tested release; proceed with care and report all issues.
+
+c6.69.00
+
+Added `use_classroom_owner_access` Boolean variable to `gam.cfg` that controls how GAM gets
+classroom member information and removes students/teachers. Client access does not provide
+complete information about non-domain students/teachers.
+* `False` - Use client access; this is the default. Use if you don't have non-domain members in your courses.
+* `True` - Use service account access as the classroom owner. An extra API call is required per course to authenticate the owner; this will affect performance
+
+Added the following command which must be used to delete classroom invitations for non-domain students/teachers.
+```
+gam delete classroominvitation courses <CourseEntity> (ids <ClassroomInvitationIDEntity>)|(role all|owner|student|teacher)
+```
+You can obtain the classroom invitation IDs with these commands:
+```
+gam show classroominvitations (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
+        [role all|owner|student|teacher] [formatjson]
+gam print classroominvitations [todrive <ToDriveAttribute>*] (course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
+        [role all|owner|student|teacher] [formatjson [quotechar <Character>]]
+```
+
+6.68.08
+
+Updated `gam <UserTypeEntity> print filelist|drivefileacls|shareddriveacls ... oneitemperrow` to print
+ACLs with multiple permission details on separate rows for each basic permission/permission detail combination.
+This case occurs when a member of a Shared Drive has access to a file and also has explicitly granted access to the same file.
+
+Added `permtype member|file` to `<PermissionMatch>` that allows determining whether an ACL on a Shared Drive file was
+derived from membership or explicitly granted.
+
+6.68.07
+
+Updated `gam info user ... locations formatjson` to include the `buildingName` field in the
+`locations` entries. If `gam.cfg` contains `quick_info_user = true` or the `quick` option
+is included on the command line, add the option `buildingnames` to the command line.
+
+6.68.06
+
+Fixed bug in `gam <UserTypeEntity> copy drivefile <DriveFileID> ... mergewithparent` that incorrectly named
+the copied file with the name of the parent folder.
+
+Updated `gam <UserTypeEntity> copy|move drivefile` to avoid copying/moving the same file twice.
+
+6.68.05
+
+Updated `gam print groups ... ciallfields|(cifields <CIGroupFieldNameList>)` to account for an
+API shortcoming that failed to get all of the Cloud Identity fields.
+
+6.68.04
+
+Added option `skiprows <Integer>` to `gam csv|loop` that causes GAM to skip processing the first `<Integer>` filtered rows.
+
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Bulk-Processing#csv-files
+
+6.68.03
+
+Fixed bug in `gam <UserTypeEntity> create drivefileacl` that caused a trap.
+
+6.68.02
+
+Upgraded to Python 3.12.2 where possible.
+
+Added options `restricted|(audience <String>)` to `gam <UserTypeEntity> create|update chatspace` that
+sets the access options for the chat space. These options are in Developer Preview and will not be generally available.
+
+6.68.01
+
+Fixed `<PermissionMatch>` bug for real.
+
+6.68.00
+
+Fixed `<PermissionMatch>` bug introduced in 6.67.35 that caused a command error like the following or would
+not properly match `type|nottype <DriveFileACLType>` and `role|notrole <DriveFileACLRole>`.
+
+```
+ERROR: permission attribute allowfilediscovery/withlink not allowed with type {'a', 'y', 'e', 'o', 'n'}
+```
+
+My sincere apologies.
+
+6.67.39
+
+Added option `wait <Integer> <Integer>` to `gam create datatransfer` that causes GAM to wait
+for the transfer to complete. The first `<Integer>` must be in the range 5-60 and is the number
+of seconds between checks to see if the transfer has completed. The second `<Integer>` is the maximum
+number of checks to perform. By default, GAM does not wait for the transfer to complete.
+
+6.67.38
+
+Added option `tdnotify [<Boolean>]` to `<ToDriveAttribute>` that causes GAM to send notification
+emails to all `tdshare <EmailAddress>` users when the file is uploaded/updated.
+
+6.67.37
+
+Fixed bug in `gam <UserTypeEntity> show messages ... showattachments` to avoid a trap when `text/plain` attachments
+in character sets other than `UTF-8` are displayed.
+
+6.67.36
+
+Updated `gam batch <BatchContent>` and `gam tbatch <BatchContent>` commands to accept lines with the following form:
+```
+sleep <Integer>
+```
+Batch processing will suspend for `<Integer>` seconds before the next command line is processed.
+
+6.67.35
+
+Added the following options to `<PermissionMatch>` that allow more powerful matching.
+```
+nottype	<DriveFileACLType>
+typelist <DriveFileACLTypeList>
+nottypelist <DriveFileACLTypeList>
+rolelist <DriveFileACLRoleList>
+notrolelist <DriveFileACLRoleList>
+```
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Permission-Matches#define-a-match
+
+6.67.34
+
+Added option `movetoorgunitdelay <Integer>` to `gam <UserTypeEntity> create shareddrive <Name> ... ou|org|orgunit <OrgUnitItem>`.
+GAM creates the Shared Drive, verifies that it has been created and then tries to move it to `<OrgUnitItem>`. Google seems to
+require a delay or the following error is generated.
+```
+ERROR: 409: 409 - The operation was aborted.
+```
+`movetoorgunitdelay` defaults to 20 seconds which seems to work; `<Integer>` can range from 0 to 60.
+
+6.67.33
+
+Upgraded to OpenSSL 3.2.1 where possible.
+
+Fixed bug in `gam <UserTypeEntity> print shareddrives` where `role` was improperly displayed as `fileOrganizer`
+rather than `writer`.
+
+Added option `guiroles [<Boolean>]` to `gam <UserTypeEntity> info|print|show shareddrive` that maps
+the Drive API role names to the Google Drive GUI role names.
+```
+API: GUI
+commenter: Commenter
+fileOrganizer: Content manager
+organizer: Manager
+reader: Viewer
+writer: Contributor
+```
+
+6.67.32
+
+Updated `<ToDriveAttribute>` to allow multiple `tdshare <EmailAddress> commenter|reader|writer` options.
+
+Fixed bug in `gam <UserTypeEntity> print shareddrives` where `role` was improperly displayed as `unknown`
+rather than `reader` when `Allow viewers and commenters to download, print, and copy files` was unchecked for the Shared Drive.
+
+6.67.31
+
+Updated `gam <UserTypeEntity> claim|transfer ownership <DriveFileEntity>` to properly
+handle the case where `<DriveFileEntity>` referencess a Drive shortcut.
+
+6.67.30
+
+Fixed bug where the `fullpath` option in various commands was not converting the generic shared drive name `Drive` to the drive's actual name.
+
+6.67.29
+
+Added optional argument `owneraccess` to `gam courses <CourseEntity> remove teachers|students [owneracccess] <UserTypeEntity` and
+`gam course <CourseID> remove teacher|student [owneraccess] <EmailAddress>` in order to test a possible API change.
+
+Updated code to avoid a trap when `gam config auto_batch_min 1 csv file.csv gam ...` was entered.
+The `config auto_batch_min 1` is not appropriate in this context and will be ignored.
+
+6.67.28
+
+Improved handling of `Bad Request` error in `gam <UserTypeEntity> collect orphans`.
+
+6.67.27
+
+Updated `gam <UserTypeEntity> collect orphans` to handle the following error:
+```
+ERROR: 400: badRequest - Bad Request
+```
+
+6.67.26
+
+Fixed bug in `gam print vaultexports ... formatjson` that caused a trap.
+
+6.67.25
+
+Added option `owneraccess` to `gam info courses <CourseEntity>` and `gam info course <CourseID>` in order
+to test a possible API change.
+
+6.67.24
+
+Fixed bug that caused HTML password notification email messages to be displayed in raw form.
+
+6.67.23
+
+Use local copy of `googleapiclient` to remove static discovery documents to improve performance.
+
+6.67.22
+
+Added `permissionidlist <PermissionIDList>` to `<PermissionMatch>` that allows matching any permission ID in a list.
+
+Added option `exportlinkeddrivefiles <Boolean>` to `gam create vaultexport` that is used with `corpus mail`.
+
+6.67.21
+
+Updated `gam remove aliases <EmailAddress> user|group <EmailAddressEntity>` to give a more informative
+error message when the target/alias combination does not exist.
+```
+Old: User: testsimple@rdschool.org, User Alias: tsalias@rdschool.org, Remove Failed: Invalid Input: resource_id
+New: User: testsimple@rdschool.org, User Alias: tsalias@rdschool.org, Remove Failed: Does not exist
+```
+
+6.67.20
+
+Added option `onelicenseperrow|onelicenceperrow` to `gam print users ... licenses` that causes GAM to print
+a seperate user information row for each license a user is assigned. This makes processing
+the licenses in a script possible and allows better sorting in a CSV File.
+
+By default, all licenses for a user are displayed in a list on one row:
+```
+primaryEmail,LicensesCount,Licenses,LicensesDisplay
+user@domain.com,2,1010020020 1010330004,Google Workspace Enterprise Plus Google Voice Standard
+```
+With `onelicenseperrow|onelicenceperrow`, each license is on a separate row:
+```
+primaryEmail,License,LicenseDisplay
+user@domain.com,1010020020,Google Workspace Enterprise Plus
+user@domain.com 1010330004,Google Voice Standard
+```
+
+6.67.19
+
+Updated `gam create|update user ... notify` to encode the characters `<>&` in the password
+so that they display correctly when the notify message content is HTML.
+
+6.67.18
+
+Cleaned up `Getting/Got` messages for `gam print courses|course-participants`.
+
 6.67.17
 
 Added option `showitemcountonly` to various commands that causes GAM to display the
@@ -12,7 +263,7 @@ item count on stdout; no CSV file is written.
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Classroom-Membership#display-course-membership-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/ChromeOS-Devices#display-cros-device-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-counts
-* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-counts
+* See: https://github.com/taers232c/GAMADV-XTD3/wiki/Cloud-Identity-Devices#display-device-user-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Groups#display-group-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Mobile-Devices#display-mobile-device-counts
 * See: https://github.com/taers232c/GAMADV-XTD3/wiki/Organizational-Units#display-organizational-unit-counts

src/gam/gamlib/glaction.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -77,6 +77,7 @@ class GamAction():
   MOVE_MERGE = 'movm'
   NOACTION = 'noac'
   NOACTION_PREVIEW = 'noap'
+  OBLITERATE = 'obli'
   PERFORM = 'perf'
   PRE_PROVISIONED_DISABLE ='ppdi'
   PRE_PROVISIONED_REENABLE ='ppre'
@@ -193,6 +194,7 @@ class GamAction():
     MOVE_MERGE: ['Moved(Merge)', 'Move(Merge)'],
     NOACTION: ['No Action', 'No Action'],
     NOACTION_PREVIEW: ['No Action (Preview)', 'No Action (Preview)'],
+    OBLITERATE: ['Obliterated', 'Obliterate'],
     PERFORM: ['Action Performed', 'Perform Action'],
     PRE_PROVISIONED_DISABLE: ['PreProvisioned Disabled', 'PreProvisioned Disable'],
     PRE_PROVISIONED_REENABLE: ['PreProvisioned Reenabled', 'PreProvisioned Reenable'],

src/gam/gamlib/glapi.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -539,6 +539,10 @@ _SVCACCT_SCOPES = [
    'api': CLASSROOM,
    'subscopes': [],
    'scope': 'https://www.googleapis.com/auth/classroom.profile.emails'},
+  {'name': 'Classroom API - Profile Photos',
+   'api': CLASSROOM,
+   'subscopes': [],
+   'scope': 'https://www.googleapis.com/auth/classroom.profile.photos'},
   {'name': 'Classroom API - Rosters',
    'api': CLASSROOM,
    'subscopes': READONLY,

src/gam/gamlib/glcfg.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -161,6 +161,10 @@ ENABLE_GCLOUD_REAUTH = 'enable_gcloud_reauth'
 EVENT_MAX_RESULTS = 'event_max_results'
 # Path to extra_args.txt
 EXTRA_ARGS = 'extra_args'
+# Gmail CSE certificates directory
+GMAIL_CSE_INCERT_DIR = 'gmail_cse_incert_dir'
+# Gmail CSE KACL wrapped key files
+GMAIL_CSE_INKEY_DIR = 'gmail_cse_inkey_dir'
 # When processing items in batches, how many seconds should GAM wait between batches
 INTER_BATCH_WAIT = 'inter_batch_wait'
 # When retrieving lists of licenses from API, how many should be retrieved in each chunk
@@ -284,6 +288,8 @@ TODRIVE_UPLOAD_NODATA = 'todrive_upload_nodata'
 TODRIVE_USER = 'todrive_user'
 # Update CrOS org unit with orgUnitId
 UPDATE_CROS_OU_WITH_ID = 'update_cros_ou_with_id'
+# Use course owner for course access
+USE_COURSE_OWNER_ACCESS = 'use_course_owner_access'
 # Use Project ID as Project Name and App Name
 USE_PROJECTID_AS_NAME = 'use_projectid_as_name'
 # When retrieving lists of Users from API, how many should be retrieved in each chunk
@@ -359,6 +365,8 @@ Defaults = {
   ENABLE_GCLOUD_REAUTH: FALSE,
   EVENT_MAX_RESULTS: '250',
   EXTRA_ARGS: '',
+  GMAIL_CSE_INCERT_DIR: '',
+  GMAIL_CSE_INKEY_DIR: '',
   INTER_BATCH_WAIT: '0',
   LICENSE_MAX_RESULTS: '100',
   LICENSE_SKUS: '',
@@ -420,6 +428,7 @@ Defaults = {
   TODRIVE_UPLOAD_NODATA: TRUE,
   TODRIVE_USER: '',
   UPDATE_CROS_OU_WITH_ID: FALSE,
+  USE_COURSE_OWNER_ACCESS: FALSE,
   USE_PROJECTID_AS_NAME: FALSE,
   USER_MAX_RESULTS: '500',
   USER_SERVICE_ACCOUNT_ACCESS_ONLY: FALSE,
@@ -514,6 +523,8 @@ VAR_INFO = {
   ENABLE_GCLOUD_REAUTH: {VAR_TYPE: TYPE_BOOLEAN},
   EVENT_MAX_RESULTS: {VAR_TYPE: TYPE_INTEGER, VAR_LIMITS: (1, 2500)},
   EXTRA_ARGS: {VAR_TYPE: TYPE_FILE, VAR_SIGFILE: FN_EXTRA_ARGS_TXT, VAR_SFFT: ('', FN_EXTRA_ARGS_TXT), VAR_ACCESS: os.R_OK},
+  GMAIL_CSE_INCERT_DIR: {VAR_TYPE: TYPE_DIRECTORY},
+  GMAIL_CSE_INKEY_DIR: {VAR_TYPE: TYPE_DIRECTORY},
   INTER_BATCH_WAIT: {VAR_TYPE: TYPE_FLOAT, VAR_LIMITS: (0.0, 60.0)},
   LICENSE_MAX_RESULTS: {VAR_TYPE: TYPE_INTEGER, VAR_LIMITS: (10, 1000)},
   LICENSE_SKUS: {VAR_TYPE: TYPE_STRING, VAR_LIMITS: (0, None)},
@@ -575,6 +586,7 @@ VAR_INFO = {
   TODRIVE_UPLOAD_NODATA: {VAR_TYPE: TYPE_BOOLEAN},
   TODRIVE_USER: {VAR_TYPE: TYPE_STRING, VAR_LIMITS: (0, None)},
   UPDATE_CROS_OU_WITH_ID: {VAR_TYPE: TYPE_BOOLEAN},
+  USE_COURSE_OWNER_ACCESS: {VAR_TYPE: TYPE_BOOLEAN},
   USE_PROJECTID_AS_NAME: {VAR_TYPE: TYPE_BOOLEAN},
   USER_MAX_RESULTS: {VAR_TYPE: TYPE_INTEGER, VAR_LIMITS: (1, 500)},
   USER_SERVICE_ACCOUNT_ACCESS_ONLY: {VAR_TYPE: TYPE_BOOLEAN},

src/gam/gamlib/glclargs.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -379,6 +379,7 @@ class GamCLArgs():
   PRINT_CMD = 'print'
   SET_CMD = 'set'
   CLEAR_CMD = 'clear'
+  SLEEP_CMD = 'sleep'
 # Command line batch/csv/loop/tbatch keywords
   BATCH_CMD = 'batch'
   CSV_CMD = 'csv'
@@ -519,6 +520,10 @@ class GamCLArgs():
   ARG_CROSES = 'croses'
   ARG_CROSACTIVITY = 'crosactivity'
   ARG_CROSTELEMETRY = 'crostelemetry'
+  ARG_CSEIDENTITY = 'cseidentity'
+  ARG_CSEIDENTITIES = 'cseidentities'
+  ARG_CSEKEYPAIR = 'csekeypair'
+  ARG_CSEKEYPAIRS = 'csekeypairs'
   ARG_CURRENTPROJECTID = 'currentprojectid'
   ARG_CUSTOMER = 'customer'
   ARG_DATASTUDIOASSET = 'datastudioasset'
@@ -845,6 +850,7 @@ class GamCLArgs():
   OB_COURSE_WORK_STATE_LIST = "CourseWorkStateList"
   OB_CROS_DEVICE_ENTITY = 'CrOSDeviceEntity'
   OB_CROS_ENTITY = 'CrOSEntity'
+  OB_CSE_KEYPAIR_ID = 'CSEKeyPairID'
   OB_CUSTOMER_ID = 'CustomerID'
   OB_CUSTOMER_AUTH_TOKEN = 'CustomerAuthToken'
   OB_DEVICE_FILE_ENTITY = 'DeviceFileEntity'
@@ -930,6 +936,9 @@ class GamCLArgs():
   OB_ORGUNIT_PATH = 'OrgUnitPath'
   OB_PARAMETER_VALUE = 'ParameterValue'
   OB_PASSWORD = 'Password'
+  OB_PERMISSION_ID_LIST = 'PermissionIDList'
+  OB_PERMISSION_ROLE_LIST = 'PermissionRoleList'
+  OB_PERMISSION_TYPE_LIST = 'PermissionTypeList'
   OB_PHOTO_FILENAME_PATTERN = 'FilenameNamePattern'
   OB_PRINTER_ID = 'PrinterID'
   OB_PRIVILEGE_LIST = 'PrivilegeList'

src/gam/gamlib/glentity.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -150,12 +150,14 @@ class GamEntity():
   CRITERIA = 'crit'
   CROS_DEVICE = 'cros'
   CROS_SERIAL_NUMBER = 'crsn'
+  CSE_IDENTITY = 'csei'
+  CSE_KEYPAIR = 'csek'
   CUSTOMER_DOMAIN = 'cudo'
   CUSTOMER_ID = 'cuid'
   DATE = 'date'
   DEFAULT_LANGUAGE = 'dfla'
   DELEGATE = 'dele'
-  DELETED_USER = 'del'
+  DELETED_USER = 'delu'
   DELIVERY = 'deli'
   DEVICE = 'devi'
   DEVICE_FILE = 'devf'
@@ -163,7 +165,7 @@ class GamEntity():
   DEVICE_USER = 'devu'
   DEVICE_USER_CLIENT_STATE = 'ducs'
   DISCOVERY_JSON_FILE = 'disc'
-  DOCUMENT = 'doc '
+  DOCUMENT = 'docu'
   DOMAIN = 'doma'
   DOMAIN_ALIAS = 'doal'
   DOMAIN_CONTACT = 'doco'
@@ -483,6 +485,8 @@ class GamEntity():
     CRITERIA: ['Criteria', 'Criteria'],
     CROS_DEVICE: ['CrOS Devices', 'CrOS Device'],
     CROS_SERIAL_NUMBER: ['CrOS Serial Numbers', 'CrOS Serial Numbers'],
+    CSE_IDENTITY: ['CSE Identities', 'CSE Identity'],
+    CSE_KEYPAIR: ['CSE KeyPairs', 'CSE KeyPair'],
     CUSTOMER_DOMAIN: ['Customer Domains', 'Customer Domain'],
     CUSTOMER_ID: ['Customer IDs', 'Customer ID'],
     DATE: ['Dates', 'Date'],

src/gam/gamlib/glgapi.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -115,11 +115,13 @@ LIMIT_EXCEEDED = 'limitExceeded'
 LOGIN_REQUIRED = 'loginRequired'
 MALFORMED_WORKING_LOCATION_EVENT = 'malformedWorkingLocationEvent'
 MEMBER_NOT_FOUND = 'memberNotFound'
+MYDRIVE_HIERARCHY_DEPTH_LIMIT_EXCEEDED = 'myDriveHierarchyDepthLimitExceeded'
 NO_LIST_TEAMDRIVES_ADMINISTRATOR_PRIVILEGE = 'noListTeamDrivesAdministratorPrivilege'
 NO_MANAGE_TEAMDRIVE_ADMINISTRATOR_PRIVILEGE = 'noManageTeamDriveAdministratorPrivilege'
 NOT_A_CALENDAR_USER = 'notACalendarUser'
 NOT_FOUND = 'notFound'
 NOT_IMPLEMENTED = 'notImplemented'
+NUM_CHILDREN_IN_NON_ROOT_LIMIT_EXCEEDED = 'numChildrenInNonRootLimitExceeded'
 OPERATION_NOT_SUPPORTED = 'operationNotSupported'
 ORGANIZER_ON_NON_TEAMDRIVE_NOT_SUPPORTED = 'organizerOnNonTeamDriveNotSupported'
 ORGANIZER_ON_NON_TEAMDRIVE_ITEM_NOT_SUPPORTED = 'organizerOnNonTeamDriveItemNotSupported'
@@ -181,8 +183,8 @@ SERVICE_NOT_AVAILABLE_RETRY_REASONS = [SERVICE_NOT_AVAILABLE]
 ACTIVITY_THROW_REASONS = [SERVICE_NOT_AVAILABLE, BAD_REQUEST]
 ALERT_THROW_REASONS = [SERVICE_NOT_AVAILABLE, AUTH_ERROR]
 CALENDAR_THROW_REASONS = [SERVICE_NOT_AVAILABLE, AUTH_ERROR, NOT_A_CALENDAR_USER]
-CIGROUP_CREATE_THROW_REASONS = [SERVICE_NOT_AVAILABLE, ALREADY_EXISTS, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, INVALID, INVALID_ARGUMENT, PERMISSION_DENIED]
-CIGROUP_GET_THROW_REASONS = [SERVICE_NOT_AVAILABLE, NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, BAD_REQUEST, INVALID, SYSTEM_ERROR, PERMISSION_DENIED]
+CIGROUP_CREATE_THROW_REASONS = [SERVICE_NOT_AVAILABLE, ALREADY_EXISTS, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, INVALID, INVALID_ARGUMENT, PERMISSION_DENIED, FAILED_PRECONDITION]
+CIGROUP_GET_THROW_REASONS = [SERVICE_NOT_AVAILABLE, NOT_FOUND, GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, BAD_REQUEST, INVALID, SYSTEM_ERROR, PERMISSION_DENIED]
 CIGROUP_LIST_THROW_REASONS = [SERVICE_NOT_AVAILABLE, RESOURCE_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, BAD_REQUEST, INVALID, INVALID_ARGUMENT, SYSTEM_ERROR, PERMISSION_DENIED]
 CIGROUP_LIST_USERKEY_THROW_REASONS = CIGROUP_LIST_THROW_REASONS+[INVALID_ARGUMENT]
 CIGROUP_UPDATE_THROW_REASONS = [SERVICE_NOT_AVAILABLE, NOT_FOUND, GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS,
@@ -248,9 +250,9 @@ DRIVE3_MODIFY_LABEL_THROW_REASONS = DRIVE_USER_THROW_REASONS+[FILE_NOT_FOUND, NO
 GMAIL_THROW_REASONS = [SERVICE_NOT_AVAILABLE, BAD_REQUEST]
 GMAIL_LIST_THROW_REASONS = [FAILED_PRECONDITION, PERMISSION_DENIED, INVALID, INVALID_ARGUMENT]
 GMAIL_SMIME_THROW_REASONS = [SERVICE_NOT_AVAILABLE, BAD_REQUEST, INVALID_ARGUMENT, FORBIDDEN, NOT_FOUND, PERMISSION_DENIED]
+GROUP_GET_THROW_REASONS = [GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, BAD_REQUEST, INVALID, SYSTEM_ERROR]
 GROUP_GET_RETRY_REASONS = [INVALID, SYSTEM_ERROR, SERVICE_NOT_AVAILABLE]
 GROUP_CREATE_THROW_REASONS = [DUPLICATE, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, INVALID, INVALID_INPUT]
-GROUP_GET_THROW_REASONS = [GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, BAD_REQUEST, INVALID, SYSTEM_ERROR]
 GROUP_UPDATE_THROW_REASONS = [GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, INVALID, INVALID_INPUT]
 GROUP_SETTINGS_THROW_REASONS = [NOT_FOUND, GROUP_NOT_FOUND, DOMAIN_NOT_FOUND, DOMAIN_CANNOT_USE_APIS, FORBIDDEN, SYSTEM_ERROR, PERMISSION_DENIED,
                                 INVALID, INVALID_PARAMETER, INVALID_ATTRIBUTE_VALUE, INVALID_INPUT, SERVICE_LIMIT, SERVICE_NOT_AVAILABLE, AUTH_ERROR, REQUIRED]
@@ -274,6 +276,7 @@ YOUTUBE_THROW_REASONS = [SERVICE_NOT_AVAILABLE, AUTH_ERROR, UNSUPPORTED_SUPERVIS
 REASON_MESSAGE_MAP = {
   ABORTED: [
     ('Label name exists or conflicts', DUPLICATE),
+    ('The operation was aborted', ABORTED),
     ],
   CONDITION_NOT_MET: [
     ('Cyclic memberships not allowed', CYCLIC_MEMBERSHIPS_NOT_ALLOWED),

src/gam/gamlib/glmsgs.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2023 Ross Scroggs All Rights Reserved.
+# Copyright (C) 2024 Ross Scroggs All Rights Reserved.
 #
 # All Rights Reserved.
 #
@@ -191,6 +191,7 @@ CSV_DATA_ALREADY_SAVED = 'CSV data already saved'
 CSV_FILE_HEADERS = 'The CSV file ({0}) has the following headers:\n'
 CSV_SAMPLE_COMMANDS = 'Here are the first {0} commands {1} will run\n'
 DATA_FIELD_MISMATCH = 'datafield {0} does not match saved datafield {1}'
+DATA_TRANSFER_COMPLETED = 'Data Transfer completed: {0}\n'
 DATA_UPLOADED_TO_DRIVE_FILE = 'Data uploaded to Drive File'
 DEFAULT_SMIME = 'Default S/MIME'
 DELETED = 'Deleted'
@@ -231,6 +232,7 @@ FAILED_PRECONDITION = 'Failed precondition'
 FAILED_TO_PARSE_AS_JSON = 'Failed to parse as JSON'
 FAILED_TO_PARSE_AS_LIST = 'Failed to parse as list'
 FIELD_NOT_FOUND_IN_SCHEMA = 'Field {0} not found in schema {1}'
+FILE_NOT_FOUND = 'File {0} not found'
 FINISHED = 'Finished'
 FILTER_CAN_ONLY_CONTAIN_ONE_CATEGORY_LABEL = 'Filter can only contain one CATEGORY label'
 FILTER_CAN_ONLY_CONTAIN_ONE_USER_LABEL = 'Filter can only contain one USER label'
@@ -299,6 +301,8 @@ IS_NOT_UNIQUE = 'Is not unique, {0}: {1}'
 IS_REQD_TO_CHG_PWD_NO_DELEGATION = 'Is required to change password at next login. You must change password or clear changepassword flag for delegation.'
 IS_SUSPENDED_NO_BACKUPCODES = 'User is suspended. You must unsuspend to process backupcodes'
 IS_SUSPENDED_NO_DELEGATION = 'Is suspended. You must unsuspend for delegation.'
+JSON_ERROR = 'JSON error "{0}" in file {1}'
+JSON_KEY_NOT_FOUND = 'JSON key "{0}" not found in file {1}'
 KIOSK_MODE_REQUIRED = ' This command ({0}) requires that the ChromeOS device be in Kiosk mode.'
 LESS_THAN_1_SECOND = 'less than 1 second'
 LIST_CHROMEOS_INVALID_INPUT_PAGE_TOKEN_RETRY = 'List ChromeOSdevices Invalid Input: pageToken retry'
@@ -479,6 +483,7 @@ USE_DOIT_ARGUMENT_TO_PERFORM_ACTION = 'Use the "doit" argument to perform action
 USING_N_PROCESSES = '{0},0/{1},Using {2} {3}...\n'
 VALUES_ARE_NOT_CONSISTENT = 'Values are not consistent'
 VERSION_UPDATE_AVAILABLE = 'Version update available'
+WAITING_FOR_DATA_TRANSFER_TO_COMPLETE_SLEEPING = 'Waiting for Data Transfer to complete. Sleeping {0} seconds\n'
 WAITING_FOR_SERVICE_ACCOUNT_CREATION_TO_COMPLETE_SLEEPING = 'Waiting for Service Account creation to complete. Sleeping {0} seconds\n'
 WAITING_FOR_SHARED_DRIVE_CREATION_TO_COMPLETE_SLEEPING = 'Waiting for Shared Drive creation to complete. Sleeping {0} seconds\n'
 WHAT_IS_YOUR_PROJECT_ID = '\nWhat is your project ID? '

src/gam/googleapiclient/__init__.py

@@ -0,0 +1,27 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Set default logging handler to avoid "No handler found" warnings.
+import logging
+
+try:  # Python 2.7+
+    from logging import NullHandler
+except ImportError:
+
+    class NullHandler(logging.Handler):
+        def emit(self, record):
+            pass
+
+
+logging.getLogger(__name__).addHandler(NullHandler())

src/gam/googleapiclient/_auth.py

@@ -0,0 +1,167 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for authentication using oauth2client or google-auth."""
+
+import httplib2
+
+try:
+    import google.auth
+    import google.auth.credentials
+
+    HAS_GOOGLE_AUTH = True
+except ImportError:  # pragma: NO COVER
+    HAS_GOOGLE_AUTH = False
+
+try:
+    import google_auth_httplib2
+except ImportError:  # pragma: NO COVER
+    google_auth_httplib2 = None
+
+try:
+    import oauth2client
+    import oauth2client.client
+
+    HAS_OAUTH2CLIENT = True
+except ImportError:  # pragma: NO COVER
+    HAS_OAUTH2CLIENT = False
+
+
+def credentials_from_file(filename, scopes=None, quota_project_id=None):
+    """Returns credentials loaded from a file."""
+    if HAS_GOOGLE_AUTH:
+        credentials, _ = google.auth.load_credentials_from_file(
+            filename, scopes=scopes, quota_project_id=quota_project_id
+        )
+        return credentials
+    else:
+        raise EnvironmentError(
+            "client_options.credentials_file is only supported in google-auth."
+        )
+
+
+def default_credentials(scopes=None, quota_project_id=None):
+    """Returns Application Default Credentials."""
+    if HAS_GOOGLE_AUTH:
+        credentials, _ = google.auth.default(
+            scopes=scopes, quota_project_id=quota_project_id
+        )
+        return credentials
+    elif HAS_OAUTH2CLIENT:
+        if scopes is not None or quota_project_id is not None:
+            raise EnvironmentError(
+                "client_options.scopes and client_options.quota_project_id are not supported in oauth2client."
+                "Please install google-auth."
+            )
+        return oauth2client.client.GoogleCredentials.get_application_default()
+    else:
+        raise EnvironmentError(
+            "No authentication library is available. Please install either "
+            "google-auth or oauth2client."
+        )
+
+
+def with_scopes(credentials, scopes):
+    """Scopes the credentials if necessary.
+
+    Args:
+        credentials (Union[
+            google.auth.credentials.Credentials,
+            oauth2client.client.Credentials]): The credentials to scope.
+        scopes (Sequence[str]): The list of scopes.
+
+    Returns:
+        Union[google.auth.credentials.Credentials,
+            oauth2client.client.Credentials]: The scoped credentials.
+    """
+    if HAS_GOOGLE_AUTH and isinstance(credentials, google.auth.credentials.Credentials):
+        return google.auth.credentials.with_scopes_if_required(credentials, scopes)
+    else:
+        try:
+            if credentials.create_scoped_required():
+                return credentials.create_scoped(scopes)
+            else:
+                return credentials
+        except AttributeError:
+            return credentials
+
+
+def authorized_http(credentials):
+    """Returns an http client that is authorized with the given credentials.
+
+    Args:
+        credentials (Union[
+            google.auth.credentials.Credentials,
+            oauth2client.client.Credentials]): The credentials to use.
+
+    Returns:
+        Union[httplib2.Http, google_auth_httplib2.AuthorizedHttp]: An
+            authorized http client.
+    """
+    from googleapiclient.http import build_http
+
+    if HAS_GOOGLE_AUTH and isinstance(credentials, google.auth.credentials.Credentials):
+        if google_auth_httplib2 is None:
+            raise ValueError(
+                "Credentials from google.auth specified, but "
+                "google-api-python-client is unable to use these credentials "
+                "unless google-auth-httplib2 is installed. Please install "
+                "google-auth-httplib2."
+            )
+        return google_auth_httplib2.AuthorizedHttp(credentials, http=build_http())
+    else:
+        return credentials.authorize(build_http())
+
+
+def refresh_credentials(credentials):
+    # Refresh must use a new http instance, as the one associated with the
+    # credentials could be a AuthorizedHttp or an oauth2client-decorated
+    # Http instance which would cause a weird recursive loop of refreshing
+    # and likely tear a hole in spacetime.
+    refresh_http = httplib2.Http()
+    if HAS_GOOGLE_AUTH and isinstance(credentials, google.auth.credentials.Credentials):
+        request = google_auth_httplib2.Request(refresh_http)
+        return credentials.refresh(request)
+    else:
+        return credentials.refresh(refresh_http)
+
+
+def apply_credentials(credentials, headers):
+    # oauth2client and google-auth have the same interface for this.
+    if not is_valid(credentials):
+        refresh_credentials(credentials)
+    return credentials.apply(headers)
+
+
+def is_valid(credentials):
+    if HAS_GOOGLE_AUTH and isinstance(credentials, google.auth.credentials.Credentials):
+        return credentials.valid
+    else:
+        return (
+            credentials.access_token is not None
+            and not credentials.access_token_expired
+        )
+
+
+def get_credentials_from_http(http):
+    if http is None:
+        return None
+    elif hasattr(http.request, "credentials"):
+        return http.request.credentials
+    elif hasattr(http, "credentials") and not isinstance(
+        http.credentials, httplib2.Credentials
+    ):
+        return http.credentials
+    else:
+        return None

src/gam/googleapiclient/_helpers.py

@@ -0,0 +1,207 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper functions for commonly used utilities."""
+
+import functools
+import inspect
+import logging
+import urllib
+
+logger = logging.getLogger(__name__)
+
+POSITIONAL_WARNING = "WARNING"
+POSITIONAL_EXCEPTION = "EXCEPTION"
+POSITIONAL_IGNORE = "IGNORE"
+POSITIONAL_SET = frozenset(
+    [POSITIONAL_WARNING, POSITIONAL_EXCEPTION, POSITIONAL_IGNORE]
+)
+
+positional_parameters_enforcement = POSITIONAL_WARNING
+
+_SYM_LINK_MESSAGE = "File: {0}: Is a symbolic link."
+_IS_DIR_MESSAGE = "{0}: Is a directory"
+_MISSING_FILE_MESSAGE = "Cannot access {0}: No such file or directory"
+
+
+def positional(max_positional_args):
+    """A decorator to declare that only the first N arguments may be positional.
+
+    This decorator makes it easy to support Python 3 style keyword-only
+    parameters. For example, in Python 3 it is possible to write::
+
+        def fn(pos1, *, kwonly1=None, kwonly2=None):
+            ...
+
+    All named parameters after ``*`` must be a keyword::
+
+        fn(10, 'kw1', 'kw2')  # Raises exception.
+        fn(10, kwonly1='kw1')  # Ok.
+
+    Example
+    ^^^^^^^
+
+    To define a function like above, do::
+
+        @positional(1)
+        def fn(pos1, kwonly1=None, kwonly2=None):
+            ...
+
+    If no default value is provided to a keyword argument, it becomes a
+    required keyword argument::
+
+        @positional(0)
+        def fn(required_kw):
+            ...
+
+    This must be called with the keyword parameter::
+
+        fn()  # Raises exception.
+        fn(10)  # Raises exception.
+        fn(required_kw=10)  # Ok.
+
+    When defining instance or class methods always remember to account for
+    ``self`` and ``cls``::
+
+        class MyClass(object):
+
+            @positional(2)
+            def my_method(self, pos1, kwonly1=None):
+                ...
+
+            @classmethod
+            @positional(2)
+            def my_method(cls, pos1, kwonly1=None):
+                ...
+
+    The positional decorator behavior is controlled by
+    ``_helpers.positional_parameters_enforcement``, which may be set to
+    ``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or
+    ``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do
+    nothing, respectively, if a declaration is violated.
+
+    Args:
+        max_positional_arguments: Maximum number of positional arguments. All
+                                  parameters after this index must be
+                                  keyword only.
+
+    Returns:
+        A decorator that prevents using arguments after max_positional_args
+        from being used as positional parameters.
+
+    Raises:
+        TypeError: if a keyword-only argument is provided as a positional
+                   parameter, but only if
+                   _helpers.positional_parameters_enforcement is set to
+                   POSITIONAL_EXCEPTION.
+    """
+
+    def positional_decorator(wrapped):
+        @functools.wraps(wrapped)
+        def positional_wrapper(*args, **kwargs):
+            if len(args) > max_positional_args:
+                plural_s = ""
+                if max_positional_args != 1:
+                    plural_s = "s"
+                message = (
+                    "{function}() takes at most {args_max} positional "
+                    "argument{plural} ({args_given} given)".format(
+                        function=wrapped.__name__,
+                        args_max=max_positional_args,
+                        args_given=len(args),
+                        plural=plural_s,
+                    )
+                )
+                if positional_parameters_enforcement == POSITIONAL_EXCEPTION:
+                    raise TypeError(message)
+                elif positional_parameters_enforcement == POSITIONAL_WARNING:
+                    logger.warning(message)
+            return wrapped(*args, **kwargs)
+
+        return positional_wrapper
+
+    if isinstance(max_positional_args, int):
+        return positional_decorator
+    else:
+        args, _, _, defaults, _, _, _ = inspect.getfullargspec(max_positional_args)
+        return positional(len(args) - len(defaults))(max_positional_args)
+
+
+def parse_unique_urlencoded(content):
+    """Parses unique key-value parameters from urlencoded content.
+
+    Args:
+        content: string, URL-encoded key-value pairs.
+
+    Returns:
+        dict, The key-value pairs from ``content``.
+
+    Raises:
+        ValueError: if one of the keys is repeated.
+    """
+    urlencoded_params = urllib.parse.parse_qs(content)
+    params = {}
+    for key, value in urlencoded_params.items():
+        if len(value) != 1:
+            msg = "URL-encoded content contains a repeated value:" "%s -> %s" % (
+                key,
+                ", ".join(value),
+            )
+            raise ValueError(msg)
+        params[key] = value[0]
+    return params
+
+
+def update_query_params(uri, params):
+    """Updates a URI with new query parameters.
+
+    If a given key from ``params`` is repeated in the ``uri``, then
+    the URI will be considered invalid and an error will occur.
+
+    If the URI is valid, then each value from ``params`` will
+    replace the corresponding value in the query parameters (if
+    it exists).
+
+    Args:
+        uri: string, A valid URI, with potential existing query parameters.
+        params: dict, A dictionary of query parameters.
+
+    Returns:
+        The same URI but with the new query parameters added.
+    """
+    parts = urllib.parse.urlparse(uri)
+    query_params = parse_unique_urlencoded(parts.query)
+    query_params.update(params)
+    new_query = urllib.parse.urlencode(query_params)
+    new_parts = parts._replace(query=new_query)
+    return urllib.parse.urlunparse(new_parts)
+
+
+def _add_query_parameter(url, name, value):
+    """Adds a query parameter to a url.
+
+    Replaces the current value if it already exists in the URL.
+
+    Args:
+        url: string, url to add the query parameter to.
+        name: string, query parameter name.
+        value: string, query parameter value.
+
+    Returns:
+        Updated query parameter. Does not update the url if value is None.
+    """
+    if value is None:
+        return url
+    else:
+        return update_query_params(url, {name: value})

src/gam/googleapiclient/channel.py

@@ -0,0 +1,315 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Channel notifications support.
+
+Classes and functions to support channel subscriptions and notifications
+on those channels.
+
+Notes:
+  - This code is based on experimental APIs and is subject to change.
+  - Notification does not do deduplication of notification ids, that's up to
+    the receiver.
+  - Storing the Channel between calls is up to the caller.
+
+
+Example setting up a channel:
+
+  # Create a new channel that gets notifications via webhook.
+  channel = new_webhook_channel("https://example.com/my_web_hook")
+
+  # Store the channel, keyed by 'channel.id'. Store it before calling the
+  # watch method because notifications may start arriving before the watch
+  # method returns.
+  ...
+
+  resp = service.objects().watchAll(
+    bucket="some_bucket_id", body=channel.body()).execute()
+  channel.update(resp)
+
+  # Store the channel, keyed by 'channel.id'. Store it after being updated
+  # since the resource_id value will now be correct, and that's needed to
+  # stop a subscription.
+  ...
+
+
+An example Webhook implementation using webapp2. Note that webapp2 puts
+headers in a case insensitive dictionary, as headers aren't guaranteed to
+always be upper case.
+
+  id = self.request.headers[X_GOOG_CHANNEL_ID]
+
+  # Retrieve the channel by id.
+  channel = ...
+
+  # Parse notification from the headers, including validating the id.
+  n = notification_from_headers(channel, self.request.headers)
+
+  # Do app specific stuff with the notification here.
+  if n.resource_state == 'sync':
+    # Code to handle sync state.
+  elif n.resource_state == 'exists':
+    # Code to handle the exists state.
+  elif n.resource_state == 'not_exists':
+    # Code to handle the not exists state.
+
+
+Example of unsubscribing.
+
+  service.channels().stop(channel.body()).execute()
+"""
+from __future__ import absolute_import
+
+import datetime
+import uuid
+
+from googleapiclient import _helpers as util
+from googleapiclient import errors
+
+# The unix time epoch starts at midnight 1970.
+EPOCH = datetime.datetime(1970, 1, 1)
+
+# Map the names of the parameters in the JSON channel description to
+# the parameter names we use in the Channel class.
+CHANNEL_PARAMS = {
+    "address": "address",
+    "id": "id",
+    "expiration": "expiration",
+    "params": "params",
+    "resourceId": "resource_id",
+    "resourceUri": "resource_uri",
+    "type": "type",
+    "token": "token",
+}
+
+X_GOOG_CHANNEL_ID = "X-GOOG-CHANNEL-ID"
+X_GOOG_MESSAGE_NUMBER = "X-GOOG-MESSAGE-NUMBER"
+X_GOOG_RESOURCE_STATE = "X-GOOG-RESOURCE-STATE"
+X_GOOG_RESOURCE_URI = "X-GOOG-RESOURCE-URI"
+X_GOOG_RESOURCE_ID = "X-GOOG-RESOURCE-ID"
+
+
+def _upper_header_keys(headers):
+    new_headers = {}
+    for k, v in headers.items():
+        new_headers[k.upper()] = v
+    return new_headers
+
+
+class Notification(object):
+    """A Notification from a Channel.
+
+    Notifications are not usually constructed directly, but are returned
+    from functions like notification_from_headers().
+
+    Attributes:
+      message_number: int, The unique id number of this notification.
+      state: str, The state of the resource being monitored.
+      uri: str, The address of the resource being monitored.
+      resource_id: str, The unique identifier of the version of the resource at
+        this event.
+    """
+
+    @util.positional(5)
+    def __init__(self, message_number, state, resource_uri, resource_id):
+        """Notification constructor.
+
+        Args:
+          message_number: int, The unique id number of this notification.
+          state: str, The state of the resource being monitored. Can be one
+            of "exists", "not_exists", or "sync".
+          resource_uri: str, The address of the resource being monitored.
+          resource_id: str, The identifier of the watched resource.
+        """
+        self.message_number = message_number
+        self.state = state
+        self.resource_uri = resource_uri
+        self.resource_id = resource_id
+
+
+class Channel(object):
+    """A Channel for notifications.
+
+    Usually not constructed directly, instead it is returned from helper
+    functions like new_webhook_channel().
+
+    Attributes:
+      type: str, The type of delivery mechanism used by this channel. For
+        example, 'web_hook'.
+      id: str, A UUID for the channel.
+      token: str, An arbitrary string associated with the channel that
+        is delivered to the target address with each event delivered
+        over this channel.
+      address: str, The address of the receiving entity where events are
+        delivered. Specific to the channel type.
+      expiration: int, The time, in milliseconds from the epoch, when this
+        channel will expire.
+      params: dict, A dictionary of string to string, with additional parameters
+        controlling delivery channel behavior.
+      resource_id: str, An opaque id that identifies the resource that is
+        being watched. Stable across different API versions.
+      resource_uri: str, The canonicalized ID of the watched resource.
+    """
+
+    @util.positional(5)
+    def __init__(
+        self,
+        type,
+        id,
+        token,
+        address,
+        expiration=None,
+        params=None,
+        resource_id="",
+        resource_uri="",
+    ):
+        """Create a new Channel.
+
+        In user code, this Channel constructor will not typically be called
+        manually since there are functions for creating channels for each specific
+        type with a more customized set of arguments to pass.
+
+        Args:
+          type: str, The type of delivery mechanism used by this channel. For
+            example, 'web_hook'.
+          id: str, A UUID for the channel.
+          token: str, An arbitrary string associated with the channel that
+            is delivered to the target address with each event delivered
+            over this channel.
+          address: str,  The address of the receiving entity where events are
+            delivered. Specific to the channel type.
+          expiration: int, The time, in milliseconds from the epoch, when this
+            channel will expire.
+          params: dict, A dictionary of string to string, with additional parameters
+            controlling delivery channel behavior.
+          resource_id: str, An opaque id that identifies the resource that is
+            being watched. Stable across different API versions.
+          resource_uri: str, The canonicalized ID of the watched resource.
+        """
+        self.type = type
+        self.id = id
+        self.token = token
+        self.address = address
+        self.expiration = expiration
+        self.params = params
+        self.resource_id = resource_id
+        self.resource_uri = resource_uri
+
+    def body(self):
+        """Build a body from the Channel.
+
+        Constructs a dictionary that's appropriate for passing into watch()
+        methods as the value of body argument.
+
+        Returns:
+          A dictionary representation of the channel.
+        """
+        result = {
+            "id": self.id,
+            "token": self.token,
+            "type": self.type,
+            "address": self.address,
+        }
+        if self.params:
+            result["params"] = self.params
+        if self.resource_id:
+            result["resourceId"] = self.resource_id
+        if self.resource_uri:
+            result["resourceUri"] = self.resource_uri
+        if self.expiration:
+            result["expiration"] = self.expiration
+
+        return result
+
+    def update(self, resp):
+        """Update a channel with information from the response of watch().
+
+        When a request is sent to watch() a resource, the response returned
+        from the watch() request is a dictionary with updated channel information,
+        such as the resource_id, which is needed when stopping a subscription.
+
+        Args:
+          resp: dict, The response from a watch() method.
+        """
+        for json_name, param_name in CHANNEL_PARAMS.items():
+            value = resp.get(json_name)
+            if value is not None:
+                setattr(self, param_name, value)
+
+
+def notification_from_headers(channel, headers):
+    """Parse a notification from the webhook request headers, validate
+      the notification, and return a Notification object.
+
+    Args:
+      channel: Channel, The channel that the notification is associated with.
+      headers: dict, A dictionary like object that contains the request headers
+        from the webhook HTTP request.
+
+    Returns:
+      A Notification object.
+
+    Raises:
+      errors.InvalidNotificationError if the notification is invalid.
+      ValueError if the X-GOOG-MESSAGE-NUMBER can't be converted to an int.
+    """
+    headers = _upper_header_keys(headers)
+    channel_id = headers[X_GOOG_CHANNEL_ID]
+    if channel.id != channel_id:
+        raise errors.InvalidNotificationError(
+            "Channel id mismatch: %s != %s" % (channel.id, channel_id)
+        )
+    else:
+        message_number = int(headers[X_GOOG_MESSAGE_NUMBER])
+        state = headers[X_GOOG_RESOURCE_STATE]
+        resource_uri = headers[X_GOOG_RESOURCE_URI]
+        resource_id = headers[X_GOOG_RESOURCE_ID]
+        return Notification(message_number, state, resource_uri, resource_id)
+
+
+@util.positional(2)
+def new_webhook_channel(url, token=None, expiration=None, params=None):
+    """Create a new webhook Channel.
+
+    Args:
+      url: str, URL to post notifications to.
+      token: str, An arbitrary string associated with the channel that
+        is delivered to the target address with each notification delivered
+        over this channel.
+      expiration: datetime.datetime, A time in the future when the channel
+        should expire. Can also be None if the subscription should use the
+        default expiration. Note that different services may have different
+        limits on how long a subscription lasts. Check the response from the
+        watch() method to see the value the service has set for an expiration
+        time.
+      params: dict, Extra parameters to pass on channel creation. Currently
+        not used for webhook channels.
+    """
+    expiration_ms = 0
+    if expiration:
+        delta = expiration - EPOCH
+        expiration_ms = (
+            delta.microseconds / 1000 + (delta.seconds + delta.days * 24 * 3600) * 1000
+        )
+        if expiration_ms < 0:
+            expiration_ms = 0
+
+    return Channel(
+        "web_hook",
+        str(uuid.uuid4()),
+        token,
+        url,
+        expiration=expiration_ms,
+        params=params,
+    )

src/gam/googleapiclient/discovery_cache/__init__.py

@@ -0,0 +1,78 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Caching utility for the discovery document."""
+
+from __future__ import absolute_import
+
+import logging
+import os
+
+LOGGER = logging.getLogger(__name__)
+
+DISCOVERY_DOC_MAX_AGE = 60 * 60 * 24  # 1 day
+DISCOVERY_DOC_DIR = os.path.join(
+    os.path.dirname(os.path.realpath(__file__)), "documents"
+)
+
+
+def autodetect():
+    """Detects an appropriate cache module and returns it.
+
+    Returns:
+      googleapiclient.discovery_cache.base.Cache, a cache object which
+      is auto detected, or None if no cache object is available.
+    """
+    if "GAE_ENV" in os.environ:
+        try:
+            from . import appengine_memcache
+
+            return appengine_memcache.cache
+        except Exception:
+            pass
+    try:
+        from . import file_cache
+
+        return file_cache.cache
+    except Exception:
+        LOGGER.info(
+            "file_cache is only supported with oauth2client<4.0.0", exc_info=False
+        )
+        return None
+
+
+def get_static_doc(serviceName, version):
+    """Retrieves the discovery document from the directory defined in
+    DISCOVERY_DOC_DIR corresponding to the serviceName and version provided.
+
+    Args:
+        serviceName: string, name of the service.
+        version: string, the version of the service.
+
+    Returns:
+        A string containing the contents of the JSON discovery document,
+        otherwise None if the JSON discovery document was not found.
+    """
+
+    content = None
+    doc_name = "{}.{}.json".format(serviceName, version)
+
+    try:
+        with open(os.path.join(DISCOVERY_DOC_DIR, doc_name), "r") as f:
+            content = f.read()
+    except FileNotFoundError:
+        # File does not exist. Nothing to do here.
+        pass
+
+    return content

src/gam/googleapiclient/discovery_cache/appengine_memcache.py

@@ -0,0 +1,55 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""App Engine memcache based cache for the discovery document."""
+
+import logging
+
+# This is only an optional dependency because we only import this
+# module when google.appengine.api.memcache is available.
+from google.appengine.api import memcache
+
+from . import base
+from ..discovery_cache import DISCOVERY_DOC_MAX_AGE
+
+LOGGER = logging.getLogger(__name__)
+
+NAMESPACE = "google-api-client"
+
+
+class Cache(base.Cache):
+    """A cache with app engine memcache API."""
+
+    def __init__(self, max_age):
+        """Constructor.
+
+        Args:
+          max_age: Cache expiration in seconds.
+        """
+        self._max_age = max_age
+
+    def get(self, url):
+        try:
+            return memcache.get(url, namespace=NAMESPACE)
+        except Exception as e:
+            LOGGER.warning(e, exc_info=True)
+
+    def set(self, url, content):
+        try:
+            memcache.set(url, content, time=int(self._max_age), namespace=NAMESPACE)
+        except Exception as e:
+            LOGGER.warning(e, exc_info=True)
+
+
+cache = Cache(max_age=DISCOVERY_DOC_MAX_AGE)

src/gam/googleapiclient/discovery_cache/base.py

@@ -0,0 +1,46 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""An abstract class for caching the discovery document."""
+
+import abc
+
+
+class Cache(object):
+    """A base abstract cache class."""
+
+    __metaclass__ = abc.ABCMeta
+
+    @abc.abstractmethod
+    def get(self, url):
+        """Gets the content from the memcache with a given key.
+
+        Args:
+          url: string, the key for the cache.
+
+        Returns:
+          object, the value in the cache for the given key, or None if the key is
+          not in the cache.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def set(self, url, content):
+        """Sets the given key and content in the cache.
+
+        Args:
+          url: string, the key for the cache.
+          content: string, the discovery document.
+        """
+        raise NotImplementedError()

src/gam/googleapiclient/discovery_cache/file_cache.py

@@ -0,0 +1,145 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""File based cache for the discovery document.
+
+The cache is stored in a single file so that multiple processes can
+share the same cache. It locks the file whenever accessing to the
+file. When the cache content is corrupted, it will be initialized with
+an empty cache.
+"""
+
+from __future__ import division
+
+import datetime
+import json
+import logging
+import os
+import tempfile
+
+try:
+    from oauth2client.contrib.locked_file import LockedFile
+except ImportError:
+    # oauth2client < 2.0.0
+    try:
+        from oauth2client.locked_file import LockedFile
+    except ImportError:
+        # oauth2client > 4.0.0 or google-auth
+        raise ImportError(
+            "file_cache is unavailable when using oauth2client >= 4.0.0 or google-auth"
+        )
+
+from . import base
+from ..discovery_cache import DISCOVERY_DOC_MAX_AGE
+
+LOGGER = logging.getLogger(__name__)
+
+FILENAME = "google-api-python-client-discovery-doc.cache"
+EPOCH = datetime.datetime(1970, 1, 1)
+
+
+def _to_timestamp(date):
+    try:
+        return (date - EPOCH).total_seconds()
+    except AttributeError:
+        # The following is the equivalent of total_seconds() in Python2.6.
+        # See also: https://docs.python.org/2/library/datetime.html
+        delta = date - EPOCH
+        return (
+            delta.microseconds + (delta.seconds + delta.days * 24 * 3600) * 10**6
+        ) / 10**6
+
+
+def _read_or_initialize_cache(f):
+    f.file_handle().seek(0)
+    try:
+        cache = json.load(f.file_handle())
+    except Exception:
+        # This means it opens the file for the first time, or the cache is
+        # corrupted, so initializing the file with an empty dict.
+        cache = {}
+        f.file_handle().truncate(0)
+        f.file_handle().seek(0)
+        json.dump(cache, f.file_handle())
+    return cache
+
+
+class Cache(base.Cache):
+    """A file based cache for the discovery documents."""
+
+    def __init__(self, max_age):
+        """Constructor.
+
+        Args:
+          max_age: Cache expiration in seconds.
+        """
+        self._max_age = max_age
+        self._file = os.path.join(tempfile.gettempdir(), FILENAME)
+        f = LockedFile(self._file, "a+", "r")
+        try:
+            f.open_and_lock()
+            if f.is_locked():
+                _read_or_initialize_cache(f)
+            # If we can not obtain the lock, other process or thread must
+            # have initialized the file.
+        except Exception as e:
+            LOGGER.warning(e, exc_info=True)
+        finally:
+            f.unlock_and_close()
+
+    def get(self, url):
+        f = LockedFile(self._file, "r+", "r")
+        try:
+            f.open_and_lock()
+            if f.is_locked():
+                cache = _read_or_initialize_cache(f)
+                if url in cache:
+                    content, t = cache.get(url, (None, 0))
+                    if _to_timestamp(datetime.datetime.now()) < t + self._max_age:
+                        return content
+                return None
+            else:
+                LOGGER.debug("Could not obtain a lock for the cache file.")
+                return None
+        except Exception as e:
+            LOGGER.warning(e, exc_info=True)
+        finally:
+            f.unlock_and_close()
+
+    def set(self, url, content):
+        f = LockedFile(self._file, "r+", "r")
+        try:
+            f.open_and_lock()
+            if f.is_locked():
+                cache = _read_or_initialize_cache(f)
+                cache[url] = (content, _to_timestamp(datetime.datetime.now()))
+                # Remove stale cache.
+                for k, (_, timestamp) in list(cache.items()):
+                    if (
+                        _to_timestamp(datetime.datetime.now())
+                        >= timestamp + self._max_age
+                    ):
+                        del cache[k]
+                f.file_handle().truncate(0)
+                f.file_handle().seek(0)
+                json.dump(cache, f.file_handle())
+            else:
+                LOGGER.debug("Could not obtain a lock for the cache file.")
+        except Exception as e:
+            LOGGER.warning(e, exc_info=True)
+        finally:
+            f.unlock_and_close()
+
+
+cache = Cache(max_age=DISCOVERY_DOC_MAX_AGE)

src/gam/googleapiclient/errors.py

@@ -0,0 +1,197 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Errors for the library.
+
+All exceptions defined by the library
+should be defined in this file.
+"""
+from __future__ import absolute_import
+
+__author__ = "jcgregorio@google.com (Joe Gregorio)"
+
+import json
+
+from googleapiclient import _helpers as util
+
+
+class Error(Exception):
+    """Base error for this module."""
+
+    pass
+
+
+class HttpError(Error):
+    """HTTP data was invalid or unexpected."""
+
+    @util.positional(3)
+    def __init__(self, resp, content, uri=None):
+        self.resp = resp
+        if not isinstance(content, bytes):
+            raise TypeError("HTTP content should be bytes")
+        self.content = content
+        self.uri = uri
+        self.error_details = ""
+        self.reason = self._get_reason()
+
+    @property
+    def status_code(self):
+        """Return the HTTP status code from the response content."""
+        return self.resp.status
+
+    def _get_reason(self):
+        """Calculate the reason for the error from the response content."""
+        reason = self.resp.reason
+        try:
+            try:
+                data = json.loads(self.content.decode("utf-8"))
+            except json.JSONDecodeError:
+                # In case it is not json
+                data = self.content.decode("utf-8")
+            if isinstance(data, dict):
+                reason = data["error"]["message"]
+                error_detail_keyword = next(
+                    (
+                        kw
+                        for kw in ["detail", "details", "errors", "message"]
+                        if kw in data["error"]
+                    ),
+                    "",
+                )
+                if error_detail_keyword:
+                    self.error_details = data["error"][error_detail_keyword]
+            elif isinstance(data, list) and len(data) > 0:
+                first_error = data[0]
+                reason = first_error["error"]["message"]
+                if "details" in first_error["error"]:
+                    self.error_details = first_error["error"]["details"]
+            else:
+                self.error_details = data
+        except (ValueError, KeyError, TypeError):
+            pass
+        if reason is None:
+            reason = ""
+        return reason.strip()
+
+    def __repr__(self):
+        if self.error_details:
+            return '<HttpError %s when requesting %s returned "%s". Details: "%s">' % (
+                self.resp.status,
+                self.uri,
+                self.reason,
+                self.error_details,
+            )
+        elif self.uri:
+            return '<HttpError %s when requesting %s returned "%s">' % (
+                self.resp.status,
+                self.uri,
+                self.reason,
+            )
+        else:
+            return '<HttpError %s "%s">' % (self.resp.status, self.reason)
+
+    __str__ = __repr__
+
+
+class InvalidJsonError(Error):
+    """The JSON returned could not be parsed."""
+
+    pass
+
+
+class UnknownFileType(Error):
+    """File type unknown or unexpected."""
+
+    pass
+
+
+class UnknownLinkType(Error):
+    """Link type unknown or unexpected."""
+
+    pass
+
+
+class UnknownApiNameOrVersion(Error):
+    """No API with that name and version exists."""
+
+    pass
+
+
+class UnacceptableMimeTypeError(Error):
+    """That is an unacceptable mimetype for this operation."""
+
+    pass
+
+
+class MediaUploadSizeError(Error):
+    """Media is larger than the method can accept."""
+
+    pass
+
+
+class ResumableUploadError(HttpError):
+    """Error occurred during resumable upload."""
+
+    pass
+
+
+class InvalidChunkSizeError(Error):
+    """The given chunksize is not valid."""
+
+    pass
+
+
+class InvalidNotificationError(Error):
+    """The channel Notification is invalid."""
+
+    pass
+
+
+class BatchError(HttpError):
+    """Error occurred during batch operations."""
+
+    @util.positional(2)
+    def __init__(self, reason, resp=None, content=None):
+        self.resp = resp
+        self.content = content
+        self.reason = reason
+
+    def __repr__(self):
+        if getattr(self.resp, "status", None) is None:
+            return '<BatchError "%s">' % (self.reason)
+        else:
+            return '<BatchError %s "%s">' % (self.resp.status, self.reason)
+
+    __str__ = __repr__
+
+
+class UnexpectedMethodError(Error):
+    """Exception raised by RequestMockBuilder on unexpected calls."""
+
+    @util.positional(1)
+    def __init__(self, methodId=None):
+        """Constructor for an UnexpectedMethodError."""
+        super(UnexpectedMethodError, self).__init__(
+            "Received unexpected call %s" % methodId
+        )
+
+
+class UnexpectedBodyError(Error):
+    """Exception raised by RequestMockBuilder on unexpected bodies."""
+
+    def __init__(self, expected, provided):
+        """Constructor for an UnexpectedMethodError."""
+        super(UnexpectedBodyError, self).__init__(
+            "Expected: [%s] - Provided: [%s]" % (expected, provided)
+        )

src/gam/googleapiclient/mimeparse.py

@@ -0,0 +1,183 @@
+# Copyright 2014 Joe Gregorio
+#
+# Licensed under the MIT License
+
+"""MIME-Type Parser
+
+This module provides basic functions for handling mime-types. It can handle
+matching mime-types against a list of media-ranges. See section 14.1 of the
+HTTP specification [RFC 2616] for a complete explanation.
+
+   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+
+Contents:
+ - parse_mime_type():   Parses a mime-type into its component parts.
+ - parse_media_range(): Media-ranges are mime-types with wild-cards and a 'q'
+                          quality parameter.
+ - quality():           Determines the quality ('q') of a mime-type when
+                          compared against a list of media-ranges.
+ - quality_parsed():    Just like quality() except the second parameter must be
+                          pre-parsed.
+ - best_match():        Choose the mime-type with the highest quality ('q')
+                          from a list of candidates.
+"""
+from __future__ import absolute_import
+
+from functools import reduce
+
+__version__ = "0.1.3"
+__author__ = "Joe Gregorio"
+__email__ = "joe@bitworking.org"
+__license__ = "MIT License"
+__credits__ = ""
+
+
+def parse_mime_type(mime_type):
+    """Parses a mime-type into its component parts.
+
+    Carves up a mime-type and returns a tuple of the (type, subtype, params)
+    where 'params' is a dictionary of all the parameters for the media range.
+    For example, the media range 'application/xhtml;q=0.5' would get parsed
+    into:
+
+       ('application', 'xhtml', {'q', '0.5'})
+    """
+    parts = mime_type.split(";")
+    params = dict(
+        [tuple([s.strip() for s in param.split("=", 1)]) for param in parts[1:]]
+    )
+    full_type = parts[0].strip()
+    # Java URLConnection class sends an Accept header that includes a
+    # single '*'. Turn it into a legal wildcard.
+    if full_type == "*":
+        full_type = "*/*"
+    (type, subtype) = full_type.split("/")
+
+    return (type.strip(), subtype.strip(), params)
+
+
+def parse_media_range(range):
+    """Parse a media-range into its component parts.
+
+    Carves up a media range and returns a tuple of the (type, subtype,
+    params) where 'params' is a dictionary of all the parameters for the media
+    range.  For example, the media range 'application/*;q=0.5' would get parsed
+    into:
+
+       ('application', '*', {'q', '0.5'})
+
+    In addition this function also guarantees that there is a value for 'q'
+    in the params dictionary, filling it in with a proper default if
+    necessary.
+    """
+    (type, subtype, params) = parse_mime_type(range)
+    if (
+        "q" not in params
+        or not params["q"]
+        or not float(params["q"])
+        or float(params["q"]) > 1
+        or float(params["q"]) < 0
+    ):
+        params["q"] = "1"
+
+    return (type, subtype, params)
+
+
+def fitness_and_quality_parsed(mime_type, parsed_ranges):
+    """Find the best match for a mime-type amongst parsed media-ranges.
+
+    Find the best match for a given mime-type against a list of media_ranges
+    that have already been parsed by parse_media_range(). Returns a tuple of
+    the fitness value and the value of the 'q' quality parameter of the best
+    match, or (-1, 0) if no match was found. Just as for quality_parsed(),
+    'parsed_ranges' must be a list of parsed media ranges.
+    """
+    best_fitness = -1
+    best_fit_q = 0
+    (target_type, target_subtype, target_params) = parse_media_range(mime_type)
+    for (type, subtype, params) in parsed_ranges:
+        type_match = type == target_type or type == "*" or target_type == "*"
+        subtype_match = (
+            subtype == target_subtype or subtype == "*" or target_subtype == "*"
+        )
+        if type_match and subtype_match:
+            param_matches = reduce(
+                lambda x, y: x + y,
+                [
+                    1
+                    for (key, value) in target_params.items()
+                    if key != "q" and key in params and value == params[key]
+                ],
+                0,
+            )
+            fitness = (type == target_type) and 100 or 0
+            fitness += (subtype == target_subtype) and 10 or 0
+            fitness += param_matches
+            if fitness > best_fitness:
+                best_fitness = fitness
+                best_fit_q = params["q"]
+
+    return best_fitness, float(best_fit_q)
+
+
+def quality_parsed(mime_type, parsed_ranges):
+    """Find the best match for a mime-type amongst parsed media-ranges.
+
+    Find the best match for a given mime-type against a list of media_ranges
+    that have already been parsed by parse_media_range(). Returns the 'q'
+    quality parameter of the best match, 0 if no match was found. This function
+    bahaves the same as quality() except that 'parsed_ranges' must be a list of
+    parsed media ranges.
+    """
+
+    return fitness_and_quality_parsed(mime_type, parsed_ranges)[1]
+
+
+def quality(mime_type, ranges):
+    """Return the quality ('q') of a mime-type against a list of media-ranges.
+
+    Returns the quality 'q' of a mime-type when compared against the
+    media-ranges in ranges. For example:
+
+    >>> quality('text/html','text/*;q=0.3, text/html;q=0.7,
+                  text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5')
+    0.7
+
+    """
+    parsed_ranges = [parse_media_range(r) for r in ranges.split(",")]
+
+    return quality_parsed(mime_type, parsed_ranges)
+
+
+def best_match(supported, header):
+    """Return mime-type with the highest quality ('q') from list of candidates.
+
+    Takes a list of supported mime-types and finds the best match for all the
+    media-ranges listed in header. The value of header must be a string that
+    conforms to the format of the HTTP Accept: header. The value of 'supported'
+    is a list of mime-types. The list of supported mime-types should be sorted
+    in order of increasing desirability, in case of a situation where there is
+    a tie.
+
+    >>> best_match(['application/xbel+xml', 'text/xml'],
+                   'text/*;q=0.5,*/*; q=0.1')
+    'text/xml'
+    """
+    split_header = _filter_blank(header.split(","))
+    parsed_header = [parse_media_range(r) for r in split_header]
+    weighted_matches = []
+    pos = 0
+    for mime_type in supported:
+        weighted_matches.append(
+            (fitness_and_quality_parsed(mime_type, parsed_header), pos, mime_type)
+        )
+        pos += 1
+    weighted_matches.sort()
+
+    return weighted_matches[-1][0][1] and weighted_matches[-1][2] or ""
+
+
+def _filter_blank(i):
+    for s in i:
+        if s.strip():
+            yield s

src/gam/googleapiclient/model.py

@@ -0,0 +1,409 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Model objects for requests and responses.
+
+Each API may support one or more serializations, such
+as JSON, Atom, etc. The model classes are responsible
+for converting between the wire format and the Python
+object representation.
+"""
+from __future__ import absolute_import
+
+__author__ = "jcgregorio@google.com (Joe Gregorio)"
+
+import json
+import logging
+import platform
+import urllib
+
+from googleapiclient import version as googleapiclient_version
+from googleapiclient.errors import HttpError
+
+_LIBRARY_VERSION = googleapiclient_version.__version__
+_PY_VERSION = platform.python_version()
+
+LOGGER = logging.getLogger(__name__)
+
+dump_request_response = False
+
+
+def _abstract():
+    raise NotImplementedError("You need to override this function")
+
+
+class Model(object):
+    """Model base class.
+
+    All Model classes should implement this interface.
+    The Model serializes and de-serializes between a wire
+    format such as JSON and a Python object representation.
+    """
+
+    def request(self, headers, path_params, query_params, body_value):
+        """Updates outgoing requests with a serialized body.
+
+        Args:
+          headers: dict, request headers
+          path_params: dict, parameters that appear in the request path
+          query_params: dict, parameters that appear in the query
+          body_value: object, the request body as a Python object, which must be
+                      serializable.
+        Returns:
+          A tuple of (headers, path_params, query, body)
+
+          headers: dict, request headers
+          path_params: dict, parameters that appear in the request path
+          query: string, query part of the request URI
+          body: string, the body serialized in the desired wire format.
+        """
+        _abstract()
+
+    def response(self, resp, content):
+        """Convert the response wire format into a Python object.
+
+        Args:
+          resp: httplib2.Response, the HTTP response headers and status
+          content: string, the body of the HTTP response
+
+        Returns:
+          The body de-serialized as a Python object.
+
+        Raises:
+          googleapiclient.errors.HttpError if a non 2xx response is received.
+        """
+        _abstract()
+
+
+class BaseModel(Model):
+    """Base model class.
+
+    Subclasses should provide implementations for the "serialize" and
+    "deserialize" methods, as well as values for the following class attributes.
+
+    Attributes:
+      accept: The value to use for the HTTP Accept header.
+      content_type: The value to use for the HTTP Content-type header.
+      no_content_response: The value to return when deserializing a 204 "No
+          Content" response.
+      alt_param: The value to supply as the "alt" query parameter for requests.
+    """
+
+    accept = None
+    content_type = None
+    no_content_response = None
+    alt_param = None
+
+    def _log_request(self, headers, path_params, query, body):
+        """Logs debugging information about the request if requested."""
+        if dump_request_response:
+            LOGGER.info("--request-start--")
+            LOGGER.info("-headers-start-")
+            for h, v in headers.items():
+                LOGGER.info("%s: %s", h, v)
+            LOGGER.info("-headers-end-")
+            LOGGER.info("-path-parameters-start-")
+            for h, v in path_params.items():
+                LOGGER.info("%s: %s", h, v)
+            LOGGER.info("-path-parameters-end-")
+            LOGGER.info("body: %s", body)
+            LOGGER.info("query: %s", query)
+            LOGGER.info("--request-end--")
+
+    def request(self, headers, path_params, query_params, body_value):
+        """Updates outgoing requests with a serialized body.
+
+        Args:
+          headers: dict, request headers
+          path_params: dict, parameters that appear in the request path
+          query_params: dict, parameters that appear in the query
+          body_value: object, the request body as a Python object, which must be
+                      serializable by json.
+        Returns:
+          A tuple of (headers, path_params, query, body)
+
+          headers: dict, request headers
+          path_params: dict, parameters that appear in the request path
+          query: string, query part of the request URI
+          body: string, the body serialized as JSON
+        """
+        query = self._build_query(query_params)
+        headers["accept"] = self.accept
+        headers["accept-encoding"] = "gzip, deflate"
+        if "user-agent" in headers:
+            headers["user-agent"] += " "
+        else:
+            headers["user-agent"] = ""
+        headers["user-agent"] += "(gzip)"
+        if "x-goog-api-client" in headers:
+            headers["x-goog-api-client"] += " "
+        else:
+            headers["x-goog-api-client"] = ""
+        headers["x-goog-api-client"] += "gdcl/%s gl-python/%s" % (
+            _LIBRARY_VERSION,
+            _PY_VERSION,
+        )
+
+        if body_value is not None:
+            headers["content-type"] = self.content_type
+            body_value = self.serialize(body_value)
+        self._log_request(headers, path_params, query, body_value)
+        return (headers, path_params, query, body_value)
+
+    def _build_query(self, params):
+        """Builds a query string.
+
+        Args:
+          params: dict, the query parameters
+
+        Returns:
+          The query parameters properly encoded into an HTTP URI query string.
+        """
+        if self.alt_param is not None:
+            params.update({"alt": self.alt_param})
+        astuples = []
+        for key, value in params.items():
+            if type(value) == type([]):
+                for x in value:
+                    x = x.encode("utf-8")
+                    astuples.append((key, x))
+            else:
+                if isinstance(value, str) and callable(value.encode):
+                    value = value.encode("utf-8")
+                astuples.append((key, value))
+        return "?" + urllib.parse.urlencode(astuples)
+
+    def _log_response(self, resp, content):
+        """Logs debugging information about the response if requested."""
+        if dump_request_response:
+            LOGGER.info("--response-start--")
+            for h, v in resp.items():
+                LOGGER.info("%s: %s", h, v)
+            if content:
+                LOGGER.info(content)
+            LOGGER.info("--response-end--")
+
+    def response(self, resp, content):
+        """Convert the response wire format into a Python object.
+
+        Args:
+          resp: httplib2.Response, the HTTP response headers and status
+          content: string, the body of the HTTP response
+
+        Returns:
+          The body de-serialized as a Python object.
+
+        Raises:
+          googleapiclient.errors.HttpError if a non 2xx response is received.
+        """
+        self._log_response(resp, content)
+        # Error handling is TBD, for example, do we retry
+        # for some operation/error combinations?
+        if resp.status < 300:
+            if resp.status == 204:
+                # A 204: No Content response should be treated differently
+                # to all the other success states
+                return self.no_content_response
+            return self.deserialize(content)
+        else:
+            LOGGER.debug("Content from bad request was: %r" % content)
+            raise HttpError(resp, content)
+
+    def serialize(self, body_value):
+        """Perform the actual Python object serialization.
+
+        Args:
+          body_value: object, the request body as a Python object.
+
+        Returns:
+          string, the body in serialized form.
+        """
+        _abstract()
+
+    def deserialize(self, content):
+        """Perform the actual deserialization from response string to Python
+        object.
+
+        Args:
+          content: string, the body of the HTTP response
+
+        Returns:
+          The body de-serialized as a Python object.
+        """
+        _abstract()
+
+
+class JsonModel(BaseModel):
+    """Model class for JSON.
+
+    Serializes and de-serializes between JSON and the Python
+    object representation of HTTP request and response bodies.
+    """
+
+    accept = "application/json"
+    content_type = "application/json"
+    alt_param = "json"
+
+    def __init__(self, data_wrapper=False):
+        """Construct a JsonModel.
+
+        Args:
+          data_wrapper: boolean, wrap requests and responses in a data wrapper
+        """
+        self._data_wrapper = data_wrapper
+
+    def serialize(self, body_value):
+        if (
+            isinstance(body_value, dict)
+            and "data" not in body_value
+            and self._data_wrapper
+        ):
+            body_value = {"data": body_value}
+        return json.dumps(body_value)
+
+    def deserialize(self, content):
+        try:
+            content = content.decode("utf-8")
+        except AttributeError:
+            pass
+        try:
+            body = json.loads(content)
+        except json.decoder.JSONDecodeError:
+            body = content
+        else:
+            if self._data_wrapper and "data" in body:
+                body = body["data"]
+        return body
+
+    @property
+    def no_content_response(self):
+        return {}
+
+
+class RawModel(JsonModel):
+    """Model class for requests that don't return JSON.
+
+    Serializes and de-serializes between JSON and the Python
+    object representation of HTTP request, and returns the raw bytes
+    of the response body.
+    """
+
+    accept = "*/*"
+    content_type = "application/json"
+    alt_param = None
+
+    def deserialize(self, content):
+        return content
+
+    @property
+    def no_content_response(self):
+        return ""
+
+
+class MediaModel(JsonModel):
+    """Model class for requests that return Media.
+
+    Serializes and de-serializes between JSON and the Python
+    object representation of HTTP request, and returns the raw bytes
+    of the response body.
+    """
+
+    accept = "*/*"
+    content_type = "application/json"
+    alt_param = "media"
+
+    def deserialize(self, content):
+        return content
+
+    @property
+    def no_content_response(self):
+        return ""
+
+
+class ProtocolBufferModel(BaseModel):
+    """Model class for protocol buffers.
+
+    Serializes and de-serializes the binary protocol buffer sent in the HTTP
+    request and response bodies.
+    """
+
+    accept = "application/x-protobuf"
+    content_type = "application/x-protobuf"
+    alt_param = "proto"
+
+    def __init__(self, protocol_buffer):
+        """Constructs a ProtocolBufferModel.
+
+        The serialized protocol buffer returned in an HTTP response will be
+        de-serialized using the given protocol buffer class.
+
+        Args:
+          protocol_buffer: The protocol buffer class used to de-serialize a
+          response from the API.
+        """
+        self._protocol_buffer = protocol_buffer
+
+    def serialize(self, body_value):
+        return body_value.SerializeToString()
+
+    def deserialize(self, content):
+        return self._protocol_buffer.FromString(content)
+
+    @property
+    def no_content_response(self):
+        return self._protocol_buffer()
+
+
+def makepatch(original, modified):
+    """Create a patch object.
+
+    Some methods support PATCH, an efficient way to send updates to a resource.
+    This method allows the easy construction of patch bodies by looking at the
+    differences between a resource before and after it was modified.
+
+    Args:
+      original: object, the original deserialized resource
+      modified: object, the modified deserialized resource
+    Returns:
+      An object that contains only the changes from original to modified, in a
+      form suitable to pass to a PATCH method.
+
+    Example usage:
+      item = service.activities().get(postid=postid, userid=userid).execute()
+      original = copy.deepcopy(item)
+      item['object']['content'] = 'This is updated.'
+      service.activities.patch(postid=postid, userid=userid,
+        body=makepatch(original, item)).execute()
+    """
+    patch = {}
+    for key, original_value in original.items():
+        modified_value = modified.get(key, None)
+        if modified_value is None:
+            # Use None to signal that the element is deleted
+            patch[key] = None
+        elif original_value != modified_value:
+            if type(original_value) == type({}):
+                # Recursively descend objects
+                patch[key] = makepatch(original_value, modified_value)
+            else:
+                # In the case of simple types or arrays we just replace
+                patch[key] = modified_value
+        else:
+            # Don't add anything to patch if there's no change
+            pass
+    for key in modified:
+        if key not in original:
+            patch[key] = modified[key]
+
+    return patch

src/gam/googleapiclient/schema.py

@@ -0,0 +1,317 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Schema processing for discovery based APIs
+
+Schemas holds an APIs discovery schemas. It can return those schema as
+deserialized JSON objects, or pretty print them as prototype objects that
+conform to the schema.
+
+For example, given the schema:
+
+ schema = \"\"\"{
+   "Foo": {
+    "type": "object",
+    "properties": {
+     "etag": {
+      "type": "string",
+      "description": "ETag of the collection."
+     },
+     "kind": {
+      "type": "string",
+      "description": "Type of the collection ('calendar#acl').",
+      "default": "calendar#acl"
+     },
+     "nextPageToken": {
+      "type": "string",
+      "description": "Token used to access the next
+         page of this result. Omitted if no further results are available."
+     }
+    }
+   }
+ }\"\"\"
+
+ s = Schemas(schema)
+ print s.prettyPrintByName('Foo')
+
+ Produces the following output:
+
+  {
+   "nextPageToken": "A String", # Token used to access the
+       # next page of this result. Omitted if no further results are available.
+   "kind": "A String", # Type of the collection ('calendar#acl').
+   "etag": "A String", # ETag of the collection.
+  },
+
+The constructor takes a discovery document in which to look up named schema.
+"""
+from __future__ import absolute_import
+
+# TODO(jcgregorio) support format, enum, minimum, maximum
+
+__author__ = "jcgregorio@google.com (Joe Gregorio)"
+
+
+from collections import OrderedDict
+
+from googleapiclient import _helpers as util
+
+
+class Schemas(object):
+    """Schemas for an API."""
+
+    def __init__(self, discovery):
+        """Constructor.
+
+        Args:
+          discovery: object, Deserialized discovery document from which we pull
+            out the named schema.
+        """
+        self.schemas = discovery.get("schemas", {})
+
+        # Cache of pretty printed schemas.
+        self.pretty = {}
+
+    @util.positional(2)
+    def _prettyPrintByName(self, name, seen=None, dent=0):
+        """Get pretty printed object prototype from the schema name.
+
+        Args:
+          name: string, Name of schema in the discovery document.
+          seen: list of string, Names of schema already seen. Used to handle
+            recursive definitions.
+
+        Returns:
+          string, A string that contains a prototype object with
+            comments that conforms to the given schema.
+        """
+        if seen is None:
+            seen = []
+
+        if name in seen:
+            # Do not fall into an infinite loop over recursive definitions.
+            return "# Object with schema name: %s" % name
+        seen.append(name)
+
+        if name not in self.pretty:
+            self.pretty[name] = _SchemaToStruct(
+                self.schemas[name], seen, dent=dent
+            ).to_str(self._prettyPrintByName)
+
+        seen.pop()
+
+        return self.pretty[name]
+
+    def prettyPrintByName(self, name):
+        """Get pretty printed object prototype from the schema name.
+
+        Args:
+          name: string, Name of schema in the discovery document.
+
+        Returns:
+          string, A string that contains a prototype object with
+            comments that conforms to the given schema.
+        """
+        # Return with trailing comma and newline removed.
+        return self._prettyPrintByName(name, seen=[], dent=0)[:-2]
+
+    @util.positional(2)
+    def _prettyPrintSchema(self, schema, seen=None, dent=0):
+        """Get pretty printed object prototype of schema.
+
+        Args:
+          schema: object, Parsed JSON schema.
+          seen: list of string, Names of schema already seen. Used to handle
+            recursive definitions.
+
+        Returns:
+          string, A string that contains a prototype object with
+            comments that conforms to the given schema.
+        """
+        if seen is None:
+            seen = []
+
+        return _SchemaToStruct(schema, seen, dent=dent).to_str(self._prettyPrintByName)
+
+    def prettyPrintSchema(self, schema):
+        """Get pretty printed object prototype of schema.
+
+        Args:
+          schema: object, Parsed JSON schema.
+
+        Returns:
+          string, A string that contains a prototype object with
+            comments that conforms to the given schema.
+        """
+        # Return with trailing comma and newline removed.
+        return self._prettyPrintSchema(schema, dent=0)[:-2]
+
+    def get(self, name, default=None):
+        """Get deserialized JSON schema from the schema name.
+
+        Args:
+          name: string, Schema name.
+          default: object, return value if name not found.
+        """
+        return self.schemas.get(name, default)
+
+
+class _SchemaToStruct(object):
+    """Convert schema to a prototype object."""
+
+    @util.positional(3)
+    def __init__(self, schema, seen, dent=0):
+        """Constructor.
+
+        Args:
+          schema: object, Parsed JSON schema.
+          seen: list, List of names of schema already seen while parsing. Used to
+            handle recursive definitions.
+          dent: int, Initial indentation depth.
+        """
+        # The result of this parsing kept as list of strings.
+        self.value = []
+
+        # The final value of the parsing.
+        self.string = None
+
+        # The parsed JSON schema.
+        self.schema = schema
+
+        # Indentation level.
+        self.dent = dent
+
+        # Method that when called returns a prototype object for the schema with
+        # the given name.
+        self.from_cache = None
+
+        # List of names of schema already seen while parsing.
+        self.seen = seen
+
+    def emit(self, text):
+        """Add text as a line to the output.
+
+        Args:
+          text: string, Text to output.
+        """
+        self.value.extend(["  " * self.dent, text, "\n"])
+
+    def emitBegin(self, text):
+        """Add text to the output, but with no line terminator.
+
+        Args:
+          text: string, Text to output.
+        """
+        self.value.extend(["  " * self.dent, text])
+
+    def emitEnd(self, text, comment):
+        """Add text and comment to the output with line terminator.
+
+        Args:
+          text: string, Text to output.
+          comment: string, Python comment.
+        """
+        if comment:
+            divider = "\n" + "  " * (self.dent + 2) + "# "
+            lines = comment.splitlines()
+            lines = [x.rstrip() for x in lines]
+            comment = divider.join(lines)
+            self.value.extend([text, " # ", comment, "\n"])
+        else:
+            self.value.extend([text, "\n"])
+
+    def indent(self):
+        """Increase indentation level."""
+        self.dent += 1
+
+    def undent(self):
+        """Decrease indentation level."""
+        self.dent -= 1
+
+    def _to_str_impl(self, schema):
+        """Prototype object based on the schema, in Python code with comments.
+
+        Args:
+          schema: object, Parsed JSON schema file.
+
+        Returns:
+          Prototype object based on the schema, in Python code with comments.
+        """
+        stype = schema.get("type")
+        if stype == "object":
+            self.emitEnd("{", schema.get("description", ""))
+            self.indent()
+            if "properties" in schema:
+                properties = schema.get("properties", {})
+                sorted_properties = OrderedDict(sorted(properties.items()))
+                for pname, pschema in sorted_properties.items():
+                    self.emitBegin('"%s": ' % pname)
+                    self._to_str_impl(pschema)
+            elif "additionalProperties" in schema:
+                self.emitBegin('"a_key": ')
+                self._to_str_impl(schema["additionalProperties"])
+            self.undent()
+            self.emit("},")
+        elif "$ref" in schema:
+            schemaName = schema["$ref"]
+            description = schema.get("description", "")
+            s = self.from_cache(schemaName, seen=self.seen)
+            parts = s.splitlines()
+            self.emitEnd(parts[0], description)
+            for line in parts[1:]:
+                self.emit(line.rstrip())
+        elif stype == "boolean":
+            value = schema.get("default", "True or False")
+            self.emitEnd("%s," % str(value), schema.get("description", ""))
+        elif stype == "string":
+            value = schema.get("default", "A String")
+            self.emitEnd('"%s",' % str(value), schema.get("description", ""))
+        elif stype == "integer":
+            value = schema.get("default", "42")
+            self.emitEnd("%s," % str(value), schema.get("description", ""))
+        elif stype == "number":
+            value = schema.get("default", "3.14")
+            self.emitEnd("%s," % str(value), schema.get("description", ""))
+        elif stype == "null":
+            self.emitEnd("None,", schema.get("description", ""))
+        elif stype == "any":
+            self.emitEnd('"",', schema.get("description", ""))
+        elif stype == "array":
+            self.emitEnd("[", schema.get("description"))
+            self.indent()
+            self.emitBegin("")
+            self._to_str_impl(schema["items"])
+            self.undent()
+            self.emit("],")
+        else:
+            self.emit("Unknown type! %s" % stype)
+            self.emitEnd("", "")
+
+        self.string = "".join(self.value)
+        return self.string
+
+    def to_str(self, from_cache):
+        """Prototype object based on the schema, in Python code with comments.
+
+        Args:
+          from_cache: callable(name, seen), Callable that retrieves an object
+             prototype for a schema with the given name. Seen is a list of schema
+             names already seen as we recursively descend the schema definition.
+
+        Returns:
+          Prototype object based on the schema, in Python code with comments.
+          The lines of the code will all be properly indented.
+        """
+        self.from_cache = from_cache
+        return self._to_str_impl(self.schema)

src/gam/googleapiclient/version.py

@@ -0,0 +1,15 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "2.114.0"