GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Move Argument Clinic's documentation to the Developer's Guide by AA-Turner · Pull Request #1160 · python/devguide

Conversation

@AA-Turner

@AA-Turner AA-Turner commented Sep 6, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

Would close #1151 and resolve #1148

Differences from #1151:

  • I've merged the two commits cited in Migrate Argument Clinic docs from CPython to the devguide #1151 (review) so that git log, git blame, etc will properly track the history
  • This branch starts from the current HEAD so that the repository won't have a divergent history
  • The redirects in conf.py are removed
  • Removed the changes to CODEOWNERS (these need updates anyway as the paths are wrong, it should be internals/garbage-collector.rst and development-tools/clinic.rst). This is from @erlend-aasland's note "I think it's better if this PR only focus on the act of migrating clinic.rst"

cc: @erlend-aasland

This PR should be merged with the default merge option to preserve the history (Squash & Merge should not be used!)

A


📚 Documentation preview 📚: https://cpython-devguide--1160.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

erlend-aasland reacted with hooray emoji erlend-aasland reacted with heart emoji
All reactions
  • 🎉 1 reaction
  • ❤️ 1 reaction
larryhastings and others added 30 commits January 4, 2014 12:44
@larryhastings
Issue #19659: Added documentation for Argument Clinic.
376caf0
GitHub-Issue-Link: python/cpython#63858
@larryhastings
Argument Clinic: fixed test suite, improved howto.
5ca5d3a
@larryhastings
Issue #20141: Improved Argument Clinic's support for the PyArg_Parse …
9e47d75
…"O!"

format unit.

GitHub-Issue-Link: python/cpython#64340
@larryhastings
Issue #19273: The marker comments Argument Clinic uses have been changed
01ae6c7
to improve readability.

GitHub-Issue-Link: python/cpython#63472
@zware
Closes #20200: Argument Clinic custom converter example should be in a
1f988b1
'python' clinic block, not a 'clinic' clinic block.  Patch written by
Ryan Smith-Roberts.

GitHub-Issue-Link: python/cpython#64399
@larryhastings
Issue #20214: Fixed a number of small issues and documentation errors in
5c53fd9
Argument Clinic (see issue for details).

GitHub-Issue-Link: python/cpython#64413
@larryhastings
Minor doc fix in Clinic howto.
8d13753
@larryhastings
Issue #20268: Argument Clinic now supports cloning the parameters
ef8fde7
and return converter from existing functions.

GitHub-Issue-Link: python/cpython#64467
@larryhastings
Issue #20226: Major improvements to Argument Clinic.
ecea194
* You may now specify an expression as the default value for a
  parameter!  Example: "sys.maxsize - 1".  This support is
  intentionally quite limited; you may only use values that
  can be represented as static C values.
* Removed "doc_default", simplified support for "c_default"
  and "py_default".  (I'm not sure we still even need
  "py_default", but I'm leaving it in for now in case a
  use presents itself.)
* Parameter lines support a trailing '\\' as a line
  continuation character, allowing you to break up long lines.
* The argument parsing code generated when supporting optional
  groups now uses PyTuple_GET_SIZE instead of PyTuple_GetSize,
  leading to a 850% speedup in parsing.  (Just kidding, this
  is an unmeasurable difference.)
* A bugfix for the recent regression where the generated
  prototype from pydoc for builtins would be littered with
  unreadable "=<object ...>"" default values for parameters
  that had no default value.
* Converted some asserts into proper failure messages.
* Many doc improvements and fixes.

GitHub-Issue-Link: python/cpython#64425
@larryhastings
Issue #20287: Argument Clinic's output is now configurable, allowing
71ff306
delaying its output or even redirecting it to a separate file.

GitHub-Issue-Link: python/cpython#64486
@larryhastings
Doc improvements for Clinic howto "Goals" section.
8224acf
@larryhastings
Issue #20294: Argument Clinic now supports argument parsing for __new…
3619f5f
…__ and

