Content-Length: 311466 | pFad | http://togithub.com/googleapis/python-bigquery/pull/2201

A74 docs: Improve clarity of "Output Only" fields in Dataset class by Linchin · Pull Request #2201 · googleapis/python-bigquery · GitHub
Skip to content

docs: Improve clarity of "Output Only" fields in Dataset class #2201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 5, 2025

Conversation

Linchin
Copy link
Contributor

@Linchin Linchin commented May 23, 2025

fixes b/407210727

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.
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.
@Linchin Linchin requested review from a team as code owners May 23, 2025 16:37
@Linchin Linchin requested a review from PhongChuong May 23, 2025 16:37
@product-auto-label product-auto-label bot added the size: s Pull request size is small. label May 23, 2025
@product-auto-label product-auto-label bot added the api: bigquery Issues related to the googleapis/python-bigquery API. label May 23, 2025
@chalmerlowe
Copy link
Collaborator

chalmerlowe commented May 27, 2025

I have reservations about this PR as expressed in internal issue b/407210727, comment #6

It feels like we are going overboard OR not going far enough, with very little happy medium.

@PhongChuong PhongChuong removed their request for review June 3, 2025 19:16
@PhongChuong PhongChuong removed their assignment Jun 4, 2025
Copy link
Collaborator

@chalmerlowe chalmerlowe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending passing tests.

@chalmerlowe chalmerlowe added the automerge Merge the pull request once unit tests and other checks pass. label Jun 5, 2025
@gcf-merge-on-green gcf-merge-on-green bot merged commit bd5aba8 into main Jun 5, 2025
27 checks passed
@gcf-merge-on-green gcf-merge-on-green bot removed the automerge Merge the pull request once unit tests and other checks pass. label Jun 5, 2025
@gcf-merge-on-green gcf-merge-on-green bot deleted the fix-dataset-output-only-docs-final branch June 5, 2025 19:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api: bigquery Issues related to the googleapis/python-bigquery API. size: s Pull request size is small.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants








ApplySandwichStrip

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier!      Saves Data!


--- a PPN by Garber Painting Akron. With Image Size Reduction included!

Fetched URL: http://togithub.com/googleapis/python-bigquery/pull/2201

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy