PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute #112133

vstinner · 2023-11-15T22:42:14Z

Add PyType_GetFullyQualName() function with documentation and tests.

Issue: PEP 737: PyUnicode_FromFormat(): Add %T format to format the type name of an object #111696

📚 Documentation preview 📚: https://cpython-previews--112133.org.readthedocs.build/

vstinner · 2023-11-16T02:02:17Z

Existing logic to format a type name as type.__fullyqualname__ does.

I found a lot of code like:

name = "%s.%s" % (obj.__module__, obj.__qualname__)
__repr__() method: cls = self.__class__; return f"<{cls.__module__}.{cls.__qualname__} at ...}"

traceback: only code that I found which treats the __main__ module differently:

        stype = self.exc_type.__qualname__
        smod = self.exc_type.__module__
        if smod not in ("__main__", "builtins"):
            if not isinstance(smod, str):
                smod = "<unknown>"
            stype = smod + '.' + stype

_collections_abc: _type_repr() function

def _type_repr(obj):
    ...
    if isinstance(obj, type):
        if obj.__module__ == 'builtins':
            return obj.__qualname__
        return f'{obj.__module__}.{obj.__qualname__}'
    ...

inspect: omit base_module if specified

def formatannotation(annotation, base_module=None):
    ...
    if isinstance(annotation, type):
        if annotation.__module__ in ('builtins', base_module):
            return annotation.__qualname__
        return annotation.__module__+'.'+annotation.__qualname__
    ...

unittest:

def strclass(cls):
    return "%s.%s" % (cls.__module__, cls.__qualname__)

vstinner · 2023-11-16T02:13:43Z

I added a second commit using the new type.__fullyqualname__ attribute in the stdlib to show how it can be used. Even if the attribute is not used to add new "%T" and "%#T" formats to PyUnicode_FromFormat(), this change is useful.

gvanrossum · 2023-11-16T04:12:33Z

Doc/c-api/type.rst

@@ -185,6 +185,13 @@ Type Objects

   .. versionadded:: 3.11

+.. c:function:: PyObject* PyType_GetFullyQualName(PyTypeObject *type)


Why can't it just be GetFullyQualifiedName?

We already have a PyType_GetQualName() function which returns type.__qualname__: https://docs.python.org/dev/c-api/type.html#c.PyType_GetQualName

I followed the PyType_GetQualName() name: PyType_GetFullyQualName() returns type.__fullyqualname__.

I know that, but it still tickles my grammar bone. :-(

Ok, I renamed the function to PyType_GetFullyQualifiedName().

I prefer to keep __fullyqualname__ for the attribute name. We already have __qualname__. And since it's commonly used, I prefer to make it short.

An alternative is to use FQN acronym :-D

type.__fqn__

PyType_GetFQN()

But I prefer "longer" names, so I don't need to check the doc to know what they mean ;-)

On the Internet, Domain Name Service (DNS) use FQDN: Fully Qualified Domain Name :-)

I share Guido's unease with "fullyqualname": it sounds wrong to have the abbreviated "qual" between two unabbreviated words.

For comparison:

Several dunders, including some of the most recently added ones, include an underscore in the word: __class_getitem__, __release_buffer__, __type_params__, __init_subclass__, __text_signature__

Other dunders include multiple words, often abbreviated, without underscores: __getnewargs__, __kwdefaults__, __isabstractmethod__

I would prefer __fully_qualified_name__. It's on the long side, but it matches the current name for the concept (mentioned in https://docs.python.org/3.12/glossary.html#term-qualified-name). __fqn__ seems too cryptic.

I concur with Jelle.

Ok, I renamed the attribute to __fully_qualified_name__. Does it look better to you?

It's on the long side, but it matches the current name for the concept (mentioned in https://docs.python.org/3.12/glossary.html#term-qualified-name). fqn seems too cryptic.

I agree with you.

Add PyType_GetFullyQualifiedName() function with documentation and tests.

gvanrossum · 2023-11-16T04:42:34Z

Naming is hard. Taking care of myself is harder. I have a lot going on at the moment and I really would prefer not to be responsible for this particular naming decision. Hopefully one or more of the other reviewers can help instead.

encukou · 2023-11-16T08:55:47Z

IMO, this should use something more customizable than an attribute. A format() directive for example.

malemburg · 2023-11-16T09:37:43Z

Modules/_testcapimodule.c

