whatsnew.txt for 4.30

API no longer available for some reason.

README.md

@@ -13,7 +13,7 @@ The GAM documentation is hosted in the [GitHub Wiki]
 # Mailing List / Discussion group
 The GAM mailing list / discussion group is hosted on [Google Groups].  You can join the list and interact via email, or just post from the web itself.
 # Author
-GAM is maintained by <a href="mailto:jay0lee@gmail.com">Jay Lee</a>. Please direct "how do I?" questions to the mailing list.
+GAM is maintained by <a href="mailto:jay0lee@gmail.com">Jay Lee</a>. Please direct "how do I?" questions to [Google Groups].
 
 [GAM release]: https://git.io/gamreleases
 [GitHub Releases]: https://github.com/jay0lee/GAM/releases

src/GamCommands.txt

@@ -26,6 +26,7 @@ Primitives
 	Google-Drive-storage|
 	Google-Vault
 <SKUID> ::=
+	free|standard|Google-Apps|
 	gafb|gafw|basic|gsuitebasic|Google-Apps-For-Business|
 	gafg|gsuitegovernment|gsuitegov|Google-Apps-For-Government|
 	gams|postini|gsuitegams|gsuitepostini|gsuitemessagesecurity|Google-Apps-For-Postini|
@@ -77,12 +78,13 @@ Named items
 <CalendarColorIndex> ::== <Number in range 1-24>
 <CalendarItem> ::= <EmailAddress>|<String>
 <ClientID> ::= <String>
+<CollaboratorItem> ::= <EmailAddress>|<UniqueID>|<String>
 <CourseAlias> ::= <String>
 <CourseID> ::= <Number>|d:<CourseAlias>
 <CourseParticipantType> ::= teacher|teachers|student|students
 <CrOSID> ::= <String>
 <CrOSItem> ::= <CrOSID>|(query:<QueryCrOS>)
-<DestEmailAddress> ::= <EmailAddress>
+<CustomerID> ::= <String>
 <DomainAlias> ::= <String>
 <DriveFileACLRole> :: =commenter|editor|organizer|owner|reader|writer
 <DriveFileID> ::= <String>
@@ -102,16 +104,20 @@ Named items
 <GroupItem> ::= <EmailAddress>|<UniqueID>|<String>
 <GuardianItem> ::= <EmailAddress>|<UniqueID>|<String>
 <GuardianInvitationID> ::= <String>
+<HoldItem> ::= <UniqueID>|<String>
 <HostName> ::= <String>
 <Key> ::= <String>
 <LabelID> ::= <String>
 <LabelName> ::= <String>
 <LabelReplacement> ::= <String>
 <Marker> ::= <String>
+<MatterItem> ::= <UniqueID>|<String>
+<MaximumNumberOfSeats> ::= <Number>
 <MobileID> ::= <String>
 <MobileItem> ::= <MobileID>|(query:<QueryMobile>)|(query <QueryMobile>)
 <Name> ::= <String>
 <NotificationID> ::= <String>
+<NumberOfSeats> ::= <Number>
 <OrgUnitID> ::= <String>
 <OrgUnitPath> ::= /|(/<String)+
 <ParameterKey> ::= <String>
@@ -126,12 +132,13 @@ Named items
 <QueryCalendar> ::= <String>
 <QueryContact> ::= <String> See: https://developers.google.com/google-apps/contacts/v3/reference#contacts-query-parameters-reference
 <QueryCrOS> ::= <String> See: https://support.google.com/chrome/a/answer/1698333?hl=en
-<QueryDriveFile> :: = <String> See: https://developers.google.com/drive/v2/web/search-parameters 
+<QueryDriveFile> :: = <String> See: https://developers.google.com/drive/v2/web/search-parameters
 <QueryGmail> ::= <String> See: https://support.google.com/mail/answer/7190
 <QueryMobile> ::= <String> See: https://support.google.com/a/answer/1408863?hl=en#search
 <QueryPrinter> ::= <String> See: https://developers.google.com/cloud-print/docs/appInterfaces#search
 <QueryPrintJob> ::= <String> See: https://developers.google.com/cloud-print/docs/appInterfaces#parameters_3
 <QueryUser> :: = <String> See: https://developers.google.com/admin-sdk/directory/v1/guides/search-users
+<QueryVaultCorpus> ::= <String> See: https://developers.google.com/vault/reference/rest/v1/matters.holds#CorpusQuery
 <RequestID> ::= <String>
 <ResourceID> ::= <String>
 <RoleItem> ::= <UniqueID>|<String>
@@ -304,6 +311,48 @@ Named items
 	role|
 	type
 
+<MobileFieldName> ::=
+	adbstatus|
+	applications|
+	basebandversion|
+	bootloaderversion|
+	brand|
+	buildnumber|
+	defaultlanguage|
+	developeroptionsstatus|
+	devicecompromisedstatus|
+	deviceid|
+	devicepasswordstatus|
+	email|
+	encryptionstatus|
+	firstsync|
+	hardware|
+	hardwareid|
+	imei|
+	kernelversion|
+	lastsync|
+	managedaccountisonownerprofile|
+	manufacturer|
+	meid|
+	model|
+	name|
+	networkoperator|
+	os|
+	otheraccountsinfo|
+	privilege|
+	releaseversion|
+	resourceid|
+	securitypatchlevel|
+	serialnumber|
+	status|
+	supportsworkprofile|
+	type|
+	unknownsourcesstatus|
+	useragent|
+	wifimacaddress
+
+<MobileFieldNameList> ::= "<MobileFieldName>(,<MobileFieldName>)*"
+
 <MobileOrderByFieldName> ::=
 	deviceid|email|lastsync|model|name|os|status|type
 
@@ -354,12 +403,14 @@ Items, separated by spaces, with spaces or commas in the items themselves: "'it
 
 <ACLList> ::== "<ACLScope>(,<ACLScope>)*"
 <CalendarList> ::= "<CalendarItem>(,<CalendarItem>)*"
+<CollaboratorItemList> ::= "<CollaboratorItem>(,<CollaboratorItem>)*"
 <CourseAliasList> ::= "<CourseAlias>(,<CourseAlias>)*"
 <CourseIDList> ::= "<CourseID>(,<CourseID>)*"
 <CrOSFieldNameList> ::= "<CrOSFieldName>(,<CrOSFieldName>)*"
 <CrOSList> ::= "<CrOSID>(,<CrOSID>)*"
 <DriveFileList> ::= "<DriveFileItem>(,<DriveFileItem>)*"
 <EmailAddressList> ::= "<EmailAddress>(,<EmailAddress>)*"
+<EmailItemList> ::= "<EmailItem>(,<EmailItem>)*"
 <EventIDList> ::= "<EventID>(,<EventID>)*"
 <FileFormatList> ::= "<FileFormat>(,<FileFormat)*"
 <FilterIDList> ::= "<FilterID>(,<FilterID>)*"
@@ -367,6 +418,7 @@ Items, separated by spaces, with spaces or commas in the items themselves: "'it
 <GroupList> ::= "<GroupItem>(,<GroupItem>)*"
 <GuardianStateList> ::= "<GuardianState>(,<GuardianState>)*"
 <LabelNameList> ::= "<LabelName>(,<LabelName)*"
+<MatterItemList> ::= "<MatterItem>(,<MatterItem>)*"
 <MembersFieldNameList> ::= "<MembersFieldName>(,<MembersFieldName>)*"
 <MobileList> ::= "<MobileId>(,<MobileId>)*"
 <OrgUnitList> ::== "<OrgUnitPath>(,<OrgUnitPath>)*"
@@ -437,7 +489,7 @@ Item attributes
 	(source <String> <URL>)|(privateproperty <PropertyKey> <PropertyValue>)|(sharedproperty <PropertyKey> <PropertyValue>)|
 	(recurrence <RRULE, EXRULE, RDATE and EXDATE line>)|
 	(start allday <Date>)|(start <Time>)|(end allday <Date>)|(end <Time>)|(timezone <Timezone>)|
-	(noreminders|(reminder email|popup|sms <Number>))|
+	(noreminders|(reminder <Number> email|popup|sms))|
 	(colorindex|colorid <EventColorIndex>)
 
 <GroupAttributes> ::=
@@ -471,15 +523,14 @@ Item attributes
 	(whocanviewgroup ANYONE_CAN_VIEW|ALL_IN_DOMAIN_CAN_VIEW|ALL_MEMBERS_CAN_VIEW|ALL_MANAGERS_CAN_VIEW)|
 	(whocanviewmembership ALL_IN_DOMAIN_CAN_VIEW|ALL_MEMBERS_CAN_VIEW|ALL_MANAGERS_CAN_VIEW)
 
-<MobileAttributes> ::=
-	(model <String>)|(os <String>)|(useragent <String>)|
-	(action admin_remote_wipe|wipe|admin_account_wipe|accountwipe|wipeaccount|approve|block|cancel_remote_wipe_then_activate|cancel_remote_wipe_then_block)
+<MobileAction> ::=
+	admin_remote_wipe|wipe|admin_account_wipe|accountwipe|wipeaccount|approve|block|cancel_remote_wipe_then_activate|cancel_remote_wipe_then_block
 
 <PrinterAttributes> ::= (currentquota <Number>)|(dailyquota <Number>)|
 	(defaultdisplayname <String>)|(description <String>)|(displayname <String>)|(firmware <String>)|(gcpversion <String>)|
 	(istosaccepted <Boolean>)|(manufacturer <String>)|(model <String>)|(name <String>)|(ownerid <EmailAddress>)|(proxy <String>)|(public <Boolean>)|
 	(quotaenabled <Boolean>)|(status <Number>)|(type <String>)|(uuid <String>)|
-	(setupurl <URL>)|(supporturl <URL>)|(updateurl <URL>) 
+	(setupurl <URL>)|(supporturl <URL>)|(updateurl <URL>)
 
 <SchemaFieldDefinition> ::=
 	field <FieldName> (type bool|date|double|email|int64|phone|string) [multivalued|multivalue] [indexed] [restricted] [range <Number> <Number>] endfield
