Mailman 3 May 2019 - docs

[issue35933] python doc does not say that the state kwarg in Pickler.save_reduce can be a tuple (and not only a dict)
by Pierre Glaser 18 May '19

18 May '19

New submission from Pierre Glaser <pierreglaser(a)msn.com>: Hello all, This 16-year old commit (*) allows an object's state to be updated using its slots instead of its __dict__ at unpickling time. To use this functionality, the state keyword-argument of Pickler.save_reduce (which maps to the third item of the tuple returned by __reduce__) should be a length-2 tuple. As far as I can tell, this is not mentioned in the documentation (**). I suggest having the docs updated. What do you think? (*) https://github.com/python/cpython/commit/ac5b5d2e8b849c499d323b0263ace22e56… (**) https://docs.python.org/3.8/library/pickle.html#object.__reduce__ ---------- assignee: docs@python components: Documentation messages: 335031 nosy: alexandre.vassalotti, docs@python, pierreglaser, pitrou, serhiy.storchaka priority: normal severity: normal status: open title: python doc does not say that the state kwarg in Pickler.save_reduce can be a tuple (and not only a dict) versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35933> _______________________________________

4 16

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Josh Rosenberg 18 May '19

18 May '19

Josh Rosenberg <shadowranger+python(a)gmail.com> added the comment: Ah, you're right on __call__; I've never bothered to override it on a metaclass, but yes, since a class using a metaclass is an instance of the metaclass, like all instances, calling it invokes the __call__ of its type (it's just that the default metaclass, type, has a __call__ that turns around and calls the __new__ and __init__ of the "instance", which is a class). The nomenclature is hard here. In any event, yes, overriding __call__ will let you hook into the construction of each individual instance of the classes using the metaclass. That's not generally true of all uses of metaclasses (if __call__ is inherited from type, then while new instances are technically created using the metaclass, the metaclass is just letting the normal __new__/__init__ calls take place without interference). There is very little in the way of Python official documentation on metaclasses; the line you proposed to change is one of the few places it's mentioned (most references to metaclasses are on that Data Model page). There are a couple of mentions in the PEPs, and a lot of off-site tutorials, but it's a poorly documented feature in general. It's pretty easy to demonstrate the current wording is correct though: >>> class Meta(type): ... pass ... >>> class MyMeta(metaclass=Meta): ... pass ... >>> isinstance(MyMeta, Meta) True Note that we're using isinstance, not issubclass, and we're not constructing a MyMeta instance. MyMeta itself is an instance of Meta. I really think the problem here is that the documentation is correct, but so bare it's easy to miss the implications of "MyClass and MySubclass are instances of Meta"; since the classes are instances of another class, the metaclass has the same power over them that normal classes have over their instances. That's why __call__ can hook the creation of instances, __new__ can hook the creation of the class itself, __getitem__ can be used to perform lookups on the child class (in at least of the few iterations of the typing framework, that's how List[int] and the like worked; not sure if it's still that way), and properties defined on the metaclass can be accessed on classes that use it, but not their instances. It's enormously powerful, but so complex that the Python docs tend to encourage simpler, more targeted ways of tweaking classes (e.g. decorators). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36908] "This module is always available" is confusing
by Ned Batchelder 17 May '19

17 May '19

New submission from Ned Batchelder <ned(a)nedbatchelder.com>: The math and cmath modules say this in their docs: "This module is always available." This lead a beginner to believe they didn't need to be imported. Nearly the entire standard library is always available in this sense (they can be imported). This sentence isn't useful. Can we change the first paragraph of the math module to be: "This module provides access to the mathematical functions defined by the C standard." (and similarly for the cmath module.) ---------- assignee: docs@python components: Documentation messages: 342386 nosy: docs@python, nedbat priority: normal severity: normal status: open title: "This module is always available" is confusing _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36908> _______________________________________

5 12

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Nicholas Matthews 17 May '19

17 May '19

Nicholas Matthews <nmatthews(a)asapp.com> added the comment: Thanks for the clarification. For the first point on the correctness of the original text, that makes sense, could you link me to any relevant documentation for further reading? On the second point "Meta modifies the creation of the classes themselves, not instances of the classes." I think this is not 100% correct. When you create an instance of a class via "instance = MyClass()", the `__call__` method of the metaclass is invoked, so metaclasses can control both class definition and instance creation. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Josh Rosenberg 17 May '19

17 May '19

Josh Rosenberg <shadowranger+python(a)gmail.com> added the comment: Clarification is fine, but "MyClass and MySubclass are instances of Meta:" is 100% true. Declaring a class to have a metaclass (or inheriting from a class with a metaclass) means that the class itself is an instance of the metaclass. New instances of the classes with metaclass Meta are not "created using Meta"; Meta modifies the creation of the classes themselves, not instances of the classes. Point is, your suggested change is half wrong (new instances of MyClass and MySubclass aren't directly created using Meta), and half misunderstanding the current documentation ("MyClass is an instance of Meta" already means "MyClass has the metaclass Meta"). ---------- nosy: +josh.r _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Nicholas Matthews 17 May '19

17 May '19

Nicholas Matthews <nmatthews(a)asapp.com> added the comment: Ok, I will create a PR soon and update the issue. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Stéphane Wirtel 17 May '19

17 May '19

Stéphane Wirtel <stephane(a)wirtel.be> added the comment: If you want to modify the text, please create a PR for this file: https://github.com/python/cpython/blob/master/Doc/reference/datamodel.rst#m… Don't forget to sign the CLA, Thank you ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Stéphane Wirtel 17 May '19

17 May '19

Stéphane Wirtel <stephane(a)wirtel.be> added the comment: Found here: https://docs.python.org/3/reference/datamodel.html#metaclasses Thank you ---------- status: pending -> open _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Stéphane Wirtel 17 May '19

17 May '19

Stéphane Wirtel <stephane(a)wirtel.be> added the comment: just one question, I don't find the paragraph with this text in the code. Could you share the link of this paragraph? Thank you ---------- status: open -> pending _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0

[issue36947] [Good first issue] Fix 3.3.3.1 Metaclasses Documentation
by Stéphane Wirtel 17 May '19

17 May '19

Change by Stéphane Wirtel <stephane(a)wirtel.be>: ---------- keywords: +easy title: Fix 3.3.3.1 Metaclasses Documentation -> [Good first issue] Fix 3.3.3.1 Metaclasses Documentation _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36947> _______________________________________

1 0