Are you ok with the naming convention of adding Ref suffix when adding a variant of a function which returns a strong reference instead of a borrowed reference? Do we need to go further in terms of standard?
See also issue #14: "PyLong and PyUnicode don't match the Python type names".
Point raised by @markshannon in my PR adding PyDict_GetItemRef().
(*) I would like to fix the C API to avoid functions returning borrewed references. For that, I add new variants of existing functions which return strong references, by adding a Ref suffix to their name:
- PyModule_AddObject() => PyModule_AddObjectRef()
- PyImport_AddModule() => PyImport_AddModuleRef()
- PyWeakref_GetObject() => PyWeakref_GetRef()
- PyDict_GetItemWithError() => PyDict_GetItemRef() -- it also replaces PyDict_GetItem()
In the past, other naming convention were used (other suffixes were added).
(*) To add support for Unicode filenames in the import machinery, I add variants of functions taking char* by adding Object suffix: function taking PyObject* argument. Examples:
- PyRun_SimpleFileExFlags() => PyRun_SimpleFileObject()
- PyRun_InteractiveOneFlags() => PyRun_InteractiveOneFlagsObject()
- Py_CompileStringExFlags() => Py_CompileStringObject()
- PyErr_WarnExplicit() = PyErr_WarnExplicitObject()
- PyErr_SyntaxLocationEx() => PyErr_SyntaxLocationObject()
(*) Previously, another trend was simply to add Ex suffix. Windows API has a similar pattern: WaitForMultipleObjects() => WaitForMultipleObjectsEx(). Examples in Python:
- PyErr_Print() => PyErr_PrintEx()
- Py_Finalize() => Py_FinalizeEx()
- PyErr_SyntaxLocationObject() => PyErr_SyntaxLocationObjectEx() -- this one now combines two suffix, Object and Ex :-)
(*) A fourth trend (!) is to use WithSomething suffix. Examples:
- PyDict_GetItem() => PyDict_GetItemWithError()
- PyImport_ExecCodeModuleEx() => PyImport_ExecCodeModuleWithPathnames()
- PyCFunction => PyCFunctionWithKeywords
- PyType_FromSpec() => PyType_FromSpecWithBases()
(*) I also saw another suffix, I don't know if it can be called a convention, a variant of the previous name: add Flags.
- PyRun_AnyFileEx() => PyRun_AnyFileExFlags() -- combo! Ex and Flags suffixes :-)
- PyRun_String() => PyRun_StringFlags()
- _PyStructSequence_InitBuiltin() => _PyStructSequence_InitBuiltinWithFlags -- variant of the variant... With + Flags
So I saw the following conventions to add suffixes (oldest to the most recent):
- Add Flags suffix
- Add Ex suffix
- Add WithSomething suffix
- Add Object suffix
- Add Ref suffix
The funny part is that some added functions get multiple suffixes like PyRun_AnyFileExFlags() (Ex + Flags).
Are you ok with the naming convention of adding Ref suffix when adding a variant of a function which returns a strong reference instead of a borrowed reference? Do we need to go further in terms of standard?
See also issue #14: "PyLong and PyUnicode don't match the Python type names".
Point raised by @markshannon in my PR adding PyDict_GetItemRef().
(*) I would like to fix the C API to avoid functions returning borrewed references. For that, I add new variants of existing functions which return strong references, by adding a Ref suffix to their name:
In the past, other naming convention were used (other suffixes were added).
(*) To add support for Unicode filenames in the import machinery, I add variants of functions taking
char*by addingObjectsuffix: function takingPyObject*argument. Examples:(*) Previously, another trend was simply to add
Exsuffix. Windows API has a similar pattern: WaitForMultipleObjects() => WaitForMultipleObjectsEx(). Examples in Python:(*) A fourth trend (!) is to use WithSomething suffix. Examples:
(*) I also saw another suffix, I don't know if it can be called a convention, a variant of the previous name: add Flags.
So I saw the following conventions to add suffixes (oldest to the most recent):
The funny part is that some added functions get multiple suffixes like PyRun_AnyFileExFlags() (Ex + Flags).