__init__ functions.

GitHub-Issue-Link: python/cpython#64493
@larryhastings
Doc fixes for Argument Clinic.
745625b
@ezio-melotti
GitHub-Issue-Link: python/cpython#64547
4259315
@larryhastings
Documentation fixes, including fixing "suspicious" problems.
86a65e4
@larryhastings
including correctly generating code for Clinic blocks inside C
416ba5f
preprocessor conditional blocks.

GitHub-Issue-Link: python/cpython#64655
@dstufft
Fix Issue #21528 - Fix documentation typos
6341d75
GitHub-Issue-Link: python/cpython#65727
@larryhastings
Issue #24000: Improved Argument Clinic's mapping of converters to legacy
e3c5656
"format units".  Updated the documentation to match.

GitHub-Issue-Link: python/cpython#68188
@taleinat
Argument Clinic: added missing bit of info in howto
2914da8
@berkerpeksag
Issue #24232: Fix typos. Patch by Ville Skyttä.
1b9d562
GitHub-Issue-Link: python/cpython#68420
@berkerpeksag
Issue #24232: Fix typos. Patch by Ville Skyttä.
be8c565
@orsenthil
Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multip…
f3fcaa4
…le documentation typos.

Related Issues:

#issue21528
#issue24453
@orsenthil
null merge with 3.4
62bda94
Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multiple documentation typos.

Related Issues:
#issue21528
#issue24453
@ned-deily
null merge 3.4 to 3.5 (9a0c5ffe7420 merged 3.4 to default, bypassing …
05046f9
…3.5)
@ned-deily
null merge 3.5 to default (9a0c5ffe7420 merged 3.4 to default, bypass…
70bfe58
…ing 3.5)
@vadmium
Issue #25626: Change zlib to accept Py_ssize_t and cap to UINT_MAX
0ca4094
GitHub-Issue-Link: python/cpython#69812

The underlying zlib library stores sizes in “unsigned int”. The corresponding
Python parameters are all sizes of buffers filled in by zlib, so it is okay
to reduce higher values to the UINT_MAX internal cap. OverflowError is still
raised for sizes that do not fit in Py_ssize_t.

Sizes are now limited to Py_ssize_t rather than unsigned long, because Python
byte strings cannot be larger than Py_ssize_t. Previously this could result
in a SystemError on 32-bit platforms.

This resolves a regression in the gzip module when reading more than UINT_MAX
or LONG_MAX bytes in one call, introduced by revision 62723172412c.
@vadmium
Issue #25626: Merge zlib fix from 3.5
c7b612a
@vadmium
Issue #27130: Fix handling of buffers exceeding UINT_MAX in “zlib” mo…
cfb1132
…dule

Patch by Xiang Zhang.

GitHub-Issue-Link: python/cpython#71317
@vadmium
Issue #27626: Spelling fixes in docs, comments and internal names
4d20304
Based on patch by Ville Skyttä.

GitHub-Issue-Link: python/cpython#71813
@vadmium
Issue #26462: Doc: reduce literal_block warnings, fix syntax highligh…
3c7af20
…ting.

Patch by Julien Palard.

GitHub-Issue-Link: python/cpython#70649
@erlend-aasland

erlend-aasland commented Sep 6, 2023

Copy link
Copy Markdown
Contributor

Great, thank you so much, Adam!

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

This comment was marked as resolved.

Sign in to view
@ned-deily

ned-deily commented Sep 6, 2023

Copy link
Copy Markdown
Member

I guess I’ve now satisfied the cla bot even though that email address has been dead for many years ;)

AA-Turner reacted with hooray emoji
All reactions
  • 🎉 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 6, 2023

Copy link
Copy Markdown
Contributor

@AA-Turner, are you ready for rebase-and-merge? 🚀

AA-Turner reacted with hooray emoji
All reactions
  • 🎉 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 6, 2023

Copy link
Copy Markdown
Member Author

Yessir! Hopefully all goes well...

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 6, 2023

