Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b9ce9b5

Browse files
benjaminpbenjaminp
committed
edits
1 parent b173f78 commit b9ce9b5

1 file changed

Lines changed: 58 additions & 74 deletions

File tree

‎Doc/c-api/capsule.rst‎

Lines changed: 58 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -33,107 +33,94 @@ Refer to :ref:`using-capsules` for more information on using these objects.
3333

3434
Return true if its argument is a :ctype:`PyCapsule`.
3535

36+
3637
.. cfunction:: PyObject* PyCapsule_New(void* pointer, const char* name, PyCapsule_Destructor destructor)
3738

3839
Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer*
3940
argument may not be *NULL*.
4041

41-
The *name* string may either be *NULL* or a pointer to a valid
42-
C string. If non-*NULL*, this string must outlive the capsule.
43-
(Though it is permitted to free it inside the *destructor*.)
44-
45-
If the *destructor* argument is not *NULL*,
46-
it will be called with the capsule ``PyObject *`` when it is destroyed.
47-
48-
If this capsule will be stored as an attribute of a module, it
49-
is strongly suggested that the *name* string be specified as::
42+
On failure, set an exception and return *NULL*.
5043

51-
modulename.attributename
44+
The *name* string may either be *NULL* or a pointer to a valid C string. If
45+
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
46+
free it inside the *destructor*.)
5247

53-
This will enable other modules to import the capsule
54-
using :cfunc:`PyCapsule_Import`.
48+
If the *destructor* argument is not *NULL*, it will be called with the
49+
capsule when it is destroyed.
5550

56-
Return a valid capsule on success.
57-
On failure, set an exception and return *NULL*.
51+
If this capsule will be stored as an attribute of a module, the *name* should
52+
be specified as ``modulename.attributename``. This will enable other modules
53+
to import the capsule using :cfunc:`PyCapsule_Import`.
5854

5955

6056
.. cfunction:: void* PyCapsule_GetPointer(PyObject* capsule, const char* name)
6157

62-
Retrieve the *pointer* stored in the capsule.
58+
Retrieve the *pointer* stored in the capsule. On failure, set an exception
59+
and return *NULL*.
6360

6461
The *name* parameter must compare exactly to the name stored in the capsule.
65-
If the name stored in the capsule is *NULL*, the *name* passed in must
66-
also be *NULL*. If the name stored in the capsule is non-*NULL*,
67-
the *name* passed in must also be non-*NULL*, and must match the name
68-
stored in the capsule. Python uses the C function *strcmp* to compare
69-
capsule names.
70-
71-
Return the internal *pointer* on success.
72-
On failure, set an exception and return *NULL*.
62+
If the name stored in the capsule is *NULL*, the *name* passed in must also
63+
be *NULL*. Python uses the C function :cfunc:`strcmp` to compare capsule
64+
names.
7365

7466

7567
.. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject* capsule)
7668

77-
Return the current *destructor* stored in the capsule.
78-
On failure, set an exception and return *NULL*.
69+
Return the current destructor stored in the capsule. On failure, set an
70+
exception and return *NULL*.
7971

80-
It is legal for a capsule to have a *NULL* destructor.
81-
This makes a *NULL* return code somewhat ambiguous;
82-
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
72+
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
73+
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
74+
:cfunc:`PyErr_Occurred` to disambugate.
8375

8476

8577
.. cfunction:: void* PyCapsule_GetContext(PyObject* capsule)
8678

87-
Return the current *context* stored in the capsule.
88-
On failure, set an exception and return *NULL*.
79+
Return the current context stored in the capsule. On failure, set an
80+
exception and return *NULL*.
8981

90-
It is legal for a capsule to have a *NULL* context.
91-
This makes a *NULL* return code somewhat ambiguous;
92-
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
82+
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
83+
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
84+
:cfunc:`PyErr_Occurred` to disambugate.
9385

9486

9587
.. cfunction:: const char* PyCapsule_GetName(PyObject* capsule)
9688

97-
Return the current *name* stored in the capsule.
98-
On failure, set an exception and return *NULL*.
89+
Return the current name stored in the capsule. On failure, set an exception
90+
and return *NULL*.
9991

100-
It is legal for a capsule to have a *NULL* name.
101-
This makes a *NULL* return code somewhat ambiguous;
102-
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
92+
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
93+
code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
94+
:cfunc:`PyErr_Occurred` to disambugate.
10395

10496

