Skip to content

Commit 10b831c

Browse files
Merge pull request #1636 from IntelPython/more-docstring-edits
More docstring edits
2 parents 0e05320 + e3bc17f commit 10b831c

19 files changed

+2038
-1044
lines changed

.flake8

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ per-file-ignores =
2929
dpctl/tensor/numpy_usm_shared.py: F821
3030
dpctl/tests/_cython_api.pyx: E999, E225, E227, E402
3131
dpctl/utils/_compute_follows_data.pyx: E999, E225, E227
32+
dpctl/utils/_onetrace_context.py: E501, W505
33+
dpctl/tensor/_array_api.py: E501, W505
3234
examples/cython/sycl_buffer/syclbuffer/_buffer_example.pyx: E999, E225, E402
3335
examples/cython/usm_memory/blackscholes/blackscholes.pyx: E999, E225, E226, E402
3436
examples/cython/use_dpctl_sycl/use_dpctl_sycl/_cython_api.pyx: E999, E225, E226, E402

dpctl/_sycl_context.pyx

Lines changed: 96 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -100,68 +100,68 @@ cdef class SyclContext(_SyclContext):
100100
101101
There are multiple ways to create a :class:`dpctl.SyclContext` object:
102102
103-
- Invoking the constructor with no arguments creates a context using
104-
the default selector.
103+
- Invoking the constructor with no arguments creates a context using
104+
the default selector.
105105
106-
:Example:
107-
.. code-block:: python
106+
:Example:
107+
.. code-block:: python
108108
109-
import dpctl
109+
import dpctl
110110
111-
# Create a SyclContext for default-selected device
112-
ctx = dpctl.SyclContext()
113-
print(ctx.get_devices())
111+
# Create a SyclContext for default-selected device
112+
ctx = dpctl.SyclContext()
113+
print(ctx.get_devices())
114114
115-
- Invoking the constructor with a specific filter string that creates a
116-
context for the device corresponding to the filter string.
115+
- Invoking the constructor with a specific filter string that creates a
116+
context for the device corresponding to the filter string.
117117
118-
:Example:
119-
.. code-block:: python
118+
:Example:
119+
.. code-block:: python
120120
121-
import dpctl
121+
import dpctl
122122
123-
# Create SyclContext for a gpu device
124-
ctx = dpctl.SyclContext("gpu")
125-
d = ctx.get_devices()[0]
126-
assert(d.is_gpu)
123+
# Create SyclContext for a gpu device
124+
ctx = dpctl.SyclContext("gpu")
125+
d = ctx.get_devices()[0]
126+
assert(d.is_gpu)
127127
128-
- Invoking the constructor with a :class:`dpctl.SyclDevice` object
129-
creates a context for that device.
128+
- Invoking the constructor with a :class:`dpctl.SyclDevice` object
129+
creates a context for that device.
130130
131-
:Example:
132-
.. code-block:: python
131+
:Example:
132+
.. code-block:: python
133133
134-
import dpctl
134+
import dpctl
135135
136-
# Create a level zero gpu device
137-
d = dpctl.SyclDevice("level_zero:gpu")
138-
ctx = dpctl.SyclContext(d)
139-
d = ctx.get_devices()[0]
140-
assert(d.is_gpu)
136+
# Create a level zero gpu device
137+
d = dpctl.SyclDevice("level_zero:gpu")
138+
ctx = dpctl.SyclContext(d)
139+
d = ctx.get_devices()[0]
140+
assert(d.is_gpu)
141141
142-
- Invoking the constructor with a list of :class:`dpctl.SyclDevice`
143-
objects creates a common context for all the devices. This
144-
constructor call is especially useful when creation a context for
145-
multiple sub-devices.
142+
- Invoking the constructor with a list of :class:`dpctl.SyclDevice`
143+
objects creates a common context for all the devices. This
144+
constructor call is especially useful when creation a context for
145+
multiple sub-devices.
146146
147-
:Example:
148-
.. code-block:: python
147+
:Example:
148+
.. code-block:: python
149149
150-
import dpctl
150+
import dpctl
151151
152-
# Create a CPU device using the opencl driver
153-
cpu_d = dpctl.SyclDevice("opencl:cpu")
154-
# Partition the CPU device into sub-devices with two cores each.
155-
sub_devices = cpu_d.create_sub_devices(partition=2)
156-
# Create a context common to all the sub-devices.
157-
ctx = dpctl.SyclContext(sub_devices)
158-
assert(len(ctx.get_devices) == len(sub_devices))
159-
160-
- Invoking the constructor with a named ``PyCapsule`` with name
161-
**"SyclContextRef"** that carries a pointer to a ``sycl::context``
162-
object. The capsule will be renamed upon successful consumption
163-
to ensure one-time use. A new named capsule can be constructed by
164-
using :func:`dpctl.SyclContext._get_capsule` method.
152+
# Create a CPU device using the opencl driver
153+
cpu_d = dpctl.SyclDevice("opencl:cpu")
154+
# Partition the CPU device into sub-devices with two cores each.
155+
sub_devices = cpu_d.create_sub_devices(partition=2)
156+
# Create a context common to all the sub-devices.
157+
ctx = dpctl.SyclContext(sub_devices)
158+
assert(len(ctx.get_devices) == len(sub_devices))
159+
160+
- Invoking the constructor with a named ``PyCapsule`` with name
161+
**"SyclContextRef"** that carries a pointer to a ``sycl::context``
162+
object. The capsule will be renamed upon successful consumption
163+
to ensure one-time use. A new named capsule can be constructed by
164+
using :func:`dpctl.SyclContext._get_capsule` method.
165165
166166
Args:
167167
arg (optional): Defaults to ``None``.
@@ -170,21 +170,24 @@ cdef class SyclContext(_SyclContext):
170170
named ``PyCapsule`` called **"SyclContextRef"**.
171171
172172
Raises:
173-
MemoryError: If the constructor could not allocate necessary
174-
temporary memory.
175-
SyclContextCreationError: If the :class:`dpctl.SyclContext` object
176-
creation failed.
177-
TypeError: If the list of :class:`dpctl.SyclDevice` objects was empty,
178-
or the input capsule contained a null pointer or could not
179-
be renamed.
173+
MemoryError:
174+
If the constructor could not allocate necessary
175+
temporary memory.
176+
SyclContextCreationError:
177+
If the :class:`.SyclContext` object creation failed.
178+
TypeError:
179+
If the list of :class:`dpctl.SyclDevice` objects was empty,
180+
or the input capsule contained a null pointer or could not
181+
be renamed.
180182
181183
"""
182184
@staticmethod
183185
cdef SyclContext _create(DPCTLSyclContextRef ctxt):
184186
"""
185-
Calls DPCTLContext_Delete(ctxt).
187+
Calls ``DPCTLContext_Delete(ctxt)``.
186188
187-
Users should pass a copy if they intend to keep the argument ctxt alive.
189+
Users should pass a copy if they intend to keep the argument
190+
``ctxt`` alive.
188191
"""
189192
cdef _SyclContext ret = <_SyclContext>_SyclContext.__new__(_SyclContext)
190193
_init_helper(ret, ctxt)
@@ -335,22 +338,24 @@ cdef class SyclContext(_SyclContext):
335338
:class:`dpctl.SyclContext` instance.
336339
337340
Returns:
338-
:obj:`bool`: ``True`` if the two :class:`dpctl.SyclContext` objects
339-
point to the same ``DPCTLSyclContextRef`` object, otherwise
340-
``False``.
341+
bool:
342+
``True`` if the two :class:`dpctl.SyclContext` objects
343+
point to the same ``DPCTLSyclContextRef`` object, otherwise
344+
``False``.
341345
"""
342346
return DPCTLContext_AreEq(self._ctxt_ref, ctxt.get_context_ref())
343347

