docs: add one-line docstrings to root-level helper modules by jacalata · Pull Request #1859 · tableau/server-client-python · GitHub

Motivation

The api-ref migration audit's needs_docstring bucket includes a few
helper modules that live outside server/endpoint/ and models/. They
each ship a small number of small functions, and none of them had
docstrings. Missing docstrings mean Sphinx has nothing to render on the
generated page under #1832, so users looking up parse_datetime or the
exponential-backoff constants find bare signatures with no explanation.

Behavior change

Docs only. No runtime code changes.

Four commits, one file each:

filesys_helpers.py — one-line docstring on each of the helper functions
namespace.py — one-line docstring on the module and the Namespace class
datetime_helpers.py — one-line docstrings on timestamp, parse_datetime,
format_datetime, and the UTC tzinfo class
exponential_backoff.py + config.py — one-line docstrings on the backoff
helper and the config module's public constants

Each docstring states what the function does in one sentence. Nothing
prescriptive — these helpers are stable and the docstrings are meant to
be captured by Sphinx, not to change behavior.

Test plan

No test changes; no runtime code changes.
mypy + black --check clean.
Once docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference #1832 lands, the generated Sphinx output for these modules
will render the new docstrings.

🤖 Generated with Claude Code

Coverage Report

File	Stmts	Miss	Cover	Missing
tableauserverclient
__init__.py	5	0	100%
config.py	15	0	100%
datetime_helpers.py	25	1	1	96%
exponential_backoff.py	20	0	100%
filesys_helpers.py	31	0	100%
namespace.py	25	3	3	88%
tableauserverclient/bin
__init__.py	2	0	100%
_version.py	358	212	212	41%
tableauserverclient/helpers
__init__.py	1	0	100%
logging.py	2	0	100%
strings.py	31	1	1	97%
tableauserverclient/models
__init__.py	46	0	100%
collection_item.py	41	7	7	83%
column_item.py	55	32	32	42%
connection_credentials.py	35	11	11	69%
connection_item.py	94	14	14	85%
custom_view_item.py	144	21	21	85%
data_acceleration_report_item.py	54	1	1	98%
data_alert_item.py	158	4	4	97%
data_freshness_policy_item.py	155	15	15	90%
database_item.py	207	36	36	83%
datasource_item.py	300	12	12	96%
dqw_item.py	104	5	5	95%
exceptions.py	4	0	100%
extensions_item.py	132	4	4	97%
extract_item.py	44	4	4	91%
favorites_item.py	69	8	8	88%
fileupload_item.py	19	0	100%
flow_item.py	149	10	10	93%
flow_run_item.py	71	0	100%
group_item.py	89	6	6	93%
groupset_item.py	49	7	7	86%
interval_item.py	182	32	32	82%
job_item.py	192	10	10	95%
linked_tasks_item.py	79	1	1	99%
location_item.py	29	2	2	93%
metric_item.py	129	13	13	90%
oidc_item.py	63	3	3	95%
pagination_item.py	34	1	1	97%
permissions_item.py	111	12	12	89%
project_item.py	207	31	31	85%
property_decorators.py	100	18	18	82%
reference_item.py	26	2	2	92%
revision_item.py	59	1	1	98%
schedule_item.py	209	6	6	97%
server_info_item.py	37	7	7	81%
site_item.py	636	13	13	98%
subscription_item.py	101	2	2	98%
table_item.py	119	18	18	85%
tableau_auth.py	61	25	25	59%
tableau_types.py	27	1	1	96%
tag_item.py	15	0	100%
target.py	6	0	100%
task_item.py	56	2	2	96%
user_item.py	323	16	16	95%
view_item.py	220	16	16	93%
virtual_connection_item.py	64	8	8	88%
webhook_item.py	69	1	1	99%
workbook_item.py	362	16	16	96%
tableauserverclient/server
__init__.py	9	0	100%
exceptions.py	4	0	100%
filter.py	29	1	1	97%
pager.py	33	1	1	97%
query.py	143	15	15	90%
request_factory.py	1335	195	195	85%
request_options.py	386	5	5	99%
server.py	188	23	23	88%
sort.py	6	0	100%
tableauserverclient/server/endpoint
__init__.py	35	0	100%
auth_endpoint.py	73	10	10	86%
custom_views_endpoint.py	152	12	12	92%
data_acceleration_report_endpoint.py	21	0	100%
data_alert_endpoint.py	94	23	23	76%
databases_endpoint.py	111	30	30	73%
datasources_endpoint.py	323	33	33	90%
default_permissions_endpoint.py	44	3	3	93%
dqw_endpoint.py	45	16	16	64%
endpoint.py	259	24	24	91%
exceptions.py	79	6	6	92%
extensions_endpoint.py	31	0	100%
favorites_endpoint.py	94	22	22	77%
fileuploads_endpoint.py	51	0	100%
flow_runs_endpoint.py	62	9	9	85%
flow_task_endpoint.py	21	2	2	90%
flows_endpoint.py	198	53	53	73%
groups_endpoint.py	126	9	9	93%
groupsets_endpoint.py	72	7	7	90%
jobs_endpoint.py	67	9	9	87%
linked_tasks_endpoint.py	37	0	100%
metadata_endpoint.py	88	14	14	84%
metrics_endpoint.py	55	6	6	89%
oidc_endpoint.py	42	1	1	98%
permissions_endpoint.py	44	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	127	35	35	72%
schedules_endpoint.py	119	11	11	91%
server_info_endpoint.py	36	10	10	72%
sites_endpoint.py	130	27	27	79%
subscriptions_endpoint.py	56	14	14	75%
tables_endpoint.py	110	36	36	67%
tasks_endpoint.py	63	6	6	90%
users_endpoint.py	183	8	8	96%
views_endpoint.py	150	9	9	94%
virtual_connections_endpoint.py	113	10	10	91%
webhooks_endpoint.py	54	9	9	83%
workbooks_endpoint.py	338	22	22	93%
TOTAL	12064	1424	88%

