Mercurial > bitten > bitten-test
changeset 411:a169d2e96463
Use reStructuredText as the API documentation syntax.
author | cmlenz |
---|---|
date | Tue, 07 Aug 2007 11:29:11 +0000 |
parents | 7930cdd83d13 |
children | 84b8cde2dfd4 |
files | bitten/__init__.py bitten/api.py bitten/build/__init__.py bitten/build/api.py bitten/build/config.py bitten/build/ctools.py bitten/build/javatools.py bitten/build/pythontools.py bitten/build/shtools.py bitten/build/svntools.py bitten/build/xmltools.py bitten/main.py bitten/master.py bitten/model.py bitten/queue.py bitten/recipe.py bitten/report/__init__.py bitten/report/coverage.py bitten/report/testing.py bitten/slave.py bitten/upgrades.py bitten/util/__init__.py bitten/util/loc.py bitten/util/testrunner.py bitten/util/xmlio.py bitten/web_ui.py |
diffstat | 26 files changed, 315 insertions(+), 249 deletions(-) [+] |
line wrap: on
line diff
--- a/bitten/__init__.py +++ b/bitten/__init__.py @@ -8,4 +8,7 @@ # you should have received as part of this distribution. The terms # are also available at http://bitten.edgewall.org/wiki/License. +from bitten.api import * + +__docformat__ = 'restructuredtext en' __version__ = '0.6'
--- a/bitten/api.py +++ b/bitten/api.py @@ -12,6 +12,10 @@ from trac.core import * +__all__ = ['IBuildListener', 'ILogFormatter', 'IReportChartGenerator', + 'IReportSummarizer'] +__docformat__ = 'restructuredtext en' + class IBuildListener(Interface): """Extension point interface for components that need to be notified of @@ -24,23 +28,23 @@ def build_started(build): """Called when a build slave has accepted a build initiation. - @param build: the build that was started - @type build: an instance of L{bitten.model.Build} + :param build: the build that was started + :type build: `Build` """ def build_aborted(build): """Called when a build slave cancels a build or disconnects. - @param build: the build that was aborted - @type build: an instance of L{bitten.model.Build} + :param build: the build that was aborted + :type build: `Build` """ def build_completed(build): """Called when a build slave has completed a build, regardless of the outcome. - @param build: the build that was aborted - @type build: an instance of L{bitten.model.Build} + :param build: the build that was aborted + :type build: `Build` """ @@ -51,14 +55,16 @@ def get_formatter(req, build): """Return a function that gets called for every log message. - The function must take four positional arguments, C{step}, - C{generator}, C{level} and C{message}, and return the formatted + The function must take four positional arguments, ``step``, + ``generator``, ``level`` and ``message``, and return the formatted message as a string. - @param req: the request object - @param build: the build to which the logs belong that should be - formatted - @type build: an instance of L{bitten.model.Build} + :param req: the request object + :param build: the build to which the logs belong that should be + formatted + :type build: `Build` + :return: the formatted log message + :rtype: `basestring` """ @@ -68,20 +74,22 @@ def get_supported_categories(): """Return a list of strings identifying the types of reports this - component supports.""" + component supports. + """ def render_summary(req, config, build, step, category): """Render a summary for the given report and return the resulting HTML as string. - @param req: the request object - @param config: the build configuration - @type config: an instance of L{bitten.model.BuildConfig} - @param build: the build - @type build: an instance of L{bitten.model.Build} - @param step: the build step - @type step: an instance of L{bitten.model.BuildStep} - @param category: the category of the report that should be summarized + :param req: the request object + :param config: the build configuration + :type config: `BuildConfig` + :param build: the build + :type build: `Build` + :param step: the build step + :type step: `BuildStep` + :param category: the category of the report that should be summarized + :type category: `basestring` """ @@ -91,7 +99,8 @@ def get_supported_categories(): """Return a list of strings identifying the types of reports this - component supports.""" + component supports. + """ def generate_chart_data(req, config, category): """Generate the data for a report chart. @@ -99,8 +108,9 @@ This method should store the data in the HDF of the request and return the name of the template that should process the data. - @param req: the request object - @param config: the build configuration - @type config: an instance of L{bitten.model.BuildConfig} - @param category: the category of reports to include in the chart + :param req: the request object + :param config: the build configuration + :type config: `BuildConfig` + :param category: the category of reports to include in the chart + :type category: `basestring` """
--- a/bitten/build/__init__.py +++ b/bitten/build/__init__.py @@ -8,4 +8,6 @@ # you should have received as part of this distribution. The terms # are also available at http://bitten.edgewall.org/wiki/License. -from bitten.build.api import * \ No newline at end of file +from bitten.build.api import * + +__docformat__ = 'restructuredtext en'
--- a/bitten/build/api.py +++ b/bitten/build/api.py @@ -18,6 +18,8 @@ log = logging.getLogger('bitten.build.api') +__docformat__ = 'restructuredtext en' + class BuildError(Exception): """Exception raised when a build fails.""" @@ -50,12 +52,12 @@ def __init__(self, executable, args, input=None, cwd=None): """Initialize the CommandLine object. - @param executable: the name of the program to execute - @param args: a list of arguments to pass to the executable - @param input: string or file-like object containing any input data for - the program - @param cwd: The working directory to change to before executing the - command + :param executable: the name of the program to execute + :param args: a list of arguments to pass to the executable + :param input: string or file-like object containing any input data for + the program + :param cwd: the working directory to change to before executing the + command """ self.executable = executable self.arguments = [str(arg) for arg in args] @@ -71,8 +73,8 @@ """Execute the command, and return a generator for iterating over the output written to the standard output and error streams. - @param timeout: number of seconds before the external process - should be aborted (not supported on Windows) + :param timeout: number of seconds before the external process + should be aborted (not supported on Windows) """ args = [self.executable] + self.arguments for idx, arg in enumerate(args): @@ -137,8 +139,8 @@ """Execute the command, and return a generator for iterating over the output written to the standard output and error streams. - @param timeout: number of seconds before the external process - should be aborted (not supported on Windows) + :param timeout: number of seconds before the external process + should be aborted (not supported on Windows) """ import popen2, select if self.cwd: @@ -229,13 +231,13 @@ '.DS_Store', 'Thumbs.db'] def __init__(self, basedir, include=None, exclude=None): - """Create the file set. + """Create a file set. - @param basedir: the base directory for all files in the set - @param include: a list of patterns that define which files should be - included in the set - @param exclude: a list of patterns that define which files should be - excluded from the set + :param basedir: the base directory for all files in the set + :param include: a list of patterns that define which files should be + included in the set + :param exclude: a list of patterns that define which files should be + excluded from the set """ self.files = [] self.basedir = basedir @@ -283,6 +285,6 @@ def __contains__(self, filename): """Return whether the given file name is in the set. - @param filename: the name of the file to check + :param filename: the name of the file to check """ return filename in self.files
--- a/bitten/build/config.py +++ b/bitten/build/config.py @@ -18,6 +18,8 @@ log = logging.getLogger('bitten.config') +__docformat__ = 'restructuredtext en' + class Configuration(object): """Encapsulates the configuration of a build machine. @@ -33,8 +35,8 @@ def __init__(self, filename=None, properties=None): """Create the configuration object. - @param filename: The path to the configuration file, if any - @param properties: A dictionary of the configuration properties + :param filename: the path to the configuration file, if any + :param properties: a dictionary of the configuration properties provided on the command-line """ self.properties = {} @@ -94,8 +96,8 @@ """Return whether the configuration contains a value for the specified key. - @param key: name of the configuration option using dotted notation - (for example, "python.path") + :param key: name of the configuration option using dotted notation + (for example, "python.path") """ if '.' in key: package, propname = key.split('.', 1) @@ -105,8 +107,8 @@ def __getitem__(self, key): """Return the value for the specified configuration key. - @param key: name of the configuration option using dotted notation - (for example, "python.path") + :param key: name of the configuration option using dotted notation + (for example, "python.path") """ if '.' in key: package, propname = key.split('.', 1) @@ -120,10 +122,10 @@ """Return the value of the specified configuration key, but verify that the value refers to the path of an existing directory. - If the value does not exist, or is not a directory path, return C{None}. + If the value does not exist, or is not a directory path, return `None`. - @param key: name of the configuration option using dotted notation - (for example, "ant.home") + :param key: name of the configuration option using dotted notation + (for example, "ant.home") """ dirpath = self[key] if dirpath: @@ -136,10 +138,10 @@ """Return the value of the specified configuration key, but verify that the value refers to the path of an existing file. - If the value does not exist, or is not a file path, return C{None}. + If the value does not exist, or is not a file path, return `None`. - @param key: name of the configuration option using dotted notation - (for example, "python.path") + :param key: name of the configuration option using dotted notation + (for example, "python.path") """ filepath = self[key] if filepath: @@ -154,14 +156,14 @@ """Interpolate configuration properties into a string. Properties can be referenced in the text using the notation - C{${property.name}}. A default value can be provided by appending it to + ``${property.name}``. A default value can be provided by appending it to the property name separated by a colon, for example - C{${property.name:defaultvalue}}. This value will be used when there's + ``${property.name:defaultvalue}``. This value will be used when there's no such property in the configuration. Otherwise, if no default is provided, the reference is not replaced at all. - @param text: the string containing variable references - @param vars: extra variables to use for the interpolation + :param text: the string containing variable references + :param vars: extra variables to use for the interpolation """ def _replace(m): refname = m.group('ref')
--- a/bitten/build/ctools.py +++ b/bitten/build/ctools.py @@ -23,19 +23,21 @@ log = logging.getLogger('bitten.build.ctools') +__docformat__ = 'restructuredtext en' + def configure(ctxt, file_='configure', enable=None, disable=None, with=None, without=None, cflags=None, cxxflags=None): - """Run a C{configure} script. + """Run a ``configure`` script. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the configure script - @param enable: names of the features to enable, seperated by spaces - @param disable: names of the features to disable, separated by spaces - @param with: names of external packages to include - @param without: names of external packages to exclude - @param cflags: C{CFLAGS} to pass to the configure script - @param cxxflags: C{CXXFLAGS} to pass to the configure script + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the configure script + :param enable: names of the features to enable, seperated by spaces + :param disable: names of the features to disable, separated by spaces + :param with: names of external packages to include + :param without: names of external packages to exclude + :param cflags: ``CFLAGS`` to pass to the configure script + :param cxxflags: ``CXXFLAGS`` to pass to the configure script """ args = [] if enable: @@ -64,11 +66,11 @@ def make(ctxt, target=None, file_=None, keep_going=False): """Execute a Makefile target. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the Makefile - @param keep_going: whether make should keep going when errors are - encountered + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the Makefile + :param keep_going: whether make should keep going when errors are + encountered """ executable = ctxt.config.get_filepath('make.path') or 'make' @@ -88,12 +90,12 @@ def cppunit(ctxt, file_=None, srcdir=None): """Collect CppUnit XML data. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: path of the file containing the CppUnit results; may contain - globbing wildcards to match multiple files - @param srcdir: name of the directory containing the source files, used to - link the test results to the corresponding files + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: path of the file containing the CppUnit results; may contain + globbing wildcards to match multiple files + :param srcdir: name of the directory containing the source files, used to + link the test results to the corresponding files """ assert file_, 'Missing required attribute "file"' @@ -155,14 +157,14 @@ log.warning('Error parsing CppUnit results file (%s)', e) def gcov(ctxt, include=None, exclude=None, prefix=None): - """Run C{gcov} to extract coverage data where available. + """Run ``gcov`` to extract coverage data where available. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param include: patterns of files and directories to include - @param exclude: patterns of files and directories that should be excluded - @param prefix: optional prefix name that is added to object files by the - build system + :param ctxt: the build context + :type ctxt: `Context` + :param include: patterns of files and directories to include + :param exclude: patterns of files and directories that should be excluded + :param prefix: optional prefix name that is added to object files by the + build system """ file_re = re.compile(r'^File \`(?P<file>[^\']+)\'\s*$') lines_re = re.compile(r'^Lines executed:(?P<cov>\d+\.\d+)\% of (?P<num>\d+)\s*$')
--- a/bitten/build/javatools.py +++ b/bitten/build/javatools.py @@ -23,15 +23,17 @@ log = logging.getLogger('bitten.build.javatools') +__docformat__ = 'restructuredtext en' + def ant(ctxt, file_=None, target=None, keep_going=False, args=None): """Run an Ant build. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the Ant build file - @param target: name of the target that should be executed (optional) - @param keep_going: whether Ant should keep going when errors are encountered - @param args: additional arguments to pass to Ant + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the Ant build file + :param target: name of the target that should be executed (optional) + :param keep_going: whether Ant should keep going when errors are encountered + :param args: additional arguments to pass to Ant """ executable = 'ant' ant_home = ctxt.config.get_dirpath('ant.home') @@ -97,12 +99,12 @@ def junit(ctxt, file_=None, srcdir=None): """Extract test results from a JUnit XML report. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: path to the JUnit XML test results; may contain globbing - wildcards for matching multiple results files - @param srcdir: name of the directory containing the test sources, used to - link test results to the corresponding source files + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: path to the JUnit XML test results; may contain globbing + wildcards for matching multiple results files + :param srcdir: name of the directory containing the test sources, used to + link test results to the corresponding source files """ assert file_, 'Missing required attribute "file"' try: @@ -144,6 +146,7 @@ except xmlio.ParseError, e: log.warning('Error parsing JUnit results file (%s)', e) + class _LineCounter(object): def __init__(self): self.lines = []
--- a/bitten/build/pythontools.py +++ b/bitten/build/pythontools.py @@ -25,11 +25,13 @@ log = logging.getLogger('bitten.build.pythontools') +__docformat__ = 'restructuredtext en' + def _python_path(ctxt): """Return the path to the Python interpreter. - If the configuration has a `python.path` property, the value of that option - is returned; otherwise the path to the current Python interpreter is + If the configuration has a ``python.path`` property, the value of that + option is returned; otherwise the path to the current Python interpreter is returned. """ python_path = ctxt.config.get_filepath('python.path') @@ -38,13 +40,13 @@ return sys.executable def distutils(ctxt, file_='setup.py', command='build', options=None): - """Execute a C{distutils} command. + """Execute a ``distutils`` command. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the file defining the distutils setup - @param command: the setup command to execute - @param options: additional options to pass to the command + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the file defining the distutils setup + :param command: the setup command to execute + :param options: additional options to pass to the command """ if options: if isinstance(options, basestring): @@ -81,18 +83,18 @@ def exec_(ctxt, file_=None, module=None, function=None, output=None, args=None): """Execute a Python script. - Either the C{file_} or the C{module} parameter must be provided. If - specified using the C{file_} parameter, the file must be inside the project + Either the `file_` or the `module` parameter must be provided. If + specified using the `file_` parameter, the file must be inside the project directory. If specified as a module, the module must either be resolvable - to a file, or the C{function} parameter must be provided + to a file, or the `function` parameter must be provided - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the script file to execute - @param module: name of the Python module to execute - @param function: name of the Python function to run - @param output: name of the file to which output should be written - @param args: extra arguments to pass to the script + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the script file to execute + :param module: name of the Python module to execute + :param function: name of the Python function to run + :param output: name of the file to which output should be written + :param args: extra arguments to pass to the script """ assert file_ or module, 'Either "file" or "module" attribute required' if function: @@ -121,11 +123,11 @@ output=output, args=args) def pylint(ctxt, file_=None): - """Extract data from a C{pylint} run written to a file. + """Extract data from a ``pylint`` run written to a file. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the file containing the Pylint output + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the file containing the Pylint output """ assert file_, 'Missing required attribute "file"' msg_re = re.compile(r'^(?P<file>.+):(?P<line>\d+): ' @@ -162,15 +164,15 @@ log.warning('Error opening pylint results file (%s)', e) def trace(ctxt, summary=None, coverdir=None, include=None, exclude=None): - """Extract data from a C{trace.py} run. + """Extract data from a ``trace.py`` run. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param summary: path to the file containing the coverage summary - @param coverdir: name of the directory containing the per-module coverage - details - @param include: patterns of files or directories to include in the report - @param exclude: patterns of files or directories to exclude from the report + :param ctxt: the build context + :type ctxt: `Context` + :param summary: path to the file containing the coverage summary + :param coverdir: name of the directory containing the per-module coverage + details + :param include: patterns of files or directories to include in the report + :param exclude: patterns of files or directories to exclude from the report """ assert summary, 'Missing required attribute "summary"' assert coverdir, 'Missing required attribute "coverdir"' @@ -294,9 +296,9 @@ def unittest(ctxt, file_=None): """Extract data from a unittest results file in XML format. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param file_: name of the file containing the test results + :param ctxt: the build context + :type ctxt: `Context` + :param file\_: name of the file containing the test results """ assert file_, 'Missing required attribute "file"'
--- a/bitten/build/shtools.py +++ b/bitten/build/shtools.py @@ -19,17 +19,19 @@ log = logging.getLogger('bitten.build.shtools') +__docformat__ = 'restructuredtext en' + def exec_(ctxt, executable=None, file_=None, output=None, args=None): """Execute a program or shell script. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param executable: name of the executable to run - @param file_: name of the script file, relative to the project directory, - that should be run - @param output: name of the file to which the output of the script should be - written - @param args: command-line arguments to pass to the script + :param ctxt: the build context + :type ctxt: `Context` + :param executable: name of the executable to run + :param file\_: name of the script file, relative to the project directory, + that should be run + :param output: name of the file to which the output of the script should be + written + :param args: command-line arguments to pass to the script """ assert executable or file_, \ 'Either "executable" or "file" attribute required' @@ -44,16 +46,16 @@ args=None): """Pipe the contents of a file through a program or shell script. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param executable: name of the executable to run - @param file_: name of the script file, relative to the project directory, - that should be run - @param input_: name of the file containing the data that should be passed - to the shell script on its standard input stream - @param output: name of the file to which the output of the script should be - written - @param args: command-line arguments to pass to the script + :param ctxt: the build context + :type ctxt: `Context` + :param executable: name of the executable to run + :param file\_: name of the script file, relative to the project directory, + that should be run + :param input\_: name of the file containing the data that should be passed + to the shell script on its standard input stream + :param output: name of the file to which the output of the script should be + written + :param args: command-line arguments to pass to the script """ assert executable or file_, \ 'Either "executable" or "file" attribute required' @@ -72,16 +74,16 @@ This function is not itself bound to a recipe command, but rather used from other commands. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param executable: name of the executable to run - @param file_: name of the script file, relative to the project directory, - that should be run - @param input_: name of the file containing the data that should be passed - to the shell script on its standard input stream - @param output: name of the file to which the output of the script should be - written - @param args: command-line arguments to pass to the script + :param ctxt: the build context + :type ctxt: `Context` + :param executable: name of the executable to run + :param file\_: name of the script file, relative to the project directory, + that should be run + :param input\_: name of the file containing the data that should be passed + to the shell script on its standard input stream + :param output: name of the file to which the output of the script should be + written + :param args: command-line arguments to pass to the script """ if args: if isinstance(args, basestring):
--- a/bitten/build/svntools.py +++ b/bitten/build/svntools.py @@ -15,14 +15,16 @@ log = logging.getLogger('bitten.build.svntools') +__docformat__ = 'restructuredtext en' + def checkout(ctxt, url, path=None, revision=None): """Perform a checkout from a Subversion repository. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param url: the URL of the repository - @param path: the path inside the repository - @param revision: the revision to check out + :param ctxt: the build context + :type ctxt: `Context` + :param url: the URL of the repository + :param path: the path inside the repository + :param revision: the revision to check out """ args = ['checkout'] if revision: @@ -39,11 +41,11 @@ def export(ctxt, url, path=None, revision=None): """Perform an export from a Subversion repository. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param url: the URL of the repository - @param path: the path inside the repository - @param revision: the revision to check out + :param ctxt: the build context + :type ctxt: `Context` + :param url: the URL of the repository + :param path: the path inside the repository + :param revision: the revision to check out """ args = ['export', '--force'] if revision: @@ -60,9 +62,9 @@ def update(ctxt, revision=None): """Update the local working copy from the Subversion repository. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param revision: the revision to check out + :param ctxt: the build context + :type ctxt: `Context` + :param revision: the revision to check out """ args = ['update'] if revision:
--- a/bitten/build/xmltools.py +++ b/bitten/build/xmltools.py @@ -34,17 +34,19 @@ log = logging.getLogger('bitten.build.xmltools') +__docformat__ = 'restructuredtext en' + def transform(ctxt, src=None, dest=None, stylesheet=None): """Apply an XSLT stylesheet to a source XML document. This command requires either libxslt (with Python bindings), or MSXML to be installed. - @param ctxt: the build context - @type ctxt: an instance of L{bitten.recipe.Context} - @param src: name of the XML input file - @param dest: name of the XML output file - @param stylesheet: name of the file containing the XSLT stylesheet + :param ctxt: the build context + :type ctxt: `Context` + :param src: name of the XML input file + :param dest: name of the XML output file + :param stylesheet: name of the file containing the XSLT stylesheet """ assert src, 'Missing required attribute "src"' assert dest, 'Missing required attribute "dest"'
--- a/bitten/main.py +++ b/bitten/main.py @@ -20,6 +20,9 @@ from bitten.api import IBuildListener from bitten.model import schema, schema_version, Build, BuildConfig +__all__ = ['BuildSystem'] +__docformat__ = 'restructuredtext en' + class BuildSystem(Component):
--- a/bitten/master.py +++ b/bitten/master.py @@ -35,6 +35,9 @@ from bitten.recipe import Recipe from bitten.util import xmlio +__all__ = ['BuildMaster'] +__docformat__ = 'restructuredtext en' + class BuildMaster(Component): """BEEP listener implementation for the build master."""
--- a/bitten/model.py +++ b/bitten/model.py @@ -17,6 +17,8 @@ from trac.db import Table, Column, Index +__docformat__ = 'restructuredtext en' + class BuildConfig(object): """Representation of a build configuration."""
--- a/bitten/queue.py +++ b/bitten/queue.py @@ -14,7 +14,7 @@ Trac environment. It is used by both the build master and the web interface to get the list of required builds (revisions not built yet). -Furthermore, the C{BuildQueue} class is used by the build master to determine +Furthermore, the `BuildQueue` class is used by the build master to determine the next pending build, and to match build slaves against configured target platforms. """ @@ -26,6 +26,8 @@ from trac.versioncontrol import NoSuchNode from bitten.model import BuildConfig, TargetPlatform, Build, BuildStep +__docformat__ = 'restructuredtext en' + log = logging.getLogger('bitten.queue') @@ -33,14 +35,13 @@ """Collect all changes for a build configuration that either have already been built, or still need to be built. - This function is a generator that yields C{(platform, rev, build)} tuples, - where C{platform} is a L{bitten.model.TargetPlatform} object, C{rev} is the - identifier of the changeset, and C{build} is a L{bitten.model.Build} object - or C{None}. + This function is a generator that yields ``(platform, rev, build)`` tuples, + where ``platform`` is a `TargetPlatform` object, ``rev`` is the identifier + of the changeset, and ``build`` is a `Build` object or `None`. - @param repos: the version control repository - @param config: the build configuration - @param db: a database connection (optional) + :param repos: the version control repository + :param config: the build configuration + :param db: a database connection (optional) """ env = config.env if not db: @@ -97,8 +98,8 @@ def __init__(self, env, build_all=False): """Create the build queue. - @param env: the Trac environment - @param build_all: whether older revisions should be built + :param env: the Trac environment + :param build_all: whether older revisions should be built """ self.env = env self.log = env.log @@ -110,11 +111,12 @@ """Check whether one of the pending builds can be built by the build slave. - If such a build is found, this method returns a C{(build, slave)} - tuple, where C{build} is the L{bitten.model.Build} object and C{slave} - is the name of the build slave that should handle the build. - - Otherwise, this function will return C{(None, None)} + :param name: the name of the slave + :type name: `basestring` + :param properties: the slave configuration + :type properties: `dict` + :return: the allocated build, or `None` if no build was found + :rtype: `Build` """ log.debug('Checking for pending builds...') @@ -155,9 +157,11 @@ def match_slave(self, name, properties): """Match a build slave against available target platforms. - @param name: The name of the slave - @param properties: A dict containing the properties of the slave - @return: the list of platforms the slave matched + :param name: the name of the slave + :type name: `basestring` + :param properties: the slave configuration + :type properties: `dict` + :return: the list of platforms the slave matched """ platforms = [] @@ -221,7 +225,7 @@ db.commit() def reset_orphaned_builds(self): - """Reset all in-progress builds to PENDING state. + """Reset all in-progress builds to ``PENDING`` state. This is used to cleanup after a crash of the build master process, which would leave in-progress builds in the database that aren't
--- a/bitten/recipe.py +++ b/bitten/recipe.py @@ -11,7 +11,7 @@ """Execution of build recipes. This module provides various classes that can be used to process build recipes, -most importantly the L{Recipe} class. +most importantly the `Recipe` class. """ import keyword @@ -27,7 +27,8 @@ from bitten.build.config import Configuration from bitten.util import xmlio -__all__ = ['Recipe', 'InvalidRecipeError'] +__all__ = ['Context', 'Recipe', 'Step', 'InvalidRecipeError'] +__docformat__ = 'restructuredtext en' log = logging.getLogger('bitten.recipe') @@ -45,9 +46,9 @@ def __init__(self, basedir, config=None, vars=None): """Initialize the context. - @param basedir: a string containing the working directory for the build - @param config: the build slave configuration - @type config: an instance of L{bitten.build.config.Configuration} + :param basedir: a string containing the working directory for the build + :param config: the build slave configuration + :type config: `Configuration` """ self.basedir = os.path.realpath(basedir) self.config = config or Configuration() @@ -57,11 +58,11 @@ def run(self, step, namespace, name, attr): """Run the specified recipe command. - @param step: the build step that the command belongs to - @param namespace: the namespace URI of the command - @param name: the local tag name of the command - @param attr: a dictionary containing the attributes defined on the - command element + :param step: the build step that the command belongs to + :param namespace: the namespace URI of the command + :param name: the local tag name of the command + :param attr: a dictionary containing the attributes defined on the + command element """ self.step = step @@ -98,31 +99,31 @@ def error(self, message): """Record an error message. - @param message: A string containing the error message. + :param message: a string containing the error message. """ self.output.append((Recipe.ERROR, None, self.generator, message)) def log(self, xml): """Record log output. - @param xml: an XML fragment containing the log messages + :param xml: an XML fragment containing the log messages """ self.output.append((Recipe.LOG, None, self.generator, xml)) def report(self, category, xml): """Record report data. - @param category: the name of category of the report - @param xml: an XML fragment containing the report data + :param category: the name of category of the report + :param xml: an XML fragment containing the report data """ self.output.append((Recipe.REPORT, category, self.generator, xml)) def report_file(self, category=None, file_=None): """Read report data from a file and record it. - @param category: the name of the category of the report - @param file_: the path to the file containing the report data, relative - to the base directory + :param category: the name of the category of the report + :param file\_: the path to the file containing the report data, relative + to the base directory """ filename = self.resolve(file_) try: @@ -167,8 +168,8 @@ def __init__(self, elem): """Create the step. - @param elem: the XML element representing the step - @type elem: an instance of L{bitten.util.xmlio.ParsedElement} + :param elem: the XML element representing the step + :type elem: `ParsedElement` """ self._elem = elem self.id = elem.attr['id'] @@ -181,8 +182,8 @@ def execute(self, ctxt): """Execute this step in the given context. - @param ctxt: the build context - @type ctxt: an instance of L{Context} + :param ctxt: the build context + :type ctxt: `Context` """ for child in self._elem: ctxt.run(self, child.namespace, child.name, child.attr) @@ -214,11 +215,11 @@ def __init__(self, xml, basedir=os.getcwd(), config=None): """Create the recipe. - @param xml: the XML document representing the recipe - @type xml: an instance of L{bitten.util.xmlio.ParsedElement} - @param basedir: the base directory for the build - @param config: the slave configuration (optional) - @type config: an instance of L{bitten.build.config.Configuration} + :param xml: the XML document representing the recipe + :type xml: `ParsedElement` + :param basedir: the base directory for the build + :param config: the slave configuration (optional) + :type config: `Configuration` """ assert isinstance(xml, xmlio.ParsedElement) vars = dict([(name, value) for name, value in xml.attr.items() @@ -243,8 +244,8 @@ - a step must contain at least one nested command - commands must not have nested content - @raise InvalidRecipeError: in case any of the above contraints is - violated + :raise InvalidRecipeError: in case any of the above contraints is + violated """ if self._root.name != 'build': raise InvalidRecipeError('Root element must be <build>')
--- a/bitten/report/__init__.py +++ b/bitten/report/__init__.py @@ -6,3 +6,5 @@ # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms # are also available at http://bitten.edgewall.org/wiki/License. + +__docformat__ = 'restructuredtext en'
--- a/bitten/report/coverage.py +++ b/bitten/report/coverage.py @@ -13,6 +13,8 @@ from trac.web.clearsilver import HDFWrapper from bitten.api import IReportChartGenerator, IReportSummarizer +__docformat__ = 'restructuredtext en' + class TestCoverageChartGenerator(Component): implements(IReportChartGenerator)
--- a/bitten/report/testing.py +++ b/bitten/report/testing.py @@ -13,6 +13,8 @@ from trac.web.clearsilver import HDFWrapper from bitten.api import IReportChartGenerator, IReportSummarizer +__docformat__ = 'restructuredtext en' + class TestResultsChartGenerator(Component): implements(IReportChartGenerator)
--- a/bitten/slave.py +++ b/bitten/slave.py @@ -29,6 +29,9 @@ from bitten.recipe import Recipe, InvalidRecipeError from bitten.util import xmlio +__all__ = ['BuildSlave', 'ExitSlave'] +__docformat__ = 'restructuredtext en' + log = logging.getLogger('bitten.slave') @@ -51,20 +54,19 @@ username=None, password=None): """Create the build slave instance. - @param url: The URL of the build master - @param port: TCP port number of the build master to connect to - @param name: The name with which this slave should identify itself - @param config: The slave configuration - @param dry_run: Whether the build outcome should not be reported back - to the master - @param work_dir: The working directory to use for build execution - @param keep_files: Whether files and directories created for build - execution should be kept when done - @param single_build: Whether this slave should exit after completing a - single build, or continue processing builds forever - @param username: the username to use when authentication against the - build master is requested - @param password: the password to use when authentication is needed + :param url: The URL of the build master + :param name: The name with which this slave should identify itself + :param config: The slave configuration + :param dry_run: Whether the build outcome should not be reported back + to the master + :param work_dir: The working directory to use for build execution + :param keep_files: Whether files and directories created for build + execution should be kept when done + :param single_build: Whether this slave should exit after completing a + single build, or continue processing builds forever + :param username: the username to use when authentication against the + build master is requested + :param password: the password to use when authentication is needed """ self.url = url if name is None: @@ -214,7 +216,8 @@ class ExitSlave(Exception): """Exception used internally by the slave to signal that the slave process - should be stopped.""" + should be stopped. + """ def main():
--- a/bitten/upgrades.py +++ b/bitten/upgrades.py @@ -16,6 +16,8 @@ from trac.db import DatabaseManager +__docformat__ = 'restructuredtext en' + def add_log_table(env, db): """Add a table for storing the builds logs.""" from bitten.model import BuildLog, BuildStep
--- a/bitten/util/__init__.py +++ b/bitten/util/__init__.py @@ -13,3 +13,5 @@ Functionality in these modules have no dependencies on modules outside of this package, so that they could theoretically be used in other projects. """ + +__docformat__ = 'restructuredtext en'
--- a/bitten/util/loc.py +++ b/bitten/util/loc.py @@ -22,6 +22,9 @@ import re +__all__ = ['BLANK', 'CODE', 'COMMENT', 'DOC', 'count'] +__docformat__ = 'restructuredtext en' + # Reg. exps. to find the end of a triple quote, given that # we know we're in one; use the "match" method; .span()[1] # will be the index of the character following the final @@ -64,11 +67,12 @@ def count(source): """Parse the given file-like object as Python source code. - For every line, return a C{(lineno, type, line)} tuple, where C{lineno} - is the line number (starting at 0), C{type} is one of C{BLANK}, C{CODE}, - C{COMMENT} or C{DOC}, and C{line} is the actual content of the line. - - @param source: a file-like object containing Python code + For every line in the code, this function yields a ``(lineno, type, line)`` + tuple, where ``lineno`` is the line number (starting at 0), ``type`` is + one of `BLANK`, `CODE`, `COMMENT` or `DOC`, and ``line`` is the actual + content of the line. + + :param source: a file-like object containing Python code """ quote3_finder = {'"': _dquote3_finder, "'": _squote3_finder}
--- a/bitten/util/testrunner.py +++ b/bitten/util/testrunner.py @@ -23,6 +23,8 @@ from bitten import __version__ as VERSION from bitten.util import xmlio +__docformat__ = 'restructuredtext en' + class XMLTestResult(_TextTestResult):
--- a/bitten/util/xmlio.py +++ b/bitten/util/xmlio.py @@ -20,7 +20,8 @@ from StringIO import StringIO from UserDict import DictMixin -__all__ = ['Element', 'parse'] +__all__ = ['Fragment', 'Element', 'ParsedElement', 'parse'] +__docformat__ = 'restructuredtext en' def _escape_text(text): """Escape special characters in the provided text so that it can be safely @@ -202,7 +203,8 @@ <root/> For convenience, this is also done when coercing the object to a string - using the builtin `str()` function, which is used when `print`ing an object: + using the builtin ``str()`` function, which is used when printing an + object: >>> print parse('<root></root>') <root/>