344348
def __eq__(self, other):
345349
"""
346-
Returns True if the :class:`dpctl.SyclContext` argument has the
350+
Returns ``True`` if the :class:`dpctl.SyclContext` argument has the
347351
same underlying ``DPCTLSyclContextRef`` object as this
348352
:class:`dpctl.SyclContext` instance.
349353
350354
Returns:
351-
:obj:`bool`: ``True`` if the two :class:`dpctl.SyclContext` objects
352-
point to the same ``DPCTLSyclContextRef`` object, otherwise
353-
``False``.
355+
:obj:`bool`:
356+
``True`` if the two :class:`dpctl.SyclContext` objects
357+
point to the same ``DPCTLSyclContextRef`` object, otherwise
358+
``False``.
354359
"""
355360
if isinstance(other, SyclContext):
356361
return self.equals(<SyclContext> other)
@@ -361,6 +366,10 @@ cdef class SyclContext(_SyclContext):
361366
"""
362367
Returns a hash value by hashing the underlying ``sycl::context`` object.
363368
369+
Returns:
370+
int:
371+
Hash value.
372+
364373
"""
365374
return DPCTLContext_Hash(self._ctxt_ref)
366375

@@ -373,9 +382,10 @@ cdef class SyclContext(_SyclContext):
373382
``size_t``.
374383
375384
Returns:
376-
:obj:`int`: The address of the ``DPCTLSyclContextRef`` object
377-
used to create this :class:`dpctl.SyclContext` cast to a
378-
``size_t``.
385+
int:
386+
The address of the ``DPCTLSyclContextRef`` object
387+
used to create this :class:`dpctl.SyclContext` cast to a
388+
``size_t``.
379389
"""
380390
return <size_t>self._ctxt_ref
381391

@@ -385,12 +395,14 @@ cdef class SyclContext(_SyclContext):
385395
:class:`dpctl.SyclContext` instance.
386396
387397
Returns:
388-
:obj:`list`: A :obj:`list` of :class:`dpctl.SyclDevice` objects
389-
that belong to this context.
398+
list:
399+
A :obj:`list` of :class:`dpctl.SyclDevice` objects
400+
that belong to this context.
390401
391402
Raises:
392-
ValueError: If the ``DPCTLContext_GetDevices`` call returned
393-
``NULL`` instead of a ``DPCTLDeviceVectorRef`` object.
403+
ValueError:
404+
If the ``DPCTLContext_GetDevices`` call returned
405+
``NULL`` instead of a ``DPCTLDeviceVectorRef`` object.
394406
"""
395407
cdef DPCTLDeviceVectorRef DVRef = DPCTLContext_GetDevices(
396408
self.get_context_ref()
@@ -415,11 +427,13 @@ cdef class SyclContext(_SyclContext):
415427
:class:`dpctl.SyclContext` instance.
416428
417429
Returns:
418-
:obj:`int`: Number of devices associated with the context.
430+
int:
431+
Number of devices associated with the context.
419432
420433
Raises:
421-
ValueError: If ``DPCTLContext_DeviceCount`` led to a
422-
failure.
434+
ValueError:
435+
If ``DPCTLContext_DeviceCount`` call led to a
436+
failure.
423437
"""
424438
cdef size_t num_devs = DPCTLContext_DeviceCount(self.get_context_ref())
425439
if num_devs:
@@ -454,8 +468,8 @@ cdef class SyclContext(_SyclContext):
454468
print(ctx2)
455469
456470
Returns:
457-
:obj:`str`: A string representation of the
458-
:class:`dpctl.SyclContext` object.
471+
str:
472+
A string representation of this :class:`.SyclContext` instance.
459473
460474
"""
461475
cdef size_t n = self.device_count
@@ -477,13 +491,15 @@ cdef class SyclContext(_SyclContext):
477491
of scope.
478492
479493
Returns:
480-
:class:`pycapsule`: A capsule object storing a copy of the
481-
``sycl::context`` pointer belonging to thus
482-
:class:`dpctl.SyclContext` instance.
494+
:class:`pycapsule`:
495+
A capsule object storing a copy of the
496+
``sycl::context`` pointer belonging to thus
497+
:class:`dpctl.SyclContext` instance.
483498
484499
Raises:
485-
ValueError: If the ``DPCTLContext_Copy`` fails to copy the
486-
``sycl::context`` pointer.
500+
ValueError:
501+
If the ``DPCTLContext_Copy`` fails to copy the
502+
``sycl::context`` pointer.
487503
"""
488504
cdef DPCTLSyclContextRef CRef = NULL
489505
CRef = DPCTLContext_Copy(self._ctxt_ref)

0 commit comments

Comments
 (0)