Suggested changes for https://docs.python.org/3.6/extending/extending.html

[c64c32e3-fb5d-4a19-b893-90a7f74d5b93]

BPO	29997
Nosy	@freddrake, @artgoldberg

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['type-bug', 'docs'] title = 'Suggested changes for https://docs.python.org/3.6/extending/extending.html' updated_at = user = 'https://github.com/artgoldberg' ``` bugs.python.org fields: ```python activity = actor = 'fdrake' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'ArthurGoldberg' dependencies = [] files = [] hgrepos = [] issue_num = 29997 keywords = [] message_count = 2.0 messages = ['291192', '291193'] nosy_count = 3.0 nosy_names = ['fdrake', 'docs@python', 'ArthurGoldberg'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue29997' versions = ['Python 3.6'] ```

[c64c32e3-fb5d-4a19-b893-90a7f74d5b93]

I've just taught myself how to write C extensions to Python with https://docs.python.org/3.6/extending/extending.html. I think it's quite good.

Nevertheless, I've some suggested improvements. These all use the vi s/// replacement syntax.

• Ambiguous 'it':

  s/If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly./If the latter header file does not exist on your system, Python.h declares the functions malloc(), free() and realloc() directly./

  Unclear, as 'The C function' refers to the specific example, whereas 'always has' implies that this applies to all calls from Python to C: s/The C function always has two arguments, conventionally/A C function called by Python always has two arguments, conventionally/

• In

  PyMODINIT_FUNC
  PyInit_spam(void)
  {
     PyObject *m;
  
     m = PyModule_Create(&spammodule);
     if (m == NULL)
         return NULL;
  
     SpamError = PyErr_NewException("spam.error", NULL, NULL);
     Py_INCREF(SpamError);
     PyModule_AddObject(m, "error", SpamError);
     return m;
  }

  remove

     m = PyModule_Create(&spammodule);
     if (m == NULL)
         return NULL;

  and replace it with

     ...

  because it won't compile because spammodule has not been described yet on the page.

• Self-contradictory: 'normally always' is an oxymoron. s/It should normally always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS; a value of 0 means that an obsolete variant of PyArg_ParseTuple() is used./It should always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS; however, legacy code may use 0, which indicates that an obsolete variant of PyArg_ParseTuple() is being used./

• Incomplete: this comment doesn't contain a complete thought s/module documentation, may be NULL/pointer to a string containing the module's documentation, or NULL if none is provided/

• Provide hyperlink: for user convenience, add a hyperlink to 'Modules/xxmodule.c' s/included in the Python source distribution as Modules/xxmodule.c/included in the Python source distribution as Modules/xxmodule.c/

• Incomplete: It would be good to lead programmers towards the easiest approach. s/ If you use dynamic loading,/\<new paragraph\> If you can use dynamic loading, the the easiest approach is to use Python's distutils module to build your module. If you use dynamic loading,/

[c64c32e3-fb5d-4a19-b893-90a7f74d5b93]

Also,

Incorrect number agreement: s/strategy that minimizes this kind of errors/strategy that minimizes this kind of error/