Asp Forum - Get dosctring without import

Joan Miller

2/26/2010 8:56:00 AM

When a package is imported, it gets the dosctring to store it in
*__doc__*.

Does that funcion is built in python? because I would want use it to
get the docstring without import a package

9 Answers

Diez B. Roggisch

2/26/2010 9:06:00 AM

Am 26.02.10 09:55, schrieb Joan Miller:
> When a package is imported, it gets the dosctring to store it in
> *__doc__*.
>
> Does that funcion is built in python? because I would want use it to
> get the docstring without import a package

You'd need to write your own parser for that. All standard tools simply
import, see another thread a few days ago where a user had problems with
help on modules.

Also, without importing, you'd not get docstrings of C-extension-objects.

Diez

Jean-Michel Pichavant

2/26/2010 10:28:00 AM

Joan Miller wrote:
> When a package is imported, it gets the dosctring to store it in
> *__doc__*.
>
> Does that funcion is built in python? because I would want use it to
> get the docstring without import a package
>
Epydoc, a documentation builder is able to do so with the --parse-only
option. You could take a look at the code, even grab their parser to
suit your needs. It may be quite difficult though.

JM

Ben Finney

2/26/2010 10:51:00 AM

Joan Miller <peloko45@gmail.com> writes:

> When a package is imported, it gets the dosctring to store it in
> *__doc__*.

Joan, in this message and numerous others you've been following the
widespread convention of using asterisks â??*â?? to surround text you want
to emphasise.

Normally that's good, but in a programming-language context (or any
other where asterisks have a separate established meaning), it's not a
good idea. In many cases, asterisks signify â??match any number of
arbitrary characters at this positionâ?, which gives a rather different
meaning to what you're writing.

You might be better off using quotes (like '__doc__' or â??__doc__â??), or
the reStructuredText syntax for demarcating a special element, backticks
(like `__doc__`). Even they need to be used with care, though, because
they also have specific established meanings (except the typographical
quotes, which is why I use them).

I hope that helps.

> Does that funcion is built in python? because I would want use it to
> get the docstring without import a package

Why is it you want to do this? Modules should not have unwanted side
effects when imported; if you can't import the module without invoking
those unwanted side effects, the module is poorly written.

That's not to say that such poorly-written modules don't exist. What is
the situation? Perhaps there's a better solution.

--
\ â??Earth gets its price for what Earth gives us.â? â??James Russell |
`\ Lowell |
_o__) |
Ben Finney

Peter Otten

2/26/2010 10:57:00 AM

Joan Miller wrote:

> When a package is imported, it gets the dosctring to store it in
> *__doc__*.
>
> Does that funcion is built in python? because I would want use it to
> get the docstring without import a package

Something to get you started:

import ast

def walk(root, stack):
for node in ast.iter_child_nodes(root):
if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
yield node
stack.append(node)
for child in walk(node, stack):
yield child
del stack[-1]

def get_name(node):
try:
return node.name
except AttributeError:
return "(%s)" % node.__class__.__name__

def get_path(path):
return ".".join(get_name(node) for node in path)

def find_docstrings(filename):
with open(filename) as f:
module = ast.parse(f.read())
print filename.center(len(filename) + 2).center(80, "=")
print ast.get_docstring(module)
print "=" * 80
print

path = []
for node in walk(module, path):
s = ast.get_docstring(node)
if s is not None:
name = get_path(path + [node])
print name.center(len(name) + 2).center(80, "-")
print s
print

if __name__ == "__main__":
import sys
args = sys.argv[1:]
if args:
for arg in args:
find_docstrings(arg)
else:
find_docstrings("/usr/lib/python2.6/unittest.py")
assert "unittest" not in sys.modules

To get an idea of the differences to the import-based approach try analysing
the following script:

import random

if random.choice([True, False]):
def f():
"say hello"
else:
def f():
"kill a kitten"

def g():
"whatever"
del g

Peter

Joan Miller

2/26/2010 11:23:00 AM

On 26 feb, 10:51, Ben Finney <ben+pyt...@benfinney.id.au> wrote:
> Joan Miller <pelok...@gmail.com> writes:
> > When a package is imported, it gets the dosctring to store it in
> > *__doc__*.
>
> Joan, in this message and numerous others you've been following the
> widespread convention of using asterisks ‘*’ to surround text you want
> to emphasise.
>
> Normally that's good, but in a programming-language context (or any
> other where asterisks have a separate established meaning), it's not a
> good idea. In many cases, asterisks signify “match any number of
> arbitrary characters at this position”, which gives a rather different
> meaning to what you're writing.
>
> You might be better off using quotes (like '__doc__' or ‘__doc__’), or
> the reStructuredText syntax for demarcating a special element, backticks
> (like `__doc__`). Even they need to be used with care, though, because
> they also have specific established meanings (except the typographical
> quotes, which is why I use them).
>
> I hope that helps.
>
> > Does that funcion is built in python? because I would want use it to
> > get the docstring without import a package
>
> Why is it you want to do this? Modules should not have unwanted side
> effects when imported; if you can't import the module without invoking
> those unwanted side effects, the module is poorly written.
>
> That's not to say that such poorly-written modules don't exist. What is
> the situation? Perhaps there's a better solution.
I use a function in 'setupy.py' to get automatically the description
from the package's docstring, but there is a problem when you import a
module that has to be built by cython (because it tries load a module
that doesn't exists).

Joan Miller

2/26/2010 11:30:00 AM

On 26 feb, 10:57, Peter Otten <__pete...@web.de> wrote:
> Joan Miller wrote:
> > When a package is imported, it gets the dosctring to store it in
> > *__doc__*.
>
> > Does that funcion is built in python? because I would want use it to
> > get the docstring without import a package
>
> Something to get you started:
>
> import ast
>
> def walk(root, stack):
> for node in ast.iter_child_nodes(root):
> if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
> yield node
> stack.append(node)
> for child in walk(node, stack):
> yield child
> del stack[-1]
>
> def get_name(node):
> try:
> return node.name
> except AttributeError:
> return "(%s)" % node.__class__.__name__
>
> def get_path(path):
> return ".".join(get_name(node) for node in path)
>
> def find_docstrings(filename):
> with open(filename) as f:
> module = ast.parse(f.read())
> print filename.center(len(filename) + 2).center(80, "=")
> print ast.get_docstring(module)
> print "=" * 80
> print
>
> path = []
> for node in walk(module, path):
> s = ast.get_docstring(node)
> if s is not None:
> name = get_path(path + [node])
> print name.center(len(name) + 2).center(80, "-")
> print s
> print
>
> if __name__ == "__main__":
> import sys
> args = sys.argv[1:]
> if args:
> for arg in args:
> find_docstrings(arg)
> else:
> find_docstrings("/usr/lib/python2.6/unittest.py")
> assert "unittest" not in sys.modules
>
> To get an idea of the differences to the import-based approach try analysing
> the following script:
>
> import random
>
> if random.choice([True, False]):
> def f():
> "say hello"
> else:
> def f():
> "kill a kitten"
>
> def g():
> "whatever"
> del g
>
> Peter

Thanks! What I need there is:

---------
with open(os.path.join(path, package, '__init__.py')) as f:
module = ast.parse(f.read())

print ast.get_docstring(module)

Ben Finney

2/26/2010 12:36:00 PM

Joan Miller <peloko45@gmail.com> writes:

> I use a function in 'setupy.py' to get automatically the description
> from the package's docstring, but there is a problem when you import a
> module that has to be built by cython (because it tries load a module
> that doesn't exists).

A simple approach (at least, simpler than crawling a parse tree) might
be to store the package description in a separate non-executable file.

A common convention is to have a â??READMEâ?? text file, written in
reStructuredText for rendering to various output formats as part of the
documentation. You could then have the â??setup.pyâ?? program read the
contents of that file and use it (or a slice of it) for the package
description.

--
\ â??Sometimes I â?? no, I don't.â? â??Steven Wright |
`\ |
_o__) |
Ben Finney