@@ -500,12 +551,12 @@ Item attributes
 	(im|ims clear|(type work|home|other|(custom <String>) protocol aim|gtalk|icq|jabber|msn|net_meeting|qq|skype|yahoo|(custom_protocol <String>) <String> [notprimary|primary]))|
 	(ipwhitelisted <Boolean>)|
 	(lastname|familyname <String>)|
-	(note|notes clear|([text_plain|text_html] <String>|(file <FileName>)))|
+	(note|notes clear|([text_plain|text_html] <String>|(file <FileName> [charset <Charset>])))|
 	(organization|organizations clear|([type domain_only|school|unknown|work] [customtype <String>] [name <String>] [title <String>] [department <String>] [symbol <String>]
 		[costcenter <String>]  [location <String>] [description <String>] [domain <String>] notprimary|primary))|
 	(org|ou|orgunitpath <OrgUnitPath>)
 	(password random|<String>)|
-	(phone|phones clear|([type work|home|other|work_fax|home_fax|other_fax|main|company_main|assistant|mobile|work_mobile|pager|work_pager|car|radio|callback|isdn|telex|tty_tdd|grand_central|(custom <String>)
+	(phone|phones clear|([type work|home|other|work_fax|home_fax|other_fax|main|company_main|assistant|mobile|work_mobile|pager|work_pager|car|radio|callback|isdn|telex|tty_tdd|grand_central|(custom <String>)]
 		[value <String>] notprimary|primary))|
 	(relation|relations clear|(spouse|child|mother|father|parent|brother|sister|friend|relative|domestic_partner|manager|assistant|referred_by|partner|<String> <String>))|
 	(suspended <Boolean>)|
@@ -526,6 +577,7 @@ Example: gam csv Users.csv gam update user "~primaryEmail" address type work uns
 Each user (~primaryEmail, e.g. foo@bar.com) would have their work address updated
 
 gam create project [<EmailAddress>]
+gam update project [<EmailAddress>]
 
 gam oauth|oauth2 create|request [<EmailAddress>]
 gam oauth|oauth2 delete|revoke
@@ -535,14 +587,21 @@ gam <UserTypeEntity> check serviceaccount
 
 gam whatis <EmailItem>
 
-gam create resoldcustomer <CustomerDomain> (customer_auth_token <String>)
-	(email|alternate_email <EmailAddress>) (name|organization_name <String>) (contact|contact_name <String>) [phone|phone_number <String>]
-	[address|address1 <String>] [address2 <String>] [address3 <String>]
-	[locality|city <String>] [region|state <String>] [postal|postal_code <String>] [country|country_code <String>]
-gam update resoldcustomer <CustomerID> [customer_auth_token <String>]
-	[email|alternate_email <EmailAddress>] [name|organization_name <String>] [contact|contact_name <String>] [phone|phone_number <String>]
-	[address|address1 <String>] [address2 <String>] [address3 <String>]
-	[locality|city <String>] [region|state <String>] [postal|postal_code <String>] [country|country_code <String>]
+<ResoldCustomerAttributes> ::=
+	(email|alternateemail <EmailAddress>)|
+	(contact|contactname <String>)|
+	(phone|phonenumber <String>)|
+	(name|organizationname <String>)|
+	(address|address1|addressline1 <String>)|
+	(address2|addressline2 <String>)|
+	(address3|addressline3 <String>)|
+	(city|locality <String>)|
+	(state|region <String>)|
+	(zipcode|postal|postalcode <String>)|
+	(country|countrycode <String>)
+
+gam create resoldcustomer <CustomerDomain> (customer_auth_token <String>) <ResoldCustomerAttributes>+
+gam update resoldcustomer <CustomerID> [customer_auth_token <String>] <ResoldCustomerAttribues>+
 gam info resoldcustomer <CustomerID>
 
 gam create resoldsubscription <CustomerID> (sku <SKUID>)
@@ -579,11 +638,24 @@ gam delete domainalias|aliasdomain <DomainAlias>
 gam info domainalias|aliasdomain <DomainAlias>
 gam print domainaliases|aliasdomains [todrive]
 
+<CustomerAttributes> ::=
+	(primary <DomainName>)|
+	(adminsecondaryemail|alternateemail <EmailAddress>)|
+	(contact|contactname <String>)|
+	(language <LanguageCode>)|
+	(phone|phonenumber <String>)|
+	(name|organizationname <String>)|
+	(address|address1|addressline1 <String>)|
+	(address2|addressline2 <String>)|
+	(address3|addressline3 <String>)|
+	(city|locality <String>)|
+	(state|region <String>)|
+	(zipcode|postal|postalcode <String>)|
+	(country|countrycode <String>)
+
+gam update customer <CustomerAttributes>*
+
 gam info customer
-gam update customer [adminsecondaryemail|alternateemail <EmailAddress>] [language <LanguageCode] [phone|phonenumber <String>]
-	[contact|contactname <String>] [name|organizationname <String>]
-	[address1|addressline1 <String>] [address2|addressline2 <String>] [address3|addressline3 <String>]
-	[locality <String>] [region <String>] [postalcode <String>] [country|countrycode <String>]
 
 gam create datatransfer|transfer <OldOwnerID> <DataTransferService> <NewOwnerID> (<ParameterKey> <ParameterValue>)*
 gam info datatransfer|transfer <TransferID>
@@ -614,11 +686,11 @@ gam calendar <CalendarItem> deleteevent (id|eventid <EventID>)* (query|eventquer
 gam calendar <CalendarItem> wipe
 
 gam update cros <CrOSItem> (<CrOSAttributes>+)|(action deprovision_same_model_replace|deprovision_different_model_replace|deprovision_retiring_device|disable|reenable [acknowledge_device_touch_requirement])
-gam info cros <CrOSItem> [nolists] [listlimit <Number>]
+gam info cros <CrOSItem> [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
 	[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
 
-gam print cros [todrive] [query <QueryCrOS>]
-	[orderby <CrOSOrderByFieldName> [ascending|descending]] [nolists] [listlimit <Number>]
+gam print cros [todrive] [query <QueryCrOS>] [limittoou <OrgUnitItem>]
+	[orderby <CrOSOrderByFieldName> [ascending|descending]] [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
 	[basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
 gam <CrOSTypeEntity> print
 
@@ -632,26 +704,43 @@ Prints a header row and selected fields for specified CrOS devices.
 
 The basic argument yields these column headers: deviceId,annotatedAssetId,annotatedLocation,annotatedUser,lastSync,notes,serialNumber,status
 The full argument yields all column headers including two headers, recentUsers and activeTimeRanges,
-that repeat with two subvalues each, yielding a large number of columns that make the output hard to process.
+that repeat with two/four subvalues each, yielding a large number of columns that make the output hard to process.
 The nolists argument suppresses these two headers; if you want these headers in a more manageable form use the following arguments.
-The listlimit <Number> argument limits the number of repetitions to <Number>. If <Number> equals zero, there is no limit.
-If recentusers is specified as a field, each pair of values for recentUsers is put on a separate row with all of the other headers.
-If timeranges is specified as a field, each  pair of values for activeTimeRanges is put on a separate row with all of the other headers.
+If recentusers is specified, for each recent user, the columns recentUsers.email and recentUsers.type are output on a separate row
+with all of the other headers.
+If timeranges is specified, for each time range entry, the columns activeTimeRanges.date, activeTimeRange.activeTime,
+activeTimeRanges.duration and activeTimeRanges.minutes are output on a separate row with all of the other headers.
+The listlimit <Number> argument limits the number of repetitions to <Number>; if not specified or <Number> equals zero, there is no limit.
+The start <Date> and end <Date> arguments filter the time ranges.
 
-gam update mobile <MobileItem> <MobileAttributes>+
+gam print crosactivity [todrive] [query <QueryCrOS>] [limittoou <OrgUnitItem>]
+	[recentusers] [timeranges] [both] [listlimit <Number>] [start <Date>] [end <Date>] [delimiter <String>]
+
+The basic column headers are: deviceId,annotatedAssetId,annotatedLocation,serialNumber,orgUnitPath.
+If recentusers is specified, all of the recent users email addresses, separated by the delimiter <String>,
+with header recentUsers.email, are output with the basic headers.
+If timeranges is specified, for each time range entry, activeTimeRanges.date and activeTimeRanges.duration and activeTimeRanges.minutes,
+are output on a separate row with the basic headers.
+The default is to include both recentusers and timeranges.
+The listlimit <Number> argument limits the number of recent users and time ranges to <Number>; if not specified or <Number> equals zero, there is no limit.
+The start <Date> and end <Date> arguments filter the time ranges.
+Delimiter defaults to comma.
+
+gam update mobile <MobileItem> action <MobileAction>
 gam delete mobile <MobileItem>
 gam info mobile <MobileItem>
 gam print mobile [todrive] [query <QueryMobile>] [basic|full] [orderby <MobileOrderByFieldName> [ascending|descending]]
+	fields <MobileFieldNameList>] [delimiter <String>] [appslimit <Number>] [listlimit <Number>]
 
 gam create group <EmailAddress> <GroupAttributes>*
 gam update group <GroupItem> [admincreated <Boolean>] [email <EmailAddress>] <GroupAttributes>*
-gam update group <GroupItem> add [member|manager|owner] [notsuspended] <UserTypeEntity>
-gam update group <GroupItem> delete|remove [member|manager|owner] <UserTypeEntity>
-gam update group <GroupItem> sync [member|manager|owner] [notsuspended] <UserTypeEntity>
-gam update group <GroupItem> update [member|manager|owner] <UserTypeEntity>
+gam update group <GroupItem> add [owner|manager|member] [notsuspended] <UserTypeEntity>
+gam update group <GroupItem> delete|remove [owner|manager|member] <UserTypeEntity>
+gam update group <GroupItem> sync [owner|manager|member] [notsuspended] <UserTypeEntity>
+gam update group <GroupItem> update [owner|manager|member] <UserTypeEntity>
+gam update group <GroupItem> clear [member] [manager] [owner] [suspended]
 gam delete group <GroupItem>
 gam info group <GroupItem> [nousers] [noaliases] [groups]
-gam update group <GroupItem> clear [member] [manager] [owner]
 
 gam print groups [todrive] ([domain <DomainName>] [member <UserItem>])
 	[maxresults <Number>] [allfields|([settings] <GroupFieldName>* [fields <GroupFieldNameList>])] [delimiter <String>]
@@ -679,7 +768,7 @@ gam info schema <SchemaName>
 gam show schema|schemas
 gam print schema|schemas
 
-gam create user <EmailAddress> <UserAttrubutes>*
+gam create user <EmailAddress> <UserAttributes>*
 gam update user <UserItem> <UserAttributes>* [clearschema <SchemaName>] [clearschema <SchemaName>.<FieldName>]
 gam delete user <UserItem>
 gam undelete user <UserItem> [org|ou <OrgUnitPath>]
@@ -706,7 +795,7 @@ gam update course <CourseID> <CourseAttributes>+
 gam delete course <CourseID>
 gam info course <CourseID>
 gam print courses [todrive] [teacher <UserItem>] [student <UserItem>] [alias|aliases] [delimiter <String>]
-	[show all|students|teachers] [fields <CourseFieldNameList>] [skipfields <CourseFieldNameList>]
+	[show all|students|teachers] [countsonly] [fields <CourseFieldNameList>] [skipfields <CourseFieldNameList>]
 
 gam course <CourseID> add alias <CourseAlias>
 gam course <CourseID> delete alias <CourseAlias>
@@ -748,6 +837,25 @@ gam print printjobs [todrive] [printer|printerid <PrinterID>]
 	[owner|user <EmailAddress>]
 	[limit <Number>]
 
+gam create vaulthold|hold corpus drive|groups|mail matter <MatterItem> [name <String>] [query <QueryVaultCorpus>]
+	[(accounts|groups|users <EmailItemList>) | (orgunit|ou <OrgUnit>)]
+	[starttime <Date>|<DateTime>] [endtime <Date>|<DateTime>] 
+gam update vaulthold|hold <HoldItem> matter <MatterItem> [query <QueryVaultCorpus>]
+	[([addaccounts|addgroups|addusers <EmailItemList>] [removeaccounts|removegroups|removeusers <EmailItemList>]) | (orgunit|ou <OrgUnit>)]
+	[starttime <Date>|<DateTime>] [endtime <Date>|<DateTime>] 
+gam delete vaulthold|hold <HoldItem> matter <MatterItem>
+gam info vaulthold|hold <HoldItem> matter <MatterItem>
+gam print vaultholds|holds [todrive] [matters <MatterItemList>]
+
+gam create vaultmatter|matter [name <String>] [description <string>]
+	[collaborator|collaborators <CollaboratorItemList>]
+gam update vaultmatter|matter <MatterItem> [action close|reopen|delete|undelete] [name <String>] [description <string>]
+	[addcollaborator|addcollaborators <CollaboratorItemList>] [removecollaborator|removecollaborators <CollaboratorItemList>]
+gam delete vaultmatter|matter <MatterItem>
+gam undelete vaultmatter|matter <MatterItem>
+gam info vaultmatter|matter <MatterItem>
+gam print vaultmatters|matters [todrive] [basic|full]
+
 gam <UserTypeEntity> delete|del asp|asps|applicationspecificpasswords <AspID>
 gam <UserTypeEntity> show asps|asp|applicationspecificpasswords
 
@@ -756,7 +864,7 @@ gam <UserTypeEntity> delete|del backupcodes|backupcode|verificationcodes
 gam <UserTypeEntity> show backupcodes|backupcode|verificationcodes
 
 gam <UserTypeEntity> add calendar <CalendarItem> <CalendarAttributes>*
-gam <UserTypeEntity> update calendar <CalendarItem> <CalendarAttributes>+
+gam <UserTypeEntity> update calendar <CalendarItem>|primary <CalendarAttributes>+
 gam <UserTypeEntity> delete|del calendar <CalendarItem>
 gam <UserTypeEntity> show calendars
 gam <UserTypeEntity> info calendar <CalendarItem>|primary
@@ -810,7 +918,7 @@ gam <UserTypeEntity> show tokens|token [clientid <ClientID>]
 gam <UserTypeEntity> print tokens|token [todrive] [clientid <ClientID>]
 gam print tokens|token [todrive] [clientid <ClientID>] [<UserTypeEntity>]
 
-gam <UserTypeEntity> update user <UserAttrubutes>
+gam <UserTypeEntity> update user <UserAttributes>
 
 gam <UserTypeEntity> deprovision|deprov
 
@@ -858,8 +966,8 @@ gam <UserTypeEntity> show imap|imap4
 gam <UserTypeEntity> pop|pop3 <Boolean> [for allmail|newmail|mailfromnowon|fromnowown] [action keep|leaveininbox|archive|delete|trash|markread]
 gam <UserTypeEntity> show pop|pop3
 
-gam <UserTypeEntity> [add] sendas <EmailAddress> <Name> [signature|sig <String>|(file <FileName> [charset <CharSet>]) (replace <Tag> <String>)*] [html] [replyto <EmailAddress>] [default] [treatasalias <Boolean>]
-gam <UserTypeEntity> update sendas <EmailAddress> [name <Name>] [signature|sig <String>|(file <FileName> [charset <CharSet>]) (replace <Tag> <String>)*] [html] [replyto <EmailAddress>] [default] [treatasalias <Boolean>]
+gam <UserTypeEntity> [add] sendas <EmailAddress> <Name> [signature|sig <String>|(file <FileName> [charset <Charset>]) (replace <Tag> <String>)*] [html] [replyto <EmailAddress>] [default] [treatasalias <Boolean>]
+gam <UserTypeEntity> update sendas <EmailAddress> [name <Name>] [signature|sig <String>|(file <FileName> [charset <Charset>]) (replace <Tag> <String>)*] [html] [replyto <EmailAddress>] [default] [treatasalias <Boolean>]
 gam <UserTypeEntity> delete sendas <EmailAddress>
 gam <UserTypeEntity> show sendas [format]
 gam <UserTypeEntity> info sendas <EmailAddress> [format]
@@ -881,6 +989,6 @@ gam <UserTypeEntity> show teamdrives
 gam <UserTypeEntity> print teamdrives [todrive]
 
 gam <UserTypeEntity> vacation <FalseValues>
-gam <UserTypeEntity> vacation <TrueValues> subject <String> (message <String>)|(file <FileName> [charset <CharSet>]) (replace <Tag> <String>)* [html]
+gam <UserTypeEntity> vacation <TrueValues> subject <String> (message <String>)|(file <FileName> [charset <Charset>]) (replace <Tag> <String>)* [html]
 	[contactsonly] [domainonly] [startdate <Date>] [enddate <Date>]
 gam <UserTypeEntity> show vacation [format]

src/gam-install.sh

@@ -30,14 +30,14 @@ while getopts "hd:a:o:lp:u:r:v:" OPTION
 do
      case $OPTION in
          h) usage; exit;;
-         d) target_dir=$OPTARG;;
-         a) gamarch=$OPTARG;;
-         o) gamos=$OPTARG;;
+         d) target_dir="$OPTARG";;
+         a) gamarch="$OPTARG";;
+         o) gamos="$OPTARG";;
          l) upgrade_only=true;;
