Get dosctring without import
Joan Miller
*__doc__*.
Does that funcion is built in python? because I would want use it to
get the docstring without import a package
Diez B. Roggisch
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
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
> 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
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
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
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
> 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
> 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.
docstring because each package should include a short desciption about
it.
Ben Finney
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