10597
.. cfunction:: void* PyCapsule_Import(const char* name, int no_block)
10698

107-
Import a pointer to a C object from a ``capsule`` attribute in a module.
108-
The *name* parameter should specify the full name to the attribute, as
109-
in *"module.attribute"*.
110-
The *name* stored in the capsule must match this string exactly.
111-
If *no_block* is true, import the module without blocking
112-
(using :cfunc:`PyImport_ImportModuleNoBlock`).
113-
If *no_block* is false, import the module conventionally
114-
(using :cfunc:`PyImport_ImportModule`).
99+
Import a pointer to a C object from a ``capsule`` attribute in a module. The
100+
*name* parameter should specify the full name to the attribute, as in
101+
``module.attribute``. The *name* stored in the capsule must match this
102+
string exactly. If *no_block* is true, import the module without blocking
103+
(using :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
104+
import the module conventionally (using :cfunc:`PyImport_ImportModule`).
115105

116-
Return the capsule's internal *pointer* on success.
117-
On failure, set an exception and return *NULL*.
118-
Exception: if *PyCapsule_Import* failed to import the module,
119-
and *no_block* was true, no exception is set.
106+
Return the capsule's internal *pointer* on success. On failure, set an
107+
exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to
108+
import the module, and *no_block* was true, no exception is set.
120109

121110
.. cfunction:: int PyCapsule_IsValid(PyObject* capsule, const char* name)
122111

123-
Determines whether or not a :ctype:`PyObject \*` is a valid capsule.
124-
A valid capsule is non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`,
125-
has a non-NULL *pointer*, and its internal name matches the
126-
*name* parameter. (See :cfunc:`PyCapsule_GetPointer` for
127-
information on how capsule names are compared.)
112+
Determines whether or not *capsule* is a valid capsule. A valid capsule is
113+
non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-NULL pointer
114+
stored in it, and its internal name matches the *name* parameter. (See
115+
:cfunc:`PyCapsule_GetPointer` for information on how capsule names are
116+
compared.)
128117

129-
In other words, if :cfunc:`PyCapsule_IsValid` returns a true value,
130-
calls to any of the accessors (any function starting
131-
with :cfunc:`PyCapsule_Get`) are guaranteed to succeed.
118+
In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to
119+
any of the accessors (any function starting with :cfunc:`PyCapsule_Get`) are
120+
guaranteed to succeed.
132121

133-
Return a nonzero value if the object is valid and matches the name
134-
passed in.
135-
Return 0 otherwise.
136-
This function will not fail.
122+
Return a nonzero value if the object is valid and matches the name passed in.
123+
Return 0 otherwise. This function will not fail.
137124

138125
.. cfunction:: int PyCapsule_SetContext(PyObject* capsule, void* context)
139126

@@ -142,27 +129,24 @@ Refer to :ref:`using-capsules` for more information on using these objects.
142129
Return 0 on success.
143130
Return nonzero and set an exception on failure.
144131

145-
.. cfunction:: int PyCapsule_SetDestructor(PyObject* capsule, void (*)(PyObject *) destructor)
132+
.. cfunction:: int PyCapsule_SetDestructor(PyObject* capsule, PyCapsule_Destructor destructor)
146133

147134
Set the destructor inside *capsule* to *destructor*.
148135

149-
Return 0 on success.
150-
Return nonzero and set an exception on failure.
136+
Return 0 on success. Return nonzero and set an exception on failure.
151137

152138
.. cfunction:: int PyCapsule_SetName(PyObject* capsule, const char* name)
153139

154-
Set the name inside *capsule* to *name*. If non-*NULL*, the name
155-
must outlive the capsule. If the previous *name* stored in the
156-
capsule was not *NULL*, no attempt is made to free it.
140+
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
141+
outlive the capsule. If the previous *name* stored in the capsule was not
142+
*NULL*, no attempt is made to free it.
157143

158-
Return 0 on success.
159-
Return nonzero and set an exception on failure.
144+
Return 0 on success. Return nonzero and set an exception on failure.
160145

161146
.. cfunction:: int PyCapsule_SetPointer(PyObject* capsule, void* pointer)
162147

163-
Set the void pointer inside *capsule* to *pointer*. The pointer
164-
may not be *NULL*.
148+
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
149+
*NULL*.
165150

166-
Return 0 on success.
167-
Return nonzero and set an exception on failure.
151+
Return 0 on success. Return nonzero and set an exception on failure.
168152

0 commit comments

Comments
 (0)