Skip to content
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

cuDF error handling document #7917

Merged
merged 21 commits into from
Aug 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion docs/cudf/source/developer_guide/contributing_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,4 +108,31 @@ Any attempt to write pure Cython code for this purpose should be justified with

## Exception handling

This section is under development, see https://github.com/rapidsai/cudf/pull/7917.
In alignment with [maintaining compatibility with pandas](#pandas-compatibility),
any API that cuDF shares with pandas should throw all the same exceptions as the
corresponding pandas API given the same inputs.
However, it is not required to match the corresponding pandas API's exception message.

When writing error messages,
sufficient information should be included to help users locate the source of the error,
such as including the expected argument type versus the actual argument provided.

For parameters that are not yet supported,
raise `NotImplementedError`.
There is no need to mention when the argument will be supported in the future.

### Handling libcudf Exceptions

Currently libcudf raises `cudf::logic_error` and `cudf::cuda_error`.
These error types are mapped to `RuntimeError` in python.
Several APIs use the exception payload `what()` message to determine the exception type raised by libcudf.

Determining error type based on exception payload is brittle since libcudf does not maintain API stability on exception messages.
This is a compromise due to libcudf only raising a limited number of error types.
Only adopt this strategy when necessary.

The projected roadmap is to diversify the exception types raised by libcudf.
Standard C++ natively supports various [exception types](https://en.cppreference.com/w/cpp/error/exception),
which Cython maps to [these Python exception types](https://docs.cython.org/en/latest/src/userguide/wrapping_CPlusPlus.html#exceptions).
In the future, libcudf may employ custom C++ exception types.
If that occurs, this section will be updated to reflect how these may be mapped to desired Python exception types.
1 change: 1 addition & 0 deletions docs/cudf/source/developer_guide/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Additionally, it includes longer sections on more specific topics like testing a
:maxdepth: 2

library_design
contributing_guide
Copy link
Contributor Author

@isVoid isVoid Aug 5, 2022

Choose a reason for hiding this comment

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

@vyasr I assume you did not expose the contributing guide because it's incomplete. It should be ready to publish after we merged this PR.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yup, thanks

documentation
options
```