Commit Graph

200 Commits

Author SHA1 Message Date
Petr Viktorin 4d82f628c4
gh-47146: Soft-deprecate structmember.h, expose its contents via Python.h (GH-99014)
The ``structmember.h`` header is deprecated, though it continues to be available
and there are no plans to remove it. There are no deprecation warnings. Old code
can stay unchanged (unless the extra include and non-namespaced macros bother
you greatly). Specifically, no uses in CPython are updated -- that would just be
unnecessary churn.
The ``structmember.h`` header is deprecated, though it continues to be
available and there are no plans to remove it.

Its contents are now available just by including ``Python.h``,
with a ``Py`` prefix added if it was missing:

- `PyMemberDef`, `PyMember_GetOne` and`PyMember_SetOne`
- Type macros like `Py_T_INT`, `Py_T_DOUBLE`, etc.
  (previously ``T_INT``, ``T_DOUBLE``, etc.)
- The flags `Py_READONLY` (previously ``READONLY``) and
  `Py_AUDIT_READ` (previously all uppercase)

Several items are not exposed from ``Python.h``:

- `T_OBJECT` (use `Py_T_OBJECT_EX`)
- `T_NONE` (previously undocumented, and pretty quirky)
- The macro ``WRITE_RESTRICTED`` which does nothing.
- The macros ``RESTRICTED`` and ``READ_RESTRICTED``, equivalents of
  `Py_AUDIT_READ`.
- In some configurations, ``<stddef.h>`` is not included from ``Python.h``.
  It should be included manually when using ``offsetof()``.

The deprecated header continues to provide its original
contents under the original names.
Your old code can stay unchanged, unless the extra include and non-namespaced
macros bother you greatly.

There is discussion on the issue to rename `T_PYSSIZET` to `PY_T_SSIZE` or
similar. I chose not to do that -- users will probably copy/paste that with any
spelling, and not renaming it makes migration docs simpler.


