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

[artgoldberg]

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:

assignee = None
closed_at = None
created_at = <Date 2017-04-05.18:46:35.693>
labels = ['type-bug', 'docs']
title = 'Suggested changes for https://docs.python.org/3.6/extending/extending.html'
updated_at = <Date 2017-04-05.20:07:15.272>
user = 'https://github.com/artgoldberg'

bugs.python.org fields:

activity = <Date 2017-04-05.20:07:15.272>
actor = 'fdrake'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-04-05.18:46:35.693>
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']

[artgoldberg]

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,/

[artgoldberg]

Also,

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