Package buildbot :: Module interfaces :: Class IStatusLog
[frames] | no frames]

Class IStatusLog

source code

zope.interface.Interface --+
                           |
                          IStatusLog

I represent a single Log, which is a growing list of text items that contains some kind of output for a single BuildStep. I might be finished, in which case this list has stopped growing.

Each Log has a name, usually something boring like 'log' or 'output'. These names are not guaranteed to be unique, however they are usually chosen to be useful within the scope of a single step (i.e. the Compile step might produce both 'log' and 'warnings'). The name may also have spaces. If you want something more globally meaningful, at least within a given Build, try:

 '%s.%s' % (log.getStep.getName(), log.getName())

The Log can be presented as plain text, or it can be accessed as a list of items, each of which has a channel indicator (header, stdout, stderr) and a text chunk. An HTML display might represent the interleaved channels with different styles, while a straight download-the-text interface would just want to retrieve a big string.

The 'header' channel is used by ShellCommands to prepend a note about which command is about to be run ('running command FOO in directory DIR'), and append another note giving the exit code of the process.

Logs can be streaming: if the Log has not yet finished, you can subscribe to receive new chunks as they are added.

A ShellCommand will have a Log associated with it that gathers stdout and stderr. Logs may also be created by parsing command output or through other synthetic means (grepping for all the warnings in a compile log, or listing all the test cases that are going to be run). Such synthetic Logs are usually finished as soon as they are created.

Instance Methods
 
getName()
Returns a short string with the name of this log, probably 'log'.
source code
 
getStep()
Returns the IBuildStepStatus which owns this log.
source code
 
isFinished()
Return a boolean.
source code
 
waitUntilFinished()
Return a Deferred that will fire when the log is closed.
source code
 
subscribe(receiver, catchup)
Register an IStatusReceiver to receive chunks (with logChunk) as data is added to the Log.
source code
 
unsubscribe(receiver)
Remove a receiver previously registered with subscribe().
source code
 
subscribeConsumer(consumer)
Register an IStatusLogConsumer to receive all chunks of the logfile, including all the old entries and any that will arrive in the future.
source code
 
hasContents()
Returns True if the LogFile still has contents available.
source code
 
getText()
Return one big string with the contents of the Log.
source code
 
readlines(channel=LOG_CHANNEL_STDOUT)
Read lines from one channel of the logfile.
source code
 
getTextWithHeaders()
Return one big string with the contents of the Log.
source code
 
getChunks()
Generate a list of (channel, text) tuples.
source code
Class Variables
  __bases__ = (<InterfaceClass zope.interface.Interface>)
  __identifier__ = 'buildbot.interfaces.IStatusLog'
  __iro__ = (<InterfaceClass buildbot.interfaces.IStatusLog>, <I...
  __name__ = 'IStatusLog'
  __sro__ = (<InterfaceClass buildbot.interfaces.IStatusLog>, <I...
  dependents = <WeakKeyDictionary at 43407336>
Method Details

isFinished()

source code 

Return a boolean. True means the log has finished and is closed, False means it is still open and new chunks may be added to it.

waitUntilFinished()

source code 

Return a Deferred that will fire when the log is closed. If the log has already finished, this deferred will fire right away. The callback is given this IStatusLog instance as an argument.

subscribe(receiver, catchup)

source code 

Register an IStatusReceiver to receive chunks (with logChunk) as data is added to the Log. If you use this, you will also want to use waitUntilFinished to find out when the listener can be retired. Subscribing to a closed Log is a no-op.

If 'catchup' is True, the receiver will immediately be sent a series of logChunk messages to bring it up to date with the partially-filled log. This allows a status client to join a Log already in progress without missing any data. If the Log has already finished, it is too late to catch up: just do getText() instead.

If the Log is very large, the receiver will be called many times with a lot of data. There is no way to throttle this data. If the receiver is planning on sending the data on to somewhere else, over a narrow connection, you can get a throttleable subscription by using subscribeConsumer instead.

unsubscribe(receiver)

source code 

Remove a receiver previously registered with subscribe(). Attempts to remove a receiver which was not previously registered is a no-op.

subscribeConsumer(consumer)

source code 

Register an IStatusLogConsumer to receive all chunks of the logfile, including all the old entries and any that will arrive in the future. The consumer will first have their registerProducer method invoked with a reference to an object that can be told pauseProducing, resumeProducing, and stopProducing. Then the consumer's writeChunk method will be called repeatedly with each (channel, text) tuple in the log, starting with the very first. The consumer will be notified with finish when the log has been exhausted (which can only happen when the log is finished). Note that a small amount of data could be written via writeChunk even after pauseProducing has been called.

To unsubscribe the consumer, use producer.stopProducing.

hasContents()

source code 

Returns True if the LogFile still has contents available. Returns False for logs that have been pruned. Clients should test this before offering to show the contents of any log.

getText()

source code 

Return one big string with the contents of the Log. This merges all non-header chunks together.

readlines(channel=LOG_CHANNEL_STDOUT)

source code 

Read lines from one channel of the logfile. This returns an iterator that will provide single lines of text (including the trailing newline).

getTextWithHeaders()

source code 

Return one big string with the contents of the Log. This merges all chunks (including headers) together.

getChunks()

source code 

Generate a list of (channel, text) tuples. 'channel' is a number, 0 for stdout, 1 for stderr, 2 for header. (note that stderr is merged into stdout if PTYs are in use).


Class Variable Details

__iro__

Value:
(<InterfaceClass buildbot.interfaces.IStatusLog>,
 <InterfaceClass zope.interface.Interface>)

__sro__

Value:
(<InterfaceClass buildbot.interfaces.IStatusLog>,
 <InterfaceClass zope.interface.Interface>)