Joan Miller

2/26/2010 1:03:00 PM

On 26 feb, 12:35, Ben Finney <ben+pyt...@benfinney.id.au> wrote:
> Joan Miller <pelok...@gmail.com> writes:
> > I use a function in 'setupy.py' to get automatically the description
> > from the package's docstring, but there is a problem when you import a
> > module that has to be built by cython (because it tries load a module
> > that doesn't exists).
>
> A simple approach (at least, simpler than crawling a parse tree) might
> be to store the package description in a separate non-executable file.
>
> A common convention is to have a ‘README’ text file, written in
> reStructuredText for rendering to various output formats as part of the
> documentation. You could then have the ‘setup.py’ program read the
> contents of that file and use it (or a slice of it) for the package
> description.
I get the 'README.txt' file to get the long description but I use the
docstring because each package should include a short desciption about
it.

Ben Finney

2/26/2010 11:59:00 PM

Joan Miller <peloko45@gmail.com> writes:

> On 26 feb, 12:35, Ben Finney <ben+pyt...@benfinney.id.au> wrote:
> > A common convention is to have a â??READMEâ?? text file, written in
> > reStructuredText for rendering to various output formats as part of
> > the documentation. You could then have the â??setup.pyâ?? program read
> > the contents of that file and use it (or a slice of it) for the
> > package description.
> I get the 'README.txt' file to get the long description but I use the
> docstring because each package should include a short desciption about
> it.

I keep both in the same file:

===== README =====
FooBar, a library for spangulation.

The FooBar library provides thribbles which can be
easily frobnicated for spangulation in a sntandard manner.

Other spangulation libraries are far less weebly than this
one, which is the choice of discerning grognards everywhere.
=====

Then, the description fields are derived by splitting the file's
contents on the first paragraph break:

=====
from distutils.core import setup

readme_file = open("README")

short_description, long_description = (
d.strip()
for d in readme_file.read().split(u'\n\n', 1))

setup(
# â?¦
description=short_description,
long_description=long_description,
# â?¦
)
=====

--
\ â??Some forms of reality are so horrible we refuse to face them, |
`\ unless we are trapped into it by comedy. To label any subject |
_o__) unsuitable for comedy is to admit defeat.â? â??Peter Sellers |
Ben Finney

comp.lang.python

Get dosctring without import

Joan Miller

Diez B. Roggisch

Jean-Michel Pichavant

Ben Finney

Peter Otten

Joan Miller

Joan Miller

Ben Finney

Joan Miller

Ben Finney

x Login to ForumsZone