docstring

I know the triple quote strings are used as docstrings, but is there a real need to have two string literals? Are there any use case when identifying between single-line & multi-line is useful. in Clojure we have 1 string literal, is multi-line and we use it as docstring. So why the difference in python? The advantage of having to be explicit about creating a multi-line string literal is probably best demonstrated with an example: with open("filename.ext) as f: for line in f: print(line.upper()) Of course, any decent syntax-highlighting editor will catch that, but: It isn't always the case

I'm using Sphinx to document a Python project. There seems to be a bit of inconsistency with the .. csv-table:: directive. The main issue is a new line in a cell. And my questionable mental health. The following code: .. csv-table:: :header: Header1, Header2, Header3 A, B, "These lines appear as one line, even though they are written in two lines." C, D, "| These lines appear as two lines, | but they are indented, and my OCD will simply not allow it." E, F, "| If I continue this line in another line, it will appear in a new line." G, H, "If there is a blank line between the two lines, there

I would like to set the func_doc (as an expression) within def . def f(): '''My function help''' #Set the docstring def g(): "My function " + "help" # An expression, so not read as a docstring # can I put something here to set the docstring as an expression? g.func_doc # is None g.func_doc = "My function " + "help" # This works Is this possible? (two reasons I can think for doing this: importing a function from a module (and you want to import the docstring too) and using a lexer .) You can't do that, since only a string literal is recognized as a docstring. But you can use a decorator to set

I have a descriptor that turns a method into a property on the class level: class classproperty(object): def __init__(self, getter): self.getter = getter self.__doc__ = getter.__doc__ def __get__(self, instance, owner): return self.getter(owner) Used like this: class A(object): @classproperty def test(cls): "docstring" return "Test" However, I now can't access the __doc__ attribute (which is logical, because accessing A.test.__doc__ will fetch the __doc__ of str , because A.test already returns "Test" . My final goal is that my docstring will appear in sphinx, so it is not feasible to retrieve

I have Python classes with object attributes which are only declared as part of running the constructor, like so: class Foo(object): def __init__(self, base): self.basepath = base temp = [] for run in os.listdir(self.basepath): if self.foo(run): temp.append(run) self.availableruns = tuple(sorted(temp)) If I now use either help(Foo) or attempt to document Foo in Sphinx, the self.basepath and self.availableruns attributes are not shown. That's a problem for users of our API. I've tried searching for a standard way to ensure that these "dynamically declared" attributes can be found (and

I was just wondering what is the difference between two ways of writing Python Docstrings ( __doc__ ): three single quotes: ''' Comment goes here ''' three double quotes: """ Comment goes here """ Is there any subtle difference in the way doc string could be formatted later while generating docs? No. They are the same. The only difference is that the first one can contain a sequence of three unescaped double quotes, while the second can contain a sequence of three unescaped single quotes. (In other words, because the delimiters are different, there is a slight difference in what characters you

In twisted's sourcecode, many docstrings contain formats like this: L{xxx} or C{xxx} or a line begin with an '@', what's their meanings? for example, in twisted/internet/interfaces.py: def registerProducer(producer, streaming): """ Register to receive data from a producer. ... For L{IPullProducer} providers, C{resumeProducing} will be called once each time data is required. ... @type producer: L{IProducer} provider ... @return: C{None} """ L{IPullProducer} , C{resumeProducing} , @type producer ? By the way, are these formats a part of standard python docstring formats? If so, where should I

Sometimes a function in Python may accept an argument of a flexible type. Or it may return a value of a flexible type. Now I can't remember a good example of such a function right now, therefore I am demonstrating what such a function may look like with a toy example below. I want to know how to write docstrings for such functions using the Sphinx documentation notation. In the example below, the arguments may be either str or int . Similarly it may return either str or int . I have given an example docstrings (both in the default Sphinx notation as well as the Google notation understood by