bpo-36974: expand call protocol documentation (GH-13844) · python/cpython@9a13a38 (original) (raw)

`@@ -248,246 +248,6 @@ Object Protocol

248

` of base classes).

249

250

251

.. c:function:: int PyCallable_Check(PyObject *o)

252

-

253


 Determine if the object *o* is callable. Return ``1`` if the object is callable

254


 and ``0`` otherwise. This function always succeeds.

255

-

256

-

257

.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)

258

-

259

Call a callable Python object callable without any arguments. It is the

260

most efficient way to call a callable Python object without any argument.

261

-

262

Return the result of the call on success, or raise an exception and return

263


 ``NULL`` on failure.

264

-

265

.. versionadded:: 3.9

266

-

267

-

268

.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)

269

-

270

Call a callable Python object callable with exactly 1 positional argument

271

arg and no keyword arguments.

272

-

273

Return the result of the call on success, or raise an exception and return

274


 ``NULL`` on failure.

275

-

276

.. versionadded:: 3.9

277

-

278

-

279

.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

280

-

281

Call a callable Python object callable, with arguments given by the

282

tuple args, and named arguments given by the dictionary kwargs.

283

-

284


 *args* must not be ``NULL``, use an empty tuple if no arguments are needed.

285


 If no named arguments are needed, *kwargs* can be ``NULL``.

286

-

287

Return the result of the call on success, or raise an exception and return

288


 ``NULL`` on failure.

289

-

290

This is the equivalent of the Python expression:

291


 ``callable(*args, **kwargs)``.

292

-

293

-

294

.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)

295

-

296

Call a callable Python object callable, with arguments given by the

297


 tuple *args*. If no arguments are needed, then *args* can be ``NULL``.

298

-

299

Return the result of the call on success, or raise an exception and return

300


 ``NULL`` on failure.

301

-

302


 This is the equivalent of the Python expression: ``callable(*args)``.

303

-

304

-

305

.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)

306

-

307

Call a callable Python object callable, with a variable number of C arguments.

308

`` -

The C arguments are described using a :c:func:Py_BuildValue style format

309


 string. The format can be ``NULL``, indicating that no arguments are provided.

310

-

311

Return the result of the call on success, or raise an exception and return

312


 ``NULL`` on failure.

313

-

314


 This is the equivalent of the Python expression: ``callable(*args)``.

315

-

316

`` -

Note that if you only pass :c:type:PyObject \* args,

317

`` -

:c:func:PyObject_CallFunctionObjArgs is a faster alternative.

318

-

319

.. versionchanged:: 3.4

320


 The type of *format* was changed from ``char *``.

321

-

322

-

323

.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

324

-

325

Call the method named name of object obj with a variable number of C

326

`` -

arguments. The C arguments are described by a :c:func:Py_BuildValue format

327

string that should produce a tuple.

328

-

329


 The format can be ``NULL``, indicating that no arguments are provided.

330

-

331

Return the result of the call on success, or raise an exception and return

332


 ``NULL`` on failure.

333

-

334

This is the equivalent of the Python expression:

335


 ``obj.name(arg1, arg2, ...)``.

336

-

337

`` -

Note that if you only pass :c:type:PyObject \* args,

338

`` -

:c:func:PyObject_CallMethodObjArgs is a faster alternative.

339

-

340

.. versionchanged:: 3.4

341


 The types of *name* and *format* were changed from ``char *``.

342

-

343

-

344

.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)

345

-

346

Call a callable Python object callable, with a variable number of

347

`` -

:c:type:PyObject\* arguments. The arguments are provided as a variable number

348


 of parameters followed by ``NULL``.

349

-

350

Return the result of the call on success, or raise an exception and return

351


 ``NULL`` on failure.

352

-

353

This is the equivalent of the Python expression:

354


 ``callable(arg1, arg2, ...)``.

355

-

356

-

357

.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)

358

-

359

Calls a method of the Python object obj, where the name of the method is given as a

360

Python string object in name. It is called with a variable number of

361

`` -

:c:type:PyObject\* arguments. The arguments are provided as a variable number

362


 of parameters followed by ``NULL``.

363

-

364

Return the result of the call on success, or raise an exception and return

365


 ``NULL`` on failure.

366

-

367

-

368

.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

369

-

370

Call a method of the Python object obj without arguments,

371

where the name of the method is given as a Python string object in name.

372

-

373