-         p) update_profile=$OPTARG;;
-         u) adminuser=$OPTARG;;
-         r) regularuser=$OPTARG;;
-         v) gamversion=$OPTARG;;
+         p) update_profile="$OPTARG";;
+         u) adminuser="$OPTARG";;
+         r) regularuser="$OPTARG";;
+         v) gamversion="$OPTARG";;
          ?) usage; exit;;
      esac
 done
@@ -157,10 +157,10 @@ echo_yellow "Downloading file $name from $browser_download_url to $temp_archive_
 # Save archive to temp w/o losing our path
 (cd $temp_archive_dir && curl -O -L $browser_download_url)
 
-mkdir -p $target_dir
+mkdir -p "$target_dir"
 
 echo_yellow "Extracting archive to $target_dir"
-tar xf $temp_archive_dir/$name -C $target_dir
+tar xf $temp_archive_dir/$name -C "$target_dir"
 rc=$?
 if (( $rc != 0 )); then
   echo_red "ERROR: extracting the GAM archive with tar failed with error $rc. Exiting."
@@ -171,7 +171,7 @@ fi
 
 if [ "$upgrade_only" = true ]; then
   echo_green "Here's information about your GAM upgrade:"
-  $target_dir/gam/gam version
+  "$target_dir/gam/gam" version
   rc=$?
   if (( $rc != 0 )); then
     echo_red "ERROR: Failed running GAM for the first time with $rc. Please report this error to GAM mailing list. Exiting."
@@ -201,7 +201,7 @@ while true; do
       break
       ;;
     [Nn]*)
-      touch $target_dir/gam/nobrowser.txt > /dev/null 2>&1
+      touch "$target_dir/gam/nobrowser.txt" > /dev/null 2>&1
       break
       ;;
     *)
@@ -219,14 +219,14 @@ while true; do
       if [ "$adminuser" == "" ]; then
         read -p "Please enter your G Suite admin email address: " adminuser
       fi
-      $target_dir/gam/gam create project $adminuser
+      "$target_dir/gam/gam" create project $adminuser
       rc=$?
       if (( $rc == 0 )); then
         echo_green "Project creation complete."
         project_created=true
         break
       else
-        echo_red "Projection creation failed. Trying again. Say N to skip projection creation."
+        echo_red "Project creation failed. Trying again. Say N to skip project creation."
       fi
       ;;
     [Nn]*)
@@ -244,7 +244,7 @@ while $project_created; do
   read -p "Are you ready to authorize GAM to perform G Suite management operations as your admin account? (yes or no) " yn
   case $yn in
     [Yy]*)
-      $target_dir/gam/gam oauth create $adminuser
+      "$target_dir/gam/gam" oauth create $adminuser
       rc=$?
       if (( $rc == 0 )); then
         echo_green "Admin authorization complete."
@@ -273,7 +273,7 @@ while $project_created; do
         read -p "Please enter the email address of a regular G Suite user: " regularuser
       fi
       echo_yellow "Great! Checking service account scopes.This will fail the first time. Follow the steps to authorize and retry. It can take a few minutes for scopes to PASS after they've been authorized in the admin console."
