Document how to make classes in the C API.

[AraHaan]

BPO	30390
Nosy	@serhiy-storchaka, @AraHaan

^{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 = <Date 2017-05-17.20:05:35.991>
created_at = <Date 2017-05-17.17:56:45.313>
labels = ['extension-modules', '3.7', 'invalid', 'docs']
title = 'Document how to make classes in the C API.'
updated_at = <Date 2017-05-17.20:05:35.989>
user = 'https://github.com/AraHaan'

bugs.python.org fields:

activity = <Date 2017-05-17.20:05:35.989>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-05-17.20:05:35.991>
closer = 'serhiy.storchaka'
components = ['Documentation', 'Extension Modules']
creation = <Date 2017-05-17.17:56:45.313>
creator = 'Decorater'
dependencies = []
files = []
hgrepos = []
issue_num = 30390
keywords = []
message_count = 5.0
messages = ['293863', '293864', '293865', '293880', '293884']
nosy_count = 3.0
nosy_names = ['docs@python', 'serhiy.storchaka', 'Decorater']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue30390'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[AraHaan]

On the C API, it tells how to make modules, functions, variables, and other things, but what about classes?

Like for example if you wanted to make a class with all of the methods having to use direct C Code which would then be converted to PyObject *'s for returning the information the C Code would normally return.

Not only that but also being able to create class instance variables using the C API as well.

Like for example here is an example class (As it would be if it was written in python):

class Example:
    def __init__(self):
        self.data = None  # None being a place holder for now.

    def somefunction(self):
        # C Code here.
        self.data = ret  # return value for the C Code.
        return self.data

Yes, there are better ways than writing the return data to the instance variable and returning it. That is just an example, I have classes that uses them for other things that does not return anything making the instance variables be the only way to get the data.

But yeah long story short I think creating classes with the C API should be documented if not already, or at least an example of doing one to be added as an guide for others wondering how to use the C API to make their own (non exception) classes.

[AraHaan]

Hmm seems that when looking at the exports in python36.dll that the following functions seem to not be documented as far as I seen:

PyClassMethodDescr_Type
PyClassMethod_New
PyClassMethod_Type

There might be more functions dealing with classes that are not documented. However looking through the whole exports would take to long as there are so many.

[serhiy-storchaka]

This is documented. See https://docs.python.org/3/extending/newtypes.html.

[AraHaan]

Still it does look the functions lited in the second comment are undocumented.

https://docs.python.org/3/search.html?q=PyClassMethodDescr_Type
https://docs.python.org/3/search.html?q=PyClassMethod_New&check_keywords=yes&area=default

However on the last function I did find 1 thing However it was not what I was looking for. What I actually was looking for was the args for the 3 functions and description on what it does and all that similar to how this function is documented:

PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
Return value: New reference.
Call a callable Python object callable_object, with arguments given by the tuple args. If no arguments are needed, then args may be NULL. Returns the result of the call on success, or NULL on failure. This is the equivalent of the Python expression callable_object(*args).

This is actually the reason why the issue was opened as the functions was not documented like this.

[serhiy-storchaka]

The title of this issue is "Document how to make classes in the C API." This already is documented.

For documenting the PyClassMethod* names open a new issue.