About PyDoc_VAR should be changed to be invisible

Core Development C API
1

It seems that PyDoc_VAR is rarely used directly in the CPython repository, for example:

PyDoc_VAR(sample_doc);
sample_doc = PyDoc_STR("...");

However, most instances seem to use PyDoc_STRVAR(sample_doc, "...");
So, I think PyDoc_VAR might be better off being made invisible, like _PyDoc_VAR, rather than being part of the public interface.

This is my first post, let me know if you see any formatting mistakes. thanks.

2

It is part of the public API and is used by third party code. That means we can’t just change or remove the API.

1 Like
3

Thanks for the help.

4

Did you encounter some issue with the name? For example, does it conflict with a name from another library that makes it hard to use in the same project as Python?

In general, we like changes to be motivated by things outside of “code cleaning” or refactoring. So if there’s a reason to change it, you should definitely say so.

2 Likes
5

Maybe not. I think it seems to exist just to simplify macros. And as I mentioned before, there doesn’t appear to be any direct use of it throughout the codebase. Perhaps it could be turned into an internal API instead of being public.

6

But as you point out, it’s barely used internally. Which means it only exists for public API - making it internal would break users, and wouldn’t benefit us at all because we barely use it.

Do you see how this suggestion seems like the opposite of what the evidence shows? That’s why I ask if you have some other reason, because I assume you’re logical and believe that making it internal would be a good idea, but the reasoning you are showing doesn’t show that. Maybe it’s just confusion (which is okay :slight_smile: happens to us all), but if you’ve got a real reason then I want to make sure we get to hear it and don’t miss out.

7

It seems that my description was incorrect. The code snippet I presented earlier is an exception, as the entire codebase does not use that approach but instead directly uses PyDoc_VARSTR. However, as you mentioned, there might be other users who rely on the redundant method I described, meaning they do not use PyDoc_VARSTR. In that case, I will retract my statement(Perhaps users employ the writing method I mentioned and rely on it heavily. Well, there doesn’t seem to be an issue with that).

Since the codebase extensively uses PyDoc_STRVAR and does not use the redundant method I mentioned, I believe for the codebase it should be privatized (maybe users also do not use the redundant method I mentioned and thus use PyDoc_STRVAR, but this can no longer be proven)