Glossary for naming APIs

[encukou]

Parts taken fromVictor's suffix survey: capi-workgroup/problems#52

We might want to provide a glossary to help keep API names consistent. Here's a draft.

Name components

• From<type> (e.g. PyLong_FromLong): creates an object
• As<type> (e.g. PyLong_AsLong): converts to a C type
• Get: Retrieve a value (no side effect except allocation/refcounting)
• Va: Takes varargs

Suffixes

• Object (in functions, e.g. ): Takes a Python object rather than a native type (e.g. PyImport_AddModuleObject(PyObject*) vs. PyImport_AddModule(char*))
• Object (type, e.g. PyLongObject): The instance struct. Omit the underscore (it's not PyLong_Object).
• _<typename> (_PyObject_CallFunction_SizeT): Has an unexpected argument/return type, or a different type than a similar function
• _impl: "Inner" function that has a wrapper. Used e.g. by Argument Clinic, and by C-specific speedups (Avoid macros and static inline functions #18). Should be marked private (_Py) if exposed to users.

Exceptions to rules

(These are new proposals)

• Unchecked: Doesn't validate a (pre)condition that's normally checked
• Unsafe: Doesn't uphold some invariant that users expect
• terms around managing ownership - see Terminology for managing ownership #25

Suffixes for "evolved" versions of functions:

• Ref: Returns a new reference
• WithError: Has proper error handling
• With* (WithKeywords, WithBases, etc.): Takes an additional argument.
• Flags: Takes additional flags
• Ex: Takes additional arguments. Avoid this; use a more specific name.

XXX: Should we prefer adding these suffixes rather to using a different base name. (Should the "fixed" version of PyDict_GetItem be PyDict_GetItemRef or PyDict_FetchItem?) IMO, the suffix is uglier but clearer, and clarity wins that contest.

Avoid

• New
• Fast
• Ex

[encukou]

Re. capi-workgroup/problems#14 (PyLong and PyUnicode don't match the Python type names) I propose that we opt to stay consistent rather than match Python names:

Avoid

• PyInt (use PyLong as the category prefix for the Python int type)
• PyStr (use PyUnicode as the category prefix for the Python str type)

If we were designing a new API, we could switch to PyInt/PyStr. But as long as the old names are available, consistency will result in less confusion.
(I'm aware that this is a catch-22 policy which ensures that they will always stay available.)

[davidhewitt]

@encukou what do you think about the guideline for PyInt and PyStr extending to downstream projects? At the moment PyO3 is a little confused about what to name these types, we expose PyInt and PyLong as aliases for the same type, and similarly we have aliases PyUnicode and PyString (oops, not even PyStr).

Should PyO3 back up and reduce just back to PyLong and PyUnicode? Or do you think it's better for PyO3 to go for the clean break (because it can relatively easily deprecate things compared to CPython) and switch over to PyInt / PyStr?

[gvanrossum]

I’m not Petr but I think that’s really up to PyO3.

[davidhewitt]

@gvanrossum fair point and I've intended to start a thread on this on the PyO3 issue tracker for a while. For what it's worth I was leaning towards PyInt and PyStr because I think it's generally easier for PyO3 users to find APIs when they share names with pure Python code rather than the C API.

I'll mark as off-topic.

[encukou]

The question is off topic, but this discussion might be interesting for us as well. I've restored your comments. For any PyO3-specific follow-ups, your tracker is of course a better fit.

Yup, it depends on the project.
One thing to watch out for is that Python reserves the Py namespace, so it's free to use PyInt* or PyStr* in the future. Don't extend the namespace with aliases to current functions. The naming guidelines we're coming up here are meant to change and adapt as time goes on.

But PyO3 seems have a separate cffi namespace, so it should be fine here.

[encukou]

Should we prefer adding suffixes rather to using a different base name? E.g. should the "fixed" version of PyDict_GetItem be PyDict_GetItemRef or PyDict_FetchItem?

IMO, the suffix is uglier but clearer, and clarity wins that contest.