diff options
Diffstat (limited to 'sandbox/tibs/pysource2/package.py')
| -rw-r--r-- | sandbox/tibs/pysource2/package.py | 185 |
1 files changed, 0 insertions, 185 deletions
diff --git a/sandbox/tibs/pysource2/package.py b/sandbox/tibs/pysource2/package.py deleted file mode 100644 index 96524693f..000000000 --- a/sandbox/tibs/pysource2/package.py +++ /dev/null @@ -1,185 +0,0 @@ -"""package.py - support for calculating package documentation. - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import os -from docutils.readers.python.moduleparser import Node, parse_module - -DEBUG = 0 - -class NotAPackageException(Exception): - pass - - -# ---------------------------------------------------------------------- -class Package(Node): - """This class represents a Python package. - - `filename` is the name of the package - i.e., the package name. - This may be extended/altered/expanded to include/disambiguate the - name of the package, the "full" name of the package (e.g., if it is - a sub-package) and the full path of the package, as needs indicate. - - Note that a package must, by definition, include at least one module, - i.e., __init__.py (otherwise, it isn't a package). - """ - - def __init__(self, filename): - """Initialise a Package. - - Note that this does *not* take a "node" argument, since a Package - is not actually quite like the Module and other sub-nodes. - - @@@ (Actually, there's a case to say that Node should be able to take - a "node" value of None and cope, in which case our life would be - easier - I may work on that later on...) - """ - # Hackery - the following two lines copied from Node itself. - self.children = [] - self.lineno = None - self.filename = filename - - def attlist(self): - return Node.attlist(self, filename=self.filename) - - - -# ---------------------------------------------------------------------- -class NotPython(Node): - """This class is used to represent a non-Python file. - - @@@ If the file isn't Python, should we try for reStructuredText? - """ - - def __init__(self, filename): - """Initialise a NotPython instance. - - @@@ Same caveats as Package. - """ - # Hackery - the following two lines copied from Node itself. - self.children = [] - self.lineno = None - self.filename = filename - - def attlist(self): - return Node.attlist(self, filename=self.filename) - - -# ---------------------------------------------------------------------- -def parse_package_or_module(path): - """Parse a package or module for documentation purposes. - - `path` should either be a directory representing a Python package, or - a single Python file. - """ - path = os.path.normpath(path) - if os.path.isdir(path): - return parse_package(path) - else: - return parse_file(path,path) - -def parse_package(package_path): - """Parse a package for documentation purposes. - - `package_path` should be the system path of the package directory, which is - not necessarily the same as the Python path... - """ - - if DEBUG: print "Parsing package",package_path - - package_path = os.path.normpath(package_path) - dir,file = os.path.split(package_path) - if dir == "": - dir = "." - return parse_subpackage(dir,file) - -def parse_subpackage(package_path,subpackage): - """Parse a subpackage for documentation purposes. - - `package_path` should be the system path of the package directory, - and `subpackage` is the (file) name of the subpackage therein. It - is assumed that this is already known to be a directory. - """ - - sub_path = os.path.join(package_path,subpackage) - - if DEBUG: print "Parsing sub-package",sub_path - - files = os.listdir(sub_path) - if "__init__.py" not in files: - raise NotAPackageException,\ - "Directory '%s' is not a Python package"%sub_path - - node = Package(subpackage) - - # Should we sort the files? Well, if we don't have them in a predictable - # order, it is harder to test the result(!), and also I believe that it - # is easier to use the output if there is some obvious ordering. Of course, - # the question then becomes whether packages and modules should be in the - # same sequence, or separated. - files.sort() - - for filename in files: - fullpath = os.path.join(sub_path,filename) - if os.path.isdir(fullpath): - try: - node.append(parse_subpackage(sub_path,filename)) - except NotAPackageException: - pass - else: - # We do *not* want to try .pyc or .pyo files - we can guarantee - # that they won't parse (the Python compiler code gets unhappy - # about NULL bytes therein), and we definitely don't want an - # entry for such files in our documentation. - # Similarly, I work on Linux, and don't want to consider files - # that end with "~" (this last is a bit nasty...) - if os.path.splitext(filename)[1] not in (".pyc",".pyo") and \ - filename[-1] != "~": - node.append(parse_file(fullpath,filename)) - return node - -def parse_file(fullpath,filename): - """Parse a single file (which we hope is a Python file). - - * `fullpath` is the full path of the file - * `filename` is the name we want to use for it in the docutils tree - - Returns a docutils parse tree for said file. - """ - - if DEBUG: print "Parsing file",fullpath - - # @@@ Should we worry about the extension of the file? - # Trying to use that to predict the contents can be a problem - # - we already know that we have to worry about ".pyw" as well - # as ".py", not to mention the possibility (e.g., on Unix) of - # having removed the extension in order to make an executable - # file "look" more like a Unix executable. On the whole, it's - # probably better to try to parse a file, and worry about it - # not parsing if/when that occurs. - module = open(fullpath) - try: - module_body = module.read() - try: - module_node = parse_module(module_body,filename) - except SyntaxError: - # OK - it wasn't Python - so what *should* we do with it? - module_node = NotPython(filename) - if DEBUG: print " (not Python)" - return module_node - finally: - module.close() - - - -# ---------------------------------------------------------------------- -if __name__ == "__main__": - result = parse_package("trivial_package") - print result |