Co-Authored-By: Alexander Belopolsky <abalkin@users.noreply.github.com>
Co-Authored-By: Matthias Braun <MatzeB@users.noreply.github.com>
2022-11-22 08:25:43 +01:00
Erlend E. Aasland e063c23c65
gh-93358: Fix python-config docs for how to embed Python (#98649) 2022-10-29 20:46:34 +02:00
Adam Turner f612565bd3
gh-93738: Disallow pre-v3 syntax in the C domain (#97962)
Also, disable using invalid sphinx-lint 0.6.2.
2022-10-06 10:11:37 -07:00
Adam Turner 0031e62973
gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) (#97768)
:c:type:`<C type>` -> :c:expr:`<C type>`

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
2022-10-05 11:01:14 -07:00
Adam Turner 0e72606dd4
gh-93738: Documentation C syntax (Function glob patterns -> literal markup) (#97774) 2022-10-05 08:22:28 -07:00
Mark Shannon 0f733fffe8
GH-95245: Document use of `MANAGED` flags instead of offsets. (GH-96044) 2022-08-30 16:26:08 +01:00
Serhiy Storchaka f79547a429
gh-91838: Use HTTPS links in docs for resources which redirect to HTTPS (GH-95527)
If an HTTP link is redirected to a same looking HTTPS link, the latter can
be used directly without changes in readability and behavior.
It protects from a men-in-the-middle attack.

This change does not affect Python examples.
2022-08-04 10:13:49 +03:00
Christian Heimes a566912049
gh-85454: Remove distutils documentation (#95239)
Most places now refer to setuptools or link to setuptools documentation.
Some examples like zipapp need to be updated later.
2022-07-25 15:50:46 +02:00
Ned Batchelder 3440d197a5
Docs: remove redundant "adverb-adjective" hyphens from compound modifiers (GH-94551)
Discussion: https://discuss.python.org/t/slight-grammar-fix-throughout-adverbs-dont-need-hyphen/17021
2022-07-05 11:16:10 +02:00
CAM Gerlach f1bbcba74f
gh-76773: Update docs mentioning no-longer-supported Windows versions & features (GH-92529) 2022-05-10 09:30:32 +03:00
Oleg Iarygin a573cb2fec
gh-91118: Fix docstrings that do not honor --without-doc-strings (#31769)
Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
2022-04-17 20:39:32 -07:00
rtobar b275267aa7
bpo-45790: List macros in same order in which fields are described (GH-29529)
Signed-off-by: Rodrigo Tobar <rtobar@icrar.org>

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
2022-04-04 19:36:33 -07:00
Terry Jan Reedy ad43dc0b54
bpo-25381: Update explanation of exceptions in C. (GH-26838)
* bpo-25381: Update explanation of exception globals

This paragraph in extending/extending.rst was unchanged (except for
NULL markup) since committed in 2007 Aug 15 for 2.6 alpha.

* Respond to reviews and remove duplication.

* Update Doc/extending/extending.rst

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
2021-11-15 14:38:53 -08:00
Dmitry Smirnov 454cdb99ab
bpo-45633: Fix newtypes doc typo (GH-29318) 2021-11-02 22:47:06 +08:00
Sam Gross 35e1ff38ee
bpo-28737: Document when tp_dealloc should call PyObject_GC_UnTrack() (GH-29246)
Objects that support garbage collection ("container" objects) should
call PyObject_GC_UnTrack() from their destructors before clearing any
fields which may point to other "container" objects.
2021-10-27 21:15:13 +02:00
Steve Dower 87655e2cf5
bpo-42800: Rename AUDIT_READ to PY_AUDIT_READ (GH-25736) 2021-04-30 01:08:55 +01:00
Ryan Hileman 9a2c2a9ec3
bpo-42800: add audit hooks for f_code and tb_frame (GH-24182)
Accessing the following attributes will now fire PEP 578 style audit hooks as ("object.__getattr__", obj, name):
* PyTracebackObject: tb_frame
* PyFrameObject: f_code
* PyGenObject: gi_code, gi_frame
* PyCoroObject: cr_code, cr_frame
* PyAsyncGenObject: ag_code, ag_frame
Add an AUDIT_READ attribute flag aliased to READ_RESTRICTED.
Update obsolete flag documentation.
2021-04-30 00:15:55 +01:00
Victor Stinner 2459b92a4d
bpo-43774: Remove --without-cycle-gc doc (GH-25364)
The configure --without-cycle-gc option has been removed in Python
2.3 by the commit cccd1e7248. It's now
time to remove the last reference to it in the documentation.
2021-04-12 16:58:45 +01:00
Shreyan Avigyan ea9b2d6319
bpo-43739: Add type declaration Doc/extending/extending.rst example 2021-04-10 08:54:32 -07:00
Victor Stinner a41782cc84
bpo-43774: Document configure options (GH-25283)
Add Doc/using/configure.rst documentation to document configure,
preprocessor, compiler and linker options.

Add a new section about the "Python debug build".
2021-04-08 22:32:21 +02:00
Victor Stinner 0e2a0f72cc
bpo-42802: Remove distutils bdist_wininst command (GH-24043)
The distutils bdist_wininst command deprecated in Python 3.8 has been
removed. The distutils bidst_wheel command is now recommended to
distribute binary packages on Windows.

* Remove Lib/distutils/command/bdist_wininst.py
* Remove PC/bdist_wininst/ project
* Remove Lib/distutils/command/wininst-*.exe programs
* Remove all references to bdist_wininst
2021-01-09 00:35:01 +01:00
Victor Stinner bb0b08540c
bpo-40204: Fix reference to terms in the doc (GH-21865)
Sphinx 3 requires to refer to terms with the exact case.

For example, fix the Sphinx 3 warning:

Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.
2020-08-14 12:20:05 +02:00
Cajetan Rodrigues d4f3923d59
bpo-40279: Add some error-handling to the module initialisation docs example (GH-19705) 2020-04-25 07:27:53 +02: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
Krishna Oza 038503e08a bpo-38391: Fixing a typo for Py_DECREF (GH-16616) 2019-10-07 19:57:45 +08:00
Brandt Bucher 224b8aaa7e bpo-26868: Fix example usage of PyModule_AddObject. (#15725)
* Add a note to the PyModule_AddObject docs.

* Correct example usages of PyModule_AddObject.

* Whitespace.

* Clean up wording.

* 📜🤖 Added by blurb_it.

* First code review.

* Add < 0 in the tests with PyModule_AddObject
2019-09-12 13:11:20 +01:00
Jeroen Demeyer 7f41c8e0dd bpo-37493: use _PyObject_CallNoArg in more places (GH-14575) 2019-07-04 19:35:31 +09: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
Wu Wei 662ebd2ab2 Doc: add the missing ".tp_flags" in type definition (GH-12902) 2019-04-22 20:08:20 +09:00
Inada Naoki c88feceb44
Doc: define PY_SSIZE_T_CLEAN always (GH-12794) 2019-04-13 10:46:21 +09:00
Caleb Marchent 42f55ee500 fix typo in doc (#12686) 2019-04-10 18:03:02 -04:00
Serhiy Storchaka 62be74290a
bpo-33012: Fix invalid function cast warnings with gcc 8. (GH-6749)
Fix invalid function cast warnings with gcc 8
for method conventions different from METH_NOARGS, METH_O and
METH_VARARGS excluding Argument Clinic generated code.
2018-11-27 13:27:31 +02:00
Serhiy Storchaka 3f819ca138
bpo-35110: Fix unintentional spaces around hyphens and dashes. (GH-10231) 2018-10-31 02:26:06 +02:00
Eric Snow 9e7c92193c
bpo-17045: Improve C-API doc for PyTypeObject. (gh-7413)
The existing doc had a number of info gaps and was a little hard to use.  This patch provides several quick-reference tables as well as examples.
2018-06-14 15:46:35 -06:00
Siddhesh Poyarekar 55edd0c185 bpo-33012: Fix invalid function cast warnings with gcc 8 for METH_NOARGS. (GH-6030)
METH_NOARGS functions need only a single argument but they are cast
into a PyCFunction, which takes two arguments.  This triggers an
invalid function cast warning in gcc8 due to the argument mismatch.
Fix this by adding a dummy unused argument.
2018-04-29 21:59:33 +03:00
Serhiy Storchaka 46936d5a71
Improve highlighting of some code blocks. (GH-6401) 2018-04-08 19:18:04 +03:00
Antoine Pitrou 1d80a56173
bpo-33201: Modernize "Extension types" doc (GH-6337)
* bpo-33201: Modernize "Extension types" doc
* Split tutorial and other topics
* Some small fixes
* Address some review comments
* Rename noddy* to custom* and shoddy to sublist
* Fix markup
2018-04-07 18:14:03 +02:00
Serhiy Storchaka 5bb0005f9f
Make formatting of some return codes conforming to the general style. (#5587) 2018-02-09 13:31:19 +02:00
Sanyam Khurana 338cd83c5d bpo-25910: Link redirections in docs (#1933)
Fixes some redirection links in docs.
2018-01-20 01:25:37 +01:00
Emanuele Gaifas cdfe910e74 Extending Python Doc minor updates (GH-4518)
Move footnote markers to be closer to the related terminology:
before the end of the sentence, instead of after.
2017-11-24 00:49:57 -08:00
Stefan Krah ca72589bfa bpo-31443: Formulate the type slot initialization rules in terms of C99. (#3688) 2017-09-22 17:44:58 +02:00
Sergey Fedoseev d9a2b99ac4 Fix the indentation in Extending Python code example (GH-3244)
Code was indented with three spaces.
Fixed using four spaces.
2017-08-30 07:50:40 -07:00
INADA Naoki a6296d34a4 bpo-31095: fix potential crash during GC (GH-2974) 2017-08-24 14:55:17 +09:00
UltimateCoder 8856940cf2 bpo-28315: Improve code examples in docs (GH-1372)
Replace
   File "<stdin>", line 1, in ? 
with 
   File "<stdin>", line 1, in <module>
2017-05-03 09:46:45 -07:00
Serhiy Storchaka 84b8e92e46 bpo-29918: Add missed "const" modifiers in C API documentation. (#846) 2017-03-30 10:01:03 +03:00
Serhiy Storchaka 007d7ff73f Issue #28761: The fields name and doc of structures PyMemberDef, PyGetSetDef,
PyStructSequence_Field, PyStructSequence_Desc, and wrapperbase are now of
type "const char *" rather of "char *".
2016-11-22 07:58:08 +02:00
Serhiy Storchaka bb8fd5b1eb Fixed the documentation of the structure PyMethodDef.
The fields ml_name and ml_doc are of type "const char *" rather of "char *".
2016-11-21 11:38:14 +02:00
Serhiy Storchaka 06a8dea46d Fixed the documentation of the structure PyMethodDef.
The fields ml_name and ml_doc are of type "const char *" rather of "char *".
2016-11-21 11:37:18 +02:00
Martin Panter 9440787867 Issue #26638: Merge option warning fixes from 3.5 into 3.6 2016-10-30 04:21:23 +00:00