Copy link
Copy Markdown
Contributor

Yessir! Hopefully all goes well...

Hm, perhaps a merge commit would be preferable to rebase in this case.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 6, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

There are some embedded merges (e.g. f57d28b) -- I don't know if a rebase-merge would linearise. A standard merge commit would work for certain.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk

hugovk commented Sep 6, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

The enabled options are squash and merge, and rebase and merge.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 6, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

I think a rebase-and-merge does something a la this:

$ git switch <pr-branch>
$ git rebase main  # put everything on "top" of main
$ git switch main
$ git merge --ff @{-1}  # fast-forward through the rebased branch

So, we'll end up with ~70 more commits after b70b763. Perhaps that's ok. Here's a local rebase-and-main of this PR:

$ git switch main
$ git pull
$ gh co 1160
$ git rebase main
$ git switch -
$ git merge --ff @{-1}
$ git log --oneline upstream/main.. | wc -l
    68
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 6, 2023

Copy link
Copy Markdown
Contributor

The enabled options are squash and merge, and rebase and merge.

Yeah, we'd need a repo admin to enable the merge option for a little while. But I'm not sure it's worth it.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 6, 2023

Copy link
Copy Markdown
Member Author

Let me try making a PR against my fork & rebase-merging

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland erlend-aasland mentioned this pull request Sep 6, 2023
Migrate Argument Clinic docs from CPython to the devguide #1151
Closed
@AA-Turner

AA-Turner commented Sep 6, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

It seems, unfortunately, that history is fully linearised with a rebase-merge:

https://github.com/AA-Turner/devguide/commits/main/

This branch (pre rebase-merge -- note the embedded branches)

