Skip to content

gh-119180: Rename parameter to __annotate__ functions#124461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
JelleZijlstra wants to merge 2 commits into from
Closed

gh-119180: Rename parameter to __annotate__ functions #124461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f768678
gh-119180: Rename parameter to __annotate__ functions
JelleZijlstra Sep 24, 2024
06a17db
fix tests
JelleZijlstra Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion Include/internal/pycore_global_objects_fini_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 0 additions & 1 deletion Include/internal/pycore_global_strings.h
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -43,7 +43,6 @@ struct _Py_global_strings {
STRUCT_FOR_STR(defaults, ".defaults")
STRUCT_FOR_STR(dot_locals, ".<locals>")
STRUCT_FOR_STR(empty, "")
STRUCT_FOR_STR(format, ".format")
STRUCT_FOR_STR(generic_base, ".generic_base")
STRUCT_FOR_STR(json_decoder, "json.decoder")
STRUCT_FOR_STR(kwdefaults, ".kwdefaults")
Expand Down
1 change: 0 additions & 1 deletion Include/internal/pycore_runtime_init_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 0 additions & 4 deletions Include/internal/pycore_unicodeobject_generated.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Lib/test/test_pydoc/test_pydoc.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -79,7 +79,7 @@ class A(builtins.object)
class B(builtins.object)
| Methods defined here:
|
| __annotate__(...)
| __annotate__(__format__, /)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
Expand DownExpand Up@@ -180,7 +180,7 @@ class A(builtins.object)

class B(builtins.object)
Methods defined here:
__annotate__(...)
__annotate__(__format__, /)
----------------------------------------------------------------------
Data descriptors defined here:
__dict__
Expand Down
12 changes: 12 additions & 0 deletions Lib/test/test_type_annotations.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
import annotationlib
import inspect
import textwrap
import types
import unittest
Expand DownExpand Up@@ -266,6 +267,17 @@ def check_annotations(self, f):
f.__annotations__ = {"z": 43}
self.assertIs(f.__annotate__, None)

def test_annotate_function_signature(self):
def f(x: int): pass
anno = f.__annotate__
self.assertIsInstance(anno, types.FunctionType)
self.assertEqual(anno.__name__, "__annotate__")

expected_sig = inspect.Signature(
[inspect.Parameter("__format__", inspect.Parameter.POSITIONAL_ONLY)]

@iritkatrieliritkatrielSep 24, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

__format__ is already used in a different context, as a method name. Can this be confusing?

@JelleZijlstraJelleZijlstraSep 24, 2024

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel it's unlikely to cause much confusion, since the name will very rarely show up to users (only if they introspect annotate functions, which is very unlikely to happen), and in a context that doesn't have anything to do with the __format__ method.

@carljmcarljmSep 24, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that we are kind of picking a name out of thin air that we expect not to matter, it seems like we might as well avoid the potential for someone thinking this is related to __format__? Would there be an issue with just using _format? (I don't feel strongly about this at all.)

@JelleZijlstraJelleZijlstraSep 24, 2024

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should use a dundered name because dundered name are reserved to the implementation. Users could use a class named _format in their annotations.

The current PR has this behavior:

>>> def f(x: __format__): pass
... >>> f.__annotations__
{'x': 1}

I think with a dunder name we can handwave that away with "don't do that", but a user could reasonably use the name _format.

Still we could use a different name like __fmt__ or __annotate__ (I think Larry suggested the latter, but that name feels more confusing than __format__).

@carljmcarljmSep 24, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yeah, makes sense why it needs to be a dunder name. Given users should never have to type it, or likely see it, and the main thing we prefer to avoid is collisions with a user parameter, should we actually prefer something longer, like __annotation_format__?

)
self.assertEqual(inspect.signature(anno), expected_sig)


class DeferredEvaluationTests(unittest.TestCase):
def test_function(self):
Expand Down
3 changes: 1 addition & 2 deletions Python/codegen.c
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -655,8 +655,7 @@ codegen_setup_annotations_scope(compiler *c, location loc,
codegen_enter_scope(c, name, COMPILE_SCOPE_ANNOTATIONS,
key, loc.lineno, NULL, &umd));

// if .format != 1: raise NotImplementedError
_Py_DECLARE_STR(format, ".format");
// if __format__ != 1: raise NotImplementedError
ADDOP_I(c, loc, LOAD_FAST, 0);
ADDOP_LOAD_CONST(c, loc, _PyLong_GetOne());
ADDOP_I(c, loc, COMPARE_OP, (Py_NE << 5) | compare_masks[Py_NE]);
Expand Down
5 changes: 2 additions & 3 deletions Python/symtable.c
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1427,12 +1427,11 @@ symtable_enter_block(struct symtable *st, identifier name, _Py_block_ty block,
int result = symtable_enter_existing_block(st, ste);
Py_DECREF(ste);
if (block == AnnotationBlock || block == TypeVariableBlock || block == TypeAliasBlock) {
_Py_DECLARE_STR(format, ".format");
// We need to insert code that reads this "parameter" to the function.
if (!symtable_add_def(st, &_Py_STR(format), DEF_PARAM, loc)) {
if (!symtable_add_def(st, &_Py_ID(__format__), DEF_PARAM, loc)) {
return 0;
}
if (!symtable_add_def(st, &_Py_STR(format), USE, loc)) {
if (!symtable_add_def(st, &_Py_ID(__format__), USE, loc)) {
return 0;
}
}
Expand Down