-      $target_dir/gam/gam user $adminuser check serviceaccount
+      "$target_dir/gam/gam" user $adminuser check serviceaccount
       rc=$?
       if (( $rc == 0 )); then
         echo_green "Service account authorization complete."
@@ -294,7 +294,7 @@ while $project_created; do
 done
 
 echo_green "Here's information about your new GAM installation:"
-$target_dir/gam/gam version
+"$target_dir/gam/gam" version
 rc=$?
 if (( $rc != 0 )); then
   echo_red "ERROR: Failed running GAM for the first time with $rc. Please report this error to GAM mailing list. Exiting."

src/oauth2client/__init__.py

@@ -14,7 +14,7 @@
 
 """Client library for using OAuth2, especially with Google APIs."""
 
-__version__ = '4.0.0'
+__version__ = '4.1.2'
 
 GOOGLE_AUTH_URI = 'https://accounts.google.com/o/oauth2/v2/auth'
 GOOGLE_DEVICE_URI = 'https://accounts.google.com/o/oauth2/device/code'

src/oauth2client/_helpers.py

@@ -251,8 +251,8 @@ def validate_file(filename):
         raise IOError(_SYM_LINK_MESSAGE.format(filename))
     elif os.path.isdir(filename):
         raise IOError(_IS_DIR_MESSAGE.format(filename))
-    #elif not os.path.isfile(filename):
-    #    warnings.warn(_MISSING_FILE_MESSAGE.format(filename))
+    elif not os.path.isfile(filename):
+        warnings.warn(_MISSING_FILE_MESSAGE.format(filename))
 
 
 def _parse_pem_key(raw_key_input):

src/oauth2client/_pkce.py

@@ -38,7 +38,7 @@ def code_verifier(n_bytes=64):
     Returns:
         Bytestring, representing urlsafe base64-encoded random data.
     """
-    verifier = base64.urlsafe_b64encode(os.urandom(n_bytes))
+    verifier = base64.urlsafe_b64encode(os.urandom(n_bytes)).rstrip(b'=')
     # https://tools.ietf.org/html/rfc7636#section-4.1
     # minimum length of 43 characters and a maximum length of 128 characters.
     if len(verifier) < 43:
@@ -60,6 +60,8 @@ def code_challenge(verifier):
             code_verifier().
 
     Returns:
-        Bytestring, representing a urlsafe base64-encoded sha256 hash digest.
+        Bytestring, representing a urlsafe base64-encoded sha256 hash digest,
+            without '=' padding.
     """
-    return base64.urlsafe_b64encode(hashlib.sha256(verifier).digest())
+    digest = hashlib.sha256(verifier).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b'=')

src/oauth2client/client.py

@@ -108,7 +108,7 @@ except ValueError:  # pragma: NO COVER
     GCE_METADATA_TIMEOUT = 3
 
 _SERVER_SOFTWARE = 'SERVER_SOFTWARE'
-_GCE_METADATA_URI = 'http://169.254.169.254'
+_GCE_METADATA_URI = 'http://' + os.getenv('GCE_METADATA_IP', '169.254.169.254')
 _METADATA_FLAVOR_HEADER = 'metadata-flavor'  # lowercase header
 _DESIRED_METADATA_FLAVOR = 'Google'
 _GCE_HEADERS = {_METADATA_FLAVOR_HEADER: _DESIRED_METADATA_FLAVOR}
@@ -271,7 +271,7 @@ class Credentials(object):
                 to_serialize[key] = val.decode('utf-8')
             if isinstance(val, set):
                 to_serialize[key] = list(val)
-        return json.dumps(to_serialize, indent=4, sort_keys=True)
+        return json.dumps(to_serialize)
 
     def to_json(self):
         """Creating a JSON representation of an instance of Credentials.
@@ -451,7 +451,7 @@ class OAuth2Credentials(Credentials):
     def __init__(self, access_token, client_id, client_secret, refresh_token,
                  token_expiry, token_uri, user_agent, revoke_uri=None,
                  id_token=None, token_response=None, scopes=None,
-                 token_info_uri=None):
+                 token_info_uri=None, id_token_jwt=None):
         """Create an instance of OAuth2Credentials.
 
         This constructor is not usually called by the user, instead
@@ -474,8 +474,11 @@ class OAuth2Credentials(Credentials):
                             because some providers (e.g. wordpress.com) include
                             extra fields that clients may want.
             scopes: list, authorized scopes for these credentials.
-          token_info_uri: string, the URI for the token info endpoint. Defaults
-                          to None; scopes can not be refreshed if this is None.
+            token_info_uri: string, the URI for the token info endpoint.
+                            Defaults to None; scopes can not be refreshed if
+                            this is None.
+            id_token_jwt: string, the encoded and signed identity JWT. The
+                          decoded version of this is stored in id_token.
 
         Notes:
             store: callable, A callable that when passed a Credential
@@ -493,6 +496,7 @@ class OAuth2Credentials(Credentials):
         self.user_agent = user_agent
         self.revoke_uri = revoke_uri
         self.id_token = id_token
+        self.id_token_jwt = id_token_jwt
         self.token_response = token_response
         self.scopes = set(_helpers.string_to_scopes(scopes or []))
         self.token_info_uri = token_info_uri
@@ -621,6 +625,7 @@ class OAuth2Credentials(Credentials):
             data['user_agent'],
             revoke_uri=data.get('revoke_uri', None),
             id_token=data.get('id_token', None),
+            id_token_jwt=data.get('id_token_jwt', None),
             token_response=data.get('token_response', None),
             scopes=data.get('scopes', None),
             token_info_uri=data.get('token_info_uri', None))
@@ -786,8 +791,10 @@ class OAuth2Credentials(Credentials):
                 self.token_expiry = None
             if 'id_token' in d:
                 self.id_token = _extract_id_token(d['id_token'])
+                self.id_token_jwt = d['id_token']
             else:
                 self.id_token = None
+                self.id_token_jwt = None
             # On temporary refresh errors, the user does not actually have to
             # re-authorize, so we unflag here.
             self.invalid = False
