From 9c4fb40fbe108ba7ad9a37f25c2929269adbb107 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Thu, 31 Aug 2017 19:57:51 -0700 Subject: Fix many epydoc warnings --- src/engine/SCons/Action.py | 29 +++++---- src/engine/SCons/Builder.py | 23 ++++---- src/engine/SCons/Conftest.py | 42 +++++++------ src/engine/SCons/Environment.py | 3 + src/engine/SCons/Errors.py | 85 +++++++++++++-------------- src/engine/SCons/Memoize.py | 4 +- src/engine/SCons/Node/FS.py | 30 ++++------ src/engine/SCons/SConf.py | 6 +- src/engine/SCons/Scanner/LaTeX.py | 22 ++++--- src/engine/SCons/Scanner/__init__.py | 6 +- src/engine/SCons/Script/Interactive.py | 19 +++--- src/engine/SCons/Taskmaster.py | 46 ++++++++------- src/engine/SCons/Util.py | 51 ++++++++-------- src/engine/SCons/Variables/BoolVariable.py | 10 ++-- src/engine/SCons/Variables/EnumVariable.py | 24 ++++---- src/engine/SCons/Variables/ListVariable.py | 12 ++-- src/engine/SCons/Variables/PackageVariable.py | 24 ++++---- src/engine/SCons/Variables/PathVariable.py | 9 ++- src/engine/SCons/Variables/__init__.py | 21 ++++--- src/engine/SCons/cpp.py | 7 ++- src/engine/SCons/dblite.py | 4 +- test/Interactive/help.py | 13 ++-- 22 files changed, 251 insertions(+), 239 deletions(-) diff --git a/src/engine/SCons/Action.py b/src/engine/SCons/Action.py index d6fe30b4..b44088bf 100644 --- a/src/engine/SCons/Action.py +++ b/src/engine/SCons/Action.py @@ -222,9 +222,10 @@ def _code_contents(code, docstring=None): recompilations from moving a Python function. See: - * https://docs.python.org/2/library/inspect.html - * http://python-reference.readthedocs.io/en/latest/docs/code/index.html - For info on what each co_ variable provides + - https://docs.python.org/2/library/inspect.html + - http://python-reference.readthedocs.io/en/latest/docs/code/index.html + + For info on what each co\_ variable provides The signature is as follows (should be byte/chars): co_argcount, len(co_varnames), len(co_cellvars), len(co_freevars), @@ -281,8 +282,7 @@ def _code_contents(code, docstring=None): def _function_contents(func): - """Return the signature contents of a function. - + """ The signature is as follows (should be byte/chars): < _code_contents (see above) from func.__code__ > ,( comma separated _object_contents for function argument defaults) @@ -290,10 +290,12 @@ def _function_contents(func): See also: https://docs.python.org/3/reference/datamodel.html - func.__code__ - The code object representing the compiled function body. - func.__defaults__ - A tuple containing default argument values for those arguments - that have defaults, or None if no arguments have a default value - func.__closure__ - None or a tuple of cells that contain bindings for the function's free variables. + - func.__code__ - The code object representing the compiled function body. + - func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value + - func.__closure__ - None or a tuple of cells that contain bindings for the function's free variables. + + :Returns: + Signature contents of a function. (in bytes) """ contents = [_code_contents(func.__code__, func.__doc__)] @@ -330,9 +332,12 @@ def _function_contents(func): def _object_instance_content(obj): """ Returns consistant content for a action class or an instance thereof - :param obj: Should be either and action class or an instance thereof - :return: bytearray or bytes representing the obj suitable for generating - a signiture from. + + :Parameters: + - `obj` Should be either and action class or an instance thereof + + :Returns: + bytearray or bytes representing the obj suitable for generating a signature from. """ retval = bytearray() diff --git a/src/engine/SCons/Builder.py b/src/engine/SCons/Builder.py index 21f1b4ae..afc2cf0d 100644 --- a/src/engine/SCons/Builder.py +++ b/src/engine/SCons/Builder.py @@ -1,4 +1,5 @@ -"""SCons.Builder +""" +SCons.Builder Builder object subsystem. @@ -31,7 +32,7 @@ There is also a proxy that looks like a Builder: Builders and their proxies have the following public interface methods used by other modules: - __call__() + - __call__() THE public interface. Calling a Builder object (with the use of internal helper methods) sets up the target and source dependencies, appropriate mapping to a specific action, and the @@ -39,12 +40,12 @@ used by other modules: variable. This also takes care of warning about possible mistakes in keyword arguments. - add_emitter() + - add_emitter() Adds an emitter for a specific file suffix, used by some Tool modules to specify that (for example) a yacc invocation on a .y can create a .h *and* a .c file. - add_action() + - add_action() Adds an action for a specific file suffix, heavily used by Tool modules to add their specific action(s) for turning a source file into an object file to the global static @@ -52,23 +53,23 @@ used by other modules: There are the following methods for internal use within this module: - _execute() + - _execute() The internal method that handles the heavily lifting when a Builder is called. This is used so that the __call__() methods can set up warning about possible mistakes in keyword-argument overrides, and *then* execute all of the steps necessary so that the warnings only occur once. - get_name() + - get_name() Returns the Builder's name within a specific Environment, primarily used to try to return helpful information in error messages. - adjust_suffix() - get_prefix() - get_suffix() - get_src_suffix() - set_src_suffix() + - adjust_suffix() + - get_prefix() + - get_suffix() + - get_src_suffix() + - set_src_suffix() Miscellaneous stuff for handling the prefix and suffix manipulation we use in turning source file names into target file names. diff --git a/src/engine/SCons/Conftest.py b/src/engine/SCons/Conftest.py index 4db7e062..abaf00d4 100644 --- a/src/engine/SCons/Conftest.py +++ b/src/engine/SCons/Conftest.py @@ -706,11 +706,12 @@ def CheckProg(context, prog_name): def _YesNoResult(context, ret, key, text, comment = None): """ Handle the result of a test with a "yes" or "no" result. - "ret" is the return value: empty if OK, error message when not. - "key" is the name of the symbol to be defined (HAVE_foo). - "text" is the source code of the program used for testing. - "comment" is the C comment to add above the line defining the symbol (the - comment is automatically put inside a /* */). If None, no comment is added. + + :Parameters: + - `ret` is the return value: empty if OK, error message when not. + - `key` is the name of the symbol to be defined (HAVE_foo). + - `text` is the source code of the program used for testing. + - `comment` is the C comment to add above the line defining the symbol (the comment is automatically put inside a /\* \*/). If None, no comment is added. """ if key: _Have(context, key, not ret, comment) @@ -724,18 +725,20 @@ def _YesNoResult(context, ret, key, text, comment = None): def _Have(context, key, have, comment = None): """ Store result of a test in context.havedict and context.headerfilename. - "key" is a "HAVE_abc" name. It is turned into all CAPITALS and non- - alphanumerics are replaced by an underscore. + + :Parameters: + - `key` - is a "HAVE_abc" name. It is turned into all CAPITALS and non-alphanumerics are replaced by an underscore. + - `have` - value as it should appear in the header file, include quotes when desired and escape special characters! + - `comment` is the C comment to add above the line defining the symbol (the comment is automatically put inside a /\* \*/). If None, no comment is added. + + The value of "have" can be: - 1 - Feature is defined, add "#define key". - 0 - Feature is not defined, add "/* #undef key */". - Adding "undef" is what autoconf does. Not useful for the - compiler, but it shows that the test was done. - number - Feature is defined to this number "#define key have". - Doesn't work for 0 or 1, use a string then. - string - Feature is defined to this string "#define key have". - Give "have" as is should appear in the header file, include quotes - when desired and escape special characters! + - 1 - Feature is defined, add "#define key". + - 0 - Feature is not defined, add "/\* #undef key \*/". Adding "undef" is what autoconf does. Not useful for the compiler, but it shows that the test was done. + - number - Feature is defined to this number "#define key have". Doesn't work for 0 or 1, use a string then. + - string - Feature is defined to this string "#define key have". + + """ key_up = key.upper() key_up = re.sub('[^A-Z0-9_]', '_', key_up) @@ -786,10 +789,11 @@ def _lang2suffix(lang): When "lang" is empty or None C is assumed. Returns a tuple (lang, suffix, None) when it works. For an unrecognized language returns (None, None, msg). + Where: - lang = the unified language name - suffix = the suffix, including the leading dot - msg = an error message + - lang = the unified language name + - suffix = the suffix, including the leading dot + - msg = an error message """ if not lang or lang in ["C", "c"]: return ("C", ".c", None) diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py index 6a127db5..42b28e61 100644 --- a/src/engine/SCons/Environment.py +++ b/src/engine/SCons/Environment.py @@ -2189,13 +2189,16 @@ class Base(SubstitutionEnvironment): """This function converts a string or list into a list of strings or Nodes. This makes things easier for users by allowing files to be specified as a white-space separated list to be split. + The input rules are: - A single string containing names separated by spaces. These will be split apart at the spaces. - A single Node instance - A list containing either strings or Node instances. Any strings in the list are not split at spaces. + In all cases, the function returns a list of Nodes and strings.""" + if SCons.Util.is_List(arg): return list(map(self.subst, arg)) elif SCons.Util.is_String(arg): diff --git a/src/engine/SCons/Errors.py b/src/engine/SCons/Errors.py index 1df8cb91..2ba007cc 100644 --- a/src/engine/SCons/Errors.py +++ b/src/engine/SCons/Errors.py @@ -38,55 +38,55 @@ class BuildError(Exception): """ Errors occurring while building. BuildError have the following attributes: + ========================================= - Information about the cause of the build error: - ----------------------------------------------- + Information about the cause of the build error: + ----------------------------------------------- - errstr : a description of the error message + errstr : a description of the error message - status : the return code of the action that caused the build - error. Must be set to a non-zero value even if the - build error is not due to an action returning a - non-zero returned code. + status : the return code of the action that caused the build error. + Must be set to a non-zero value even if the build error is not due + to an action returning a non-zero returned code. - exitstatus : SCons exit status due to this build error. - Must be nonzero unless due to an explicit Exit() - call. Not always the same as status, since - actions return a status code that should be - respected, but SCons typically exits with 2 - irrespective of the return value of the failed - action. + exitstatus : SCons exit status due to this build error. + Must be nonzero unless due to an explicit Exit() + call. Not always the same as status, since + actions return a status code that should be + respected, but SCons typically exits with 2 + irrespective of the return value of the failed + action. - filename : The name of the file or directory that caused the - build error. Set to None if no files are associated with - this error. This might be different from the target - being built. For example, failure to create the - directory in which the target file will appear. It - can be None if the error is not due to a particular - filename. + filename : The name of the file or directory that caused the + build error. Set to None if no files are associated with + this error. This might be different from the target + being built. For example, failure to create the + directory in which the target file will appear. It + can be None if the error is not due to a particular + filename. - exc_info : Info about exception that caused the build - error. Set to (None, None, None) if this build - error is not due to an exception. + exc_info : Info about exception that caused the build + error. Set to (None, None, None) if this build + error is not due to an exception. - Information about the cause of the location of the error: - --------------------------------------------------------- + Information about the cause of the location of the error: + --------------------------------------------------------- - node : the error occured while building this target node(s) - - executor : the executor that caused the build to fail (might - be None if the build failures is not due to the - executor failing) - - action : the action that caused the build to fail (might be - None if the build failures is not due to the an - action failure) + node : the error occured while building this target node(s) - command : the command line for the action that caused the - build to fail (might be None if the build failures - is not due to the an action failure) - """ + executor : the executor that caused the build to fail (might + be None if the build failures is not due to the + executor failing) + + action : the action that caused the build to fail (might be + None if the build failures is not due to the an + action failure) + + command : the command line for the action that caused the + build to fail (might be None if the build failures + is not due to the an action failure) + """ def __init__(self, node=None, errstr="Unknown error", status=2, exitstatus=2, @@ -94,7 +94,6 @@ class BuildError(Exception): exc_info=(None, None, None)): # py3: errstr should be string and not bytes. - # import pdb; pdb.set_trace() self.errstr = SCons.Util.to_str(errstr) self.status = status @@ -142,13 +141,13 @@ def convert_to_BuildError(status, exc_info=None): """ Convert any return code a BuildError Exception. - `status' can either be a return code or an Exception. + :Parameters: + - `status`: can either be a return code or an Exception. + The buildError.status we set here will normally be used as the exit status of the "scons" process. """ - # import pdb; pdb.set_trace() - if not exc_info and isinstance(status, Exception): exc_info = (status.__class__, status, None) diff --git a/src/engine/SCons/Memoize.py b/src/engine/SCons/Memoize.py index 9774bdd3..5bdcf42b 100644 --- a/src/engine/SCons/Memoize.py +++ b/src/engine/SCons/Memoize.py @@ -34,7 +34,7 @@ values in a consistent way. In particular, it requires that the class uses a dictionary named "_memo" to store the cached values. Here is an example of wrapping a method that returns a computed value, -with no input parameters: +with no input parameters:: @SCons.Memoize.CountMethodCall def foo(self): @@ -51,7 +51,7 @@ with no input parameters: return result Here is an example of wrapping a method that will return different values -based on one or more input arguments: +based on one or more input arguments:: def _bar_key(self, argument): # Memoization return argument # Memoization diff --git a/src/engine/SCons/Node/FS.py b/src/engine/SCons/Node/FS.py index c31ac6c4..684f0d11 100644 --- a/src/engine/SCons/Node/FS.py +++ b/src/engine/SCons/Node/FS.py @@ -559,14 +559,13 @@ class Base(SCons.Node.Node): our relative and absolute paths, identify our parent directory, and indicate that this node should use signatures.""" + if SCons.Debug.track_instances: logInstanceCreation(self, 'Node.FS.Base') SCons.Node.Node.__init__(self) - # Filenames and paths are probably reused and are intern'ed to - # save some memory. - - #: Filename with extension as it was specified when the object was - #: created; to obtain filesystem path, use Python str() function + # Filenames and paths are probably reused and are intern'ed to save some memory. + # Filename with extension as it was specified when the object was + # created; to obtain filesystem path, use Python str() function self.name = SCons.Util.silent_intern(name) self.fs = fs #: Reference to parent Node.FS object @@ -2255,8 +2254,8 @@ class RootDir(Dir): name = drive dirname = drive + OS_SEP - #: Filename with extension as it was specified when the object was - #: created; to obtain filesystem path, use Python str() function + # Filename with extension as it was specified when the object was + # created; to obtain filesystem path, use Python str() function self.name = SCons.Util.silent_intern(name) self.fs = fs #: Reference to parent Node.FS object @@ -2959,7 +2958,7 @@ class File(Base): We'd like to remove a lot more attributes like self.sources and self.sources_set, but they might get used in a next build step. For example, during configuration - the source files for a built *.o file are used to figure out + the source files for a built E{*}.o file are used to figure out which linker to use for the resulting Program (gcc vs. g++)! That's why we check for the 'keep_targetinfo' attribute, config Nodes and the Interactive mode just don't allow @@ -3448,20 +3447,15 @@ class FileFinder(object): @SCons.Memoize.CountDictCall(_find_file_key) def find_file(self, filename, paths, verbose=None): """ - find_file(str, [Dir()]) -> [nodes] + Find a node corresponding to either a derived file or a file that exists already. - filename - a filename to find - paths - a list of directory path *nodes* to search in. Can be - represented as a list, a tuple, or a callable that is - called with no arguments and returns the list or tuple. + Only the first file found is returned, and none is returned if no file is found. - returns - the node created from the found file. + filename: A filename to find + paths: A list of directory path *nodes* to search in. Can be represented as a list, a tuple, or a callable that is called with no arguments and returns the list or tuple. - Find a node corresponding to either a derived file or a file - that exists already. + returns The node created from the found file. - Only the first file found is returned, and none is returned - if no file is found. """ memo_key = self._find_file_key(filename, paths) try: diff --git a/src/engine/SCons/SConf.py b/src/engine/SCons/SConf.py index 889af4a0..48eed8ee 100644 --- a/src/engine/SCons/SConf.py +++ b/src/engine/SCons/SConf.py @@ -459,9 +459,9 @@ class SConfBase(object): If value is None (default), then #define name is written. If value is not none, then #define name value is written. - comment is a string which will be put as a C comment in the - header, to explain the meaning of the value (appropriate C comments /* and - */ will be put automatically.""" + comment is a string which will be put as a C comment in the header, to explain the meaning of the value + (appropriate C comments will be added automatically). + """ lines = [] if comment: comment_str = "/* %s */" % comment diff --git a/src/engine/SCons/Scanner/LaTeX.py b/src/engine/SCons/Scanner/LaTeX.py index e5abb0c2..5800443a 100644 --- a/src/engine/SCons/Scanner/LaTeX.py +++ b/src/engine/SCons/Scanner/LaTeX.py @@ -78,8 +78,10 @@ def modify_env_var(env, var, abspath): return save class FindENVPathDirs(object): - """A class to bind a specific *PATH variable name to a function that - will return all of the *path directories.""" + """ + A class to bind a specific E{*}PATH variable name to a function that + will return all of the E{*}path directories. + """ def __init__(self, variable): self.variable = variable def __call__(self, env, dir=None, target=None, source=None, argument=None): @@ -96,7 +98,8 @@ class FindENVPathDirs(object): def LaTeXScanner(): - """Return a prototype Scanner instance for scanning LaTeX source files + """ + Return a prototype Scanner instance for scanning LaTeX source files when built with latex. """ ds = LaTeX(name = "LaTeXScanner", @@ -107,7 +110,8 @@ def LaTeXScanner(): return ds def PDFLaTeXScanner(): - """Return a prototype Scanner instance for scanning LaTeX source files + """ + Return a prototype Scanner instance for scanning LaTeX source files when built with pdflatex. """ ds = LaTeX(name = "PDFLaTeXScanner", @@ -118,7 +122,8 @@ def PDFLaTeXScanner(): return ds class LaTeX(SCons.Scanner.Base): - """Class for scanning LaTeX files for included files. + """ + Class for scanning LaTeX files for included files. Unlike most scanners, which use regular expressions that just return the included file name, this returns a tuple consisting @@ -135,10 +140,12 @@ class LaTeX(SCons.Scanner.Base): The actual subset and search order may be altered by DeclareGraphicsExtensions command. This complication is ignored. - The default order corresponds to experimentation with teTeX + The default order corresponds to experimentation with teTeX:: + $ latex --version pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4) kpathsea version 3.5.4 + The order is: ['.eps', '.ps'] for latex ['.png', '.pdf', '.jpg', '.tif']. @@ -150,8 +157,7 @@ class LaTeX(SCons.Scanner.Base): env['TEXINPUTS'] for "lstinputlisting" keyword env['BIBINPUTS'] for "bibliography" keyword env['BSTINPUTS'] for "bibliographystyle" keyword - env['INDEXSTYLE'] for "makeindex" keyword, no scanning support needed - just allows user to set it if needed. + env['INDEXSTYLE'] for "makeindex" keyword, no scanning support needed just allows user to set it if needed. FIXME: also look for the class or style in document[class|style]{} FIXME: also look for the argument of bibliographystyle{} diff --git a/src/engine/SCons/Scanner/__init__.py b/src/engine/SCons/Scanner/__init__.py index c0f1a933..f7828abe 100644 --- a/src/engine/SCons/Scanner/__init__.py +++ b/src/engine/SCons/Scanner/__init__.py @@ -62,8 +62,10 @@ def Scanner(function, *args, **kw): class FindPathDirs(object): - """A class to bind a specific *PATH variable name to a function that - will return all of the *path directories.""" + """ + A class to bind a specific E{*}PATH variable name to a function that + will return all of the E{*}path directories. + """ def __init__(self, variable): self.variable = variable def __call__(self, env, dir=None, target=None, source=None, argument=None): diff --git a/src/engine/SCons/Script/Interactive.py b/src/engine/SCons/Script/Interactive.py index 6be7b270..cc4f23cf 100644 --- a/src/engine/SCons/Script/Interactive.py +++ b/src/engine/SCons/Script/Interactive.py @@ -99,17 +99,14 @@ except ImportError: class SConsInteractiveCmd(cmd.Cmd): """\ - build [TARGETS] Build the specified TARGETS and their dependencies. - 'b' is a synonym. - clean [TARGETS] Clean (remove) the specified TARGETS and their - dependencies. 'c' is a synonym. - exit Exit SCons interactive mode. - help [COMMAND] Prints help for the specified COMMAND. 'h' and - '?' are synonyms. - shell [COMMANDLINE] Execute COMMANDLINE in a subshell. 'sh' and '!' - are synonyms. - version Prints SCons version information. - """ + +build [TARGETS] Build the specified TARGETS and their dependencies. 'b' is a synonym. +clean [TARGETS] Clean (remove) the specified TARGETS and their dependencies. 'c' is a synonym. +exit Exit SCons interactive mode. +help [COMMAND] Prints help for the specified COMMAND. 'h' and '?' are synonyms. +shell [COMMANDLINE] Execute COMMANDLINE in a subshell. 'sh' and '!' are synonyms. +version Prints SCons version information. +""" synonyms = { 'b' : 'build', diff --git a/src/engine/SCons/Taskmaster.py b/src/engine/SCons/Taskmaster.py index 9bd95975..17507a6f 100644 --- a/src/engine/SCons/Taskmaster.py +++ b/src/engine/SCons/Taskmaster.py @@ -25,16 +25,19 @@ from __future__ import print_function import sys __doc__ = """ -Generic Taskmaster module for the SCons build engine. - -This module contains the primary interface(s) between a wrapping user -interface and the SCons build engine. There are two key classes here: - + Generic Taskmaster module for the SCons build engine. + ===================================================== + + This module contains the primary interface(s) between a wrapping user + interface and the SCons build engine. There are two key classes here: + Taskmaster + ---------- This is the main engine for walking the dependency graph and calling things to decide what does or doesn't need to be built. Task + ---- This is the base class for allowing a wrapping interface to decide what does or doesn't actually need to be done. The intention is for a wrapping interface to subclass this as @@ -42,7 +45,7 @@ interface and the SCons build engine. There are two key classes here: The canonical example is the SCons native Python interface, which has Task subclasses that handle its specific behavior, - like printing "`foo' is up to date" when a top-level target + like printing "'foo' is up to date" when a top-level target doesn't need to be built, and handling the -c option by removing targets as its "build" action. There is also a separate subclass for suppressing this output when the -q option is used. @@ -689,14 +692,14 @@ class Taskmaster(object): at node A. The Taskmaster first considers whether node A's child B is up-to-date. Then, recursively, node B needs to check whether node C is up-to-date. This leaves us with a - dependency graph looking like: + dependency graph looking like:: - Next candidate \ - \ - Node A (Pending) --> Node B(Pending) --> Node C (NoState) - ^ | - | | - +-------------------------------------+ + Next candidate \ + \ + Node A (Pending) --> Node B(Pending) --> Node C (NoState) + ^ | + | | + +-------------------------------------+ Now, when the Taskmaster examines the Node C's child Node A, it finds that Node A is in the "pending" state. Therefore, @@ -705,15 +708,14 @@ class Taskmaster(object): Pending children indicate that the Taskmaster has potentially loop back through a cycle. We say potentially because it could also occur when a DAG is evaluated in parallel. For example, - consider the following graph: - - - Node A (Pending) --> Node B(Pending) --> Node C (Pending) --> ... - | ^ - | | - +----------> Node D (NoState) --------+ - / - Next candidate / + consider the following graph:: + + Node A (Pending) --> Node B(Pending) --> Node C (Pending) --> ... + | ^ + | | + +----------> Node D (NoState) --------+ + / + Next candidate / The Taskmaster first evaluates the nodes A, B, and C and starts building some children of node C. Assuming, that the diff --git a/src/engine/SCons/Util.py b/src/engine/SCons/Util.py index 846d06c9..f4783991 100644 --- a/src/engine/SCons/Util.py +++ b/src/engine/SCons/Util.py @@ -231,16 +231,17 @@ class DisplayEngine(object): def set_mode(self, mode): self.print_it = mode + def render_tree(root, child_func, prune=0, margin=[0], visited=None): """ Render a tree of nodes into an ASCII tree view. - root - the root node of the tree - child_func - the function called to get the children of a node - prune - don't visit the same node twice - margin - the format of the left margin to use for children of root. - 1 results in a pipe, and 0 results in no pipe. - visited - a dictionary of visited nodes in the current branch if not prune, - or in the whole tree if prune. + + :Parameters: + - `root`: the root node of the tree + - `child_func`: the function called to get the children of a node + - `prune`: don't visit the same node twice + - `margin`: the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe. + - `visited`: a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune. """ rname = str(root) @@ -281,14 +282,13 @@ def print_tree(root, child_func, prune=0, showtags=0, margin=[0], visited=None): lines directly instead of creating a string representation in memory, so that huge trees can be printed. - root - the root node of the tree - child_func - the function called to get the children of a node - prune - don't visit the same node twice - showtags - print status information to the left of each node line - margin - the format of the left margin to use for children of root. - 1 results in a pipe, and 0 results in no pipe. - visited - a dictionary of visited nodes in the current branch if not prune, - or in the whole tree if prune. + :Parameters: + - `root` - the root node of the tree + - `child_func` - the function called to get the children of a node + - `prune` - don't visit the same node twice + - `showtags` - print status information to the left of each node line + - `margin` - the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe. + - `visited` - a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune. """ rname = str(root) @@ -1454,19 +1454,20 @@ def make_path_relative(path): def AddMethod(obj, function, name=None): """ - Adds either a bound method to an instance or the function itself - (or an unbound method in Python 2) to a class. + Adds either a bound method to an instance or the function itself (or an unbound method in Python 2) to a class. If name is ommited the name of the specified function is used by default. - Example: - a = A() - def f(self, x, y): + + Example:: + + a = A() + def f(self, x, y): self.z = x + y - AddMethod(f, A, "add") - a.add(2, 4) - print(a.z) - AddMethod(lambda self, i: self.l[i], a, "listIndex") - print(a.listIndex(5)) + AddMethod(f, A, "add") + a.add(2, 4) + print(a.z) + AddMethod(lambda self, i: self.l[i], a, "listIndex") + print(a.listIndex(5)) """ if name is None: name = function.__name__ diff --git a/src/engine/SCons/Variables/BoolVariable.py b/src/engine/SCons/Variables/BoolVariable.py index c005a62d..ce46eda3 100644 --- a/src/engine/SCons/Variables/BoolVariable.py +++ b/src/engine/SCons/Variables/BoolVariable.py @@ -2,12 +2,12 @@ This file defines the option type for SCons implementing true/false values. -Usage example: +Usage example:: - opts = Variables() - opts.Add(BoolVariable('embedded', 'build for an embedded system', 0)) - ... - if env['embedded'] == 1: + opts = Variables() + opts.Add(BoolVariable('embedded', 'build for an embedded system', 0)) + ... + if env['embedded'] == 1: ... """ diff --git a/src/engine/SCons/Variables/EnumVariable.py b/src/engine/SCons/Variables/EnumVariable.py index 9448ba9a..a9fb1000 100644 --- a/src/engine/SCons/Variables/EnumVariable.py +++ b/src/engine/SCons/Variables/EnumVariable.py @@ -3,14 +3,14 @@ This file defines the option type for SCons allowing only specified input-values. -Usage example: +Usage example:: - opts = Variables() - opts.Add(EnumVariable('debug', 'debug output and symbols', 'no', + opts = Variables() + opts.Add(EnumVariable('debug', 'debug output and symbols', 'no', allowed_values=('yes', 'no', 'full'), map={}, ignorecase=2)) - ... - if env['debug'] == 'full': + ... + if env['debug'] == 'full': ... """ @@ -69,16 +69,14 @@ def EnumVariable(key, help, default, allowed_values, map={}, ignorecase=0): 'ignorecase' defines the behaviour of the validator: - If ignorecase == 0, the validator/converter are case-sensitive. - If ignorecase == 1, the validator/converter are case-insensitive. - If ignorecase == 2, the validator/converter is case-insensitive and - the converted value will always be lower-case. + If ignorecase == 0, the validator/converter are case-sensitive. + If ignorecase == 1, the validator/converter are case-insensitive. + If ignorecase == 2, the validator/converter is case-insensitive and the converted value will always be lower-case. - The 'validator' tests whether the value is in the list of allowed - values. The 'converter' converts input values according to the - given 'map'-dictionary (unmapped input values are returned - unchanged). + The 'validator' tests whether the value is in the list of allowed values. The 'converter' converts input values + according to the given 'map'-dictionary (unmapped input values are returned unchanged). """ + help = '%s (%s)' % (help, '|'.join(allowed_values)) # define validator if ignorecase >= 1: diff --git a/src/engine/SCons/Variables/ListVariable.py b/src/engine/SCons/Variables/ListVariable.py index f2fdc18f..90248676 100644 --- a/src/engine/SCons/Variables/ListVariable.py +++ b/src/engine/SCons/Variables/ListVariable.py @@ -7,17 +7,17 @@ separated by comma. After the option has been processed, the option value holds either the named list elements, all list elements or no list elements at all. -Usage example: +Usage example:: - list_of_libs = Split('x11 gl qt ical') + list_of_libs = Split('x11 gl qt ical') - opts = Variables() - opts.Add(ListVariable('shared', + opts = Variables() + opts.Add(ListVariable('shared', 'libraries to build as shared libraries', 'all', elems = list_of_libs)) - ... - for lib in list_of_libs: + ... + for lib in list_of_libs: if lib in env['shared']: env.SharedObject(...) else: diff --git a/src/engine/SCons/Variables/PackageVariable.py b/src/engine/SCons/Variables/PackageVariable.py index 4ab08567..a0ace253 100644 --- a/src/engine/SCons/Variables/PackageVariable.py +++ b/src/engine/SCons/Variables/PackageVariable.py @@ -13,18 +13,18 @@ Usage example: x11=yes (will search for the package installation dir) x11=/usr/local/X11 (will check this path for existence) - To replace autoconf's --with-xxx=yyy - - opts = Variables() - opts.Add(PackageVariable('x11', - 'use X11 installed here (yes = search some places', - 'yes')) - ... - if env['x11'] == True: - dir = ... search X11 in some standard places ... - env['x11'] = dir - if env['x11']: - ... build with x11 ... + To replace autoconf's --with-xxx=yyy :: + + opts = Variables() + opts.Add(PackageVariable('x11', + 'use X11 installed here (yes = search some places', + 'yes')) + ... + if env['x11'] == True: + dir = ... search X11 in some standard places ... + env['x11'] = dir + if env['x11']: + ... build with x11 ... """ # diff --git a/src/engine/SCons/Variables/PathVariable.py b/src/engine/SCons/Variables/PathVariable.py index e615a531..0ffcbc53 100644 --- a/src/engine/SCons/Variables/PathVariable.py +++ b/src/engine/SCons/Variables/PathVariable.py @@ -8,8 +8,7 @@ Arguments to PathVariable are: option-name = name of this option on the command line (e.g. "prefix") option-help = help string for option option-dflt = default value for this option - validator = [optional] validator for option value. Predefined - validators are: + validator = [optional] validator for option value. Predefined validators are: PathAccept -- accepts any path setting; no validation PathIsDir -- path must be an existing directory @@ -25,7 +24,7 @@ Arguments to PathVariable are: and the env is the env to which the Options have been added. -Usage example: +Usage example:: Examples: prefix=/usr/local @@ -34,8 +33,8 @@ Usage example: opts = Variables() opts.Add(PathVariable('qtdir', - 'where the root of Qt is installed', - qtdir, PathIsDir)) + 'where the root of Qt is installed', + qtdir, PathIsDir)) opts.Add(PathVariable('qt_includes', 'where the Qt includes are installed', '$qtdir/includes', PathIsDirCreate)) diff --git a/src/engine/SCons/Variables/__init__.py b/src/engine/SCons/Variables/__init__.py index 1fe44351..5b20b300 100644 --- a/src/engine/SCons/Variables/__init__.py +++ b/src/engine/SCons/Variables/__init__.py @@ -115,13 +115,13 @@ class Variables(object): """ Add an option. - key - the name of the variable, or a list or tuple of arguments - help - optional help text for the options - default - optional default value - validator - optional function that is called to validate the option's value - Called with (key, value, environment) - converter - optional function that is called to convert the option's value before - putting it in the environment. + + @param key: the name of the variable, or a list or tuple of arguments + @param help: optional help text for the options + @param default: optional default value + @param validator: optional function that is called to validate the option's value + @type validator: Called with (key, value, environment) + @param converter: optional function that is called to convert the option's value before putting it in the environment. """ if SCons.Util.is_List(key) or isinstance(key, tuple): @@ -141,14 +141,17 @@ class Variables(object): Each list element is a tuple/list of arguments to be passed on to the underlying method for adding options. - Example: - opt.AddVariables( + Example:: + + opt.AddVariables( ('debug', '', 0), ('CC', 'The C compiler'), ('VALIDATE', 'An option for testing validation', 'notset', validator, None), ) + """ + for o in optlist: self._do_add(*o) diff --git a/src/engine/SCons/cpp.py b/src/engine/SCons/cpp.py index 2e20017d..161f070a 100644 --- a/src/engine/SCons/cpp.py +++ b/src/engine/SCons/cpp.py @@ -26,7 +26,6 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" __doc__ = """ SCons C Pre-Processor module """ -#TODO 2.3 and before has no sorted() import SCons.compat import os @@ -543,9 +542,11 @@ class PreProcessor(object): This handles recursive expansion of values without "" or <> surrounding the name until an initial " or < is found, to handle + #include FILE - where FILE is a #define somewhere else. - """ + + where FILE is a #define somewhere else.""" + s = t[1] while not s[0] in '<"': #print("s =", s) diff --git a/src/engine/SCons/dblite.py b/src/engine/SCons/dblite.py index 4ef2222d..12b4f766 100644 --- a/src/engine/SCons/dblite.py +++ b/src/engine/SCons/dblite.py @@ -40,8 +40,8 @@ except NameError: dblite_suffix = '.dblite' # TODO: Does commenting this out break switching from py2/3? -# if bytes is not str: -# dblite_suffix += '.p3' +if bytes is not str: + dblite_suffix += '.p3' tmp_suffix = '.tmp' diff --git a/test/Interactive/help.py b/test/Interactive/help.py index 6020bdec..869876f1 100644 --- a/test/Interactive/help.py +++ b/test/Interactive/help.py @@ -57,15 +57,12 @@ scons.send('h\n') scons.send('?\n') help_text = """\ -build [TARGETS] Build the specified TARGETS and their dependencies. - 'b' is a synonym. -clean [TARGETS] Clean (remove) the specified TARGETS and their - dependencies. 'c' is a synonym. + +build [TARGETS] Build the specified TARGETS and their dependencies. 'b' is a synonym. +clean [TARGETS] Clean (remove) the specified TARGETS and their dependencies. 'c' is a synonym. exit Exit SCons interactive mode. -help [COMMAND] Prints help for the specified COMMAND. 'h' and - '?' are synonyms. -shell [COMMANDLINE] Execute COMMANDLINE in a subshell. 'sh' and '!' - are synonyms. +help [COMMAND] Prints help for the specified COMMAND. 'h' and '?' are synonyms. +shell [COMMANDLINE] Execute COMMANDLINE in a subshell. 'sh' and '!' are synonyms. version Prints SCons version information. """ -- cgit v1.2.1