diff options
Diffstat (limited to 'sandbox/tibs/pysource2')
| -rw-r--r-- | sandbox/tibs/pysource2/__init__.py | 10 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/log.txt | 113 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/not_a_directory | 0 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/package.py | 185 | ||||
| -rwxr-xr-x | sandbox/tibs/pysource2/pysrc2html.py | 46 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/reader.py | 31 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/temp.rst | 81 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/temp.txt | 79 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/test_package.py | 179 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/test_reader.py | 127 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/transform.py | 157 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/trivial_package/__init__.py | 2 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/trivial_package/file1.py | 14 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/trivial_package/file2.py | 2 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/trivial_package/not_python | 3 | ||||
| -rw-r--r-- | sandbox/tibs/pysource2/trivial_package/sub_package/__init__.py | 0 |
16 files changed, 0 insertions, 1029 deletions
diff --git a/sandbox/tibs/pysource2/__init__.py b/sandbox/tibs/pysource2/__init__.py deleted file mode 100644 index d7e9d8a32..000000000 --- a/sandbox/tibs/pysource2/__init__.py +++ /dev/null @@ -1,10 +0,0 @@ -"""Package pysource2 - Python source to Python source documentation - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' diff --git a/sandbox/tibs/pysource2/log.txt b/sandbox/tibs/pysource2/log.txt deleted file mode 100644 index 9bae3e9e0..000000000 --- a/sandbox/tibs/pysource2/log.txt +++ /dev/null @@ -1,113 +0,0 @@ -============================= -Writing and testing pysource2 -============================= - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -pysource2 is my attempt to rewrite the original pysource. pysource -itself was a proof-of-concept module to find docstrings withing Python -source files and present them as (by default) HTML documentation, as -described by the Docutils project. Since it was written before the -Docutils codebase became stabilised around its current Reader/Writer -patterns, it doesn't really mesh well with the current approaches. Also, -lots of the code is fairly grotty anyway, and could do with a rewrite on -principle - not least because it is not well tested. - -So, pysource2 is both that rewrite, and also an attempt on my part to -learn how to do test driven development. - -Setting the path -================ - -I want to take my docutils stuff directly from the source directories, -so that I work with the latest CVS code, and don't have to keep installing -things. Thus I need to set the Python path to point to the source -directories:: - - export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils - -Since I'm using Python 2.2.3, I also need the modules in the "extras" -directory:: - - export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils/extras - -If I want access to the testing stuff, I also need the "test" -directory:: - - export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils/test - - -NB: Relies upon the code in docutils/docutils/readers/python/moduleparser.py - -Log -=== -The "obvious" place to start is with packages - the previous pysource -never did quite get them right (for a start, it wouldn't cope with -sub-packages). Also, having a utility to report on packages, then on -modules, and gradually on to finer levels of detail, seems like giving -something useful as soon as possible. - -It looked over-complex to adopt the docutils test framework itself, -initially, especially since I am new both to unit testing *and* to test -driven development. So I am being less ambitious, and working with -"pure" unit tests - I reckon I'll learn more that way. - -So, the first pass gives me package.py and test_package.py. - -My first impressions of (such a little bit of) development is that TDD -does indeed give one the feeling of reassurance I'd expected from my -half-TDD efforts in Java at LSL. - -Initially, I was looking to detect a request for a package that didn't -exist, or wasn't a directory file, explicitly, with dedicated -exceptions. This felt rather over-complex, and indeed refactoring those -tests out and just catching a (non-explicit) OSError in the tests works -well enough - in reality, a user is not going to ask to parse a package -that is not already known to be an existant directory (heck, the "user" -is probably a program that's just figured out if the thing whose -documentation is wanted is a file or a directory), and if they do then -OSError makes sense since it is what one would normally get. - - -Questions -========= - -* Should we attempt to parse files that don't end in ".py"? - - What about ".pyw"? - - What about Python files on Unix which have had their extension removed and - been made executable? - -* Should there be an option to produce a document for a directory of Python - files that is not a package - e.g., a directory of useful scripts put - together just to be on the UNIX path, or Python's own library. - - -TODO -==== - - * Add a method to Module to indicate if it has an Attribute called - __docformat__, and if so, what its value is. - - * That requires understanding how the testing for the moduleparser is - organised and works, so I can add an appropriate test. - - * At which stage, should I incorporate Package (and NotPython) therein? - - * Write a simple transform (first learn how!) to parse any Docstring - contents in a module with __docformat__ equal to one of the reStructuredText - indicators. - - * Write another transform to turn the Pythonic doctree into a standard one. - - * At which point, we'll have something useful, albeit not very powerful, - so provide an appropriate command line interface for (at least) HTML output. - - * Work out how to do attribute references, etc., in *this* context (I have - no idea if the mechanisms from the original pysource will be any use). - diff --git a/sandbox/tibs/pysource2/not_a_directory b/sandbox/tibs/pysource2/not_a_directory deleted file mode 100644 index e69de29bb..000000000 --- a/sandbox/tibs/pysource2/not_a_directory +++ /dev/null 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 diff --git a/sandbox/tibs/pysource2/pysrc2html.py b/sandbox/tibs/pysource2/pysrc2html.py deleted file mode 100755 index 9aaf26782..000000000 --- a/sandbox/tibs/pysource2/pysrc2html.py +++ /dev/null @@ -1,46 +0,0 @@ -#!/usr/bin/env python -"""pysrc2html - Read Python package/modules and output HTML documentation - -@@@ I'm not terribly happy with the name of this module, but it will do for -now (pydoc2html *might* be better?) - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import sys -from package import parse_package_or_module -import transform -from docutils.writers.html4css1 import Writer -from docutils.frontend import OptionParser - -usage = '%prog [options] [<package-directory> | <python-file> [html-file]]' -description = ('Generates .html documentation for the given Python package' - ' or module.') - -writer = Writer() - -option_parser = OptionParser(components=[writer], - usage=usage,description=description) - -settings = option_parser.parse_args(sys.argv[1:]) - -source_path = settings._source -target_path = settings._destination - -nodes = parse_package_or_module(source_path) - -# That then needs converting to a docutils tree -document = transform.make_document(nodes,settings) - -# And *that* wants converting to the appropriate output format -try: - target = open(target_path,"w") - writer.write(document,target) -finally: - target.close() diff --git a/sandbox/tibs/pysource2/reader.py b/sandbox/tibs/pysource2/reader.py deleted file mode 100644 index 6e4c7dfd2..000000000 --- a/sandbox/tibs/pysource2/reader.py +++ /dev/null @@ -1,31 +0,0 @@ -"""reader.py - docutils Reader for Python source code - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import docutils.readers -from docutils.readers.python.moduleparser import Node, parse_module -#from package import parse_package -from transform import make_document - -class Reader(docutils.readers.Reader): - """A Python source code specific Reader. - """ - - config_section = 'python reader' - config_section_dependencies = ('readers',) - - def parse(self): - """Parse `self.input` into a document tree.""" - - tree = parse_module(self.input,self.source.source_path) - self.document = document = make_document(tree) - #self.document = document = self.new_document() - #self.parser.parse(self.input, document) - document.current_source = document.current_line = None diff --git a/sandbox/tibs/pysource2/temp.rst b/sandbox/tibs/pysource2/temp.rst deleted file mode 100644 index fa2836232..000000000 --- a/sandbox/tibs/pysource2/temp.rst +++ /dev/null @@ -1,81 +0,0 @@ -<document source="temp.txt"> - <comment xml:space="preserve"> - This is a simple reStructuredText file that represents what I would - <comment xml:space="preserve"> - like the output of transforming my test Python code to be - <section class="package" id="package-trivial-package" name="package trivial_package"> - <title> - Package trivial_package - <section class="module" id="module-trivial-package-init" name="module trivial_package.__init__"> - <title> - Module trivial_package.__init__ - <block_quote class="docstring"> - <paragraph> - A simple docstring. - <section class="module" id="module-trivial-package-file1" name="module trivial_package.file1"> - <title> - Module trivial_package.file1 - <block_quote class="docstring"> ## Hmm - not quite right - <paragraph> - This is the first example file. It - <emphasis> - does - use reStructuredText. - <paragraph> - Attributes: - <bullet_list bullet="*"> - <list_item> - <paragraph> - __docformat__ = "reST" (line 5) - <paragraph> - Import: os (line 7) - <section class="class" id="class-trivial-package-file1-fred" name="class trivial_package.file1.fred"> - <title> - Class trivial_package.file1.Fred - <field_list> - <field> - <field_name> - line - <field_body> - <paragraph> - 9 - <paragraph class="docstring"> ## Hmm - An example class - it announces each instance as it is created. - <section class="method" id="method-trivial-package-file1-fred-init" name="method trivial_package.file1.fred.__init__"> - <title> - Method trivial_package.file1.Fred.__init__ - <field_list> - <field> - <field_name> - line - <field_body> - <paragraph> - 13 - <field> - <field_name> - parameters - <field_body> - <paragraph> - self - <section class="module" id="module-trivial-package-file2" name="module trivial_package.file2"> - <title> - Module trivial_package.file2 - <block_quote class="docstring"> - <paragraph> - This module is - <emphasis> - not - using reStructuredText for its docstrings. - <section class="file" id="file-trivial-package-not-python" name="file trivial_package.not_python"> - <title> - File trivial_package.not_python - <paragraph> - (Not a Python module) - <section class="package" id="package-trivial-package-sub-package" name="package trivial_package.sub_package"> - <title> - Package trivial_package.sub_package - <section class="module" id="module-trivial-package-sub-package-init" name="module trivial_package.sub_package.__init__"> - <title> - Module trivial_package.sub_package.__init__ - <paragraph> - (No documentation) diff --git a/sandbox/tibs/pysource2/temp.txt b/sandbox/tibs/pysource2/temp.txt deleted file mode 100644 index dc1e9640f..000000000 --- a/sandbox/tibs/pysource2/temp.txt +++ /dev/null @@ -1,79 +0,0 @@ -.. This is a simple reStructuredText file that represents what I would -.. like the output of transforming my test Python code to be - -.. class:: package - -======================= -Package trivial_package -======================= - -.. class:: module - -Module trivial_package.__init__ -=============================== - - .. class:: docstring - - A simple docstring. - -.. class:: module - -Module trivial_package.file1 -============================ - - .. class:: docstring - - This is the first example file. It *does* use reStructuredText. - - Attributes: - - * __docformat__ = "reST" (line 5) - - Import: os (line 7) - -.. class:: class - -Class trivial_package.file1.Fred --------------------------------- - -:line: 9 - - .. class:: docstring - - An example class - it announces each instance as it is created. - -.. class:: method - -Method trivial_package.file1.Fred.__init__ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:line: 13 -:parameters: self - -.. class:: module - -Module trivial_package.file2 -============================ - - .. class:: docstring - - This module is *not* using reStructuredText for its docstrings. - -.. class:: file - -File trivial_package.not_python -=============================== - -(Not a Python module) - -.. class:: package - -Package trivial_package.sub_package -=================================== - -.. class:: module - -Module trivial_package.sub_package.__init__ -------------------------------------------- - -(No documentation) diff --git a/sandbox/tibs/pysource2/test_package.py b/sandbox/tibs/pysource2/test_package.py deleted file mode 100644 index d267d3937..000000000 --- a/sandbox/tibs/pysource2/test_package.py +++ /dev/null @@ -1,179 +0,0 @@ -#! /usr/bin/env python -"""test_package.py - -Unit tests for parsing packages for pysource. - -Initially, this is a standalone test, but ultimately it may be merged into the -mechanisms used for the Docutils self-tests. - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import unittest - -from package import parse_package, NotAPackageException -from transform import make_document - -# The following is to ensure that there are .pyc files in the package -# - this is important for testing, since the Python compiler gets quite -# unhappy if given a non-text file to play with (it doesn't like null bytes), -# so we need to do something about that... -import trivial_package - -class PackageTest(unittest.TestCase): - - def testNoSuchDirectory(self): - """Not a package - no such directory. - """ - - self.assertRaises(OSError, - parse_package, - "no_such_directory") - - def testNotADirectory(self): - """Not a package - file is not a directory. - """ - - self.assertRaises(OSError, - parse_package, - "not_a_directory") - - def testNotAPackage(self): - """Not a package - directory is empty. - """ - - self.assertRaises(NotAPackageException, - parse_package, - "not_a_package") - - def testPackage(self): - """A package containing subpackage(s) - - The directory is called "trivial_package" for historical reasons. - """ - - wanted_result = """\ -<Package filename="trivial_package"> - <Module filename="__init__.py"> - <Docstring> - A simple docstring. - <Module filename="file1.py"> - <Docstring> - This is the first example file. It *does* use reStructuredText. - <Attribute lineno="5" name="__docformat__"> - <Expression lineno="5"> - "reST" - <Import lineno="7"> - os - <Class lineno="9" name="Fred"> - <Docstring lineno="9"> - An example class - it announces each instance as it is created. - <Method lineno="13" name="__init__"> - <ParameterList lineno="13"> - <Parameter lineno="13" name="self"> - <Module filename="file2.py"> - <Docstring> - This module is *not* using reStructuredText for its docstrings. - <NotPython filename="not_python"> - <Package filename="sub_package"> - <Module filename="__init__.py">\n""" - - actual_result = str(parse_package("trivial_package")) - - if wanted_result != actual_result: - print "+++++++++++++++++++++++++ WANT" - print wanted_result - print "+++++++++++++++++++++++++ GOT" - print actual_result - print "+++++++++++++++++++++++++" - - self.assertEqual(actual_result,wanted_result) - - def testMakeDocument(self): - """ - Turn our Package tree into a docutils Document. - """ - - # I've split the wanted result string up into substrings so I can - # amend it more easily (or so I hope). - trivial_package = """\ -<document source="Package trivial_package"> - <section class="package" id="package-trivial-package" name="package trivial_package"> - <title> - Package trivial_package\n""" - - # The "xml:space" attribute is by observation, not prediction - module_init = """\ - <section class="module" id="module-trivial-package-init" name="module trivial_package.__init__"> - <title> - Module trivial_package.__init__ - <literal_block class="docstring" xml:space="preserve"> - A simple docstring.\n""" - - module_file1 = """\ - <section class="module" id="module-trivial-package-file1" name="module trivial_package.file1"> - <title> - Module trivial_package.file1 - <literal_block class="docstring" xml:space="preserve"> - This is the first example file. It *does* use reStructuredText. - <section class="class" id="class-trivial-package-file1-fred" name="class trivial_package.file1.fred"> - <title> - Class trivial_package.file1.Fred - <literal_block class="docstring" xml:space="preserve"> - An example class - it announces each instance as it is created.\n""" - - module_file2 = """\ - <section class="module" id="module-trivial-package-file2" name="module trivial_package.file2"> - <title> - Module trivial_package.file2 - <literal_block class="docstring" xml:space="preserve"> - This module is *not* using reStructuredText for its docstrings.\n""" - - non_python_file = """\ - <section class="file" id="file-trivial-package-not-python" name="file trivial_package.not_python"> - <title> - File trivial_package.not_python - <paragraph> - File - <literal> - not_python - is not a Python module.\n""" - - sub_package = """\ - <section class="package" id="package-trivial-package-sub-package" name="package trivial_package.sub_package"> - <title> - Package trivial_package.sub_package\n""" - - sub_module_init = """\ - <section class="module" id="module-trivial-package-sub-package-init" name="module trivial_package.sub_package.__init__"> - <title> - Module trivial_package.sub_package.__init__\n""" - - wanted_result = (trivial_package + module_init + module_file1 + - module_file2 + non_python_file + sub_package + - sub_module_init) - - tree = parse_package("trivial_package") - - document = make_document(tree) - - actual_result = document.pformat() - - if wanted_result != actual_result: - print "+++++++++++++++++++++++++ WANT" - print wanted_result - print "+++++++++++++++++++++++++ GOT" - print actual_result - print "+++++++++++++++++++++++++" - - self.assertEqual(actual_result,wanted_result) - - -if __name__ == "__main__": - unittest.main() diff --git a/sandbox/tibs/pysource2/test_reader.py b/sandbox/tibs/pysource2/test_reader.py deleted file mode 100644 index e48f20749..000000000 --- a/sandbox/tibs/pysource2/test_reader.py +++ /dev/null @@ -1,127 +0,0 @@ -#! /usr/bin/env python -"""test_reader.py - -Unit tests for the Python source Reader - -Initially, this is a standalone test, but ultimately it may be merged into the -mechanisms used for the Docutils self-tests. - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import unittest - -from package import parse_package -from transform import make_document -from reader import Reader -from docutils.core import publish_string -from docutils.readers.python.moduleparser import parse_module - -class PackageTest(unittest.TestCase): - - def testReader(self): - """Test the reader works as expected - """ - reader = Reader() - - source="# A Python comment" - source_path="test.py" - - # Hmm - extra debugging info... - publish_string = publish_string_with_traceback - - actual_result = publish_string(reader=reader,reader_name="python", - parser_name="restructuredtext", - writer_name="pseudoxml", - source=source, source_path=source_path) - - wanted_result = """\ -<document source="Module test"> - <section class="module" id="module-test" name="module test"> - <title> - Module test\n""" - - - if wanted_result != actual_result: - print "+++++++++++++++++++++++++ WANT" - print wanted_result - print "+++++++++++++++++++++++++ GOT" - print actual_result - print "+++++++++++++++++++++++++" - - self.assertEqual(actual_result,wanted_result) - - def testTool(self): - """Trying to think what to do for packages""" - # The Reader interface is designed to work with single test entities, - # either a string or the content of a text file (i.e., a single thing - # that can be accessed via some sort of "read" method). - # This doesn't work for packages, where one has multiple files. - # Thus I suspect that the Reader interface is not appropriate for - # what I want to do (at least, not without doing it unnecessary - # violence and making it a lot more complicated). - # So I need to do things "by hand"... - - source="# A Python comment" - source_path="test.py" - - # Since a body of text is a Module, not a Package, we'll go straight - # to it - nodes = parse_module(source,source_path) - - # That then needs converting to a docutils tree - document = make_document(nodes) - - # And *that* wants converting to the appropriate output format - - from docutils.writers.pseudoxml import Writer - writer = Writer() - writer.document = document - writer.translate() - actual_result = writer.output - - wanted_result = """\ -<document source="Module test"> - <section class="module" id="module-test" name="module test"> - <title> - Module test\n""" - - - if wanted_result != actual_result: - print "+++++++++++++++++++++++++ WANT" - print wanted_result - print "+++++++++++++++++++++++++ GOT" - print actual_result - print "+++++++++++++++++++++++++" - - self.assertEqual(actual_result,wanted_result) - - -def publish_string_with_traceback(reader=None,reader_name=None, - parser_name=None,writer_name=None, - source=None,source_path=None): - """A modified version of publish_string, so I can request traceback. - """ - from docutils.core import Publisher - from docutils import io - pub = Publisher(reader=reader, - source_class=io.StringInput, - destination_class=io.StringOutput) - pub.set_components(reader_name="python", - parser_name="restructuredtext", - writer_name="pseudoxml") - - pub.process_command_line(argv=["--traceback"]) - - pub.set_source(source=source, source_path=source_path) - return pub.publish(enable_exit=False) - - -if __name__ == "__main__": - unittest.main() diff --git a/sandbox/tibs/pysource2/transform.py b/sandbox/tibs/pysource2/transform.py deleted file mode 100644 index 1be37bd02..000000000 --- a/sandbox/tibs/pysource2/transform.py +++ /dev/null @@ -1,157 +0,0 @@ -"""transform.py - create a docutils Document tree from a Package or Module tree - -: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.utils import new_document -import docutils.nodes as nodes -from package import Package, NotPython -from docutils.readers.python.moduleparser import Module, Class, Docstring - -def make_document(tree,settings=None): - """Return a docutils Document tree constructed from this Python tree. - - The tree given must be either a Package or Module tree. - """ - - # @@@ Can it ever be anything other than a package or module? - # I'd assert not - the module is the basic "smallest unit". - # Should we test that? - if isinstance(tree,Package): - document = new_document("Package %s"%tree.filename,settings) - section = make_package_section(tree) - else: - document = new_document("Module %s"%os.path.splitext(tree.filename)[0], - settings) - section = make_module_section(tree) - document.append(section) - return document - -def make_package_section(tree,parent_name=None): - """Return a docutils tree constructed from this Package tree - """ - if parent_name: - tree_name = "%s.%s"%(parent_name,tree.filename) - else: - tree_name = tree.filename - title = "Package %s"%(tree_name) - - # @@@ Do I really want to normalise (case fold, in particular) - # the id/name for this section? Python names can legitimately - # distinguish case, and whilst that's not terribly useful at - # the file level (since not all OS/filesystems keep such a - # distinction), it certainly is a valid possibility *within* - # a file... - # - # make_id() produces a name that starts with [a-z] and continues - # with a-z, 0-9 and hyphen (or something like that). - # - # fully_normalize_name() reduces spaces to single spaces (OK), - # but also lowercases. - # - # @@@ Think more on usage here, I guess - section = nodes.section(CLASS="package",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # @@@ I'm enforcing an order of modules before non-python files before - # subpackages here - # - do I really care? - # - do I want some other way order? - # - is this the best way to do it (e.g., I could sort the children - # into order first instead) - for child in tree.children: - if isinstance(child,Module): - subsection = make_module_section(child,tree_name) - section.append(subsection) - for child in tree.children: - if isinstance(child,NotPython): - subsection = make_not_python_section(child,tree_name) - section.append(subsection) - for child in tree.children: - if isinstance(child,Package): - subsection = make_package_section(child,tree_name) - section.append(subsection) - return section - -def make_module_section(tree,parent_name=None): - """Return a docutils tree constructed from this Module sub-tree - """ - module_name = os.path.splitext(tree.filename)[0] - if parent_name: - tree_name = "%s.%s"%(parent_name,module_name) - else: - tree_name = module_name - title = "Module %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="module",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # Assume that the docstring must be the first child - if len(tree.children) > 0 and \ - isinstance(tree.children[0],Docstring): - section.append(make_docstring(tree.children[0])) - - # @@@ Again, I'm looking for classes before anything else - for child in tree.children: - if isinstance(child,Class): - subsection = make_class_section(child,tree_name) - section.append(subsection) - - return section - -def make_not_python_section(tree,parent_name=None): - """Return a docutils tree constructed from this NotPython (file) sub-tree - """ - if parent_name: - tree_name = "%s.%s"%(parent_name,tree.filename) - else: - tree_name = tree.filename - title = "File %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="file",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - paragraph = nodes.paragraph(text="File ") - paragraph.append(nodes.literal(text=tree.filename)) - paragraph.append(nodes.Text(" is not a Python module.")) - section.append(paragraph) - return section - -def make_class_section(tree,parent_name): - """Return a docutils tree constructed from this Class sub-tree - """ - tree_name = "%s.%s"%(parent_name,tree.name) - title = "Class %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="class",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # Assume that the docstring must be the first child - if len(tree.children) > 0 and \ - isinstance(tree.children[0],Docstring): - section.append(make_docstring(tree.children[0])) - - # @@@ Don't forget that we want base classes to be named at - # some point - - return section - -def make_docstring(docstring): - return nodes.literal_block(text=docstring.text,CLASS="docstring") diff --git a/sandbox/tibs/pysource2/trivial_package/__init__.py b/sandbox/tibs/pysource2/trivial_package/__init__.py deleted file mode 100644 index 3e664b315..000000000 --- a/sandbox/tibs/pysource2/trivial_package/__init__.py +++ /dev/null @@ -1,2 +0,0 @@ -"""A simple docstring. -""" diff --git a/sandbox/tibs/pysource2/trivial_package/file1.py b/sandbox/tibs/pysource2/trivial_package/file1.py deleted file mode 100644 index 9636cb676..000000000 --- a/sandbox/tibs/pysource2/trivial_package/file1.py +++ /dev/null @@ -1,14 +0,0 @@ -#! /usr/bin/env python -"""This is the first example file. It *does* use reStructuredText. -""" - -__docformat__ = "reST" - -import os - -class Fred: - """An example class - it announces each instance as it is created. - """ - - def __init__(self): - print "Aha" diff --git a/sandbox/tibs/pysource2/trivial_package/file2.py b/sandbox/tibs/pysource2/trivial_package/file2.py deleted file mode 100644 index d0e203574..000000000 --- a/sandbox/tibs/pysource2/trivial_package/file2.py +++ /dev/null @@ -1,2 +0,0 @@ -"""This module is *not* using reStructuredText for its docstrings. -""" diff --git a/sandbox/tibs/pysource2/trivial_package/not_python b/sandbox/tibs/pysource2/trivial_package/not_python deleted file mode 100644 index b447bba55..000000000 --- a/sandbox/tibs/pysource2/trivial_package/not_python +++ /dev/null @@ -1,3 +0,0 @@ -The content of this file is not Python. - -(Although it *is*, in fact, reStructuredText.) diff --git a/sandbox/tibs/pysource2/trivial_package/sub_package/__init__.py b/sandbox/tibs/pysource2/trivial_package/sub_package/__init__.py deleted file mode 100644 index e69de29bb..000000000 --- a/sandbox/tibs/pysource2/trivial_package/sub_package/__init__.py +++ /dev/null |