Re: [Python-Dev] One-line abstractmethod function?
On Fri, Dec 06, 2013 at 07:28:57AM +0100, Gregory Salvan wrote:
> Hi,
> maybe a syntax like that can correspond:
>
> class MyObject(metaclass=ObjectSpec):
> ''' MyObject doc'''
> 'attr1 contains something'
> attr1 = None
> 'attr2 contains something'
> attr2 = str
> 'method1 do something'
> method1 = NotImplementedMethod('self', 'arg1', kwarg1=str)
I really don't like the idea of extending the docstring syntax to
arbitrary objects. Docstrings are just the right amount of magic to be
useful, without being so much as to be confusing. If you extend them to
arbitrary objects, that crosses the line. I really don't like the look
of the above, I'd rather see:
class MyObject(metaclass=ObjectSpec):
''' MyObject doc
attr1 contains something
attr2 contains something
'''
attr1 = None
attr2 = str
@NotImplementedMethod
def method1(self, arg1, kwarg1=str):
'''method1 do something'''
One-liners are over-rated, especially since there isn't that much that
you can fit in 80 or even 100 chars on a single line. Toy examples,
like "method1 do something", sure. But real methods that do real things?
Not so often.
Besides, this suggestion changes the semantics of code, and therefore
would need to go through a "from __future__ import docstring_everywhere"
phase. Currently, bare strings can be used for multiline comments, as
the compiler discards them at compile-time:
fe()
fi()
fo()
fum()
"""At this point, we can smell the blood of any Englishmen in the
vicinity."""
bread = grind_bones(englishman)
Another issue is that many objects (particularly built-ins) cannot take
additional attributes. So where are you going to attach the docstrings?
What are you going to do with singletons like None?
"Amount of spam."""
spam = None
"Amount of eggs."""
eggs = None
print(spam.__doc__)
=> 'Amount of eggs.'
> Metaclass "ObjectSpec" would extend ABCMeta to search class source code for
> comments before members assignement,
What do you expect to happen when the source code is not available?
The behaviour of code should not depend on whether it is pre-compiled or
not.
--
Steven
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] One-line abstractmethod function?
We might adopt the conventions promoted by the Sphinx autodoc extension: http://sphinx-doc.org/ext/autodoc.html#directive-autofunction Example: class Foo: """Docstring for class Foo.""" #: Doc comment for class attribute Foo.bar. #: It can have multiple lines. bar = 1 flox = 1.5 #: Doc comment for Foo.flox. One line only. baz = 2 """Docstring for class attribute Foo.baz.""" def __init__(self): #: Doc comment for instance attribute qux. self.qux = 3 self.spam = 4 """Docstring for instance attribute spam.""" -- --Guido van Rossum (python.org/~guido) ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Summary of Python tracker Issues
ACTIVITY SUMMARY (2013-11-29 - 2013-12-06) Python tracker at http://bugs.python.org/ To view or respond to any of the issues listed below, click on the issue. Do NOT respond to this message. Issues counts and deltas: open4323 ( +6) closed 27359 (+70) total 31682 (+76) Open issues with patches: 1982 Issues opened (56) == #10717: Multiprocessing module cannot call instance methods across pro http://bugs.python.org/issue10717 reopened by alexandre.vassalotti #16549: regression: -m json.tool module is broken http://bugs.python.org/issue16549 reopened by Arfrever #19835: Add a MemoryError singleton to fix an unlimited loop when the http://bugs.python.org/issue19835 opened by haypo #19837: Wire protocol encoding for the JSON module http://bugs.python.org/issue19837 opened by ncoghlan #19838: test.test_pathlib.PosixPathTest.test_touch_common fails on Fre http://bugs.python.org/issue19838 opened by Claudiu.Popa #19840: The is no way to tell shutil.move to ignore metadata http://bugs.python.org/issue19840 opened by zodalahtathi #19841: ConfigParser PEP issues http://bugs.python.org/issue19841 opened by Ivailo.Monev #19843: Wait for multiple sub-processes to terminate http://bugs.python.org/issue19843 opened by giampaolo.rodola #19846: print() and write() are relying on sys.getfilesystemencoding() http://bugs.python.org/issue19846 opened by Sworddragon #19847: Setting the default filesystem-encoding http://bugs.python.org/issue19847 opened by Sworddragon #19851: imp.reload problem with submodule http://bugs.python.org/issue19851 opened by ronaldoussoren #19855: uuid._find_mac fails if an executable not in /sbin or /usr/sbi http://bugs.python.org/issue19855 opened by serhiy.storchaka #19856: Possible bug in shutil.move() on Windows http://bugs.python.org/issue19856 opened by serhiy.storchaka #19857: test_imaplib doesn't always reap SocketServer thread http://bugs.python.org/issue19857 opened by neologix #19858: Make pickletools.optimize aware of the MEMOIZE opcode. http://bugs.python.org/issue19858 opened by alexandre.vassalotti #19861: Update What's New for Python 3.4 http://bugs.python.org/issue19861 opened by serhiy.storchaka #19862: Unclear xpath caching for custom namespaces http://bugs.python.org/issue19862 opened by valeriy.nov #19863: Missing function attributes in 2.7 docs. http://bugs.python.org/issue19863 opened by mark.dickinson #19864: multiprocessing Proxy docs need locking semantics explained http://bugs.python.org/issue19864 opened by maxpolk #19865: create_unicode_buffer() fails on non-BMP strings on Windows http://bugs.python.org/issue19865 opened by gergely.erdelyi #19866: tests aifc, sunau and wave failures on a fresh Win64 installat http://bugs.python.org/issue19866 opened by francismb #19867: pickletools.OpcodeInfo.code is a string http://bugs.python.org/issue19867 opened by pitrou #19869: BaseCookie does not complain if a non RFC compliant cookie hea http://bugs.python.org/issue19869 opened by florianpilz #19870: Backport Cookie fix to 2.7 (httponly / secure flag) http://bugs.python.org/issue19870 opened by florianpilz #19871: json module won't parse a float that starts with a decimal poi http://bugs.python.org/issue19871 opened by picomancer #19873: There is a duplicate function in Lib/test/test_pathlib.py http://bugs.python.org/issue19873 opened by vajrasky #19875: test_getsockaddrarg occasional failure http://bugs.python.org/issue19875 opened by pitrou #19876: selectors (and asyncio?): document behaviour on closed files/s http://bugs.python.org/issue19876 opened by haypo #19878: bz2.BZ2File.__init__() cannot be called twice with non-existen http://bugs.python.org/issue19878 opened by Level #19879: imageop: bug in error handler http://bugs.python.org/issue19879 opened by Level #19880: unittest: on failure, TestCase.run() keeps a reference to the http://bugs.python.org/issue19880 opened by haypo #19883: Integer overflow in zipimport.c http://bugs.python.org/issue19883 opened by christian.heimes #19884: Importing readline produces erroneous output http://bugs.python.org/issue19884 opened by bkabrda #19885: lzma segfault when __init__ with non-existent file after execu http://bugs.python.org/issue19885 opened by vajrasky #19886: Better estimated memory requirements for bigmem tests http://bugs.python.org/issue19886 opened by serhiy.storchaka #19887: Path.resolve() ENAMETOOLONG on pathologic symlinks http://bugs.python.org/issue19887 opened by serhiy.storchaka #19888: Three argument type() super call sets __name__ but not __qualn http://bugs.python.org/issue19888 opened by zkrynicki #19890: Typo in multiprocessing docs http://bugs.python.org/issue19890 opened by Antony.Lee #19891: Exiting Python REPL prompt with user without home directory th http://bugs.python.org/issue19891 opened by vajrasky #19893: Python cApi memory problem. Py_Initialize memory leak http://bugs.python.org/issu
Re: [Python-Dev] One-line abstractmethod function?
On 12/6/2013 5:46 AM, Steven D'Aprano wrote:
On Fri, Dec 06, 2013 at 07:28:57AM +0100, Gregory Salvan wrote:
class MyObject(metaclass=ObjectSpec):
''' MyObject doc'''
'attr1 contains something'
attr1 = None
'attr2 contains something'
attr2 = str
'method1 do something'
method1 = NotImplementedMethod('self', 'arg1', kwarg1=str)
I really don't like the idea of extending the docstring syntax to
arbitrary objects.
> ...
Another issue is that many objects (particularly built-ins) cannot take
additional attributes. So where are you going to attach the docstrings?
For data attributes, which are usually mutable, it should be attached to
the attribute *concept*, which is represented by the name, rather than
the current but usually changeable value. Values are usually already
documented either by a value representation or a docstring. This could
be done with a string subclass that is used as needed.
For methods, the value is nearly always constant. When multiple methods
share the same function, they usually also share the same name, and
represent the same concept.
A half-way measure would be to extend help() (pydoc, I guess) to
recognize the same attribute comment conventions as Sphinx autodoc when
source is available, as it usually is. If we do this, I think the
conventions should be 'blessed' in an info pep. Docstrings are seldom
needed for runtime execution, which is why we have an option to remove them.
--
Terry Jan Reedy
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Attribute docstrings [was: One-line abstractmethod function?]
Reply-To set to python-id...@python.org. Terry Reedy writes: > For data attributes, which are usually mutable, it should be attached to > the attribute *concept*, which is represented by the name, rather than > the current but usually changeable value. Values are usually already > documented either by a value representation or a docstring. This could > be done with a string subclass that is used as needed. > > For methods, the value is nearly always constant. When multiple methods > share the same function, they usually also share the same name, and > represent the same concept. Aside: Properties are which? Data, or method? It's also not clear to me that "def first (self): return self.values[0]" is unlikely to be used for completely different purposes than getting the head of a list. I conclude the considerations above are mostly red herrings. The important thing, I suppose, is that the names of attributes defined in a class are not mutable. This means that their docstrings can be kept in a completely separate dict (or other string -> string mapping), which could even be stored in a separate file. (Emacs Lisp uses this to good effect. The DOC file for XEmacs is 1.6MB; for GNU Emacs it's 2.4MB.) Of course it has its problems, but they're pretty minor. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
