Code example to match actual output

[tetsutohara]

Description of the feature request:

Hi everyone.

Issues

On the document, the code and expected output does not much.
For example, on python/count_tokens.py explains below.

    def test_tokens_text_only(self):
        # [START tokens_text_only]
        from google import genai

        client = genai.Client()
        prompt = "The quick brown fox jumps over the lazy dog."

        # Count tokens using the new client method.
        total_tokens = client.models.count_tokens(
            model="gemini-3.5-flash", contents=prompt
        )
        print("total_tokens: ", total_tokens)
        # ( e.g., total_tokens: 10 )

        response = client.models.generate_content(
            model="gemini-3.5-flash", contents=prompt
        )

        # The usage_metadata provides detailed token counts.
        print(response.usage_metadata)
        # ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )
        # [END tokens_text_only]

However,

        print("total_tokens: ", total_tokens)
        # ( e.g., total_tokens: 10 )

does not reply as ( e.g. ) says.

Question and Proposal

Are ( e.g.)s intentionally written like above on the document?
If not and if we try to nicely write the document for beginners, we should write like below code.

    def test_tokens_text_only(self):
        # [START tokens_text_only]
        from google import genai

        client = genai.Client()
        prompt = "The quick brown fox jumps over the lazy dog."

        # Count tokens using the new client method.
-       total_tokens = client.models.count_tokens(
-           model="gemini-3.5-flash", contents=prompt
-       )
-       print("total_tokens: ", total_tokens)
+       response = client.models.count_tokens(
+           model="gemini-3.5-flash", contents=prompt
+       )
+       print("total_tokens: ", response.total_tokens)

        # ( e.g., total_tokens: 10 )

        response = client.models.generate_content(
            model="gemini-3.5-flash", contents=prompt
        )

        # The usage_metadata provides detailed token counts.
-        print(response.usage_metadata)
+        metadata = response.usage_metadata
+        print(f"prompt_token_count: {metadata.prompt_token_count}, candidates_token_count: {metadata.candidates_token_count}, total_token_count: {metadata.total_token_count}")
        # ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )
        # [END tokens_text_only]

My concern

If we conduct this change, we have to change many parts on the document. Thus, I need your advices.
Thank you.

What problem are you trying to solve with this feature?

No response

Any other information you'd like to share?

No response

[markmcd]

Thanks for this suggestion.

IMO the shorter version is good as it keeps the code concise without having to enumerate every possible field on the response.

If we want to make sure the values are correct though, you could add assertions to the Python code, so when we run the tests, we will see failures and know they need updating. These should not be part of the sample code though (e.g. they go after the [END ...] block).

[tetsutohara]

Hi @markmcd

Thank you for your reply.
I understand your points.

Can I confirm two things?

1. Is the following example implementation of the assertion correct?

        # The usage_metadata provides detailed token counts.
        print(response.usage_metadata)
        # ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )
        # [END tokens_text_only]

+      self.assertEqual(response.usage_metadata.prompt_token_count, 11)

2. How important is it to add these assertions for this code? I mean, is adding assertions required, or is it just a nice-to-have for now?

Thank you!