Pull request overview

This PR improves the generated API reference by adding concise, one-line docstrings to several root-level helper modules so Sphinx can render meaningful descriptions for commonly used helpers and constants.

Changes:

Add module/class/function docstrings in namespace.py, filesys_helpers.py, datetime_helpers.py, and exponential_backoff.py.
Add docstrings to Config and its public configuration properties in config.py.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tableauserverclient/namespace.py	Adds docstrings for the namespace helper error and class/method.
tableauserverclient/filesys_helpers.py	Adds docstrings for filename/path helpers and file inspection utilities.
tableauserverclient/exponential_backoff.py	Adds docstrings for the backoff timer class and its sleep behavior.
tableauserverclient/datetime_helpers.py	Adds docstrings clarifying timestamp/UTC parsing and formatting helpers.
tableauserverclient/config.py	Adds docstrings documenting env-var-driven runtime configuration properties.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Two one-word docstring nits from Copilot: - CHUNK_SIZE_MB docstring now names the default (50). Previously it cited the env var without saying what a caller gets if it isn't set. - get_file_type's docstring now mentions it raises ValueError when no magic bytes match, instead of only describing the happy path.

Two one-word nits: - config.py: PAGE_SIZE docstring names the default (100), matching the sibling docstrings on FILESIZE_LIMIT_MB and CHUNK_SIZE_MB. - namespace.py: detect() docstring now mentions it raises UnknownNamespaceError on unrecognized namespaces. Matches the earlier fix on get_file_type's ValueError.

docs only change, merging with AI review only

jacalata added 4 commits August 11, 2026 13:53

docs: add docstrings to exponential_backoff.py

8c2fa08

docs: add docstrings to datetime_helpers.py

b4babb4

docs: add docstrings to namespace.py

a36c2e6

docs: add docstrings to filesys_helpers.py

46aa1bc

jacalata requested a lite review from Copilot August 17, 2026 20:03

Copilot started reviewing on behalf of jacalata August 17, 2026 20:04 View session

Copilot AI reviewed Aug 17, 2026

View reviewed changes

Comment thread tableauserverclient/config.py

Comment thread tableauserverclient/filesys_helpers.py Outdated

jacalata added 2 commits August 18, 2026 01:27

jacalata enabled auto-merge (squash) August 20, 2026 05:41

jacalata disabled auto-merge August 20, 2026 07:35

jacalata merged commit 1823c78 into development Aug 20, 2026
31 checks passed

jacalata deleted the jac/docstrings-root-files branch August 20, 2026 07:36

docs: add one-line docstrings to root-level helper modules by jacalata · Pull Request #1859 · tableau/server-client-python · GitHub

Uh oh!

docs: add one-line docstrings to root-level helper modules - #1859

docs: add one-line docstrings to root-level helper modules#1859
jacalata merged 6 commits into
developmentfrom
jac/docstrings-root-files

jacalata commented Aug 11, 2026

Uh oh!

github-actions Bot commented Aug 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

jacalata commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: add one-line docstrings to root-level helper modules by jacalata · Pull Request #1859 · tableau/server-client-python · GitHub

Uh oh!

docs: add one-line docstrings to root-level helper modules - #1859

docs: add one-line docstrings to root-level helper modules#1859jacalata merged 6 commits intodevelopmenttableau/server-client-python:developmentfrom jac/docstrings-root-filestableau/server-client-python:jac/docstrings-root-filesCopy head branch name to clipboard

Conversation

jacalata commented Aug 11, 2026

Motivation

Behavior change

Test plan

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

jacalata commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: add one-line docstrings to root-level helper modules#1859
jacalata merged 6 commits into
developmentfrom
jac/docstrings-root-files

github-actions Bot commented Aug 11, 2026 •
edited
Loading