Commit Graph

168 Commits

Author SHA1 Message Date
Victor Stinner 764e83db85
gh-93103: Deprecate global configuration variable (#93104)
Deprecate global configuration variables, like
Py_IgnoreEnvironmentFlag, in the documentation: the
Py_InitializeFromConfig() API should be instead.
2022-05-23 14:56:35 +02:00
Victor Stinner 299692afd8
gh-88279: Deprecate PySys_SetArgvEx() (#92363)
Deprecate the following C functions:

* PySys_SetArgv()
* PySys_SetArgvEx()
* PySys_SetPath()
2022-05-06 05:24:29 +02:00
Robert Howlett 43b135f94e
gh-92047: Py_GetVersion multi-digit minor version (GH-92047) (#92048) 2022-05-05 11:33:35 +02:00
Victor Stinner 6811bdef63
gh-88097: doc: fix link to Py_Version (#92141) 2022-05-02 15:29:22 +02:00
Mark Shannon 5974827c71
GH-88756: Update docs for PEP 523 eval function type. (GH-91788) 2022-04-21 18:14:01 +01:00
Victor Stinner 2b4f2f5fa4
Revert "bpo-46850: Move _PyEval_EvalFrameDefault() to internal C API (GH-32052)" (GH-32343)
* Revert "bpo-46850: Move _PyInterpreterState_SetEvalFrameFunc() to internal C API (GH-32054)"

This reverts commit f877b40e3f.

* Revert "bpo-46850: Move _PyEval_EvalFrameDefault() to internal C API (GH-32052)"

This reverts commit b9a5522dd9.
2022-04-06 13:58:07 +02:00
Jelle Zijlstra 897bc6f928
More minor fixes to C API docs (GH-31525)
* wording fixes in type.rst

* grammar and punctuation in sys.rst

* set: grammar fixes

* structures: capitalization fix

* grammar fixes for sequence

* objects: point to Py_TYPE instead of direct object access

* numbers: add more explicit Python equivalences

* method: add missing period

* memory: grammar fix

* mapping: grammar fixes

* long: grammar fix

* iter: fix grammar for PyAIter_Check

* init: grammar fix
2022-04-02 12:31:05 -07:00
Victor Stinner f877b40e3f
bpo-46850: Move _PyInterpreterState_SetEvalFrameFunc() to internal C API (GH-32054)
Move the private _PyFrameEvalFunction type, and private
_PyInterpreterState_GetEvalFrameFunc() and
_PyInterpreterState_SetEvalFrameFunc() functions to the internal C
API. The _PyFrameEvalFunction callback function type now uses the
_PyInterpreterFrame type which is part of the internal C API.

Update the _PyFrameEvalFunction documentation.
2022-04-01 10:55:00 +02:00
Gabriele N. Tornetta 50669083fe
bpo-43931: Export Python version as API data (GH-25577)
When Python is embedded in other applications, it is not easy to determine which version of Python is being used. This change exposes the Python version as part of the API data. Tools like Austin (https://github.com/P403n1x87/austin) can benefit from this data when targeting applications like uWSGI, as the Python version can then be inferred systematically by looking at the exported symbols rather than relying on unreliable pattern matching or other hacks (like remote code execution etc...).

Automerge-Triggered-By: GH:pablogsal
2021-12-09 17:52:05 -08:00
Julien Palard bda69abe84
[doc]: Fix missing space in c-api/init.rst and add rstlint rule (GH-28988) 2021-10-19 21:13:24 +02:00
Victor Stinner 547d26aa08
bpo-43760: Add PyThreadState_EnterTracing() (GH-28542)
Add PyThreadState_EnterTracing() and PyThreadState_LeaveTracing()
functions to the limited C API to suspend and resume tracing and
profiling.

Add an unit test on the PyThreadState C API to _testcapi.

Add also internal _PyThreadState_DisableTracing() and
_PyThreadState_ResetTracing().
2021-10-15 16:06:30 +02:00
Serhiy Storchaka 36122e1814
bpo-41203: Replace Mac OS X and OS X with macOS (GH-28515)
Replace old names when they refer to actual versions of macOS.
Keep historical names in references to older versions.

Co-authored-by: Patrick Reader <_@pxeger.com>
2021-09-22 20:33:36 +03:00
Eric Snow 044e8d866f
bpo-45019: Add a tool to generate list of modules to include for frozen modules (gh-27980)
Frozen modules must be added to several files in order to work properly. Before this change this had to be done manually. Here we add a tool to generate the relevant lines in those files instead. This helps us avoid mistakes and omissions.

https://bugs.python.org/issue45019
2021-08-30 17:25:11 -06:00
Victor Stinner 6cd0446ef7
bpo-44113: Deprecate old functions to config Python init (GH-26060)
Deprecate the following functions to configure the Python
initialization:

* PySys_AddWarnOption()
* PySys_AddWarnOptionUnicode()
* PySys_AddXOption()
* PySys_HasWarnOptions()
* Py_SetPath()
* Py_SetProgramName()
* Py_SetPythonHome()
* Py_SetStandardStreamEncoding()
* _Py_SetProgramFullPath()

Use the new PyConfig API of the Python Initialization Configuration
instead (PEP 587).
2021-05-12 23:59:25 +02:00
Ken Jin 9712358277
Docs: Remove stray semicolon in init.rst (GH-23974)
Removed stray semicolon which was causing the docs to render weirdly (it's the function right under the one [here](https://docs.python.org/3/c-api/init.html#c._PyInterpreterState_GetEvalFrameFunc)).
2021-01-14 07:57:08 -08:00
Victor Stinner ace3f9a0ce
bpo-42260: Fix _PyConfig_Read() if compute_path_config=0 (GH-23220)
Fix _PyConfig_Read() if compute_path_config=0: use values set by
Py_SetPath(), Py_SetPythonHome() and Py_SetProgramName(). Add
compute_path_config parameter to _PyConfig_InitPathConfig().

The following functions now return NULL if called before
Py_Initialize():

* Py_GetExecPrefix()
* Py_GetPath()
* Py_GetPrefix()
* Py_GetProgramFullPath()
* Py_GetProgramName()
* Py_GetPythonHome()

These functions no longer automatically computes the Python Path
Configuration. Moreover, Py_SetPath() no longer computes
program_full_path.
2020-11-10 21:10:22 +01:00
Victor Stinner 23c5f93b83
bpo-42294: Add borrowed/strong reference to doc glossary (GH-23206)
Add "borrowed reference" and "strong reference" to the documentation
glossary.

Enhance also Py_INCREF() and Py_NewRef() documentation.
2020-11-09 13:40:47 +01:00
Victor Stinner 4b9aad4999
bpo-42236: Enhance init and encoding documentation (GH-23109)
Enhance the documentation of the Python startup, filesystem encoding
and error handling, locale encoding. Add a new "Python UTF-8 Mode"
section.

* Add "locale encoding" and "filesystem encoding and error handler"
  to the glossary
* Remove documentation from Include/cpython/initconfig.h: move it to
  Doc/c-api/init_config.rst.
* Doc/c-api/init_config.rst:

  * Document command line options and environment variables
  * Document default values.

* Add a new "Python UTF-8 Mode" section in Doc/library/os.rst.
* Add warnings to Py_DecodeLocale() and Py_EncodeLocale() docs.
* Document how Python selects the filesystem encoding and error
  handler at a single place: PyConfig.filesystem_encoding and
  PyConfig.filesystem_errors.
* PyConfig: move orig_argv member at the right place.
2020-11-02 16:49:54 +01:00
Victor Stinner 474652fe93
bpo-40204, doc: Fix syntax of C variables (GH-21846)
For example, fix the following Sphinx 3 errors:

Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
  void \*obj
  -----^

Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
  PyObject*
  --------^

The modified documentation is compatible with Sphinx 2 and Sphinx 3.
2020-08-13 22:11:50 +02:00
Victor Stinner 4386b9045e
bpo-40429: PyThreadState_GetFrame() returns a strong ref (GH-19781)
The PyThreadState_GetFrame() function now returns a strong reference
to the frame.
2020-04-29 03:01:43 +02:00
Victor Stinner a42ca74fa3
bpo-40421: Add PyFrame_GetCode() function (GH-19757)
PyFrame_GetCode(frame): return a borrowed reference to the frame
code.

Replace frame->f_code with PyFrame_GetCode(frame) in most code,
except in frameobject.c, genobject.c and ceval.c.

Also add PyFrame_GetLineNumber() to the limited C API.
2020-04-28 19:01:31 +02:00
Victor Stinner 1a1bd2e238
bpo-40302: Replace PY_INT64_T with int64_t (GH-19573)
* Replace PY_INT64_T with int64_t
* Replace PY_UINT32_T with uint32_t
* Replace PY_UINT64_T with uint64_t

sha3module.c no longer checks if PY_UINT64_T is defined since it's
always defined and uint64_t is always available on platforms
supported by Python.
2020-04-17 19:13:06 +02:00
Victor Stinner 71a3522ef8
bpo-38644: Make tstate more explicit inside pystate.c (GH-19182)
Fix PyInterpreterState_New(): Don't call PyErr_SetString() when there
is no current Python thread state (if tstate is NULL).
2020-03-26 22:46:14 +01:00
Victor Stinner 5c3cda0d1a
bpo-39947: Add PyThreadState_GetID() function (GH-19163)
Add PyThreadState_GetID() function: get the unique identifier of a
Python thread state.
2020-03-25 21:23:53 +01:00
Victor Stinner fd1e1a18fa
bpo-39947: Add PyThreadState_GetFrame() function (GH-19092)
Add PyThreadState_GetFrame() function: get the current frame
of a Python thread state.
2020-03-20 15:51:45 +01:00
Victor Stinner 50e6e99178
bpo-39984: Move pending calls to PyInterpreterState (GH-19066)
If Py_AddPendingCall() is called in a subinterpreter, the function is
now scheduled to be called from the subinterpreter, rather than being
called from the main interpreter.

Each subinterpreter now has its own list of scheduled calls.

* Move pending and eval_breaker fields from _PyRuntimeState.ceval
  to PyInterpreterState.ceval.
* new_interpreter() now calls _PyEval_InitThreads() to create
  pending calls lock.
* Fix Py_AddPendingCall() for subinterpreters. It now calls
  _PyThreadState_GET() which works in a subinterpreter if the
  caller holds the GIL, and only falls back on
  PyGILState_GetThisThreadState() if _PyThreadState_GET()
  returns NULL.
2020-03-19 02:41:21 +01:00
Victor Stinner 8fb02b6e19
bpo-39947: Add PyThreadState_GetInterpreter() (GH-18981)
Add PyThreadState_GetInterpreter(tstate): get the interpreter of a
Python thread state.
2020-03-13 23:38:08 +01:00
Victor Stinner be79373a78
bpo-39947: Add PyInterpreterState_Get() function (GH-18979)
* Rename _PyInterpreterState_Get() to PyInterpreterState_Get() and
  move it the limited C API.
* Add _PyInterpreterState_Get() alias to PyInterpreterState_Get() for
  backward compatibility with Python 3.8.
2020-03-13 18:15:33 +01:00
Victor Stinner 309d7cc5df
bpo-35370: Add _PyEval_SetTrace() function (GH-18975)
* sys.settrace(), sys.setprofile() and _lsprof.Profiler.enable() now
  properly report PySys_Audit() error if "sys.setprofile" or
  "sys.settrace" audit event is denied.
* Add _PyEval_SetProfile() and _PyEval_SetTrace() function: similar
  to PyEval_SetProfile() and PyEval_SetTrace() but take a tstate
  parameter and return -1 on error.
* Add _PyObject_FastCallTstate() function.
2020-03-13 16:39:12 +01:00
Victor Stinner 0b72b23fb0
bpo-38500: Add _PyInterpreterState_SetEvalFrameFunc() (GH-17340)
PyInterpreterState.eval_frame function now requires a tstate (Python
thread state) parameter.

Add private functions to the C API to get and set the frame
evaluation function:

* Add tstate parameter to _PyFrameEvalFunction function type.
* Add _PyInterpreterState_GetEvalFrameFunc() and
  _PyInterpreterState_SetEvalFrameFunc() functions.
* Add tstate parameter to _PyEval_EvalFrameDefault().
2020-03-12 23:18:39 +01:00
Victor Stinner b4698ecfdb
bpo-39877: Deprecate PyEval_InitThreads() (GH-18892)
Deprecated PyEval_InitThreads() and PyEval_ThreadsInitialized().
Calling PyEval_InitThreads() now does nothing.
2020-03-10 01:28:54 +01:00
Victor Stinner 4d96b4635a
bpo-39511: PyThreadState_Clear() calls on_delete (GH-18296)
PyThreadState.on_delete is a callback used to notify Python when a
thread completes. _thread._set_sentinel() function creates a lock
which is released when the thread completes. It sets on_delete
callback to the internal release_sentinel() function. This lock is
known as Threading._tstate_lock in the threading module.

The release_sentinel() function uses the Python C API. The problem is
that on_delete is called late in the Python finalization, when the C
API is no longer fully working.

The PyThreadState_Clear() function now calls the
PyThreadState.on_delete callback. Previously, that happened in
PyThreadState_Delete().

The release_sentinel() function is now called when the C API is still
fully working.
2020-02-01 02:30:25 +01:00
Victor Stinner 17c68b8107
bpo-38631: Replace Py_FatalError() with assert() in ceval.c (GH-18279)
Replace a few Py_FatalError() calls if tstate is NULL with
assert(tstate != NULL) in ceval.c.

PyEval_AcquireThread(), PyEval_ReleaseThread() and
PyEval_RestoreThread() must never be called with a NULL tstate.
2020-01-30 12:20:48 +01:00
Petr Viktorin 6c5d661342 bpo-39161: Document multi-phase init modules under Py_NewInterpreter() (GH-17896)
\+ this also adds a stronger warning against sharing objects between (sub-)interpreters.



https://bugs.python.org/issue39161
2020-01-09 04:05:18 -08:00
Gurupad Hegde 6c7bb38ff2 bpo-39136: Fixed typos (GH-17720)
funtion -> function; configuraton -> configuration; defintitions -> definitions;
focusses -> focuses; necesarily -> necessarily; follwing -> following;
Excape -> Escape,
2019-12-28 17:16:02 -05:00
Eric Snow 73cdb0c6b2 bpo-38816: Add notes in the C-API docs about fork in subinterpreters. (GH-17176)
The C-API docs are a bit sparse on the interplay between C `fork()` and the CPython runtime.  This change adds some more information on the subject.


https://bugs.python.org/issue38816
2019-11-15 13:28:54 -08:00
Serhiy Storchaka e835b31d2b
bpo-38600: NULL -> ``NULL``. (GH-17001)
Also fix some other formatting.
2019-10-30 21:37:16 +02:00
Serhiy Storchaka 25fc088607
bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950)
Replace all *NULL* with ``NULL``.
2019-10-30 12:03:20 +02:00
Joannah Nanjekye 8855e47d09 bpo-38266: Revert bpo-37878: Make PyThreadState_DeleteCurrent() Internal (GH-16558)
Revert the removal of PyThreadState_DeleteCurrent() with documentation.
2019-10-04 13:35:42 +02:00
Victor Stinner 1ce152a42e
bpo-38234: Py_SetPath() uses the program full path (GH-16357)
Py_SetPath() now sets sys.executable to the program full path
(Py_GetProgramFullPath()), rather than to the program name
(Py_GetProgramName()).

Fix also memory leaks in pathconfig_set_from_config().
2019-09-24 17:44:15 +02:00
Christian Heimes ed4b3216e5 bpo-37363: Document internal audit events (GH-14663)
Three internal cpython events were not documented, yet.

Signed-off-by: Christian Heimes <christian@python.org>



https://bugs.python.org/issue37363
2019-09-12 06:13:02 -07:00
Victor Stinner 1beb7c3de9
bpo-36763, doc: Add links in the new C API init doc (GH-15433) 2019-08-23 17:59:12 +01:00
Joannah Nanjekye 854d0a4b98 bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-12666) 2019-08-02 09:50:22 -06:00
Stéphane Wirtel cbb6484573 Doc: Replace the deprecated highlightlang directive by highlight. (#13377)
highlightlang is deprecated since April 2018 in Sphinx.
See https://github.com/sphinx-doc/sphinx/pull/4845
2019-05-17 15:25:34 +05:30
Victor Stinner c1f7262f70
bpo-36728: Remove PyEval_ReInitThreads documentation (GH-13282) 2019-05-13 16:22:51 +02:00
Joannah Nanjekye f781d202a2 bpo-36475: Finalize PyEval_AcquireLock() and PyEval_AcquireThread() properly (GH-12667)
PyEval_AcquireLock() and PyEval_AcquireThread() now
terminate the current thread if called while the interpreter is
finalizing, making them consistent with PyEval_RestoreThread(),
Py_END_ALLOW_THREADS, and PyGILState_Ensure().
2019-04-29 10:38:45 +02:00
Pablo Galindo fde9b33dfe
bpo-36427: Document that PyEval_RestoreThread and PyGILState_Ensure can terminate the calling thread (GH-12541)
Calling these function from a thread when the runtime is finalizing will terminate
the thread, even if the thread was not created by Python. Users can use 
_Py_IsFinalizing or sys.is_finalizing to check if the interpreter is in the process of
being finalized before calling this function to avoid unwanted termination.
2019-04-13 17:23:24 +01:00
Joannah Nanjekye 8c61739def bpo-36157:Document PyInterpreterState_Main() (GH-12238)
I have added documentation for `PyInterpreterState_Main()`.
 I chose to place it under Advanced Debugger Support together with similar functions like `PyInterpreterState_Head()`, `PyInterpreterState_Next(`), and `PyInterpreterState_ThreadHead()` .


https://bugs.python.org/issue36157
2019-04-01 08:08:43 -07:00
Nick Coghlan ddbb978e10
C API docs: Py_IsInitialized is always safe to call (GH-12630) 2019-03-30 21:24:05 +10:00
Eric Snow d2fdd1fedf
bpo-36124: Add PyInterpreterState.dict. (gh-12132) 2019-03-15 17:47:43 -06:00