Return the result of the call on success, or raise an exception and return

374


 ``NULL`` on failure.

375

-

376

.. versionadded:: 3.9

377

-

378

-

379

.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

380

-

381

Call a method of the Python object obj with a single positional argument

382

arg, where the name of the method is given as a Python string object in

383

name.

384

-

385

Return the result of the call on success, or raise an exception and return

386


 ``NULL`` on failure.

387

-

388

.. versionadded:: 3.9

389

-

390

-

391

.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

392

-

393

Call a callable Python object callable, using

394

`` -

:c:data:vectorcall <PyTypeObject.tp_vectorcall_offset> if possible.

395

-

396

args is a C array with the positional arguments.

397

-

398

nargsf is the number of positional arguments plus optionally the flag

399

`` -

:const:PY_VECTORCALL_ARGUMENTS_OFFSET (see below).

400

To get actual number of arguments, use

401

`` -

:c:func:PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>.

402

-

403


 *kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword

404

names, which must be strings. In the latter case, the values of the keyword

405

arguments are stored in args after the positional arguments.

406

The number of keyword arguments does not influence nargsf.

407

-

408


 *kwnames* must contain only objects of type ``str`` (not a subclass),

409

and all keys must be unique.

410

-

411

Return the result of the call on success, or raise an exception and return

412


 ``NULL`` on failure.

413

-

414

This uses the vectorcall protocol if the callable supports it;

415

otherwise, the arguments are converted to use

416

`` -

:c:member:~PyTypeObject.tp_call.

417

-

418

.. note::

419

-

420

This function is provisional and expected to become public in Python 3.9,

421

with a different name and, possibly, changed semantics.

422

If you use the function, plan for updating your code for Python 3.9.

423

-

424

.. versionadded:: 3.8

425

-

426

.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET

427

-

428

If set in a vectorcall nargsf argument, the callee is allowed to

429


 temporarily change ``args[-1]``. In other words, *args* points to

430

argument 1 (not 0) in the allocated vector.

431


 The callee must restore the value of ``args[-1]`` before returning.

432

-

433

`` -

For :c:func:_PyObject_VectorcallMethod, this flag means instead that

434


 ``args[0]`` may be changed.

435

-

436

Whenever they can do so cheaply (without additional allocation), callers

437

`` -

are encouraged to use :const:PY_VECTORCALL_ARGUMENTS_OFFSET.

438

Doing so will allow callables such as bound methods to make their onward

439

calls (which include a prepended self argument) cheaply.

440

-

441

.. versionadded:: 3.8

442

-

443

.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

444

-

445

Given a vectorcall nargsf argument, return the actual number of

446

arguments.

447


 Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.

448

-

449

.. versionadded:: 3.8

450

-

451

.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

452

-

453

`` -

Same as :c:func:_PyObject_Vectorcall except that the keyword arguments

454


 are passed as a dictionary in *kwdict*. This may be ``NULL`` if there

455

are no keyword arguments.

456

-

457

`` -

For callables supporting :c:data:vectorcall <PyTypeObject.tp_vectorcall_offset>,

458

the arguments are internally converted to the vectorcall convention.

459

Therefore, this function adds some overhead compared to

460

`` -

:c:func:_PyObject_Vectorcall.

461

It should only be used if the caller already has a dictionary ready to use.

462

-

463

.. note::

464

-

465

This function is provisional and expected to become public in Python 3.9,

466

with a different name and, possibly, changed semantics.

467

If you use the function, plan for updating your code for Python 3.9.

468

-

469

.. versionadded:: 3.8

470

-

471

.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

472

-

473

Call a method using the vectorcall calling convention. The name of the method

474

is given as Python string name. The object whose method is called is

475

args[0] and the args array starting at args[1] represents the arguments

476

of the call. There must be at least one positional argument.

477

nargsf is the number of positional arguments including args[0],

478


 plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may

479

temporarily be changed. Keyword arguments can be passed just like in

480

`` -

:c:func:_PyObject_Vectorcall.

481

-

482

`` -

If the object has the :const:Py_TPFLAGS_METHOD_DESCRIPTOR feature,

483

this will actually call the unbound method object with the full

484

args vector as arguments.

485

-

486

Return the result of the call on success, or raise an exception and return

487


 ``NULL`` on failure.

488

-

489

.. versionadded:: 3.9

490

-

491

251

`.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)

492

252

493

253

` .. index:: builtin: hash