$ git log upstream/main..migrate-argument-clinic-docs-rebase --oneline --graph --simplify-merges
* d400976 (origin/migrate-argument-clinic-docs-rebase, migrate-argument-clinic-docs-rebase, macdr-tmp) Adapt clinic.rst
* 2853c96 Add clinic.rst to Development Tools
* bb50117 Add clinic.rst with history
* 151a8c7 Docs: clean up Argument Clinic howto's (#107797)
* c312d0d gh-104683: Add --exclude option to Argument Clinic CLI (#107770)
* ed0c511 gh-86457: Add docs for Argument Clinic @text_signature directive (#107747)
* 5bdd8a1 gh-95065: Add Argument Clinic support for deprecating positional use of parameters (#95151)
* 9034038 Docs: Argument Clinic: Move the CConverter class to the reference (#107671)
* 8d09b74 Docs: Argument Clinic: Improve 'How to write a custom converter' (#107328)
* a4ae828 gh-107507: Replace 'The goals of Argument Clinic' with a summary (#107508)
* 66aa05c Docs: Argument Clinic: Restructure "Basic concepts and usage" (#106981)
* 8d22321 Docs: Remove the numbered steps from the Argument Clinic tutorial (#107203)
* 2886f0a Docs: Add missing markup to Argument Clinic docs (#106876)
* 344c441 Docs: Remove duplicate word in Argument Clinic howto heading (#107169)
* 3eef763 Docs: Argument Clinic: Add Background and Tutorial top-level sections (#106904)
* 415cecb Docs: Argument Clinic: Group guides about default values (#106872)
* a8eaf77 Docs: Normalise Argument Clinic advanced topics headings (#106842)
* e3fa19a Docs: Normalize Argument Clinic How-To section capitalization (#106788)
* 295ff8c gh-104389: Add 'unused' keyword to Argument Clinic C converters (#104390)
* fd1d602 gh-64658: Expand Argument Clinic return converter docs (#104175)
* e470d87 gh-98763: Prefer "python" over "python3" for command line examples in docs. (#98761)
* 57ffbb3 docs: Change links to label refs (#98454)
* 5a09524 gh-97956: Mention `generate_global_objects.py` in `AC How-To` (#97957)
* 4cd7406 gh-95007: Remove the NoneType return converter from Argument Clinic Doc (#95529)
* 31b05dc Docs: remove redundant "adverb-adjective" hyphens from compound modifiers (GH-94551)
* e500f1e Document Py_ssize_t. (GH-92512)
* 7c1e59b gh-92536: PEP 623: Remove wstr and legacy APIs from Unicode (GH-92537)
* 3c27a95 bpo-46613: Add PyType_GetModuleByDef to the public API (GH-31081)
* b24f012 bpo-45320: Remove long-deprecated inspect methods (GH-28618)
* a29a2f9 bpo-42048: Clinic Howto: Document AC's defining_class converter (GH-23978)
* bdcd2e0 bpo-38600: NULL -> ``NULL``. (GH-17001)
* aed5df8 Doc: Replace the deprecated highlightlang directive by highlight. (#13377)
* 51b5015 bpo-35042: Use the :pep: role where a PEP is specified (#10036)
* e2b893d bpo-20260: Implement non-bitwise unsigned int converters for Argument Clinic. (GH-8434)
* fca9801 Docs: be less specific about python versions (GH-6985)
* e8feb55 Improve highlighting of some code blocks. (GH-6401)
* c20fce3 bpo-29596: Improve clinic howto documentation (GH-1710)
* 41e583f bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
*   f6f3d84 Issue #28755: Merge Arg Clinic howto from 3.6
|\
| *   f57d28b Issues #28755, #28753: Merge Arg Clinic howto from 3.5
| |\
| | * a34489a Issue #28755: Improve syntax highlighting in Arg Clinic howto
| | * 45df510 Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
* | | a814275 Change an en-dash to an em-dash.
* | | bcd28d5 Merge doc fixups from 3.6
|\| |
| * | a084c1a Merge doc fixups from 3.5
| |\|
| | * 1acf9f1 Change double hyphens (en dashes) to em (longer) dashes
* | | 979f676 Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
|/ /
* / f296eec clinic: PY_LONG_LONG -> long long
|/
* a219cc1 Issue #27745: Fix some typos in Argument Clinic howto, by Lele Gaifax
* 42a5613 Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
* 43460f5 Issue #27626: Spelling fixes in docs, comments and internal names
* 8d02d63 Issue #27130: Fix handling of buffers exceeding UINT_MAX in “zlib” module
*   a8f1fd9 Issue #25626: Merge zlib fix from 3.5
|\
| * d3999f3 Issue #25626: Change zlib to accept Py_ssize_t and cap to UINT_MAX
* | f474f74 null merge 3.5 to default (9a0c5ffe7420 merged 3.4 to default, bypassing 3.5)
|\|
| *   521f916 null merge 3.4 to 3.5 (9a0c5ffe7420 merged 3.4 to default, bypassing 3.5)
| |\
* | \   44a5dd0 null merge with 3.4
|\ \ \
| |/ /
|/| /
| |/
| * ce0eea3 Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multiple documentation typos.
* | 9d3c415 Issue #24232: Fix typos. Patch by Ville Skyttä.
|\|
| * 1c71560 Issue #24232: Fix typos. Patch by Ville Skyttä.
* | 76f3c98 Argument Clinic: added missing bit of info in howto
* | 9932752 Issue #24000: Improved Argument Clinic's mapping of converters to legacy "format units".  Updated the documentation to match.
* | 1a50188 Fix Issue #21528 - Fix documentation typos
|/
* 397ed13 #Issue 20456: Several improvements and bugfixes for Argument Clinic, including correctly generating code for Clinic blocks inside C preprocessor conditional blocks.
* e68d632 Documentation fixes, including fixing "suspicious" problems.
* d1f7bad #20348: fix headers markup in Argument Clinic howto.  Patch by Moritz Neeb.
* a058a0e Doc fixes for Argument Clinic.
* 36ddfaa Issue #20294: Argument Clinic now supports argument parsing for __new__ and __init__ functions.
* 432d1c5 Doc improvements for Clinic howto "Goals" section.
* 2bbdb20 Issue #20287: Argument Clinic's output is now configurable, allowing delaying its output or even redirecting it to a separate file.
* 5cc73dc Issue #20226: Major improvements to Argument Clinic.
* 95b9ad1 Issue #20268: Argument Clinic now supports cloning the parameters and return converter from existing functions.
* cbad5d2 Minor doc fix in Clinic howto.
* 0729c14 Issue #20214: Fixed a number of small issues and documentation errors in Argument Clinic (see issue for details).
* 246016e Closes #20200: Argument Clinic custom converter example should be in a 'python' clinic block, not a 'clinic' clinic block.  Patch written by Ryan Smith-Roberts.
* f8f8a8a Issue #19273: The marker comments Argument Clinic uses have been changed to improve readability.
* 7324097 Issue #20141: Improved Argument Clinic's support for the PyArg_Parse "O!" format unit.
* 467c3ef Argument Clinic: fixed test suite, improved howto.
* 29b0880 Issue #19659: Added documentation for Argument Clinic.

My fork (post rebase-merge) -- note no branches

$ git log upstream/main..origin/main --oneline --graph --simplify-merges
* 6825c6e (origin/main) Adapt clinic.rst
* 6b83f2a Add clinic.rst to Development Tools
* 0912b4e Add clinic.rst with history
* 3614c6c Docs: clean up Argument Clinic howto's (#107797)
* 4c91a7d gh-104683: Add --exclude option to Argument Clinic CLI (#107770)
* 41c0a2d gh-86457: Add docs for Argument Clinic @text_signature directive (#107747)
* 9a08231 gh-95065: Add Argument Clinic support for deprecating positional use of parameters (#95151)
* a4a2f41 Docs: Argument Clinic: Move the CConverter class to the reference (#107671)
* 52e9a80 Docs: Argument Clinic: Improve 'How to write a custom converter' (#107328)
* 82a50e3 gh-107507: Replace 'The goals of Argument Clinic' with a summary (#107508)
* cf6f1a9 Docs: Argument Clinic: Restructure "Basic concepts and usage" (#106981)
* c0e1277 Docs: Remove the numbered steps from the Argument Clinic tutorial (#107203)
* dfd211b Docs: Add missing markup to Argument Clinic docs (#106876)
* 6172656 Docs: Remove duplicate word in Argument Clinic howto heading (#107169)
* 897bf32 Docs: Argument Clinic: Add Background and Tutorial top-level sections (#106904)
* 838112b Docs: Argument Clinic: Group guides about default values (#106872)
* da7f601 Docs: Normalise Argument Clinic advanced topics headings (#106842)
* fe2d48d Docs: Normalize Argument Clinic How-To section capitalization (#106788)
* 47f614c gh-104389: Add 'unused' keyword to Argument Clinic C converters (#104390)
* df452a4 gh-64658: Expand Argument Clinic return converter docs (#104175)
* 0c38d4b gh-98763: Prefer "python" over "python3" for command line examples in docs. (#98761)
* 3c0411c docs: Change links to label refs (#98454)
* 1f34c27 gh-97956: Mention `generate_global_objects.py` in `AC How-To` (#97957)
* 98510f9 gh-95007: Remove the NoneType return converter from Argument Clinic Doc (#95529)
* f135d64 Docs: remove redundant "adverb-adjective" hyphens from compound modifiers (GH-94551)
* 78d52d4 Document Py_ssize_t. (GH-92512)
* fb4a070 gh-92536: PEP 623: Remove wstr and legacy APIs from Unicode (GH-92537)
* 05650e7 bpo-46613: Add PyType_GetModuleByDef to the public API (GH-31081)
* 8da453d bpo-45320: Remove long-deprecated inspect methods (GH-28618)
* dacc8bf bpo-42048: Clinic Howto: Document AC's defining_class converter (GH-23978)
* 0117a9d bpo-38600: NULL -> ``NULL``. (GH-17001)
* f9fde8e Doc: Replace the deprecated highlightlang directive by highlight. (#13377)
* f9dcc92 bpo-35042: Use the :pep: role where a PEP is specified (#10036)
* 610ace1 bpo-20260: Implement non-bitwise unsigned int converters for Argument Clinic. (GH-8434)
* a314057 Docs: be less specific about python versions (GH-6985)
* 290fd75 Improve highlighting of some code blocks. (GH-6401)
* 0de8622 bpo-29596: Improve clinic howto documentation (GH-1710)
* 110adf4 bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
* b17ea88 Issue #28755: Improve syntax highlighting in Arg Clinic howto
* 33188e3 Change an en-dash to an em-dash.
* 777e85b Change double hyphens (en dashes) to em (longer) dashes
* 551516f Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
* 91259d6 clinic: PY_LONG_LONG -> long long
* e7fd394 Issue #27745: Fix some typos in Argument Clinic howto, by Lele Gaifax
* 4fadd2f Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
* 45eee05 Issue #27626: Spelling fixes in docs, comments and internal names
* 1d230bf Issue #27130: Fix handling of buffers exceeding UINT_MAX in “zlib” module
* 29ae29b Issue #25626: Change zlib to accept Py_ssize_t and cap to UINT_MAX
* dee5132 Issue #24232: Fix typos. Patch by Ville Skyttä.
* 748bbea Argument Clinic: added missing bit of info in howto
* e617cac Issue #24000: Improved Argument Clinic's mapping of converters to legacy "format units".  Updated the documentation to match.
* cc72f86 Fix Issue #21528 - Fix documentation typos
* d624f48 #Issue 20456: Several improvements and bugfixes for Argument Clinic, including correctly generating code for Clinic blocks inside C preprocessor conditional blocks.
* 59d789a Documentation fixes, including fixing "suspicious" problems.
* a71c6f3 #20348: fix headers markup in Argument Clinic howto.  Patch by Moritz Neeb.
* 97cd258 Doc fixes for Argument Clinic.
* 6ffe3ba Issue #20294: Argument Clinic now supports argument parsing for __new__ and __init__ functions.
* 07501c0 Doc improvements for Clinic howto "Goals" section.
* cb677af Issue #20287: Argument Clinic's output is now configurable, allowing delaying its output or even redirecting it to a separate file.
* 8255c89 Issue #20226: Major improvements to Argument Clinic.
* 4ab173e Issue #20268: Argument Clinic now supports cloning the parameters and return converter from existing functions.
* 5b0ce65 Minor doc fix in Clinic howto.
* 4d263f5 Issue #20214: Fixed a number of small issues and documentation errors in Argument Clinic (see issue for details).
* 220d083 Closes #20200: Argument Clinic custom converter example should be in a 'python' clinic block, not a 'clinic' clinic block.  Patch written by Ryan Smith-Roberts.
* 0f7c066 Issue #19273: The marker comments Argument Clinic uses have been changed to improve readability.
* 7e7dae0 Issue #20141: Improved Argument Clinic's support for the PyArg_Parse "O!" format unit.
* cc3f6d6 Argument Clinic: fixed test suite, improved howto.
* 32ca987 Issue #19659: Added documentation for Argument Clinic.

A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 6, 2023

Copy link
Copy Markdown
Member Author

The other (unforseen) downside of a rebase-merge is that it sets the committer for each commit to the person doing the merge (don't ask me why!):

image

A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 6, 2023

Copy link
Copy Markdown
Contributor

The other (unforseen) downside of a rebase-merge is that it sets the committer for each commit to the person doing the merge (don't ask me why!):

Well, rebasing implies rewriting the Git history. I think a merge commit is the best way to land this.

AA-Turner reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk

hugovk commented Sep 6, 2023

Copy link
Copy Markdown
Member

Becasue a rebase is rewriting history, and the rebaser is creating new commits with new SHAs. The original author/committer is preserved in an author trailer.

erlend-aasland and AA-Turner reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 6, 2023

Copy link
Copy Markdown
Member Author

I don't know who the admins are for the devguide repo (ironically, the devguide only lists the admins for the CPython repo!) -- is there an obvious way to find out that I'm missing?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk

hugovk commented Sep 7, 2023

Copy link
Copy Markdown
Member

Scroll up a bit, there's a GitHub org owners list at https://devguide.python.org/developer-workflow/development-cycle/#current-owners

Is it really worth an exception in this case? I'm fine with the existing options of either squash and merge, or rebase and merge.

Everyone still gets credit in the commits, and the PR is still here to show all the old commits.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 7, 2023

Copy link
Copy Markdown
Member Author

GitHub org owners

Of course, forgot they had admin rights momentarily

Is it really worth an exception in this case? I'm fine with the existing options of either squash and merge, or rebase and merge.

Everyone still gets credit in the commits, and the PR is still here to show all the old commits.

I'd like to argue that it is. Moving histories like this PR does is fairly uncommon, but is also a 'one chance to get right' activity. Preserving the history properly allows for local (offline etc) inspection (this is often useful to me on trains/planes with poor or zero internet connection), proper git blame for working out the rationale of a change, etc.

A specific argument against using this PR as the history: When looking through the commit history of the PEPs or CPython the links to now-dead VCS hosts are too numerous to list. GitHub might be shut down in 20 years, or Python migrate to another DCVS host, (or another VCS), etc -- embedding the data in the repository itself, as intended by git, is the better thing to do here. Though it is more inconvenient to accomplish.

Sorry for the mild diatribe!
A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 7, 2023

Copy link
Copy Markdown
Contributor

After sleeping on this, I'm fine with the rebase option. If we want, we can also rewrite the commit titles (gh-xxx => python/cpython#xxx), so the commit title links will work. What do you think?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 8, 2023

Copy link
Copy Markdown
Contributor

After sleeping on this, I'm fine with the rebase option. If we want, we can also rewrite the commit titles (gh-xxx => python/cpython#xxx), so the commit title links will work. What do you think?

Like this: erlend-aasland#1

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner
AA-Turner force-pushed the migrate-argument-clinic-docs-rebase branch from d400976 to 7e4977f Compare September 13, 2023 22:56
erlend-aasland
erlend-aasland approved these changes Sep 15, 2023
View reviewed changes
@erlend-aasland

erlend-aasland commented Sep 15, 2023

Copy link
Copy Markdown
Contributor

@AA-Turner, ready for rebase and merge?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 25, 2023

Copy link
Copy Markdown
Contributor

Gentle ping, @AA-Turner :)

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Sep 25, 2023

Copy link
Copy Markdown
Member Author

Yep, no further changes from me.

A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland

erlend-aasland commented Sep 26, 2023

Copy link
Copy Markdown
Contributor

🤞🚀

AA-Turner reacted with hooray emoji
All reactions
  • 🎉 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@erlend-aasland
erlend-aasland merged commit 4baaf76 into python:main Sep 26, 2023
@erlend-aasland erlend-aasland mentioned this pull request Sep 26, 2023
Move the Argument Clinic docs to the devguide python/cpython#107518
Closed
3 tasks done
@AA-Turner AA-Turner mentioned this pull request Aug 18, 2025
Move Argument Clinic Tutorial & How-To Guides to new pages #1641
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@erlend-aasland erlend-aasland erlend-aasland approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Migrate Argument Clinic docs from the CPython repo to the devguide

Uh oh!

There was an error while loading. Please reload this page.

20 participants

@AA-Turner @erlend-aasland @ned-deily @hugovk @larryhastings @zware @ezio-melotti @dstufft @taleinat @berkerpeksag @orsenthil @vadmium @benjaminp @serhiy-storchaka @gfyoung @grimreaper @matrixise @encukou @methane @JulienPalard
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.