diff --git a/docs/cudf/source/conf.py b/docs/cudf/source/conf.py index 64468754dcef..409a438d4579 100644 --- a/docs/cudf/source/conf.py +++ b/docs/cudf/source/conf.py @@ -39,6 +39,7 @@ from sphinx.ext import intersphinx from sphinx.ext.autodoc import ClassDocumenter from sphinx.highlighting import lexers +from sphinx.util.nodes import make_refnode class PseudoLexer(RegexLexer): @@ -497,6 +498,27 @@ def _cached_intersphinx_lookup(env, node, contnode): return ref +def _resolve_cpp_xref(app, env, node, contnode, name): + docname, objtype, anchor = _domain_objects[name] + fromdocname = node.get("refdoc", env.docname) + for reftype in (node["reftype"], objtype): + if ( + ref := env.domains["cpp"].resolve_xref( + env, + fromdocname, + app.builder, + reftype, + name, + node, + contnode, + ) + ) is not None: + return ref + return make_refnode( + app.builder, fromdocname, docname, anchor, contnode, name + ) + + def on_missing_reference(app, env, node, contnode): # These variables are defined outside the function to speed up the build. global \ @@ -512,8 +534,10 @@ def on_missing_reference(app, env, node, contnode): if _domain_objects is None: _domain_objects = {} _prefixed_domain_objects = {} - for name, _, _, docname, _, _ in env.domains["cpp"].get_objects(): - _domain_objects[name] = docname + for name, _, objtype, docname, anchor, _ in env.domains[ + "cpp" + ].get_objects(): + _domain_objects[name] = (docname, objtype, anchor) for prefix in _all_namespaces: _prefixed_domain_objects[f"{prefix}{name}"] = name @@ -562,6 +586,15 @@ def on_missing_reference(app, env, node, contnode): if match := re.search("(.*)<.*>", reftarget): reftarget = match.group(1) + # Breathe sometimes emits bare C++ targets that are already registered + # in the C++ domain, for example enum types in parameter lists. + if ( + reftarget in _domain_objects + and (ref := _resolve_cpp_xref(app, env, node, contnode, reftarget)) + is not None + ): + return ref + # Try to find the target prefixed with e.g. namespaces in case that's # all that's missing. # We need to do this search because the call sites may not have used @@ -576,15 +609,7 @@ def on_missing_reference(app, env, node, contnode): name = f"{prefix}{reftarget}" break if name is not None: - return env.domains["cpp"].resolve_xref( - env, - _domain_objects[name], - app.builder, - node["reftype"], - name, - node, - contnode, - ) + return _resolve_cpp_xref(app, env, node, contnode, name) # Final possibility is an intersphinx lookup to see if the symbol # exists in one of the other inventories. First we check the symbol diff --git a/python/pylibcudf/pylibcudf/column.pyx b/python/pylibcudf/pylibcudf/column.pyx index 3ffe35ee212b..826cf4e1b503 100644 --- a/python/pylibcudf/pylibcudf/column.pyx +++ b/python/pylibcudf/pylibcudf/column.pyx @@ -615,7 +615,7 @@ cdef class Column: DataType dtype, size_type size, children: Iterable[Column], - ): + ) -> Column: """ Create a Column from an RMM DeviceBuffer. @@ -825,7 +825,7 @@ cdef class Column: size_type size, object stream: CudaStreamLike | None = None, DeviceMemoryResource mr=None, - ): + ) -> Column: """Create a Column from a Scalar. Parameters @@ -894,7 +894,7 @@ cdef class Column: size_type size, object stream: CudaStreamLike | None = None, DeviceMemoryResource mr=None, - ): + ) -> Column: """Create an all null column from a template. Parameters @@ -988,7 +988,7 @@ cdef class Column: cls, obj: SupportsArrayInterface, object stream: CudaStreamLike | None = None, - ): + ) -> Column: """ Create a Column from an object implementing the NumPy Array Interface. @@ -1046,7 +1046,7 @@ cdef class Column: cls, obj: SupportsCudaArrayInterface, object stream: CudaStreamLike | None = None, - ): + ) -> Column: """ Create a Column from an object implementing the CUDA Array Interface. @@ -1089,7 +1089,7 @@ cdef class Column: cls, obj: SupportsCudaArrayInterface | SupportsArrayInterface, object stream: CudaStreamLike | None = None, - ): + ) -> Column: """ Create a Column from any object which supports the NumPy or CUDA array interface. @@ -1308,7 +1308,7 @@ cdef class Column: release_arrow_array_raw(raw_host_array_ptr) @classmethod - def struct_from_children(cls, children: Iterable[Column]): + def struct_from_children(cls, children: Iterable[Column]) -> Column: """ Create a struct Column from a list of child columns. diff --git a/python/pylibcudf/pylibcudf/io/avro.pyx b/python/pylibcudf/pylibcudf/io/avro.pyx index 7343fe46559e..0e1e1e0797d8 100644 --- a/python/pylibcudf/pylibcudf/io/avro.pyx +++ b/python/pylibcudf/pylibcudf/io/avro.pyx @@ -34,7 +34,7 @@ cdef class AvroReaderOptions: For details, see :cpp:class:`cudf::io::avro_reader_options` """ @staticmethod - def builder(SourceInfo source): + def builder(SourceInfo source) -> AvroReaderOptionsBuilder: """ Create a AvroWriterOptionsBuilder object @@ -93,6 +93,8 @@ cdef class AvroReaderOptions: cdef class AvroReaderOptionsBuilder: + """Builder to build options for ``read_avro``.""" + cpdef AvroReaderOptionsBuilder columns(self, list col_names: list[str]): """ Set names of the column to be read. diff --git a/python/pylibcudf/pylibcudf/io/csv.pyx b/python/pylibcudf/pylibcudf/io/csv.pyx index 71de5671ecf9..7a1f2a64abdc 100644 --- a/python/pylibcudf/pylibcudf/io/csv.pyx +++ b/python/pylibcudf/pylibcudf/io/csv.pyx @@ -53,7 +53,7 @@ cdef class CsvReaderOptions: For details, see :cpp:class:`cudf::io::csv_reader_options` """ @staticmethod - def builder(SourceInfo source): + def builder(SourceInfo source) -> CsvReaderOptionsBuilder: """ Create a CsvWriterOptionsBuilder object @@ -715,7 +715,7 @@ cdef class CsvWriterOptions: For details, see :cpp:class:`cudf::io::csv_writer_options` """ @staticmethod - def builder(SinkInfo sink, Table table): + def builder(SinkInfo sink, Table table) -> CsvWriterOptionsBuilder: """Create a CsvWriterOptionsBuilder object For details, see :cpp:func:`cudf::io::csv_writer_options::builder` diff --git a/python/pylibcudf/pylibcudf/io/json.pxd b/python/pylibcudf/pylibcudf/io/json.pxd index e46942ea14bc..c348bcce046c 100644 --- a/python/pylibcudf/pylibcudf/io/json.pxd +++ b/python/pylibcudf/pylibcudf/io/json.pxd @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION. +# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 from libcpp cimport bool from libcpp.map cimport map @@ -79,7 +79,7 @@ cdef class JsonReaderOptionsBuilder: ) cpdef JsonReaderOptionsBuilder strict_validation(self, bool val) cpdef JsonReaderOptionsBuilder unquoted_control_chars(self, bool val) - cpdef build(self) + cpdef JsonReaderOptions build(self) cpdef TableWithMetadata read_json( JsonReaderOptions options, object stream = *, DeviceMemoryResource mr = * diff --git a/python/pylibcudf/pylibcudf/io/json.pyx b/python/pylibcudf/pylibcudf/io/json.pyx index b38ee649339b..e79fce019d9e 100644 --- a/python/pylibcudf/pylibcudf/io/json.pyx +++ b/python/pylibcudf/pylibcudf/io/json.pyx @@ -162,7 +162,7 @@ cdef class JsonReaderOptions: For details, see `:cpp:class:`cudf::io::json_reader_options` """ @staticmethod - def builder(SourceInfo source): + def builder(SourceInfo source) -> JsonReaderOptionsBuilder: """ Create a JsonReaderOptionsBuilder object @@ -362,6 +362,8 @@ cdef class JsonReaderOptions: cdef class JsonReaderOptionsBuilder: + """Builder to build options for ``read_json``.""" + cpdef JsonReaderOptionsBuilder byte_range_offset(self, size_t byte_range_offset): """ Set number of bytes to skip from source start. @@ -701,7 +703,7 @@ cdef class JsonReaderOptionsBuilder: self.c_obj.unquoted_control_chars(val) return self - cpdef build(self): + cpdef JsonReaderOptions build(self): """Create a JsonReaderOptions object""" cdef JsonReaderOptions json_options = JsonReaderOptions.__new__( JsonReaderOptions @@ -911,7 +913,7 @@ cdef class JsonWriterOptions: For details, see :cpp:class:`cudf::io::json_writer_options` """ @staticmethod - def builder(SinkInfo sink, Table table): + def builder(SinkInfo sink, Table table) -> JsonWriterOptionsBuilder: """ Create a JsonWriterOptionsBuilder object @@ -996,6 +998,8 @@ cdef class JsonWriterOptions: self.c_obj.set_compression(comptype) cdef class JsonWriterOptionsBuilder: + """Builder to build options for ``write_json``.""" + cpdef JsonWriterOptionsBuilder metadata(self, TableWithMetadata tbl_w_meta): """ Sets optional metadata (with column names). diff --git a/python/pylibcudf/pylibcudf/io/orc.pyx b/python/pylibcudf/pylibcudf/io/orc.pyx index b91473d79541..50d0185ea113 100644 --- a/python/pylibcudf/pylibcudf/io/orc.pyx +++ b/python/pylibcudf/pylibcudf/io/orc.pyx @@ -275,7 +275,7 @@ cdef class OrcReaderOptions: For details, see :cpp:class:`cudf::io::orc_reader_options` """ @staticmethod - def builder(SourceInfo source): + def builder(SourceInfo source) -> OrcReaderOptionsBuilder: """ Create a OrcReaderOptionsBuilder object @@ -423,6 +423,8 @@ cdef class OrcReaderOptions: self.c_obj.set_source(src.c_obj) cdef class OrcReaderOptionsBuilder: + """Builder to build options for ``read_orc``.""" + cpdef OrcReaderOptionsBuilder use_index(self, bool use): """ Enable/Disable use of row index to speed-up reading. @@ -507,6 +509,8 @@ cpdef ParsedOrcStatistics read_parsed_orc_statistics( cdef class OrcWriterOptions: + """The settings to use for ``write_orc``.""" + cpdef void set_stripe_size_bytes(self, size_t size_bytes): """ Sets the maximum stripe size, in bytes. @@ -564,7 +568,7 @@ cdef class OrcWriterOptions: self.c_obj.set_row_index_stride(stride) @staticmethod - def builder(SinkInfo sink, Table table): + def builder(SinkInfo sink, Table table) -> OrcWriterOptionsBuilder: """ Create builder to create OrcWriterOptions. @@ -591,6 +595,8 @@ cdef class OrcWriterOptions: cdef class OrcWriterOptionsBuilder: + """Builder to build options for ``write_orc``.""" + cpdef OrcWriterOptionsBuilder compression(self, compression_type comp): """ Sets compression type. @@ -613,7 +619,7 @@ cdef class OrcWriterOptionsBuilder: """ Choose granularity of column statistics to be written. - For details, see :cpp:func:`enable_statistics` + For details, see :cpp:func:`cudf::io::orc_writer_options_builder::enable_statistics` Parameters ---------- @@ -758,6 +764,8 @@ cdef class OrcChunkedWriter: cdef class ChunkedOrcWriterOptions: + """The settings to use for chunked ORC writing.""" + cpdef void set_stripe_size_bytes(self, size_t size_bytes): """ Sets the maximum stripe size, in bytes. @@ -809,7 +817,7 @@ cdef class ChunkedOrcWriterOptions: self.c_obj.set_row_index_stride(stride) @staticmethod - def builder(SinkInfo sink): + def builder(SinkInfo sink) -> ChunkedOrcWriterOptionsBuilder: """ Create builder to create ChunkedOrcWriterOptions. @@ -834,6 +842,8 @@ cdef class ChunkedOrcWriterOptions: cdef class ChunkedOrcWriterOptionsBuilder: + """Builder to build options for chunked ORC writing.""" + cpdef ChunkedOrcWriterOptionsBuilder compression(self, compression_type comp): """ Sets compression type. diff --git a/python/pylibcudf/pylibcudf/io/parquet.pxd b/python/pylibcudf/pylibcudf/io/parquet.pxd index 3178c67dec11..3570e19c4a71 100644 --- a/python/pylibcudf/pylibcudf/io/parquet.pxd +++ b/python/pylibcudf/pylibcudf/io/parquet.pxd @@ -73,7 +73,7 @@ cdef class ParquetReaderOptionsBuilder: cpdef ParquetReaderOptionsBuilder use_jit_filter(self, bool use_jit_filter) cpdef ParquetReaderOptionsBuilder case_sensitive_names(self, bool val) cpdef ParquetReaderOptionsBuilder decimal_width(self, type_id width) - cpdef build(self) + cpdef ParquetReaderOptions build(self) cdef class ChunkedParquetReader: diff --git a/python/pylibcudf/pylibcudf/io/parquet.pyx b/python/pylibcudf/pylibcudf/io/parquet.pyx index 8ed8ed94981e..97a770ea7df7 100644 --- a/python/pylibcudf/pylibcudf/io/parquet.pyx +++ b/python/pylibcudf/pylibcudf/io/parquet.pyx @@ -119,7 +119,7 @@ cdef class ParquetReaderOptions: For details, see :cpp:class:`cudf::io::parquet_reader_options` """ @staticmethod - def builder(SourceInfo source): + def builder(SourceInfo source) -> ParquetReaderOptionsBuilder: """ Create a ParquetReaderOptionsBuilder object @@ -344,6 +344,8 @@ cdef class ParquetReaderOptions: return self.c_obj.is_enabled_case_sensitive_names() cdef class ParquetReaderOptionsBuilder: + """Builder to build options for ``read_parquet``.""" + cpdef ParquetReaderOptionsBuilder convert_strings_to_categories(self, bool val): """ Sets enable/disable conversion of strings to categories. @@ -567,7 +569,7 @@ cdef class ParquetReaderOptionsBuilder: self.c_obj.decimal_width(width) return self - cpdef build(self): + cpdef ParquetReaderOptions build(self): """Create a ParquetReaderOptions object""" cdef ParquetReaderOptions parquet_options = ParquetReaderOptions.__new__( ParquetReaderOptions @@ -834,8 +836,10 @@ cdef class ChunkedParquetWriter: cdef class ChunkedParquetWriterOptions: + """The settings to use for chunked Parquet writing.""" + @staticmethod - def builder(SinkInfo sink): + def builder(SinkInfo sink) -> ChunkedParquetWriterOptionsBuilder: """ Create builder to create ChunkedParquetWriterOptions. @@ -874,6 +878,8 @@ cdef class ChunkedParquetWriterOptions: cdef class ChunkedParquetWriterOptionsBuilder: + """Builder to build options for chunked Parquet writing.""" + cpdef ChunkedParquetWriterOptionsBuilder metadata( self, TableInputMetadata metadata @@ -1046,9 +1052,10 @@ cdef class ChunkedParquetWriterOptionsBuilder: cdef class ParquetWriterOptions: + """The settings to use for ``write_parquet``.""" @staticmethod - def builder(SinkInfo sink, Table table): + def builder(SinkInfo sink, Table table) -> ParquetWriterOptionsBuilder: """ Create builder to create ParquetWriterOptionsBuilder. @@ -1186,6 +1193,7 @@ cdef class ParquetWriterOptions: cdef class ParquetWriterOptionsBuilder: + """Builder to build options for ``write_parquet``.""" cpdef ParquetWriterOptionsBuilder metadata(self, TableInputMetadata metadata): """ diff --git a/python/pylibcudf/pylibcudf/io/parquet_metadata.pxd b/python/pylibcudf/pylibcudf/io/parquet_metadata.pxd index fedbca1800f2..32712ccc12fd 100644 --- a/python/pylibcudf/pylibcudf/io/parquet_metadata.pxd +++ b/python/pylibcudf/pylibcudf/io/parquet_metadata.pxd @@ -58,7 +58,7 @@ cdef class ParquetMetadata: cpdef int num_rowgroups(self) - cpdef list num_rowgroups_per_file(self) + cpdef list[int] num_rowgroups_per_file(self) cpdef dict metadata(self) diff --git a/python/pylibcudf/pylibcudf/io/parquet_metadata.pyx b/python/pylibcudf/pylibcudf/io/parquet_metadata.pyx index e6015786173b..4bb0e42f0068 100644 --- a/python/pylibcudf/pylibcudf/io/parquet_metadata.pyx +++ b/python/pylibcudf/pylibcudf/io/parquet_metadata.pyx @@ -230,7 +230,7 @@ cdef class ParquetMetadata: """ return self.meta.num_rowgroups() - cpdef list num_rowgroups_per_file(self): + cpdef list[int] num_rowgroups_per_file(self): """ Returns the number of rowgroups in each file. """ diff --git a/python/pylibcudf/pylibcudf/json.pyx b/python/pylibcudf/pylibcudf/json.pyx index ca1222f5385f..983b4c72976d 100644 --- a/python/pylibcudf/pylibcudf/json.pyx +++ b/python/pylibcudf/pylibcudf/json.pyx @@ -41,7 +41,7 @@ cdef class GetJsonObjectOptions: __hash__ = None - def get_allow_single_quotes(self): + def get_allow_single_quotes(self) -> bool: """ Returns true/false depending on whether single-quotes for representing strings are allowed. @@ -53,7 +53,7 @@ cdef class GetJsonObjectOptions: """ return self.options.get_allow_single_quotes() - def get_strip_quotes_from_single_strings(self): + def get_strip_quotes_from_single_strings(self) -> bool: """ Returns true/false depending on whether individually returned string values have their quotes stripped. @@ -65,7 +65,7 @@ cdef class GetJsonObjectOptions: """ return self.options.get_strip_quotes_from_single_strings() - def get_missing_fields_as_nulls(self): + def get_missing_fields_as_nulls(self) -> bool: """ Whether a field not contained by an object is to be interpreted as null. diff --git a/python/pylibcudf/pylibcudf/scalar.pyx b/python/pylibcudf/pylibcudf/scalar.pyx index 2a663104a8d6..e5c51a15685e 100644 --- a/python/pylibcudf/pylibcudf/scalar.pyx +++ b/python/pylibcudf/pylibcudf/scalar.pyx @@ -256,7 +256,7 @@ cdef class Scalar: dtype: DataType | None = None, stream: Stream | None = None, mr: DeviceMemoryResource | None = None - ): + ) -> Scalar: """ Convert a Python standard library object to a Scalar. @@ -288,7 +288,7 @@ cdef class Scalar: np_val, stream: Stream | None = None, mr: DeviceMemoryResource | None = None - ): + ) -> Scalar: """ Convert a NumPy scalar to a Scalar. @@ -311,7 +311,9 @@ cdef class Scalar: mr = _get_memory_resource(mr) return _from_numpy(np_val, _stream, mr) - def to_py(self, stream: Stream | None = None): + def to_py( + self, stream: Stream | None = None + ) -> None | int | float | str | bool | decimal.Decimal: """ Convert a Scalar to a Python scalar. diff --git a/python/pylibcudf/pylibcudf/strings/regex_program.pyx b/python/pylibcudf/pylibcudf/strings/regex_program.pyx index df192571761f..40f21f6f06a3 100644 --- a/python/pylibcudf/pylibcudf/strings/regex_program.pyx +++ b/python/pylibcudf/pylibcudf/strings/regex_program.pyx @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION. +# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 @@ -25,7 +25,7 @@ cdef class RegexProgram: __hash__ = None @staticmethod - def create(str pattern, regex_flags flags): + def create(str pattern, regex_flags flags) -> RegexProgram: """Create a program from a pattern. For detils, see :cpp:func:`create`. diff --git a/python/pylibcudf/pylibcudf/table.pxd b/python/pylibcudf/pylibcudf/table.pxd index dc459f9245d2..167374f294c9 100644 --- a/python/pylibcudf/pylibcudf/table.pxd +++ b/python/pylibcudf/pylibcudf/table.pxd @@ -16,7 +16,7 @@ cdef class Table: cpdef int num_columns(self) cpdef int num_rows(self) - cpdef tuple shape(self) + cpdef tuple[int, int] shape(self) @staticmethod cdef Table from_libcudf( diff --git a/python/pylibcudf/pylibcudf/table.pyx b/python/pylibcudf/pylibcudf/table.pyx index 7c6d5b06c65b..2876659a7540 100644 --- a/python/pylibcudf/pylibcudf/table.pyx +++ b/python/pylibcudf/pylibcudf/table.pyx @@ -360,7 +360,7 @@ cdef class Table: self._num_rows = 0 return columns - cpdef tuple shape(self): + cpdef tuple[int, int] shape(self): """The shape of this table""" return (self.num_rows(), self.num_columns())