@@ -573,19 +573,19 @@ static PyObject *
 test_get_type_name(PyObject *self, PyObject *Py_UNUSED(ignored))
 {
    PyObject *tp_name = PyType_GetName(&PyLong_Type);
-    assert(strcmp(PyUnicode_AsUTF8(tp_name), "int") == 0);
+    assert(PyUnicode_EqualToUTF8(tp_name, "int"));


Even though it's still useful, this has nothing to do with the PR title and should go into a separate PR.

It's related, I changed the 3 tests which check the 3 C functions to get a "type name". I prefer to make the code consistent to make it easier to maintain.

This change also fix a bug: caller must check if PyUnicode_AsUTF8() is NULL. PyUnicode_EqualToUTF8() doesn't have this problem.

malemburg · 2023-11-16T09:38:22Z

Lib/typing.py

-        if obj.__module__ == 'builtins':
-            return obj.__qualname__
-        return f'{obj.__module__}.{obj.__qualname__}'
+        return obj.__fullyqualname__


You are changing the contract for the method here. This may result in breaking code relying on previous behavior.

I think that you misunderstood the API of this attribute. Please check its documentation in Doc/library/stdtypes.rst, or just try my PR.

malemburg

Functional changes should not go into this PR.

malemburg · 2023-11-16T09:40:35Z

Objects/typeobject.c

-        rtn = PyUnicode_FromFormat("<class '%s'>", type->tp_name);
-
-    Py_XDECREF(mod);
+    PyObject *result = PyUnicode_FromFormat("<class '%U'>", name);


Same comment as above: you are readding "builtins." to builtin types.

The fully qualified name omits the module if the module is "builtins". There is no behavior change. This code has multiple tests. I'm not sure that I get your comment correctly.

As you can see from the code, the "builtins." part was deliberately omitted for builtin types.

I'm not sure of what you are talking about. You are commenting type_repr() function. I didn't change the function output, it's the same:

>>> import builtins >>> print(repr(builtins.str)) # <=== HERE "builtins." is omitted <class 'str'> >>> builtins.str.__module__ 'builtins' >>> builtins.str.__qualname__ 'str'

repr() omits the module if it's "builtins". But it's added otherwise:

>>> import collections >>> print(repr(collections.OrderedDict)) <class 'collections.OrderedDict'> >>> collections.OrderedDict.__module__ 'collections' >>> collections.OrderedDict.__qualname__ 'OrderedDict'

It's the same behavior than before.

vstinner · 2023-11-16T13:50:29Z

@gvanrossum:

Naming is hard. Taking care of myself is harder.

He he, I totally get it and it's perfectly fine. Take care.

vstinner · 2023-11-16T13:59:28Z

@encukou:

IMO, this should use something more customizable than an attribute. A format() directive for example.

This change is not exclusive with extending type.__format__() to get new formats. Moreover, if we add a format to get the fully qualified name of a type, I would prefer to have a more "regular" way to get it instead of having to go through formatting.

unittest example from this PR:

def strclass(cls): return "%s.%s" % (cls.__module__, cls.__qualname__)

is replaced with:

def strclass(cls): return cls.__fully_qualified_name__

I like the ability to get an attribute rather than having to build a f-string for that.

Adding new formats to format a type name in Python has been discussed in length. Most recent to oldest discussions:

Problems:

I'm not convinced that there is a strong need for formats other than type.__name__ and type.__fully_qualified_name__. I prefer to get an attribute easy to read and understand without having to check the documentation, rather than using a single letter format such as {type|T}
So far, I didn't see a clear consensus on an API for such formatting.

So my plan is now to add type.__fully_qualified_name__ attribute, add %T (type.__name__) and %#T (type.__fully_qualified_name__) to PyUnicode_FromFormat() in C, use these new APIs, and then see if more APIs should be added.

encukou · 2023-11-16T15:15:34Z

Adding new formats to format a type name in Python has been discussed in length.

Yes. Did any of those discussions reach consensus on adding __fully_qualified_name__ with this implementation?

Doc/library/stdtypes.rst

Lib/test/test_builtin.py

Modules/_testcapimodule.c

JelleZijlstra · 2023-11-17T16:10:14Z

Objects/typeobject.c

+PyObject *
+PyType_GetFullyQualifiedName(PyTypeObject *type)
+{
+    return type_get_fullyqualname(type, NULL);


Suggested change

return type_get_fullyqualname(type, NULL);

return type_fullyqualname(type, 0);

No need to call the intermediate function

I reorganized the calls. The special function with int is_repr parameter now gets a _impl suffix. The getter losts get_ in its name to look alike type_name() and type_qualname() getters. It now calls PyType_GetFullyQualifiedName(). Does it look better to you?

…me()

vstinner · 2023-11-17T21:52:59Z

@JelleZijlstra: Please review the updated PR. I tried to address all comments of your latest review.

vstinner · 2023-11-29T13:30:43Z

I wrote PEP 737 – Unify type name formatting for these changes: see the PEP discussion.

AlexWaygood · 2023-11-29T13:33:59Z

I wrote PEP 737 – Unify type name formatting for these changes: see the PEP discussion.

Thanks for taking the time to write a PEP. I think it's important that changes to builtin classes like this go through the PEP process :-)

vstinner · 2023-12-20T10:56:40Z

PEP 737 changed the API since this PR was created. I close this PR for now and will create a new one (or maybe reopen this PR) since PEP 737 will be approved.

vstinner · 2024-03-14T14:01:21Z

The Steering Council rejected the type.__fully_qualified_name__ attribute: see https://peps.python.org/pep-0737/#id1 for details. Thomas wrote: "I think the SC could be persuaded given some concrete use-cases."

vstinner requested a review from markshannon as a code owner November 15, 2023 22:42

bedevere-app bot added the awaiting core review label Nov 15, 2023

bedevere-app bot mentioned this pull request Nov 15, 2023

PEP 737: PyUnicode_FromFormat(): Add %T format to format the type name of an object #111696

Closed

vstinner force-pushed the type_fullyqualname branch from 498a4d6 to f9a8c31 Compare November 15, 2023 22:44

vstinner requested review from gvanrossum, JelleZijlstra, AlexWaygood, rhettinger, brettcannon, ericsnowcurrently, ncoghlan, warsaw, iritkatriel and 1st1 as code owners November 16, 2023 02:12

gvanrossum reviewed Nov 16, 2023

View reviewed changes

vstinner added 2 commits November 16, 2023 05:34

pythongh-111696: Add type.__fullyqualname__ attribute

d5e8a37

Add PyType_GetFullyQualifiedName() function with documentation and tests.

Use type.__fullyqualname__ attribute

82dd956

vstinner force-pushed the type_fullyqualname branch from 19c3bf6 to 82dd956 Compare November 16, 2023 04:35

malemburg reviewed Nov 16, 2023

View reviewed changes

Rename the attribute to __fully_qualified_name__

76dcfd5

vstinner changed the title ~~gh-111696: Add type.__fullyqualname__ attribute~~ gh-111696: Add type.__fully_qualified_name__ attribute Nov 16, 2023

JelleZijlstra reviewed Nov 17, 2023

View reviewed changes

Doc: Add "fully qualified name" term to the glossary

36cf2a9

vstinner requested review from a team and vsajip as code owners November 17, 2023 21:35

vstinner added 3 commits November 17, 2023 22:44

Add tests on more types: built-in and types

266a8e5

Fix PyType_FromSpec() error handling

e63c937

type.__fully_qualified_name__ getter calls PyType_GetFullyQualifiedNa…

c79c519

…me()

Fix typo in the doc

46fb6df

rhettinger removed their request for review November 23, 2023 19:44

vstinner changed the title ~~gh-111696: Add type.__fully_qualified_name__ attribute~~ PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute Dec 1, 2023

AlexWaygood removed their request for review December 13, 2023 12:52

vstinner closed this Dec 20, 2023

vstinner deleted the type_fullyqualname branch December 20, 2023 10:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute #112133

PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute #112133

vstinner commented Nov 15, 2023 •

edited by github-actions bot

Loading

vstinner commented Nov 16, 2023

vstinner commented Nov 16, 2023

gvanrossum Nov 16, 2023

vstinner Nov 16, 2023

gvanrossum Nov 16, 2023

vstinner Nov 16, 2023

JelleZijlstra Nov 16, 2023

AlexWaygood Nov 16, 2023

vstinner Nov 16, 2023

gvanrossum commented Nov 16, 2023

encukou commented Nov 16, 2023

malemburg Nov 16, 2023

vstinner Nov 16, 2023

malemburg Nov 16, 2023

vstinner Nov 16, 2023

malemburg left a comment

malemburg Nov 16, 2023

vstinner Nov 16, 2023 •

edited

Loading

malemburg Nov 16, 2023

vstinner Nov 16, 2023

vstinner commented Nov 16, 2023

vstinner commented Nov 16, 2023

encukou commented Nov 16, 2023

JelleZijlstra Nov 17, 2023

vstinner Nov 17, 2023

vstinner commented Nov 17, 2023

vstinner commented Nov 29, 2023

AlexWaygood commented Nov 29, 2023

vstinner commented Dec 20, 2023

vstinner commented Mar 14, 2024

		@@ -185,6 +185,13 @@ Type Objects

		.. versionadded:: 3.11

		.. c:function:: PyObject* PyType_GetFullyQualName(PyTypeObject *type)

	return type_get_fullyqualname(type, NULL);
	return type_fullyqualname(type, 0);

PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute #112133

PEP 737: gh-111696: Add type.__fully_qualified_name__ attribute #112133

Conversation

vstinner commented Nov 15, 2023 • edited by github-actions bot Loading

vstinner commented Nov 16, 2023

vstinner commented Nov 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum commented Nov 16, 2023

encukou commented Nov 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

malemburg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vstinner Nov 16, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vstinner commented Nov 16, 2023

vstinner commented Nov 16, 2023

encukou commented Nov 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vstinner commented Nov 17, 2023

vstinner commented Nov 29, 2023

AlexWaygood commented Nov 29, 2023

vstinner commented Dec 20, 2023

vstinner commented Mar 14, 2024

vstinner commented Nov 15, 2023 •

edited by github-actions bot

Loading

vstinner Nov 16, 2023 •

edited

Loading