Update troubleshooting docs for Python

Author: sethvargo

README.md

@@ -322,30 +322,6 @@ regardless of the authentication mechanism.
     "token_format" is "id_token".
 
 
-## Python Usage Note
-
-When using Workload Identity Federation with Python libraries (e.g., `google-auth`), you may encounter errors when trying to refresh credentials to get an ID token. This is because the Google Auth library requires scopes to be set when refreshing credentials for impersonation.
-
-If you need an ID token in Python, you have two options:
-
-1. **Use the `token_format` parameter** (recommended): Generate the ID token directly with this action and use it as an environment variable in your Python code.
-
-2. **Add scopes before refreshing**: If using default credentials, add the required scopes before refreshing:
-
-```python
-from google.auth import default
-from google.auth.transport.requests import Request
-
-credentials, project = default()
-credentials = credentials.with_scopes(
-    ["https://www.googleapis.com/auth/cloud-platform"]
-)
-credentials.refresh(request=Request())
-```
-
-For more details and examples, see the [Troubleshooting guide](docs/TROUBLESHOOTING.md#cannot-refresh-credentials-to-retrieve-an-id-token) and [Examples](docs/EXAMPLES.md#using-default-credentials-with-scopes-in-python).
-
-
 <a id="setup"></a>
 ## Setup
 

docs/EXAMPLES.md

@@ -194,10 +194,10 @@ jobs:
         python -c "
         import os
         import requests
-        
+
         # ID token is available as environment variable
         id_token = os.environ.get('GOOGLE_ID_TOKEN', '${{ steps.auth.outputs.id_token }}')
-        
+
         # Use the token to invoke a Cloud Run service
         response = requests.get(
             'https://myapp-uvehjacqzq.a.run.app',
@@ -209,7 +209,8 @@ jobs:
 
 ### Using Default Credentials with Scopes in Python
 
-When using Workload Identity Federation with Python libraries, you may need to add scopes before refreshing credentials:
+When using Workload Identity Federation with Python libraries, you may need to
+add scopes before refreshing credentials:
 
 ```yaml
 jobs:
@@ -232,18 +233,18 @@ jobs:
         python -c "
         from google.auth import default
         from google.auth.transport.requests import Request
-        
+
         # Get default credentials
         credentials, project = default()
-        
+
         # Add scopes before refreshing for impersonation
         credentials = credentials.with_scopes(
             ['https://www.googleapis.com/auth/cloud-platform']
         )
-        
+
         # Refresh to get the token
         credentials.refresh(request=Request())
-        
+
         # Now you can use the credentials
         print(f'Access token: {credentials.token}')
         if hasattr(credentials, 'id_token'):

docs/TROUBLESHOOTING.md

@@ -230,6 +230,8 @@ tool like `jq`:
 cat credentials.json | jq -r tostring
 ```
 
+<a name="cannot-refresh"></a>
+
 ## Cannot refresh credentials to retrieve an ID token
 
 If you get an error like:
@@ -238,7 +240,9 @@ If you get an error like:
 google.auth.exceptions.RefreshError: ('Unable to acquire impersonated credentials', '{"error": {"code": 400, "message": "Request contains an invalid argument.", "status": "INVALID_ARGUMENT"}}')
 ```
 
-when trying to refresh credentials in Python code to get an ID token, this is usually because the credentials are missing required scopes. The Google Auth library requires scopes to be set when refreshing credentials for impersonation.
+when trying to refresh credentials in Python code to get an ID token, this is
+usually because the credentials are missing required scopes. The Google Auth
+library requires scopes to be set when refreshing credentials for impersonation.
 
 To fix this issue, add the required scopes before refreshing:
 
@@ -247,16 +251,19 @@ from google.auth import default
 from google.auth.transport.requests import Request
 
 credentials, project = default()
+
 # Add scopes before refreshing
 credentials = credentials.with_scopes(
     ["https://www.googleapis.com/auth/cloud-platform"]
 )
 credentials.refresh(request=Request())
+
 # Now you can access the ID token
 print(credentials.id_token)
 ```
 
-Alternatively, you can use the `token_format` parameter of this action to generate an ID token directly:
+Alternatively, you can use the `token_format` parameter of this action to
+generate an ID token directly:
 
 ```yaml
 - uses: 'google-github-actions/auth@v2'
@@ -267,7 +274,8 @@ Alternatively, you can use the `token_format` parameter of this action to genera
     id_token_audience: 'https://example.com'
 ```
 
-This will export the ID token as an environment variable that you can use in your Python code.
+This will export the ID token as an environment variable that you can use in
+your Python code.
 
 ## Organizational Policy Constraints