Formed in 2009, the Archive Team (not to be confused with the archive.org Archive-It Team) is a rogue archivist collective dedicated to saving copies of rapidly dying or deleted websites for the sake of history and digital heritage. The group is 100% composed of volunteers and interested parties, and has expanded into a large amount of related projects for saving online and digital history.
Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign upGitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
Add a section 'Extensions' #246
Conversation
|
Thanks for getting this started! Some more detailed recommendations in line, but I think this will be a useful addition. |
| @@ -0,0 +1,13 @@ | ||
| .. _extensions: | ||
|
|
||
| Write a CPython extension |
ncoghlan
Jul 26, 2017
Contributor
I'd suggest "Updating standard library extension modules"
I'd suggest "Updating standard library extension modules"
| Write a CPython extension | ||
| ========================= | ||
|
|
||
| In this section, we could explain how to write a CPython extension with the C language, but the topic can take a complete book. |
ncoghlan
Jul 26, 2017
Contributor
I think the goal of this section should be to equip folks with the tools they need to work on the existing extension modules in the reference implementation, and to add new ones if necessary.
Essential pointers:
- link to the full C API docs: https://docs.python.org/dev/c-api/
- link to PEP 399 specifically in relation to accelerator modules and testing both implementations
I think the goal of this section should be to equip folks with the tools they need to work on the existing extension modules in the reference implementation, and to add new ones if necessary.
Essential pointers:
- link to the full C API docs: https://docs.python.org/dev/c-api/
- link to PEP 399 specifically in relation to accelerator modules and testing both implementations
|
|
||
| Read the following references: | ||
|
|
||
| * https://docs.python.org/3.7/extending/ |
ncoghlan
Jul 26, 2017
Contributor
For easier maintenance, use the dev link rather than the specific version: https://docs.python.org/dev/extending/
For easier maintenance, use the dev link rather than the specific version: https://docs.python.org/dev/extending/
|
Hi @matrixise, Do you wish to finish up this PR or would you like me to do so? Thanks! |
|
@willingc I will finish this PR, really sorry, I will work on it on this evening. |
|
Minor suggested wording adjustment inline, but I think is a useful addition as is. |
|
|
||
| In this section, we could explain how to write a CPython extension with the C language, but the topic can take a complete book. | ||
|
|
||
| For this reason, we prefer to give you some links where you can read a very good documentation. |
ncoghlan
Aug 4, 2018
Contributor
Suggested wording/grammar tweak:
For this reason, we instead prefer to provide some links to existing documentation that we recommend.
(Perhaps it would also be worth mentioning core-mentorship here, and linking to the section on communications?)
Suggested wording/grammar tweak:
For this reason, we instead prefer to provide some links to existing documentation that we recommend.
(Perhaps it would also be worth mentioning core-mentorship here, and linking to the section on communications?)
|
Do we really need to create a separate document just for four links? I think the most up-to-date and detailed resource is https://pythonextensionpatterns.readthedocs.io/en/latest/ and it was already linked in the Devguide in #279. |
|
We really should have more than just the 4 links - referencing the C style guide, pointers to test_embed and test_capi, etc, start building out some extra docs for internal helper functions, etc. It would make sense to mention that as a ReST comment though, otherwise it isn't clear why we're adding such a bare bones page in the first place. |
I don't think "we'll finish this later" is a good argument for merging this PR. A TODO comment can easily be forgotten in a short time. And after two years or so, someone is going to submit a PR to remove extensions.rst because it doesn't contain any useful information. Please don't make the Devguide a place for unfinished and half baked documents. |
|
@berkerpeksag ok, but where will you put these links? |
|
PEP 399 can be mentioned at https://devguide.python.org/runtests/#writing ( |
|
"You can find this information via Google if you already know what to look for, and how to interpret the results" isn't a particularly helpful attitude for us to adopt when writing documentation aimed primarily at new CPython contributors. If starting the section out with just a few links really bothers you, then rather than saying "This doesn't have enough content, so reject it", I'd prefer to see this new section extended a bit to also cover:
|
Most of these links are from our own documentation and don't have anything to do with contributing to CPython (except PEP 399) People can read them to learn how to write Python extensions for their own projects. We don't explain how to use unittest or how to write unit tests in the devguide. We only give information specific to CPython (how to use regrtest, how to find memory leaks by using regrtest, how to make coveragepy work with extension modules,
Your suggestions sound good to me. I'd like to see a action about how to test a C API function (by using |
No description provided.