methods vs fields/members

[idzard-intentdev]

Hey @keithlostracco,
see this discussion more in the gist of me trying to learn to navigate nanobind/touchpy internals.

While creating docstrings I see in several places Python methods defined, which don't have arguments and are read-only.
For instance in choplinkpy.cpp:

chopChannels.doc() = "A container of CHOP channels";
chopChannels.def(nb::init<>())
	.def("num_channels", &ChopChannels::channelCount)
	.def("num_samples", &ChopChannels::valueCount)
	.def("rate", &ChopChannels::rate)
	.def("is_time_dependent", &ChopChannels::isTimeDependent)
	.def("channel_names", &ChopChannels::channelNames, nb::rv_policy::reference_internal);

or these two methods in comppy.cpp

comp.doc() = "A TouchDesigner component loaded in a TouchEngine instance.";
comp.def(nb::init<>())
	....
	.def("loaded",                 &Comp::loaded, nb::rv_policy::reference_internal)
	.def("frame_did_finish",       &Comp::frameDidFinish, nb::rv_policy::reference_internal)

It seems these methods could all be read-only attributes (or 'members' in TouchDesigner docs terminology) which I believe is the same as read-only fields (in nanobind terminology).

So then would it be appropriate for me to change them like this?

	.def_ro("num_channels", &ChopChannels::channelCount)
	.def_ro("num_samples", &ChopChannels::valueCount)
	.def_ro("rate", &ChopChannels::rate)
	.def_ro("is_time_dependent", &ChopChannels::isTimeDependent)
	.def_ro("channel_names", &ChopChannels::channelNames, nb::rv_policy::reference_internal);

[keithlostracco]

Yep those (chopChannels methods) could and probably should be set as read only properties. They can't be fields though since they are binding member methods not member values, so in the cases such as the chop_channels above it would need to be:

.def_prop_ro("num_channels", &ChopChannels::channelCount)
.def_prop_ro("num_samples", &ChopChannels::valueCount)
.def_prop_ro("rate", &ChopChannels::rate)
.def_prop_ro("is_time_dependent", &ChopChannels::isTimeDependent)
.def_prop_ro("channel_names", &ChopChannels::channelNames, nb::rv_policy::reference_internal);

For items like frameDidFinish() in Comp, I'm not sure if it should be a property because of it's nature. Here is a summary of what I found for deciding whether or not a value should be returned as a member/property or a method:

Properties in Python are typically used for values that:

• Represent an intrinsic characteristic of the object (such as size, length, status).
• Don't require significant computation or side effects to retrieve.
• Are not expected to change frequently in the context of a single object state.

Methods, are generally used when:

• The action involves computation or changes the object’s state.
• The value is expected to change frequently or depends on external conditions.
• The action performs a task that is more complex than just retrieving a value.

Based on the above both loaded() and frameDidFinish() fall into the method category (frameDidFinish() changes often, loaded() requires locking a mutex to read shared state value).

All the chopChannels members such as channelNames() and numChannels() could change often but likely will not in most cases and TD has already set the precedent for those values being retrieved as properties.

Note you won't see many fields directly accessed in the main classes in TouchPy (Comp, ChopLink etc...), nearly all fields are private and are only access through there corresponding "get" functions (which don't use the word get. So the private fields:
channeCount_
is accessed with the public function:
channelCount()

You can see in toplinkpy.cpp that there are a few structs such as cudaMemoryDesc that do expose public values and the reason for that is that a struct usually does expose it's member value's publicly and likely has no functionality (methods called explicitly) - like a vec4 for example.

[idzard-intentdev]

Gotcha. I agree with statements when something should be method.

And below is just me learning, but I have some difficulty with mixed up terminology between languages. In your opinion is a nanobind field the same as a Python attribute and also the same as a class 'member' as in the TD docs?

And if that is the case, don't really understand why they must be a property instead of an attribute/field...do you have another hint for me ;-)

[keithlostracco]

Yeah that's something that can definitely be confusing. A field is an attribute, and, a member in TD docs but, an attribute doesn't have to be a field, it can be a function as well (same with member outside of TD docs):

Technically all class "Members" can be values or functions... A function on a class is a member function, a value on a class is member value... Derivative uses the word member in their docs to specify member values (or properites) and method for member functions....

Member values (fields) and member methods are all attributes in Python, member is synonymous with attribute

Field is just another word for member value

A property is a combination of a member value and setter and getter methods to get and set the value. In C++ that value would typically be private and only accessible from outside the class with the setter and getter functions for that value.

Actually I would guess that the majority of TD "members" in the Python docs are actually properties and not fields (member values) since they would likely not be setting values on class directly but using get and set functions.

[idzard-intentdev]

thanks for laying that out. I'll get on it!