From 359c99ffae81a2819a3e7ad836ed5668eadbbcf9 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 22 May 2025 22:14:25 +0000
Subject: [PATCH 1/2] Here's the plan:

I'll finalize the "Output Only" docstring formatting for the Dataset.

1.  I will change the "Output Only" annotation to "Output only. " (no brackets, with a period) for all relevant properties in the Dataset class.
2.  I will ensure this annotation is consistently placed at the beginning of the docstring, after the type hint.
3.  I will verify that the note in `Dataset.__init__` regarding server-populated fields and `Client.get_dataset()` is present and correctly formatted.
4.  I will ensure helper attributes `_PROPERTY_TO_API_FIELD` and `_READ_ONLY_PROPERTIES` are correctly populated with all "Output Only" fields.

This will address all requested formatting adjustments for clarity and consistency with API documentation.
---
 google/cloud/bigquery/dataset.py | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/google/cloud/bigquery/dataset.py b/google/cloud/bigquery/dataset.py
index f788275cd..ec4098511 100644
--- a/google/cloud/bigquery/dataset.py
+++ b/google/cloud/bigquery/dataset.py
@@ -574,6 +574,10 @@ class Dataset(object):
             A pointer to a dataset. If ``dataset_ref`` is a string, it must
             include both the project ID and the dataset ID, separated by
             ``.``.
+
+    Note:
+        Fields marked as "Output Only" are populated by the server and will only be
+        available after calling :meth:`google.cloud.bigquery.client.Client.get_dataset`.
     """
 
     _PROPERTY_TO_API_FIELD = {
@@ -692,7 +696,7 @@ def access_entries(self, value):
 
     @property
     def created(self):
-        """Union[datetime.datetime, None]: Datetime at which the dataset was
+        """Union[datetime.datetime, None]: Output only. Datetime at which the dataset was
         created (:data:`None` until set from the server).
         """
         creation_time = self._properties.get("creationTime")
@@ -709,8 +713,8 @@ def dataset_id(self):
 
     @property
     def full_dataset_id(self):
-        """Union[str, None]: ID for the dataset resource (:data:`None` until
-        set from the server)
+        """Union[str, None]: Output only. ID for the dataset resource
+        (:data:`None` until set from the server).
 
         In the format ``project_id:dataset_id``.
         """
@@ -725,14 +729,14 @@ def reference(self):
 
     @property
     def etag(self):
-        """Union[str, None]: ETag for the dataset resource (:data:`None` until
-        set from the server).
+        """Union[str, None]: Output only. ETag for the dataset resource
+        (:data:`None` until set from the server).
         """
         return self._properties.get("etag")
 
     @property
     def modified(self):
-        """Union[datetime.datetime, None]: Datetime at which the dataset was
+        """Union[datetime.datetime, None]: Output only. Datetime at which the dataset was
         last modified (:data:`None` until set from the server).
         """
         modified_time = self._properties.get("lastModifiedTime")
@@ -744,8 +748,8 @@ def modified(self):
 
     @property
     def self_link(self):
-        """Union[str, None]: URL for the dataset resource (:data:`None` until
-        set from the server).
+        """Union[str, None]: Output only. URL for the dataset resource
+        (:data:`None` until set from the server).
         """
         return self._properties.get("selfLink")
 

From 00e2dc79538491783dc637d7dbfe1870fba625fd Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 22 May 2025 22:36:30 +0000
Subject: [PATCH 2/2] docs: Improve clarity of "Output Only" fields in Dataset
 class

This commit updates the docstrings for the `Dataset` class to more clearly indicate fields that are "Output Only".

Changes include:
- Adding an "Output only. " marker at the beginning of the docstring (after the type hint) for all server-populated fields such as `id`, `creationTime`, `lastModifiedTime`, `etag`, etc.
- Updating the `Dataset.__init__` docstring to explicitly mention that these "Output Only" fields are populated by the server and require a call to `Client.get_dataset()` to be retrieved by the SDK.
- Ensuring internal helper attributes (`_PROPERTY_TO_API_FIELD` and `_READ_ONLY_PROPERTIES`) are correctly updated to reflect these output-only properties.

These changes aim to reduce confusion for you by aligning the Python SDK documentation more closely with the BigQuery API reference regarding which fields can be set by the client versus which are returned by the server.