#!/usr/bin/env python # # $Id: happydocset.py,v 1.10 2002/08/24 19:57:07 doughellmann Exp $ # # Copyright 2001 Doug Hellmann. # # # All Rights Reserved # # Permission to use, copy, modify, and distribute this software and # its documentation for any purpose and without fee is hereby # granted, provided that the above copyright notice appear in all # copies and that both that copyright notice and this permission # notice appear in supporting documentation, and that the name of Doug # Hellmann not be used in advertising or publicity pertaining to # distribution of the software without specific, written prior # permission. # # DOUG HELLMANN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, # INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN # NO EVENT SHALL DOUG HELLMANN BE LIABLE FOR ANY SPECIAL, INDIRECT OR # CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS # OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # """Base for docsets. """ __rcs_info__ = { # # Creation Information # 'module_name' : '$RCSfile: happydocset.py,v $', 'rcs_id' : '$Id: happydocset.py,v 1.10 2002/08/24 19:57:07 doughellmann Exp $', 'creator' : 'Doug Hellmann ', 'project' : 'HappyDoc', 'created' : 'Sat, 10-Feb-2001 08:18:58 EST', # # Current Information # 'author' : '$Author: doughellmann $', 'version' : '$Revision: 1.10 $', 'date' : '$Date: 2002/08/24 19:57:07 $', } try: __version__ = __rcs_info__['version'].split(' ')[1] except: __version__ = '0.0' # # Import system modules # import os import parser import re import string try: from cStringIO import StringIO except: from StringIO import StringIO import symbol import sys import token import UserList # # Import Local modules # import happydoclib import parseinfo # # Module # class DocSet(UserList.UserList, happydoclib.happydom.HappyDOM): """Basic DocSet Parameters Parameters includeComments -- Boolean. False means to skip the comment parsing step in the parser. Default is True. includePrivateNames -- Boolean. False means to ignore names beginning with _. Default is True. usePackages -- Boolean. True means to provide special handling for Packages (directories containing __init__.py files) from non-package Modules. prewrittenFileBasenames -- Base names (no extensions) of files which are to be converted to the output format and included in the docset. statusMessageFunc -- function which will print a status message for the user title -- the title of the documentation set useRecursion -- Recurse into subdirectories looking for subdirectories and files within them. """ def __init__(self, formatterFactory, parserFunc, defaultParserConfigValues, inputModuleNames, author='', outputBaseDirectory=None, docsetBaseDirectory=None, descriptionFilename=None, formatterParameters={}, ignoreDirFunc=None, includeComments=1, includePrivateNames=1, usePackages=1, prewrittenFileBasenames=( 'ANNOUNCE', 'CHANGES', 'LICENSE', 'README', 'TODO', ), statusMessageFunc=None, title='HappyDoc Generated Documentation (use -t to specify a new title)', useRecursion=1, # # Special package handling arguments # packageName='', docsetRoot=None, parent=None, # # DON'T FORGET TO UPDATE THE CLONE METHOD!!! # **extraNamedParameters ): """Initialize the documentation set. Parameters formatterFactory -- a callable object which creates the type of formatter class to be used for formatting the documentation set. The object will be called and passed the DocSet along with other configuration values for the formatter. parserFunc -- Parser function which returns the info for a module. inputModuleNames -- List of modules or directories to be documented. outputBaseDirectory -- the name of the root directory for this and any parent docsets docsetBaseDirectory -- the name of the root directory for this docset descriptionFilename -- File describing the docset as a whole. formatterParameters -- other named configuration values to be passed to the formatter when it is created through the factory. Any unrecognized values will be quietly ignored. ignoreDirFunc -- Function which returns true if the directory should be ignored. packageName -- Name of the package being documented by this docset. This value should only be specified when recursively creating a docset (HappyDoc handles this case automatically). docsetRoot=None -- The root DocSet object, when recursing. *For others, see class documentation.* """ happydoclib.TRACE.into('HappyDocset', '__init__', packageName=packageName, parent=parent, docsetBaseDirectory=docsetBaseDirectory, outputBaseDirectory=outputBaseDirectory, ) happydoclib.TRACE.callerParent() # # Storage for sub-objects # self._all_packages = {} self._all_modules = {} self._all_classes = {} namespaces = ( self._all_packages, self._all_modules, self._all_classes ) # # Initialize base classes # self._status_message_func = statusMessageFunc self.statusMessage('Initializing documentation set %s...' % title) UserList.UserList.__init__(self) happydoclib.happydom.HappyDOM.__init__(self, packageName, parent, docsetBaseDirectory, namespaces) # # Store parameters # self._formatter_factory = formatterFactory self._parser_func = parserFunc self._default_parser_config_values = defaultParserConfigValues self._input_module_names = inputModuleNames self._contained_names = [] # list of inputModuleNames actually used self._title = title self._output_base_directory = outputBaseDirectory if docsetBaseDirectory: self._docset_base_directory = docsetBaseDirectory else: self._docset_base_directory = outputBaseDirectory self._description_filename = descriptionFilename self._formatter_configuration = formatterParameters self._include_private_names = happydoclib.optiontools.getBooleanArgumentValue( includePrivateNames) self._include_comments = happydoclib.optiontools.getBooleanArgumentValue( includeComments) self._use_packages = happydoclib.optiontools.getBooleanArgumentValue( usePackages) self._use_recursion = useRecursion self._ignore_dir_name = ignoreDirFunc self._prewritten_file_basenames = prewrittenFileBasenames self._prewritten_files = [] self._docset_root = docsetRoot # # Initialize this class # self._open_handles = [] # # Handle unrecognized named parameters. # for extra_param, extra_value in extraNamedParameters.items(): self.statusMessage( 'WARNING: Parameter "%s" (%s) unrecognized by docset %s.' % \ (extra_param, extra_value, self.__class__.__name__) ) # # Create the formatter # self._formatter = apply( self._formatter_factory, ( self, ), self._formatter_configuration ) # # Process the modules specified. # self.processFiles(inputModuleNames) happydoclib.TRACE.outof() return def _requiredOfSubclass(self, name): "Convenient way to raise a consistent exception." raise AttributeError('%s is not implemented for this class.' % name, self.__class__.__name__) def __del__(self): # # Attempt to reduce cycles, since the # formatter generally has a reference # to the docset as well. # self._formatter = None return def statusMessage(self, message='', verboseLevel=1): "Print a status message for the user." if self._status_message_func: self._status_message_func(message, verboseLevel) return ## ## HappyDOM ## def getFilename(self): "Returns the \"filename\" of the documentation set." happydoclib.TRACE.into('HappyDocset', 'getFilename') my_path = happydoclib.path.removePrefix( self.getDocsetBaseDirectory(), self.getOutputBaseDirectory()) happydoclib.TRACE.outof(my_path) return my_path def getSymbolInfo(self, name, tryParent=1): """Look up the info record for the name. Looks in the namespaces registered for this DOM node. If no value is found, 'None' is returned. """ # # First try locally # my_answer = happydoclib.happydom.HappyDOM.getSymbolInfo(self, name, tryParent=0) if my_answer: return my_answer # # Next try in our __init__.py module # init_module = self._all_modules.get('__init__', None) if init_module: # do not try parent, as that will call *this* method again init_answer = init_module.getSymbolInfo(name, tryParent=0) if init_answer: return init_answer # # Last, try our parent. We can just call the base class method # again with the appropriate flag set, since we know it will # fail normally but then try the parents. This saves us having # to re-implement that feature here. # if tryParent: return happydoclib.happydom.HappyDOM.getSymbolInfo( self, name, tryParent=tryParent) return None def getReference(self, formatter, sourceNode): "Return a reference to this package from sourceNode." happydoclib.TRACE.into( 'DocSet', 'getReference', formatter=formatter, sourceNode=sourceNode) init_module = self._all_modules.get('__init__', self) fully_qualified_name = formatter.getOutputNameForObject(self) happydoclib.TRACE.writeVar(fully_qualified_name=fully_qualified_name) extension = '.%s' % formatter.getFilenameExtension() len_extension = len(extension) if fully_qualified_name[-len_extension:] == extension: happydoclib.TRACE.write('fully qualified name has extension') fully_qualified_name = fully_qualified_name[:-len_extension] happydoclib.TRACE.writeVar(fully_qualified_name=fully_qualified_name) root_node_name = formatter.getRootNodeName() my_root_node = happydoclib.path.join(fully_qualified_name, root_node_name) happydoclib.TRACE.writeVar(my_root_node=my_root_node) ref = formatter.getReference( my_root_node, sourceNode.name, self.getReferenceTargetName() ) happydoclib.TRACE.outof(ref) return ref def getFullOutputNameForObject(self, infoObject=None): "Returns the output destination for documentation about this object." happydoclib.TRACE.into('DocSet', 'getFullOutputNameForObject', infoObject=infoObject) if infoObject is None: output_name = self._formatter.getFullOutputNameForObject(None) else: output_name = self._formatter.getFullOutputNameForObject(infoObject) happydoclib.TRACE.outof(output_name) return output_name ## ## External documents ## def getExternalDocumentationFile(self, filename): """Retrieve documentation that is not in a program source file. Parameters: 'filename' -- Name of the file to retrieve. """ converter_factory = happydoclib.docstring.getConverterFactoryForFile(filename) converter = converter_factory() try: file = converter.getExternalDocumentationFile(filename) except IOError: file = None return file def _foundReadme(self): """If a README file was found, return the name of the file. """ for fname in self._prewritten_files: if happydoclib.path.basename(fname)[:6] == 'README': return fname return None ## ## Docstrings ## def getSummaryAndFormat(self): """Return one line summary of the documentation set. """ happydoclib.TRACE.into('HappyDocset', 'getSummaryAndFormat', name=self.getName()) one_liner = '' format = 'PlainText' # # First check for __init__.py description. # if (not one_liner) and self._all_modules.has_key('__init__'): happydoclib.TRACE.write('Trying __init__.py') one_liner, format = self._all_modules['__init__'].getSummaryAndFormat() # # Then check for first line of README file. # if (not one_liner) and self._foundReadme(): readme_filename = self._foundReadme() external_file = self.getExternalDocumentationFile( readme_filename ) if external_file: happydoclib.TRACE.write('Trying file %s' % readme_filename) one_liner = external_file.oneLiner() format = external_file.getInputType() # # Then check for specified title. # if (not one_liner) and self._title: happydoclib.TRACE.write('Trying title') one_liner = self._title happydoclib.TRACE.outof(one_liner) return one_liner, format def getDocStringFormat(self): "Returns the docstring converter name for the docstring for this object." summary, format = self.getSummaryAndFormat() return format def getDescriptionAndFormat(self): "Returns the complete description of the docset and the docstring converter name for the format." happydoclib.TRACE.into('HappyDocSet', 'getDescriptionAndFormat') description = input_type = '' name = self.getName() # # Look for a description file (e.g. README.txt) # if self._description_filename and (self._description_filename != '-'): description_dir = '.' if self._contained_names: first_name = self._contained_names[0] if happydoclib.path.isdir(first_name): description_dir = first_name elif happydoclib.path.exists(first_name): description_dir = happydoclib.path.dirname(first_name) description_filename = happydoclib.path.join( description_dir, self._description_filename ) self.statusMessage('Looking for docset description in %s' % \ description_filename, 3) description_file = self.getExternalDocumentationFile(description_filename) if description_file: happydoclib.TRACE.write('file exists') #summary = description_file.oneLiner() description = str(description_file) input_type = description_file.getInputType() # # Look for a description in the __init__.py module. # if (not description) and (name not in ('__init__',)): init_module = self.getSymbolInfo('__init__', 0) if init_module: happydoclib.TRACE.write('found __init__') description = init_module.getDocString() input_type = init_module.getDocStringFormat() if description: happydoclib.TRACE.outof('found description') else: happydoclib.TRACE.outof('did not find description') return (description, input_type) ## ## Docset methods ## def getFormatter(self): "Returns the formatter instance being used by this docset." return self._formatter def getDocsetRoot(self): """Return the root node of the documentation set. """ if self._docset_root: return self._docset_root else: return self def clone(self, packageName, docsetBaseDirectory, inputModuleNames): """Create a new object which is configured the same as the current. It is possible, by passing optional arguments, to create a clone with a different configuration. This is useful for recursive work. Parameters packageName -- The name of the package being created. docsetBaseDirectory -- The base of output for the new docset. inputModuleNames -- Names of files to be included. """ happydoclib.TRACE.into('HappyDocset', 'clone', packageName=packageName, docsetBaseDirectory=docsetBaseDirectory, inputModuleNames=inputModuleNames) constructor_args = self.getCloneArguments(packageName, docsetBaseDirectory, inputModuleNames) new_obj = apply(self.__class__, (), constructor_args) happydoclib.TRACE.outof() return new_obj def getCloneArguments(self, packageName, docsetBaseDirectory, inputModuleNames): '''Return arguments to create a new docset based on the current one. Parameters packageName -- The name of the package being created. docsetBaseDirectory -- The base of output for the new docset. inputModuleNames -- Specify the file names to be included in the docset. Subclasses should override this method, but should also call the parent method using an algorithm such as:: subclass_args = {} subclass_args.update( ParentClass.getCloneArguments( self, packageName, baseDirectory, inputModuleNames) ) subclass_args.update( { "subClassArgument":self._sub_class_argument, }) return subclass_args ''' current_docset_path = self.getPath() happydoclib.TRACE.writeVar(current_docset_path=current_docset_path) docset_base_directory_prefix = docsetBaseDirectory[:-len(packageName)] while (docset_base_directory_prefix and (docset_base_directory_prefix[-1] == os.sep) ): docset_base_directory_prefix = docset_base_directory_prefix[:-1] happydoclib.TRACE.writeVar( docset_base_directory_prefix=docset_base_directory_prefix, ) constructor_args = { 'formatterFactory':self._formatter_factory, 'parserFunc':self._parser_func, 'defaultParserConfigValues':self._default_parser_config_values, 'inputModuleNames':inputModuleNames, 'outputBaseDirectory':self._output_base_directory, 'docsetBaseDirectory':docsetBaseDirectory, 'descriptionFilename':self._description_filename, 'formatterParameters':self._formatter_configuration, 'ignoreDirFunc':self._ignore_dir_name, 'includeComments':self._include_comments, 'includePrivateNames':self._include_private_names, 'usePackages':self._use_packages, 'prewrittenFileBasenames':self._prewritten_file_basenames, 'statusMessageFunc':self._status_message_func, 'useRecursion':self._use_recursion, 'parent':self, } # # Construct a reasonable title # if self.getName(): title = '%s.%s' % (self._title, packageName) else: title = '%s: %s' % (self._title, packageName) constructor_args['title'] = title # # Set up recursion into package with # a reference back to the root. # constructor_args.update( { 'packageName':packageName, 'docsetRoot':self.getDocsetRoot(), } ) return constructor_args def getFileInfo(self, fileName): "Parse the file and return the parseinfo instance for it." happydoclib.TRACE.into('DocSet', 'getFileInfo', fileName=fileName, ) self.statusMessage('Getting info for %s' % fileName) module_info = self._parser_func( self, fileName, self._include_comments, self._default_parser_config_values, ) happydoclib.TRACE.outof(module_info) return module_info def lookForPrewrittenFiles(self, dirName): """Look for prewritten documentation files in 'dirName'. """ self.statusMessage('Looking for non-source documentation files') self.statusMessage(' in %s' % dirName, 4) files = [] for file_basename in self._prewritten_file_basenames: pattern = '%s*' % file_basename self.statusMessage(' for %s' % pattern, 4) found = happydoclib.path.findFilesInDir( dirName, pattern ) self.statusMessage(' %s' % str(found), 4) for f in found: # # Eliminate any backup files, etc. created by # text editors. # if f[-1] in '*~#': continue # # Record this name # self.statusMessage( ' Found external documentation file\n %s' \ % f, 2) files.append(f) return files def processFiles(self, fileNames, moduleFileName=re.compile(r'^.*\.(py|cgi)$').match, ): """Get information about a list of files. Parameters fileNames -- Sequence of names of files to be read. Each file in fileNames is parsed to extract information to be used in documenting the file. """ happydoclib.TRACE.into('HappyDocset', 'processFiles', fileNames=fileNames) for file_name in fileNames: if ( happydoclib.path.isdir(file_name) and (not self._ignore_dir_name or not self._ignore_dir_name(file_name)) and (self._use_recursion >= 0) ): # # Record that we paid attention to this directory # self._contained_names.append(file_name) # # Find modules and directories within to # recurse. # dir_contents = happydoclib.path.findFilesInDir(file_name) # # Adjust the recursion factor. # # -1 -- Do not recurse. # 0 -- Recurse one level. # 1 -- Always recurse. # if not self._use_recursion: self._use_recursion = -1 # # Check if the current dir is a Package # init_file = happydoclib.path.join( file_name, '__init__.py' ) if happydoclib.path.exists( init_file ) and self._use_packages: self.statusMessage('Detected package %s' % file_name, 2 ) happydoclib.TRACE.write('Detected package %s' % file_name) # # Special handling for Package directories # orig_file_name = file_name file_name = happydoclib.path.removeRelativePrefix(file_name) package_name = happydoclib.path.basename(file_name) docset_base = self.getDocsetBaseDirectory() output_base = self.getOutputBaseDirectory() new_base = happydoclib.path.joinWithCommonMiddle( output_base, docset_base, file_name) new_docset = self.clone( packageName=package_name, docsetBaseDirectory=new_base, inputModuleNames=dir_contents, ) new_docset._prewritten_files = new_docset.lookForPrewrittenFiles( orig_file_name) self.append(new_docset) else: self.statusMessage('Recursing into %s' % file_name) # # Find pre-written files within the regular directory # self._prewritten_files = self._prewritten_files + \ self.lookForPrewrittenFiles(file_name) self.processFiles(dir_contents) elif ( not happydoclib.path.isdir(file_name) and moduleFileName(file_name) ): happydoclib.TRACE.write('regular module file') # # Record that we paid attention to this file # self._contained_names.append(file_name) # # Regular module file # try: file_info = self.getFileInfo(file_name) except SyntaxError, msg: self.statusMessage('\nERROR: SyntaxError: %s[%s] %s' % \ (file_name, msg.lineno, msg.msg) ) self.statusMessage('\n%s' % msg.text) self.statusMessage('Skipping %s' % file_name) else: self.append(file_info) else: # # Ignoring # self.statusMessage('Ignoring %s' % file_name, 4) happydoclib.TRACE.outof() return def getDocsetBaseDirectory(self): "Returns the base directory for this documentation set." happydoclib.TRACE.into('HappyDocset', 'getDocsetBaseDirectory') happydoclib.TRACE.outof(self._docset_base_directory) return self._docset_base_directory def getOutputBaseDirectory(self): "Returns the base directory for all documentation sets." happydoclib.TRACE.into('HappyDocset', 'getOutputBaseDirectory') happydoclib.TRACE.outof(self._output_base_directory) return self._output_base_directory def getClassInfo(self, className): "Returns class info if have it, None otherwise." return self._all_classes.get(className, None) def write(self): """Write the documentation set to the output. Developers creating their own, new, docset types should override this method to cause the docset instance to generate its output. """ self._requiredOfSubclass('write') return def _filterNames(self, nameList): """Remove names which should be ignored. Parameters nameList -- List of strings representing names of methods, classes, functions, etc. This method returns a list based on the contents of nameList. If private names are being ignored, they are removed before the list is returned. """ if not self._include_private_names: nameList = filter(lambda x: ( (x[0] != '_') or (x[:2] == '__') ), nameList) return nameList def close(self): "Close the open documentation set." for f in self._open_handles: try: self.closeOutput(f) except: pass return def append(self, infoObject): """Add a module to the docset. """ if infoObject.__class__ == self.__class__: # # Recursive package definition # self._all_packages[ infoObject.getName() ] = infoObject else: # # Contained module definition # self._all_modules[ infoObject.getName() ] = infoObject for c in infoObject.getClassNames(): self._all_classes[ c ] = infoObject.getClassInfo(c) # # Add to our list representation. # UserList.UserList.append(self, infoObject) return def openOutput(self, name, title, subtitle): """Open output for writing. Using this method to open output destinations means they will automatically be closed. Parameters name -- Name of output destination to open. title -- The main title to be given to the output (e.g., HTML page title or other documentation title). subtitle -- A subtitle which should be applied to the output. See also 'closeOutput'. """ self.statusMessage('\tDocumenting : "%s"' % title, 2) self.statusMessage('\t "%s"' % subtitle, 3) self.statusMessage('\t to : "%s"' % name, 3) f = self._formatter.openOutput(name, title, subtitle) self._open_handles.append(f) return f def closeOutput(self, output): """Close the output handle. Parameters output -- A handle created by 'openOutput'. """ self._formatter.closeOutput(output) return class DocsetUnitTest(happydoclib.StreamFlushTest.StreamFlushTest): def testOutputDirectory(self): filename = 'TestCases/test.py' test_output_dir = 'c:\\happydoc\\HappyDocTestOut' import happydoclib.formatter.formatter_Null docset = DocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=test_output_dir, statusMessageFunc=self.status_message_func, ) docset_base_dir = docset.getDocsetBaseDirectory() assert docset_base_dir == test_output_dir, 'Docset directory %s does not match %s' % \ (docset_base_dir, test_output_dir) output_base_dir = docset.getOutputBaseDirectory() assert docset_base_dir == test_output_dir, 'Output directory %s does not match %s' % \ (docset_base_dir, test_output_dir) docset_file_name = docset.getFilename() assert docset_file_name == test_output_dir, 'File name %s does not match expected %s' % \ (docset_file_name, test_output_dir) return if os.name != 'nt': def testPackageSummaries(self): filename = 'TestCases/test_package_summaries' basic_expected_package_info = { 'FromInit':'Summary from __init__.py', 'FromReadme':'Summary from README', 'FromReadmeTxt':'Summary from README.txt', 'FromTitle':'HappyDoc Generated Documentation (use -t to specify a new title): Nested.FromTitle', } basic_expected_package_names = basic_expected_package_info.keys() parent_expected_package_info = {} parent_expected_package_info.update(basic_expected_package_info) parent_expected_package_info['Nested'] = 'Nested Modules' parent_expected_package_info['FromTitle'] = 'HappyDoc Generated Documentation (use -t to specify a new title): FromTitle' parent_expected_package_names = parent_expected_package_info.keys() #module = getDocs(None, filename) import happydoclib.formatter.formatter_Null docset = DocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, statusMessageFunc=self.status_message_func, ) for m in docset.data: name = m.getName() assert name in parent_expected_package_names, \ 'Unexpected module %s found in docset.' % name expected_summary = parent_expected_package_info[name] actual_summary, format = m.getSummaryAndFormat() assert actual_summary == expected_summary, \ 'Summary values do not match for %s (expected "%s", got "%s")' \ % (name, expected_summary, actual_summary) if name == 'Nested': for cm in m.data: cname = cm.getName() if cname == '__init__': continue assert cname in basic_expected_package_names, \ 'Unexpected child module %s found in child docset.' % cname cexpected_summary = basic_expected_package_info[cname] cactual_summary, format = cm.getSummaryAndFormat() assert cactual_summary == cexpected_summary, \ 'Summary values do not match for child module %s (expected "%s", got "%s")' \ % (cname, cexpected_summary, cactual_summary) return def _privateNameTest(self, includePrivateNames): filename = 'TestCases/test_private_names.py' import happydoclib.formatter.formatter_Null docset = DocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, includePrivateNames=includePrivateNames, statusMessageFunc=self.status_message_func, ) assert len(docset.data) == 1, 'Did not get expected docset.' m = docset.data[0] assert m, 'Could not retrieve module' try: c = m['Public'] except KeyError: self.fail('Could not retrieve class "Public"') assert c.getName() == 'Public', 'Name of class does not match expected value.' all_function_names = c.getMethodNames() all_function_names.sort() expected_all_function_names = [ 'public_method', '_private_method', '__getattr__' ] expected_all_function_names.sort() if includePrivateNames: assert all_function_names == expected_all_function_names, \ 'Expected unfiltered names %s, got names %s' % \ (expected_all_function_names, all_function_names) else: expected_filtered_function_names = [ 'public_method', '__getattr__' ] expected_filtered_function_names.sort() filtered_function_names = docset._filterNames(all_function_names) assert filtered_function_names == expected_filtered_function_names, \ 'Expected filtered names %s, got names %s' % \ (expected_filtered_function_names, filtered_function_names) return def testPrivateNamesKeep(self): self._privateNameTest(1) return def testPrivateNamesIgnore(self): self._privateNameTest(0) return def _testIgnoreDirectoriesTestFunc(self, dirName): dir_name = happydoclib.path.basename(dirName) if dir_name in self.ignore_list: return 1 else: return 0 def testIgnoreDirectories(self): "Ignore some subdirectories." filename = '../HappyDoc' import happydoclib.formatter.formatter_Null self.ignore_list = [ 'docset', 'formatter', 'docstring', 'TestCases', 'dist', 'tmp', ] docset = DocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, ignoreDirFunc=self._testIgnoreDirectoriesTestFunc, statusMessageFunc=self.status_message_func, ) for m in docset.data: name = m.getName() assert name not in self.ignore_list, \ 'Found %s but it should have been ignored.' % name return