docs(python): add Raises descriptions for autocomplete #6164 - #8441
Open
AzazelSensei wants to merge 1 commit into
Open
docs(python): add Raises descriptions for autocomplete #6164#8441AzazelSensei wants to merge 1 commit into
AzazelSensei wants to merge 1 commit into
Conversation
Google-style parsers need 'Exception: description', not a bare type name.
AzazelSensei
requested review from
chipkent,
cpwright,
jmao-denver and
rcaudy
as code owners
August 31, 2026 12:59
Contributor
No docs changes detected for 486b7af |
Contributor
|
I have read the CLA Document and I hereby sign the CLA You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Google-style descriptions to Python server API Raises entries so autocomplete can parse and display exception details.
Changes:
- Adds descriptions for
DHError,TypeError,ValueError, and related exceptions. - Splits multi-exception entries into individually documented lines.
- Covers table, time, streaming, plotting, storage, and utility APIs.
Reviewed changes
Copilot reviewed 49 out of 49 changed files in this pull request and generated 21 comments.
Show a summary per file
| File | Description |
|---|---|
py/server/deephaven/uri.py |
Documents URI resolution errors. |
py/server/deephaven/updateby.py |
Documents update-by construction errors. |
py/server/deephaven/time.py |
Documents time and conversion errors. |
py/server/deephaven/table.py |
Documents table operation errors. |
py/server/deephaven/table_listener.py |
Documents listener errors. |
py/server/deephaven/table_factory.py |
Documents table creation errors. |
py/server/deephaven/stream/kafka/producer.py |
Documents Kafka producer errors. |
py/server/deephaven/stream/kafka/consumer.py |
Documents Kafka consumer errors. |
py/server/deephaven/stream/kafka/cdc.py |
Documents CDC errors. |
py/server/deephaven/stream/kafka/__init__.py |
Documents topic-listing errors. |
py/server/deephaven/stream/__init__.py |
Documents stream conversion errors. |
py/server/deephaven/server/executors.py |
Documents executor errors. |
py/server/deephaven/replay.py |
Documents replay errors. |
py/server/deephaven/query_library.py |
Documents query-library import errors. |
py/server/deephaven/plot/selectable_dataset.py |
Documents selectable-dataset errors. |
py/server/deephaven/plot/linestyle.py |
Documents line-style errors. |
py/server/deephaven/plot/figure.py |
Documents figure configuration errors. |
py/server/deephaven/plot/color.py |
Documents color construction errors. |
py/server/deephaven/plot/axistransform.py |
Documents axis-transform errors. |
py/server/deephaven/perfmon.py |
Documents performance-monitoring errors. |
py/server/deephaven/parquet.py |
Documents Parquet operation errors. |
py/server/deephaven/pandas.py |
Documents pandas conversion errors. |
py/server/deephaven/numpy.py |
Documents NumPy conversion errors. |
py/server/deephaven/liveness_scope.py |
Documents liveness-scope errors. |
py/server/deephaven/learn/gather.py |
Documents array-gathering errors. |
py/server/deephaven/learn/__init__.py |
Documents learning-operation errors. |
py/server/deephaven/jcompat.py |
Documents Java compatibility errors. |
py/server/deephaven/html.py |
Documents HTML conversion errors. |
py/server/deephaven/filters.py |
Documents filter construction errors. |
py/server/deephaven/experimental/table_data_service.py |
Documents table-data-service errors. |
py/server/deephaven/experimental/sql.py |
Documents SQL evaluation errors. |
py/server/deephaven/experimental/outer_joins.py |
Documents outer-join errors. |
py/server/deephaven/experimental/iceberg.py |
Normalizes Iceberg error descriptions. |
py/server/deephaven/experimental/data_index.py |
Documents data-index errors. |
py/server/deephaven/experimental/__init__.py |
Documents time-window errors. |
py/server/deephaven/execution_context.py |
Documents execution-context errors. |
py/server/deephaven/dtypes.py |
Documents dtype conversion errors. |
py/server/deephaven/dbc/odbc.py |
Documents ODBC cursor errors. |
py/server/deephaven/dbc/adbc.py |
Documents ADBC cursor errors. |
py/server/deephaven/dbc/__init__.py |
Documents database read errors. |
py/server/deephaven/csv.py |
Documents CSV operation errors. |
py/server/deephaven/column.py |
Documents column construction errors. |
py/server/deephaven/calendar.py |
Documents calendar errors. |
py/server/deephaven/barrage.py |
Documents Barrage session errors. |
py/server/deephaven/arrow.py |
Documents Arrow conversion errors. |
py/server/deephaven/appmode.py |
Documents application-state errors. |
py/server/deephaven/_table_reader.py |
Documents table-reader validation errors. |
py/server/deephaven/_gc.py |
Documents garbage-collection errors. |
py/server/deephaven_internal/jvm/__init__.py |
Documents JVM initialization errors. |
Suppressed comments (9)
py/server/deephaven/calendar.py:39
- The empty quotes look like an unexpanded path placeholder; moreover, this function also accepts a
BusinessCalendar, so the description should cover both branches.
DHError: If unable to add calendar from file ''.
py/server/deephaven/calendar.py:63
- The empty quotes look like an unexpanded name placeholder and make the description misleading.
DHError: If unable to set the default calendar name to ''.
py/server/deephaven/column.py:171
- The empty parentheses look like an unexpanded column-name placeholder and will be displayed verbatim in autocomplete.
DHError: If unable to create a ColumnDefinition ().
py/server/deephaven/experimental/iceberg.py:955
- This edit introduces a duplicated period in an already complete Raises description.
DHError: If unable to build the catalog adapter..
py/server/deephaven/_table_reader.py:274
- Besides invalid column names,
namedtuplecan reject an invalidtuple_name, and_table_reader_chunkrejects a negativechunk_size; the new description omits both cases.
ValueError: If a column name is invalid.
py/server/deephaven/_table_reader.py:329
- This wrapper delegates to
_table_reader_chunk, which raisesValueErrorfor a negativechunk_sizeas well as an invalid column name.
ValueError: If a column name is invalid.
py/server/deephaven/_table_reader.py:382
- Besides invalid column names,
namedtuplecan reject an invalidtuple_name, and_table_reader_chunkrejects a negativechunk_size; the new description omits both cases.
ValueError: If a column name is invalid.
py/server/deephaven/_table_reader.py:229
- This wrapper delegates to
_table_reader_chunk, which also raisesValueErrorwhenchunk_sizeis negative; documenting only column names omits a public argument failure.
ValueError: If a column name is invalid.
py/server/deephaven/table_listener.py:663
- This method raises
RuntimeErrorwhenstart()is called twice, but the updated Raises section still lists onlyDHError.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| Raises: | ||
| DHError, TypeError | ||
| DHError: If converting to a Python time value fails. | ||
| TypeError: If the value cannot be converted to datetime.datetime. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If table asb_sum_by operation fails. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If table avg_by operation fails. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If sum_by operation on the PartitionedTableProxy fails. |
| Raises: | ||
| DHError, TypeError | ||
| DHError: If the operation fails. | ||
| TypeError: If expect got instead. |
|
|
||
| Raises: | ||
| ValueError | ||
| ValueError: If chunk_size is negative. |
| DHError, TypeError, ValueError | ||
| DHError: If converting to a Python time value fails. | ||
| TypeError: If the value cannot be converted to numpy.timedelta64. | ||
| ValueError: If the period is not days, months, or years. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If await_update was interrupted. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If unable to listen to the table changes. |
|
|
||
| Raises: | ||
| DHError | ||
| DHError: If neither refresh_interval_ms nor source_tables is provided. |
jmao-denver
added
NoDocumentationNeeded
NoReleaseNotesNeeded
Contributor
|
Hi @AzazelSensei, thanks for the PR. Please address the CI failures and the comments from Copilot. If you need help, let me know. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Google-style docstring parsers skip a Raises entry that is only a type name, so autocomplete never shows it.
I added a short description after each Raises exception in the Python server API. Existing descriptions are unchanged.
Closes #6164