@@ -1771,7 +1778,7 @@ class DeviceFlowInfo(collections.namedtuple('DeviceFlowInfo', (
 def _oauth2_web_server_flow_params(kwargs):
     """Configures redirect URI parameters for OAuth2WebServerFlow."""
     params = {
-#        'access_type': 'offline',
+        'access_type': 'offline',
         'response_type': 'code',
     }
 
@@ -2059,15 +2066,17 @@ class OAuth2WebServerFlow(Flow):
                 token_expiry = delta + _UTCNOW()
 
             extracted_id_token = None
+            id_token_jwt = None
             if 'id_token' in d:
                 extracted_id_token = _extract_id_token(d['id_token'])
+                id_token_jwt = d['id_token']
 
             logger.info('Successfully retrieved access token')
             return OAuth2Credentials(
                 access_token, self.client_id, self.client_secret,
                 refresh_token, token_expiry, self.token_uri, self.user_agent,
                 revoke_uri=self.revoke_uri, id_token=extracted_id_token,
-                token_response=d, scopes=self.scope,
+                id_token_jwt=id_token_jwt, token_response=d, scopes=self.scope,
                 token_info_uri=self.token_info_uri)
         else:
             logger.info('Failed to retrieve access token: %s', content)
@@ -2083,7 +2092,8 @@ class OAuth2WebServerFlow(Flow):
 @_helpers.positional(2)
 def flow_from_clientsecrets(filename, scope, redirect_uri=None,
                             message=None, cache=None, login_hint=None,
-                            device_uri=None, pkce=None, code_verifier=None):
+                            device_uri=None, pkce=None, code_verifier=None,
+                            prompt=None):
     """Create a Flow from a clientsecrets file.
 
     Will create the right kind of Flow based on the contents of the
@@ -2132,7 +2142,13 @@ def flow_from_clientsecrets(filename, scope, redirect_uri=None,
                 'login_hint': login_hint,
             }
             revoke_uri = client_info.get('revoke_uri')
-            optional = ('revoke_uri', 'device_uri', 'pkce', 'code_verifier')
+            optional = (
+                'revoke_uri',
+                'device_uri',
+                'pkce',
+                'code_verifier',
+                'prompt'
+            )
             for param in optional:
                 if locals()[param] is not None:
                     constructor_kwargs[param] = locals()[param]

src/oauth2client/contrib/_fcntl_opener.py

@@ -1,81 +0,0 @@
-# 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.
-
-import errno
-import fcntl
-import time
-
-from oauth2client.contrib import locked_file
-
-
-class _FcntlOpener(locked_file._Opener):
-    """Open, lock, and unlock a file using fcntl.lockf."""
-
-    def open_and_lock(self, timeout, delay):
-        """Open the file and lock it.
-
-        Args:
-            timeout: float, How long to try to lock for.
-            delay: float, How long to wait between retries
-
-        Raises:
-            AlreadyLockedException: if the lock is already acquired.
-            IOError: if the open fails.
-            CredentialsFileSymbolicLinkError: if the file is a symbolic
-                                              link.
-        """
-        if self._locked:
-            raise locked_file.AlreadyLockedException(
-                'File {0} is already locked'.format(self._filename))
-        start_time = time.time()
-
-        locked_file.validate_file(self._filename)
-        try:
-            self._fh = open(self._filename, self._mode)
-        except IOError as e:
-            # If we can't access with _mode, try _fallback_mode and
-            # don't lock.
-            if e.errno in (errno.EPERM, errno.EACCES):
-                self._fh = open(self._filename, self._fallback_mode)
-                return
-
-        # We opened in _mode, try to lock the file.
-        while True:
-            try:
-                fcntl.lockf(self._fh.fileno(), fcntl.LOCK_EX)
-                self._locked = True
-                return
-            except IOError as e:
-                # If not retrying, then just pass on the error.
-                if timeout == 0:
-                    raise
-                if e.errno != errno.EACCES:
-                    raise
-                # We could not acquire the lock. Try again.
-                if (time.time() - start_time) >= timeout:
-                    locked_file.logger.warn('Could not lock %s in %s seconds',
-                                            self._filename, timeout)
-                    if self._fh:
-                        self._fh.close()
-                    self._fh = open(self._filename, self._fallback_mode)
-                    return
-                time.sleep(delay)
-
-    def unlock_and_close(self):
-        """Close and unlock the file using the fcntl.lockf primitive."""
-        if self._locked:
-            fcntl.lockf(self._fh.fileno(), fcntl.LOCK_UN)
-        self._locked = False
-        if self._fh:
-            self._fh.close()

src/oauth2client/contrib/_metadata.py

@@ -19,6 +19,7 @@ See https://cloud.google.com/compute/docs/metadata
 
 import datetime
 import json
+import os
 
 from six.moves import http_client
 from six.moves.urllib import parse as urlparse
@@ -28,7 +29,8 @@ from oauth2client import client
 from oauth2client import transport
 
 
-METADATA_ROOT = 'http://metadata.google.internal/computeMetadata/v1/'
+METADATA_ROOT = 'http://{}/computeMetadata/v1/'.format(
+    os.getenv('GCE_METADATA_ROOT', 'metadata.google.internal'))
 METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
 
 
@@ -38,7 +40,7 @@ def get(http, path, root=METADATA_ROOT, recursive=None):
     Args:
         http: an object to be used to make HTTP requests.
         path: A string indicating the resource to retrieve. For example,
-            'instance/service-accounts/defualt'
+            'instance/service-accounts/default'
         root: A string indicating the full path to the metadata server root.
         recursive: A boolean indicating whether to do a recursive query of
             metadata. See

src/oauth2client/contrib/_win32_opener.py

@@ -1,106 +0,0 @@
-# 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.
-
-import errno
-import time
-
-import pywintypes
-import win32con
-import win32file
-
-from oauth2client.contrib import locked_file
-
-
-class _Win32Opener(locked_file._Opener):
-    """Open, lock, and unlock a file using windows primitives."""
-
-    # Error #33:
-    #  'The process cannot access the file because another process'
-    FILE_IN_USE_ERROR = 33
-
-    # Error #158:
-    #  'The segment is already unlocked.'
-    FILE_ALREADY_UNLOCKED_ERROR = 158
-
-    def open_and_lock(self, timeout, delay):
-        """Open the file and lock it.
-
-        Args:
-            timeout: float, How long to try to lock for.
-            delay: float, How long to wait between retries
-
-        Raises:
-            AlreadyLockedException: if the lock is already acquired.
-            IOError: if the open fails.
-            CredentialsFileSymbolicLinkError: if the file is a symbolic
-                                              link.
-        """
-        if self._locked:
-            raise locked_file.AlreadyLockedException(
-                'File {0} is already locked'.format(self._filename))
-        start_time = time.time()
-
-        locked_file.validate_file(self._filename)
-        try:
-            self._fh = open(self._filename, self._mode)
-        except IOError as e:
-            # If we can't access with _mode, try _fallback_mode
-            # and don't lock.
-            if e.errno == errno.EACCES:
-                self._fh = open(self._filename, self._fallback_mode)
-                return
-
-        # We opened in _mode, try to lock the file.
-        while True:
-            try:
-                hfile = win32file._get_osfhandle(self._fh.fileno())
-                win32file.LockFileEx(
-                    hfile,
-                    (win32con.LOCKFILE_FAIL_IMMEDIATELY |
-                     win32con.LOCKFILE_EXCLUSIVE_LOCK), 0, -0x10000,
-                    pywintypes.OVERLAPPED())
-                self._locked = True
-                return
-            except pywintypes.error as e:
-                if timeout == 0:
-                    raise
-
-                # If the error is not that the file is already
-                # in use, raise.
-                if e[0] != _Win32Opener.FILE_IN_USE_ERROR:
-                    raise
-
-                # We could not acquire the lock. Try again.
-                if (time.time() - start_time) >= timeout:
-                    locked_file.logger.warn('Could not lock %s in %s seconds',
-                                            self._filename, timeout)
-                    if self._fh:
-                        self._fh.close()
-                    self._fh = open(self._filename, self._fallback_mode)
-                    return
-                time.sleep(delay)
-
-    def unlock_and_close(self):
-        """Close and unlock the file using the win32 primitive."""
-        if self._locked:
-            try:
-                hfile = win32file._get_osfhandle(self._fh.fileno())
-                win32file.UnlockFileEx(hfile, 0, -0x10000,
-                                       pywintypes.OVERLAPPED())
-            except pywintypes.error as e:
-                if e[0] != _Win32Opener.FILE_ALREADY_UNLOCKED_ERROR:
-                    raise
-        self._locked = False
-        if self._fh:
-            self._fh.close()

src/oauth2client/contrib/devshell.py

@@ -37,6 +37,7 @@ class CommunicationError(Error):
 class NoDevshellServer(Error):
     """Error when no Developer Shell server can be contacted."""
 
+
 # The request for credential information to the Developer Shell client socket
 # is always an empty PBLite-formatted JSON object, so just define it as a
 # constant.

src/oauth2client/contrib/django_util/models.py

@@ -19,6 +19,7 @@ import pickle
 
 from django.db import models
 from django.utils import encoding
+import jsonpickle
 
 import oauth2client
 
@@ -48,7 +49,12 @@ class CredentialsField(models.Field):
         elif isinstance(value, oauth2client.client.Credentials):
             return value
         else:
-            return pickle.loads(base64.b64decode(encoding.smart_bytes(value)))
+            try:
+                return jsonpickle.decode(
+                    base64.b64decode(encoding.smart_bytes(value)).decode())
+            except ValueError:
+                return pickle.loads(
+                    base64.b64decode(encoding.smart_bytes(value)))
 
     def get_prep_value(self, value):
         """Overrides ``models.Field`` method. This is used to convert
@@ -58,7 +64,8 @@ class CredentialsField(models.Field):
         if value is None:
             return None
         else:
-            return encoding.smart_text(base64.b64encode(pickle.dumps(value)))
+            return encoding.smart_text(
+                base64.b64encode(jsonpickle.encode(value).encode()))
 
     def value_to_string(self, obj):
         """Convert the field value from the provided model to a string.

src/oauth2client/contrib/flask_util.py

@@ -176,6 +176,7 @@ try:
     from flask import request
     from flask import session
     from flask import url_for
+    import markupsafe
 except ImportError:  # pragma: NO COVER
     raise ImportError('The flask utilities require flask 0.9 or newer.')
 
@@ -388,6 +389,7 @@ class UserOAuth2(object):
         if 'error' in request.args:
             reason = request.args.get(
                 'error_description', request.args.get('error', ''))
+            reason = markupsafe.escape(reason)
             return ('Authorization failed: {0}'.format(reason),
                     httplib.BAD_REQUEST)
 

src/oauth2client/contrib/locked_file.py

@@ -1,234 +0,0 @@
-# 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.
-
-"""Locked file interface that should work on Unix and Windows pythons.
-
-This module first tries to use fcntl locking to ensure serialized access
-to a file, then falls back on a lock file if that is unavialable.
-
-Usage::
-
-    f = LockedFile('filename', 'r+b', 'rb')
-    f.open_and_lock()
-    if f.is_locked():
-      print('Acquired filename with r+b mode')
-      f.file_handle().write('locked data')
-    else:
-      print('Acquired filename with rb mode')
-    f.unlock_and_close()
-
-"""
-
-from __future__ import print_function
-
-import errno
-import logging
-import os
-import time
-
-from oauth2client import util
-
-
-__author__ = 'cache@google.com (David T McWherter)'
-
-logger = logging.getLogger(__name__)
-
-
-class CredentialsFileSymbolicLinkError(Exception):
-    """Credentials files must not be symbolic links."""
-
-
-class AlreadyLockedException(Exception):
-    """Trying to lock a file that has already been locked by the LockedFile."""
-    pass
-
-
-def validate_file(filename):
-    if os.path.islink(filename):
-        raise CredentialsFileSymbolicLinkError(
-            'File: {0} is a symbolic link.'.format(filename))
-
-
-class _Opener(object):
-    """Base class for different locking primitives."""
-
-    def __init__(self, filename, mode, fallback_mode):
-        """Create an Opener.
-
-        Args:
-            filename: string, The pathname of the file.
-            mode: string, The preferred mode to access the file with.
-            fallback_mode: string, The mode to use if locking fails.
-        """
-        self._locked = False
-        self._filename = filename
-        self._mode = mode
-        self._fallback_mode = fallback_mode
-        self._fh = None
-        self._lock_fd = None
-
-    def is_locked(self):
-        """Was the file locked."""
-        return self._locked
-
-    def file_handle(self):
-        """The file handle to the file. Valid only after opened."""
-        return self._fh
-
-    def filename(self):
-        """The filename that is being locked."""
-        return self._filename
-
-    def open_and_lock(self, timeout, delay):
-        """Open the file and lock it.
-
-        Args:
-            timeout: float, How long to try to lock for.
-            delay: float, How long to wait between retries.
-        """
-        pass
-
-    def unlock_and_close(self):
-        """Unlock and close the file."""
-        pass
-
-
-class _PosixOpener(_Opener):
-    """Lock files using Posix advisory lock files."""
-
-    def open_and_lock(self, timeout, delay):
-        """Open the file and lock it.
-
-        Tries to create a .lock file next to the file we're trying to open.
-
-        Args:
-            timeout: float, How long to try to lock for.
-            delay: float, How long to wait between retries.
-
-        Raises:
-            AlreadyLockedException: if the lock is already acquired.
-            IOError: if the open fails.
-            CredentialsFileSymbolicLinkError if the file is a symbolic link.
-        """
-        if self._locked:
-            raise AlreadyLockedException(
-                'File {0} is already locked'.format(self._filename))
-        self._locked = False
-
-        validate_file(self._filename)
-        try:
-            self._fh = open(self._filename, self._mode)
-        except IOError as e:
-            # If we can't access with _mode, try _fallback_mode and don't lock.
-            if e.errno == errno.EACCES:
-                self._fh = open(self._filename, self._fallback_mode)
-                return
-
-        lock_filename = self._posix_lockfile(self._filename)
-        start_time = time.time()
-        while True:
-            try:
-                self._lock_fd = os.open(lock_filename,
-                                        os.O_CREAT | os.O_EXCL | os.O_RDWR)
-                self._locked = True
-                break
-
-            except OSError as e:
-                if e.errno != errno.EEXIST:
-                    raise
-                if (time.time() - start_time) >= timeout:
-                    logger.warn('Could not acquire lock %s in %s seconds',
-                                lock_filename, timeout)
-                    # Close the file and open in fallback_mode.
-                    if self._fh:
-                        self._fh.close()
-                    self._fh = open(self._filename, self._fallback_mode)
-                    return
-                time.sleep(delay)
-
-    def unlock_and_close(self):
-        """Unlock a file by removing the .lock file, and close the handle."""
-        if self._locked:
-            lock_filename = self._posix_lockfile(self._filename)
-            os.close(self._lock_fd)
-            os.unlink(lock_filename)
-            self._locked = False
-            self._lock_fd = None
-        if self._fh:
-            self._fh.close()
-
-    def _posix_lockfile(self, filename):
-        """The name of the lock file to use for posix locking."""
-        return '{0}.lock'.format(filename)
-
-
-class LockedFile(object):
-    """Represent a file that has exclusive access."""
-
-    @util.positional(4)
-    def __init__(self, filename, mode, fallback_mode, use_native_locking=True):
-        """Construct a LockedFile.
-
-        Args:
-            filename: string, The path of the file to open.
-            mode: string, The mode to try to open the file with.
-            fallback_mode: string, The mode to use if locking fails.
-            use_native_locking: bool, Whether or not fcntl/win32 locking is
-                                used.
-        """
-        opener = None
-        if not opener and use_native_locking:
-            try:
-                from oauth2client.contrib._win32_opener import _Win32Opener
-                opener = _Win32Opener(filename, mode, fallback_mode)
-            except ImportError:
-                try:
-                    from oauth2client.contrib._fcntl_opener import _FcntlOpener
-                    opener = _FcntlOpener(filename, mode, fallback_mode)
-                except ImportError:
-                    pass
-
-        if not opener:
-            opener = _PosixOpener(filename, mode, fallback_mode)
-
-        self._opener = opener
-
-    def filename(self):
-        """Return the filename we were constructed with."""
-        return self._opener._filename
-
-    def file_handle(self):
-        """Return the file_handle to the opened file."""
-        return self._opener.file_handle()
-
-    def is_locked(self):
-        """Return whether we successfully locked the file."""
-        return self._opener.is_locked()
-
-    def open_and_lock(self, timeout=0, delay=0.05):
-        """Open the file, trying to lock it.
-
-        Args:
-            timeout: float, The number of seconds to try to acquire the lock.
-            delay: float, The number of seconds to wait between retry attempts.
-
-        Raises:
-            AlreadyLockedException: if the lock is already acquired.
-            IOError: if the open fails.
-        """
-        self._opener.open_and_lock(timeout, delay)
-
-    def unlock_and_close(self):
-        """Unlock and close a file."""
-        self._opener.unlock_and_close()

src/oauth2client/contrib/multistore_file.py

@@ -1,505 +0,0 @@
-# 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.
-
-"""Multi-credential file store with lock support.
-
-This module implements a JSON credential store where multiple
-credentials can be stored in one file. That file supports locking
-both in a single process and across processes.
-
-The credential themselves are keyed off of:
-
-* client_id
-* user_agent
-* scope
-
-The format of the stored data is like so::
-
-    {
-      'file_version': 1,
-      'data': [
-          {
-              'key': {
-                  'clientId': '<client id>',
-                  'userAgent': '<user agent>',
-                  'scope': '<scope>'
-              },
-              'credential': {
-                  # JSON serialized Credentials.
-              }
-          }
-      ]
-    }
-
-"""
-
-import errno
-import json
-import logging
-import os
-import threading
-
-from oauth2client import client
-from oauth2client import util
-from oauth2client.contrib import locked_file
-
-__author__ = 'jbeda@google.com (Joe Beda)'
-
-logger = logging.getLogger(__name__)
-
-logger.warning(
-    'The oauth2client.contrib.multistore_file module has been deprecated and '
-    'will be removed in the next release of oauth2client. Please migrate to '
-    'multiprocess_file_storage.')
-
-# A dict from 'filename'->_MultiStore instances
-_multistores = {}
-_multistores_lock = threading.Lock()
-
-
-class Error(Exception):
-    """Base error for this module."""
-
-
-class NewerCredentialStoreError(Error):
-    """The credential store is a newer version than supported."""
-
-
-def _dict_to_tuple_key(dictionary):
-    """Converts a dictionary to a tuple that can be used as an immutable key.
-
-    The resulting key is always sorted so that logically equivalent
-    dictionaries always produce an identical tuple for a key.
-
-    Args:
-        dictionary: the dictionary to use as the key.
-
-    Returns:
-        A tuple representing the dictionary in it's naturally sorted ordering.
-    """
-    return tuple(sorted(dictionary.items()))
-
-
-@util.positional(4)
-def get_credential_storage(filename, client_id, user_agent, scope,
-                           warn_on_readonly=True):
-    """Get a Storage instance for a credential.
-
-    Args:
-        filename: The JSON file storing a set of credentials
-        client_id: The client_id for the credential
-        user_agent: The user agent for the credential
-        scope: string or iterable of strings, Scope(s) being requested
-        warn_on_readonly: if True, log a warning if the store is readonly
-
-    Returns:
-        An object derived from client.Storage for getting/setting the
-        credential.
-    """
-    # Recreate the legacy key with these specific parameters
-    key = {'clientId': client_id, 'userAgent': user_agent,
-           'scope': util.scopes_to_string(scope)}
-    return get_credential_storage_custom_key(
-        filename, key, warn_on_readonly=warn_on_readonly)
-
-
-@util.positional(2)
-def get_credential_storage_custom_string_key(filename, key_string,
-                                             warn_on_readonly=True):
-    """Get a Storage instance for a credential using a single string as a key.
-
-    Allows you to provide a string as a custom key that will be used for
-    credential storage and retrieval.
-
-    Args:
-        filename: The JSON file storing a set of credentials
-        key_string: A string to use as the key for storing this credential.
-        warn_on_readonly: if True, log a warning if the store is readonly
-
-    Returns:
-        An object derived from client.Storage for getting/setting the
-        credential.
-    """
-    # Create a key dictionary that can be used
-    key_dict = {'key': key_string}
-    return get_credential_storage_custom_key(
-        filename, key_dict, warn_on_readonly=warn_on_readonly)
-
-
-@util.positional(2)
-def get_credential_storage_custom_key(filename, key_dict,
-                                      warn_on_readonly=True):
-    """Get a Storage instance for a credential using a dictionary as a key.
-
-    Allows you to provide a dictionary as a custom key that will be used for
-    credential storage and retrieval.
-
-    Args:
-        filename: The JSON file storing a set of credentials
-        key_dict: A dictionary to use as the key for storing this credential.
-                  There is no ordering of the keys in the dictionary. Logically
-                  equivalent dictionaries will produce equivalent storage keys.
-        warn_on_readonly: if True, log a warning if the store is readonly
-
-    Returns:
-        An object derived from client.Storage for getting/setting the
-        credential.
-    """
-    multistore = _get_multistore(filename, warn_on_readonly=warn_on_readonly)
-    key = _dict_to_tuple_key(key_dict)
-    return multistore._get_storage(key)
-
-
-@util.positional(1)
-def get_all_credential_keys(filename, warn_on_readonly=True):
-    """Gets all the registered credential keys in the given Multistore.
-
-    Args:
-        filename: The JSON file storing a set of credentials
-        warn_on_readonly: if True, log a warning if the store is readonly
-
-    Returns:
-        A list of the credential keys present in the file.  They are returned
-        as dictionaries that can be passed into
-        get_credential_storage_custom_key to get the actual credentials.
-    """
-    multistore = _get_multistore(filename, warn_on_readonly=warn_on_readonly)
-    multistore._lock()
-    try:
-        return multistore._get_all_credential_keys()
-    finally:
-        multistore._unlock()
-
-
-@util.positional(1)
-def _get_multistore(filename, warn_on_readonly=True):
-    """A helper method to initialize the multistore with proper locking.
-
-    Args:
-        filename: The JSON file storing a set of credentials
-        warn_on_readonly: if True, log a warning if the store is readonly
-
-    Returns:
-        A multistore object
-    """
-    filename = os.path.expanduser(filename)
-    _multistores_lock.acquire()
-    try:
-        multistore = _multistores.setdefault(
-            filename, _MultiStore(filename, warn_on_readonly=warn_on_readonly))
-    finally:
-        _multistores_lock.release()
-    return multistore
-
-
-class _MultiStore(object):
-    """A file backed store for multiple credentials."""
-
-    @util.positional(2)
-    def __init__(self, filename, warn_on_readonly=True):
-        """Initialize the class.
-
-        This will create the file if necessary.
-        """
-        self._file = locked_file.LockedFile(filename, 'r+', 'r')
-        self._thread_lock = threading.Lock()
-        self._read_only = False
-        self._warn_on_readonly = warn_on_readonly
-
-        self._create_file_if_needed()
-
-        # Cache of deserialized store. This is only valid after the
-        # _MultiStore is locked or _refresh_data_cache is called. This is
-        # of the form of:
-        #
-        # ((key, value), (key, value)...) -> OAuth2Credential
-        #
-        # If this is None, then the store hasn't been read yet.
-        self._data = None
-
-    class _Storage(client.Storage):
-        """A Storage object that can read/write a single credential."""
-
-        def __init__(self, multistore, key):
-            self._multistore = multistore
-            self._key = key
-
-        def acquire_lock(self):
-            """Acquires any lock necessary to access this Storage.
-
-            This lock is not reentrant.
-            """
-            self._multistore._lock()
-
-        def release_lock(self):
-            """Release the Storage lock.
-
-            Trying to release a lock that isn't held will result in a
-            RuntimeError.
-            """
-            self._multistore._unlock()
-
-        def locked_get(self):
-            """Retrieve credential.
-
-            The Storage lock must be held when this is called.
-
-            Returns:
-                oauth2client.client.Credentials
-            """
-            credential = self._multistore._get_credential(self._key)
-            if credential:
-                credential.set_store(self)
-            return credential
-
-        def locked_put(self, credentials):
-            """Write a credential.
-
-            The Storage lock must be held when this is called.
-
-            Args:
-                credentials: Credentials, the credentials to store.
-            """
-            self._multistore._update_credential(self._key, credentials)
-
-        def locked_delete(self):
-            """Delete a credential.
-
-            The Storage lock must be held when this is called.
-
-            Args:
-                credentials: Credentials, the credentials to store.
-            """
-            self._multistore._delete_credential(self._key)
-
-    def _create_file_if_needed(self):
-        """Create an empty file if necessary.
-
-        This method will not initialize the file. Instead it implements a
-        simple version of "touch" to ensure the file has been created.
-        """
-        if not os.path.exists(self._file.filename()):
-            old_umask = os.umask(0o177)
-            try:
-                open(self._file.filename(), 'a+b').close()
-            finally:
-                os.umask(old_umask)
-
-    def _lock(self):
-        """Lock the entire multistore."""
-        self._thread_lock.acquire()
-        try:
-            self._file.open_and_lock()
-        except (IOError, OSError) as e:
-            if e.errno == errno.ENOSYS:
-                logger.warn('File system does not support locking the '
-                            'credentials file.')
-            elif e.errno == errno.ENOLCK:
-                logger.warn('File system is out of resources for writing the '
-                            'credentials file (is your disk full?).')
-            elif e.errno == errno.EDEADLK:
-                logger.warn('Lock contention on multistore file, opening '
-                            'in read-only mode.')
-            elif e.errno == errno.EACCES:
-                logger.warn('Cannot access credentials file.')
-            else:
-                raise
-        if not self._file.is_locked():
-            self._read_only = True
-            if self._warn_on_readonly:
-                logger.warn('The credentials file (%s) is not writable. '
-                            'Opening in read-only mode. Any refreshed '
-                            'credentials will only be '
-                            'valid for this run.', self._file.filename())
-
-        if os.path.getsize(self._file.filename()) == 0:
-            logger.debug('Initializing empty multistore file')
-            # The multistore is empty so write out an empty file.
-            self._data = {}
-            self._write()
-        elif not self._read_only or self._data is None:
-            # Only refresh the data if we are read/write or we haven't
-            # cached the data yet. If we are readonly, we assume is isn't
-            # changing out from under us and that we only have to read it
-            # once. This prevents us from whacking any new access keys that
-            # we have cached in memory but were unable to write out.
-            self._refresh_data_cache()
-
-    def _unlock(self):
-        """Release the lock on the multistore."""
-        self._file.unlock_and_close()
-        self._thread_lock.release()
-
-    def _locked_json_read(self):
-        """Get the raw content of the multistore file.
-
-        The multistore must be locked when this is called.
-
-        Returns:
-            The contents of the multistore decoded as JSON.
-        """
-        assert self._thread_lock.locked()
-        self._file.file_handle().seek(0)
-        return json.load(self._file.file_handle())
-
-    def _locked_json_write(self, data):
-        """Write a JSON serializable data structure to the multistore.
-
-        The multistore must be locked when this is called.
-
-        Args:
-            data: The data to be serialized and written.
-        """
-        assert self._thread_lock.locked()
-        if self._read_only:
-            return
-        self._file.file_handle().seek(0)
-        json.dump(data, self._file.file_handle(),
-                  sort_keys=True, indent=2, separators=(',', ': '))
-        self._file.file_handle().truncate()
-
-    def _refresh_data_cache(self):
-        """Refresh the contents of the multistore.
-
-        The multistore must be locked when this is called.
-
-        Raises:
-            NewerCredentialStoreError: Raised when a newer client has written
-            the store.
-        """
-        self._data = {}
-        try:
-            raw_data = self._locked_json_read()
-        except Exception:
-            logger.warn('Credential data store could not be loaded. '
-                        'Will ignore and overwrite.')
-            return
-
-        version = 0
-        try:
-            version = raw_data['file_version']
-        except Exception:
-            logger.warn('Missing version for credential data store. It may be '
-                        'corrupt or an old version. Overwriting.')
-        if version > 1:
-            raise NewerCredentialStoreError(
-                'Credential file has file_version of {0}. '
-                'Only file_version of 1 is supported.'.format(version))
-
-        credentials = []
-        try:
-            credentials = raw_data['data']
-        except (TypeError, KeyError):
-            pass
-
-        for cred_entry in credentials:
-            try:
-                key, credential = self._decode_credential_from_json(cred_entry)
-                self._data[key] = credential
-            except:
-                # If something goes wrong loading a credential, just ignore it
-                logger.info('Error decoding credential, skipping',
-                            exc_info=True)
-
-    def _decode_credential_from_json(self, cred_entry):
-        """Load a credential from our JSON serialization.
-
-        Args:
-            cred_entry: A dict entry from the data member of our format
-
-        Returns:
-            (key, cred) where the key is the key tuple and the cred is the
-            OAuth2Credential object.
-        """
-        raw_key = cred_entry['key']
-        key = _dict_to_tuple_key(raw_key)
-        credential = None
-        credential = client.Credentials.new_from_json(
-            json.dumps(cred_entry['credential']))
-        return (key, credential)
-
-    def _write(self):
-        """Write the cached data back out.
-
-        The multistore must be locked.
-        """
-        raw_data = {'file_version': 1}
-        raw_creds = []
-        raw_data['data'] = raw_creds
-        for (cred_key, cred) in self._data.items():
-            raw_key = dict(cred_key)
-            raw_cred = json.loads(cred.to_json())
-            raw_creds.append({'key': raw_key, 'credential': raw_cred})
-        self._locked_json_write(raw_data)
-
-    def _get_all_credential_keys(self):
-        """Gets all the registered credential keys in the multistore.
-
-        Returns:
-            A list of dictionaries corresponding to all the keys currently
-            registered
-        """
-        return [dict(key) for key in self._data.keys()]
-
-    def _get_credential(self, key):
-        """Get a credential from the multistore.
-
-        The multistore must be locked.
-
-        Args:
-            key: The key used to retrieve the credential
-
-        Returns:
-            The credential specified or None if not present
-        """
-        return self._data.get(key, None)
-
-    def _update_credential(self, key, cred):
-        """Update a credential and write the multistore.
-
-        This must be called when the multistore is locked.
-
-        Args:
-            key: The key used to retrieve the credential
-            cred: The OAuth2Credential to update/set
-        """
-        self._data[key] = cred
-        self._write()
-
-    def _delete_credential(self, key):
-        """Delete a credential and write the multistore.
-
-        This must be called when the multistore is locked.
-
-        Args:
-            key: The key used to retrieve the credential
-        """
-        try:
-            del self._data[key]
-        except KeyError:
-            pass
-        self._write()
-
-    def _get_storage(self, key):
-        """Get a Storage object to get/set a credential.
-
-        This Storage is a 'view' into the multistore.
-
-        Args:
-            key: The key used to retrieve the credential
-
-        Returns:
-            A Storage object that can be used to get/set this cred
-        """
-        return self._Storage(self, key)

src/oauth2client/tools.py

@@ -92,6 +92,7 @@ def _CreateArgumentParser():
         help='Set the logging level of detail.')
     return parser
 
+
 # argparser is an ArgumentParser that contains command-line options expected
 # by tools.run(). Pass it in as part of the 'parents' argument to your own
 # ArgumentParser.
@@ -217,16 +218,6 @@ def run_flow(flow, storage, flags=None, http=None):
     flow.redirect_uri = oauth_callback
     authorize_url = flow.step1_get_authorize_url()
 
-    if flags.short_url:
-        try:
-            from googleapiclient.discovery import build
-            service = build('urlshortener', 'v1', http=http)
-            url_result = service.url().insert(body={'longUrl': authorize_url},
-              key=u'AIzaSyBlmgbii8QfJSYmC9VTMOfqrAt5Vj5wtzE').execute()
-            authorize_url = url_result['id']
-        except:
-          pass
-
     if not flags.noauth_local_webserver:
         import webbrowser
         webbrowser.open(authorize_url, new=1, autoraise=True)

src/oauth2client/util.py

@@ -1,206 +0,0 @@
-# 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.
-
-"""Common utility library."""
-
-import functools
-import inspect
-import logging
-
-import six
-from six.moves import urllib
-
-
-__author__ = [
-    'rafek@google.com (Rafe Kaplan)',
-    'guido@google.com (Guido van Rossum)',
-]
-
-__all__ = [
-    'positional',
-    'POSITIONAL_WARNING',
-    'POSITIONAL_EXCEPTION',
-    'POSITIONAL_IGNORE',
-]
-
-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
-
-
-def positional(max_positional_args):
-    """A decorator to declare that only the first N arguments my 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, kwonly1=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
-    ``util.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 the 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 key-word only argument is provided as a positional
-                   parameter, but only if
-                   util.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, six.integer_types):
-        return positional_decorator
-    else:
-        args, _, _, defaults = inspect.getargspec(max_positional_args)
-        return positional(len(args) - len(defaults))(max_positional_args)
-
-
-def scopes_to_string(scopes):
-    """Converts scope value to a string.
-
-    If scopes is a string then it is simply passed through. If scopes is an
-    iterable then a string is returned that is all the individual scopes
-    concatenated with spaces.
-
-    Args:
-        scopes: string or iterable of strings, the scopes.
-
-    Returns:
-        The scopes formatted as a single string.
-    """
-    if isinstance(scopes, six.string_types):
-        return scopes
-    else:
-        return ' '.join(scopes)
-
-
-def string_to_scopes(scopes):
-    """Converts stringifed scope value to a list.
-
-    If scopes is a list then it is simply passed through. If scopes is an
-    string then a list of each individual scope is returned.
-
-    Args:
-        scopes: a string or iterable of strings, the scopes.
-
-    Returns:
-        The scopes in a list.
-    """
-    if not scopes:
-        return []
-    if isinstance(scopes, six.string_types):
-        return scopes.split(' ')
-    else:
-        return scopes
-
-
-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:
-        parsed = list(urllib.parse.urlparse(url))
-        q = dict(urllib.parse.parse_qsl(parsed[4]))
-        q[name] = value
-        parsed[4] = urllib.parse.urlencode(q)
-        return urllib.parse.urlunparse(parsed)

src/project-apis.txt

@@ -3,7 +3,7 @@ appsactivity.googleapis.com
 calendar-json.googleapis.com
 classroom.googleapis.com
 contacts.googleapis.com
-drive
+drive.googleapis.com
 gmail.googleapis.com
 groupssettings.googleapis.com
 licensing.googleapis.com

src/var.py

@@ -4,7 +4,7 @@ import platform
 import re
 
 gam_author = u'Jay Lee <jay0lee@gmail.com>'
-gam_version = u'4.21'
+gam_version = u'4.30'
 gam_license = u'Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0)'
 
 GAM_URL = u'https://git.io/gam'
@@ -43,6 +43,8 @@ FN_OAUTH2SERVICE_JSON = u'oauth2service.json'
 FN_OAUTH2_TXT = u'oauth2.txt'
 MY_CUSTOMER = u'my_customer'
 SKUS = {
+  u'Google-Apps': {
+    u'product': u'Google-Apps', u'aliases': [u'standard', u'free'], u'displayName': u'G Suite Free/Standard'},
   u'Google-Apps-For-Business': {
     u'product': u'Google-Apps', u'aliases': [u'gafb', u'gafw', u'basic', u'gsuitebasic'], u'displayName': u'G Suite Basic'},
   u'Google-Apps-For-Government': {
@@ -98,9 +100,12 @@ API_VER_MAPPING = {
   u'licensing': u'v1',
   u'oauth2': u'v2',
   u'plus': u'v1',
+  u'pubsub': u'v1',
   u'reports': u'reports_v1',
   u'reseller': u'v1',
   u'siteVerification': u'v1',
+  u'urlshortener': u'v1',
+  u'vault': u'v1',
   }
 
 API_SCOPE_MAPPING = {
@@ -151,7 +156,7 @@ PRINTJOB_DESCENDINGORDER_MAP = {
   u'TITLE': u'TITLE_DESC',
   }
 
-PRINTJOBS_DEFAULT_JOB_LIMIT = 25
+PRINTJOBS_DEFAULT_JOB_LIMIT = 0
 PRINTJOBS_DEFAULT_MAX_RESULTS = 100
 
 CALENDAR_REMINDER_METHODS = [u'email', u'sms', u'popup',]
@@ -412,6 +417,13 @@ FILTER_ACTION_CHOICES = [
   u'markread', u'neverspam', u'notimportant', u'star', u'trash',
   ]
 
+VAULT_MATTER_ACTIONS = [
+  u'reopen',
+  u'undelete',
+  u'close',
+  u'delete',
+  ]
+
 CROS_ARGUMENT_TO_PROPERTY_MAP = {
   u'activetimeranges': [u'activeTimeRanges.activeTime', u'activeTimeRanges.date'],
   u'annotatedassetid': [u'annotatedAssetId',],
@@ -565,6 +577,8 @@ GC_DOMAIN = u'domain'
 GC_DRIVE_DIR = u'drive_dir'
 # When retrieving lists of Drive files/folders from API, how many should be retrieved in each chunk
 GC_DRIVE_MAX_RESULTS = u'drive_max_results'
+# When retrieving lists of Google Group members from API, how many should be retrieved in each chunk
+GC_MEMBER_MAX_RESULTS = u'member_max_results'
 # If no_browser is False, writeCSVfile won't open a browser when todrive is set
 # and doRequestOAuth prints a link and waits for the verification code when oauth2.txt is being created
 GC_NO_BROWSER = u'no_browser'
@@ -606,6 +620,7 @@ GC_Defaults = {
   GC_DOMAIN: u'',
   GC_DRIVE_DIR: u'',
   GC_DRIVE_MAX_RESULTS: 1000,
+  GC_MEMBER_MAX_RESULTS: 200,
   GC_NO_BROWSER: False,
   GC_NO_CACHE: False,
   GC_NO_UPDATE_CHECK: False,
@@ -649,6 +664,7 @@ GC_VAR_INFO = {
   GC_DOMAIN: {GC_VAR_TYPE: GC_TYPE_STRING},
   GC_DRIVE_DIR: {GC_VAR_TYPE: GC_TYPE_DIRECTORY},
   GC_DRIVE_MAX_RESULTS: {GC_VAR_TYPE: GC_TYPE_INTEGER, GC_VAR_LIMITS: (1, 1000)},
+  GC_MEMBER_MAX_RESULTS: {GC_VAR_TYPE: GC_TYPE_INTEGER, GC_VAR_LIMITS: (1, 10000)},
   GC_NO_BROWSER: {GC_VAR_TYPE: GC_TYPE_BOOLEAN},
   GC_NO_CACHE: {GC_VAR_TYPE: GC_TYPE_BOOLEAN},
   GC_NO_UPDATE_CHECK: {GC_VAR_TYPE: GC_TYPE_BOOLEAN},
@@ -697,23 +713,50 @@ MESSAGE_SERVICE_NOT_APPLICABLE = u'Service not applicable for this address: {0}.
 MESSAGE_INSTRUCTIONS_OAUTH2SERVICE_JSON = u'Please run\n\ngam create project\ngam user <user> check serviceaccount\n\nto create and configure a service account.'
 MESSAGE_OAUTH2SERVICE_JSON_INVALID = u'The file {0} is missing required keys (client_email, client_id or private_key). Please remove it and recreate with the commands:\n\ngam create project\ngam user <user> check serviceaccount'
 # oauth errors
-OAUTH2_TOKEN_ERRORS = [u'access_denied', u'unauthorized_client: Unauthorized client or scope in request.', u'access_denied: Requested client not authorized.',
-                       u'invalid_grant: Not a valid email.', u'invalid_grant: Invalid email or User ID', u'invalid_grant: Bad Request',
-                       u'invalid_request: Invalid impersonation prn email address.', u'internal_failure: Backend Error']
+OAUTH2_TOKEN_ERRORS = [
+  u'access_denied',
+  u'access_denied: Requested client not authorized',
+  u'internal_failure: Backend Error',
+  u'invalid_grant: Bad Request',
+  u'invalid_grant: Invalid email or User ID',
+  u'invalid_grant: Not a valid email',
+  u'invalid_request: Invalid impersonation prn email address',
+  u'unauthorized_client: Client is unauthorized to retrieve access tokens using this method',
+  u'unauthorized_client: Unauthorized client or scope in request',
+  ]
 #
 # callGAPI throw reasons
+GAPI_ABORTED = u'aborted'
+GAPI_AUTH_ERROR = u'authError'
 GAPI_BACKEND_ERROR = u'backendError'
 GAPI_BAD_REQUEST = u'badRequest'
+GAPI_CONDITION_NOT_MET = u'conditionNotMet'
+GAPI_CYCLIC_MEMBERSHIPS_NOT_ALLOWED = u'cyclicMembershipsNotAllowed'
+GAPI_DOMAIN_CANNOT_USE_APIS = u'domainCannotUseApis'
+GAPI_DOMAIN_NOT_FOUND = u'domainNotFound'
+GAPI_DUPLICATE = u'duplicate'
+GAPI_FAILED_PRECONDITION = u'failedPrecondition'
 GAPI_FORBIDDEN = u'forbidden'
+GAPI_GROUP_NOT_FOUND = u'groupNotFound'
 GAPI_INTERNAL_ERROR = u'internalError'
 GAPI_INVALID = u'invalid'
+GAPI_INVALID_ARGUMENT = u'invalidArgument'
+GAPI_INVALID_MEMBER = u'invalidMember'
+GAPI_MEMBER_NOT_FOUND = u'memberNotFound'
 GAPI_NOT_FOUND = u'notFound'
+GAPI_NOT_IMPLEMENTED = u'notImplemented'
 GAPI_QUOTA_EXCEEDED = u'quotaExceeded'
 GAPI_RATE_LIMIT_EXCEEDED = u'rateLimitExceeded'
+GAPI_RESOURCE_NOT_FOUND = u'resourceNotFound'
 GAPI_SERVICE_NOT_AVAILABLE = u'serviceNotAvailable'
+GAPI_SYSTEM_ERROR = u'systemError'
 GAPI_USER_NOT_FOUND = u'userNotFound'
 GAPI_USER_RATE_LIMIT_EXCEEDED = u'userRateLimitExceeded'
 #
 GAPI_DEFAULT_RETRY_REASONS = [GAPI_QUOTA_EXCEEDED, GAPI_RATE_LIMIT_EXCEEDED, GAPI_USER_RATE_LIMIT_EXCEEDED, GAPI_BACKEND_ERROR, GAPI_INTERNAL_ERROR]
 GAPI_GMAIL_THROW_REASONS = [GAPI_SERVICE_NOT_AVAILABLE]
 GAPI_GPLUS_THROW_REASONS = [GAPI_SERVICE_NOT_AVAILABLE]
+GAPI_GROUP_GET_THROW_REASONS = [GAPI_GROUP_NOT_FOUND, GAPI_DOMAIN_NOT_FOUND, GAPI_DOMAIN_CANNOT_USE_APIS, GAPI_FORBIDDEN, GAPI_BAD_REQUEST]
+GAPI_GROUP_GET_RETRY_REASONS = [GAPI_INVALID, GAPI_SYSTEM_ERROR]
+GAPI_MEMBERS_THROW_REASONS = [GAPI_GROUP_NOT_FOUND, GAPI_DOMAIN_NOT_FOUND, GAPI_DOMAIN_CANNOT_USE_APIS, GAPI_INVALID, GAPI_FORBIDDEN]
+GAPI_MEMBERS_RETRY_REASONS = [GAPI_SYSTEM_ERROR]

src/whatsnew.txt

@@ -1,3 +1,16 @@
+GAM 4.30
+ - Google Vault Matters and Hold API support
+ - Ross - "gam update group" now uses batch for better performance
+ - "gam update project" enables new APIs for your project
+ - Include root level OrgUnit in OrgUnit commands
+ - Bulk move Chrome devices between OrgUnits
+ - Usual fixes / cleanups / improvements by Ross and Jay
+
+GAM 4.22
+ - Validate client id and secret from user input (reduces user errors on create project)
+ - Ross - optimize "gam print printjobs"
+ - Ross- countsonly option for gam print courses
+
 GAM 4.21
  - Drive v3 fixes/updates by Ross
  - "gam print crosactivty" command outputs active users and times