1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 """Interface documentation.
17
18 Define the interfaces that are implemented by various buildbot classes.
19 """
20
21
22
23
24 from zope.interface import Interface, Attribute
25
26
35
37 """
38 Service which feeds Change objects to the changemaster. When files or
39 directories are changed in version control, this object should represent
40 the changes as a change dictionary and call::
41
42 self.master.addChange(who=.., rev=.., ..)
43
44 See 'Writing Change Sources' in the manual for more information.
45 """
46 master = Attribute('master',
47 'Pointer to BuildMaster, automatically set when started.')
48
50 """Return a string which briefly describes this source."""
51
53 """
54 @cvar branch: branch from which source was drawn
55 @type branch: string or None
56
57 @cvar revision: revision of the source, or None to use CHANGES
58 @type revision: varies depending on VC
59
60 @cvar patch: patch applied to the source, or None if no patch
61 @type patch: None or tuple (level diff)
62
63 @cvar changes: the source step should check out the latest revision
64 in the given changes
65 @type changes: tuple of L{buildbot.changes.changes.Change} instances,
66 all of which are on the same branch
67
68 @cvar project: project this source code represents
69 @type project: string
70
71 @cvar repository: repository from which source was drawn
72 @type repository: string
73 """
74
76 """
77 Can this SourceStamp be merged with OTHER?
78 """
79
81 """Generate a SourceStamp for the merger of me and all the other
82 SourceStamps. This is called by a Build when it starts, to figure
83 out what its sourceStamp should be."""
84
86 """Get a new SourceStamp object reflecting the actual revision found
87 by a Source step."""
88
90 """Returns a list of strings to describe the stamp. These are
91 intended to be displayed in a narrow column. If more space is
92 available, the caller should join them together with spaces before
93 presenting them to the user."""
94
96 """I know how to send email, and can be used by other parts of the
97 Buildbot to contact developers."""
98 pass
99
102 """Turn a User-name string into a valid email address. Either return
103 a string (with an @ in it), None (to indicate that the user cannot
104 be reached by email), or a Deferred which will fire with the same."""
107 """I am an object, obtainable from the buildmaster, which can provide
108 status information."""
109
111 """Return the name of the project that this Buildbot is working
112 for."""
114 """Return the URL of this Buildbot's project."""
116 """Return the URL of the top-most Buildbot status page, or None if
117 this Buildbot does not provide a web status page."""
119 """Return the URL of a page which provides information on 'thing',
120 which should be an object that implements one of the status
121 interfaces defined in L{buildbot.interfaces}. Returns None if no
122 suitable page is available (or if no Waterfall is running)."""
123
125 """Return a list of IChangeSource objects."""
126
128 """Return an IChange object."""
129
131 """Return a list of ISchedulerStatus objects for all
132 currently-registered Schedulers."""
133
135 """Return a list of the names of all current Builders."""
137 """Return the IBuilderStatus object for a given named Builder. Raises
138 KeyError if there is no Builder by that name."""
139
141 """Return a list of buildslave names, suitable for passing to
142 getSlave()."""
144 """Return the ISlaveStatus object for a given named buildslave."""
145
147 """
148 Return a list of un-completed build sets.
149
150 @returns: list of L{IBuildSetStatus} implementations, via Deferred.
151 """
152
153 - def generateFinishedBuilds(builders=[], branches=[],
154 num_builds=None, finished_before=None,
155 max_search=200):
156 """Return a generator that will produce IBuildStatus objects each
157 time you invoke its .next() method, starting with the most recent
158 finished build and working backwards.
159
160 @param builders: this is a list of Builder names, and the generator
161 will only produce builds that ran on the given
162 Builders. If the list is empty, produce builds from
163 all Builders.
164
165 @param branches: this is a list of branch names, and the generator
166 will only produce builds that used the given
167 branches. If the list is empty, produce builds from
168 all branches.
169
170 @param num_builds: the generator will stop after providing this many
171 builds. The default of None means to produce as
172 many builds as possible.
173
174 @type finished_before: int: a timestamp, seconds since the epoch
175 @param finished_before: if provided, do not produce any builds that
176 finished after the given timestamp.
177
178 @type max_search: int
179 @param max_search: this method may have to examine a lot of builds
180 to find some that match the search parameters,
181 especially if there aren't any matching builds.
182 This argument imposes a hard limit on the number
183 of builds that will be examined within any given
184 Builder.
185 """
186
188 """Register an IStatusReceiver to receive new status events. The
189 receiver will immediately be sent a set of 'builderAdded' messages
190 for all current builders. It will receive further 'builderAdded' and
191 'builderRemoved' messages as the config file is reloaded and builders
192 come and go. It will also receive 'buildsetSubmitted' messages for
193 all outstanding BuildSets (and each new BuildSet that gets
194 submitted). No additional messages will be sent unless the receiver
195 asks for them by calling .subscribe on the IBuilderStatus objects
196 which accompany the addedBuilder message."""
197
199 """Unregister an IStatusReceiver. No further status messgaes will be
200 delivered."""
201
203 """I represent a set of Builds, each run on a separate Builder but all
204 using the same source tree."""
205
209 """Return the BuildSet's ID string, if any. The 'try' feature uses a
210 random string as a BuildSetID to relate submitted jobs with the
211 resulting BuildSet."""
217 """Return a list of the names of all Builders on which this set will
218 do builds.
219
220 @returns: list of names via Deferred"""
224 """Return a Deferred that fires (with this IBuildSetStatus object)
225 when all builds have finished."""
227 """Return SUCCESS/FAILURE, or None if the buildset is not finished
228 yet"""
229
230
232 """I represent a request to build a particular set of source code on a
233 particular Builder. These requests may be merged by the time they are
234 finally turned into a Build."""
235
237 """
238 Get a SourceStamp object which can be used to re-create the source tree
239 that this build used. This method will return an absolute SourceStamp
240 if possible, and its results may change as the build progresses.
241 Specifically, a "HEAD" build may later be more accurately specified by
242 an absolute SourceStamp with the specific revision information.
243
244 This method will return None if the source information is no longer
245 available.
246
247 @returns: SourceStamp via Deferred
248 """
249
251 """Return a list of IBuildStatus objects for each Build that has been
252 started in an attempt to satify this BuildRequest."""
253
255 """Register a callable that will be invoked (with a single
256 IBuildStatus object) for each Build that is created to satisfy this
257 request. There may be multiple Builds created in an attempt to handle
258 the request: they may be interrupted by the user or abandoned due to
259 a lost slave. The last Build (the one which actually gets to run to
260 completion) is said to 'satisfy' the BuildRequest. The observer will
261 be called once for each of these Builds, both old and new."""
263 """Unregister the callable that was registered with subscribe()."""
265 """Return the time when this request was submitted. Returns a
266 Deferred."""
267
268
271 """Return the name of the build slave."""
272
274 """Return a string with the slave admin's contact data."""
275
277 """Return a string with the slave host info."""
278
280 """Return True if the slave is currently online, False if not."""
281
283 """Return a timestamp (seconds since epoch) indicating when the most
284 recent message was received from the buildslave."""
288 """Return the name of this Scheduler (a string)."""
289
291 """Return an IBuildSet for all BuildSets that are pending. These
292 BuildSets are waiting for their tree-stable-timers to expire."""
298 """Return the name of this Builder (a string)."""
299
301 """Return the category of this builder (a string)."""
302
304 """Return the description of this builder (a string)."""
305
307
308 """Return a tuple (state, builds) for this Builder. 'state' is the
309 so-called 'big-status', indicating overall status (as opposed to
310 which step is currently running). It is a string, one of 'offline',
311 'idle', or 'building'. 'builds' is a list of IBuildStatus objects
312 (possibly empty) representing the currently active builds."""
313
315 """Return a list of ISlaveStatus objects for the buildslaves that are
316 used by this builder."""
317
319 """
320 Get a L{IBuildRequestStatus} implementations for all unclaimed build
321 requests.
322
323 @returns: list of objects via Deferred
324 """
325
327 """Return a list containing an IBuildStatus object for each build
328 currently in progress."""
329
330
331
332
334 """Return the IBuildStatus object representing the last finished
335 build, which may be None if the builder has not yet finished any
336 builds."""
337
339 """Return an IBuildStatus object for a historical build. Each build
340 is numbered (starting at 0 when the Builder is first added),
341 getBuild(n) will retrieve the Nth such build. getBuild(-n) will
342 retrieve a recent build, with -1 being the most recent build
343 started. If the Builder is idle, this will be the same as
344 getLastFinishedBuild(). If the Builder is active, it will be an
345 unfinished build. This method will return None if the build is no
346 longer available. Older builds are likely to have less information
347 stored: Logs are the first to go, then Steps."""
348
350 """Return an IStatusEvent object for a recent Event. Builders
351 connecting and disconnecting are events, as are ping attempts.
352 getEvent(-1) will return the most recent event. Events are numbered,
353 but it probably doesn't make sense to ever do getEvent(+n)."""
354
355 - def generateFinishedBuilds(branches=[],
356 num_builds=None,
357 max_buildnum=None, finished_before=None,
358 max_search=200,
359 ):
360 """Return a generator that will produce IBuildStatus objects each
361 time you invoke its .next() method, starting with the most recent
362 finished build, then the previous build, and so on back to the oldest
363 build available.
364
365 @param branches: this is a list of branch names, and the generator
366 will only produce builds that involve the given
367 branches. If the list is empty, the generator will
368 produce all builds regardless of what branch they
369 used.
370
371 @param num_builds: if provided, the generator will stop after
372 providing this many builds. The default of None
373 means to produce as many builds as possible.
374
375 @param max_buildnum: if provided, the generator will start by
376 providing the build with this number, or the
377 highest-numbered preceding build (i.e. the
378 generator will not produce any build numbered
379 *higher* than max_buildnum). The default of None
380 means to start with the most recent finished
381 build. -1 means the same as None. -2 means to
382 start with the next-most-recent completed build,
383 etc.
384
385 @type finished_before: int: a timestamp, seconds since the epoch
386 @param finished_before: if provided, do not produce any builds that
387 finished after the given timestamp.
388
389 @type max_search: int
390 @param max_search: this method may have to examine a lot of builds
391 to find some that match the search parameters,
392 especially if there aren't any matching builds.
393 This argument imposes a hard limit on the number
394 of builds that will be examined.
395 """
396
398 """Register an IStatusReceiver to receive new status events. The
399 receiver will be given builderChangedState, buildStarted, and
400 buildFinished messages."""
401
403 """Unregister an IStatusReceiver. No further status messgaes will be
404 delivered."""
407 - def eventGenerator(branches=[], categories=[], committers=[], minTime=0):
408 """This function creates a generator which will yield all of this
409 object's status events, starting with the most recent and progressing
410 backwards in time. These events provide the IStatusEvent interface.
411 At the moment they are all instances of buildbot.status.builder.Event
412 or buildbot.status.builder.BuildStepStatus .
413
414 @param branches: a list of branch names. The generator should only
415 return events that are associated with these branches. If the list is
416 empty, events for all branches should be returned (i.e. an empty list
417 means 'accept all' rather than 'accept none').
418
419 @param categories: a list of category names. The generator
420 should only return events that are categorized within the
421 given category. If the list is empty, events for all
422 categories should be returned.
423
424 @param comitters: a list of committers. The generator should only
425 return events caused by one of the listed committers. If the list is
426 empty or None, events from every committers should be returned.
427
428 @param minTime: a timestamp. Do not generate events occuring prior to
429 this timestamp.
430 """
433 """I represent the status of a single Build/BuildRequest. It could be
434 in-progress or finished."""
435
437 """
438 Return the BuilderStatus that owns this build.
439
440 @rtype: implementor of L{IBuilderStatus}
441 """
442
444 """Return a boolean. True means the build has finished, False means
445 it is still running."""
446
448 """Return a Deferred that will fire when the build finishes. If the
449 build has already finished, this deferred will fire right away. The
450 callback is given this IBuildStatus instance as an argument."""
451
453 """Return a string that indicates why the build was run. 'changes',
454 'forced', and 'periodic' are the most likely values. 'try' will be
455 added in the future."""
456
458 """Return a list of SourceStamp objects which can be used to re-create
459 the source tree that this build used.
460
461 This method will return None if the source information is no longer
462 available."""
463
464
465
467 """Return a list of Change objects which represent which source
468 changes went into the build."""
469
471 """Returns a string representing the list of revisions that led to
472 the build, rendered from each Change.revision"""
473
475 """Return a list of Users who are to blame for the changes that went
476 into this build. If anything breaks (at least anything that wasn't
477 already broken), blame them. Specifically, this is the set of users
478 who were responsible for the Changes that went into this build. Each
479 User is a string, corresponding to their name as known by the VC
480 repository."""
481
483 """Return a list of Users who will want to know about the results of
484 this build but who did not actually make the Changes that went into it
485 (build sheriffs, code-domain owners)."""
486
488 """Within each builder, each Build has a number. Return it."""
489
491 """Convenience method. Returns None if the previous build is
492 unavailable."""
493
495 """Return a list of IBuildStepStatus objects. For invariant builds
496 (those which always use the same set of Steps), this should always
497 return the complete list, however some of the steps may not have
498 started yet (step.getTimes()[0] will be None). For variant builds,
499 this may not be complete (asking again later may give you more of
500 them)."""
501
503 """Returns a tuple of (start, end). 'start' and 'end' are the times
504 (seconds since the epoch) when the Build started and finished. If
505 the build is still running, 'end' will be None."""
506
507
508
509
511 """Returns the number of seconds from now in which the build is
512 expected to finish, or None if we can't make a guess. This guess will
513 be refined over time."""
514
516 """Return an IBuildStepStatus object representing the currently
517 active step."""
518
519
520
521
523 """Return the name of the buildslave which handled this build."""
524
526 """Returns a list of strings to describe the build. These are
527 intended to be displayed in a narrow column. If more space is
528 available, the caller should join them together with spaces before
529 presenting them to the user."""
530
532 """Return a constant describing the results of the build: one of the
533 constants in buildbot.status.builder: SUCCESS, WARNINGS,
534 FAILURE, SKIPPED or EXCEPTION."""
535
537 """Return a list of logs that describe the build as a whole. Some
538 steps will contribute their logs, while others are are less important
539 and will only be accessible through the IBuildStepStatus objects.
540 Each log is an object which implements the IStatusLog interface."""
541
543 """Return a dictionary that maps test-name tuples to ITestResult
544 objects. This may return an empty or partially-filled dictionary
545 until the build has completed."""
546
547
548
549 - def subscribe(receiver, updateInterval=None):
550 """Register an IStatusReceiver to receive new status events. The
551 receiver will be given stepStarted and stepFinished messages. If
552 'updateInterval' is non-None, buildETAUpdate messages will be sent
553 every 'updateInterval' seconds."""
554
556 """Unregister an IStatusReceiver. No further status messgaes will be
557 delivered."""
558
560 """I describe the results of a single unit test."""
561
563 """Returns a tuple of strings which make up the test name. Tests may
564 be arranged in a hierarchy, so looking for common prefixes may be
565 useful."""
566
568 """Returns a constant describing the results of the test: SUCCESS,
569 WARNINGS, FAILURE."""
570
572 """Returns a list of short strings which describe the results of the
573 test in slightly more detail. Suggested components include
574 'failure', 'error', 'passed', 'timeout'."""
575
577
578
579 """Returns a dictionary of test logs. The keys are strings like
580 'stdout', 'log', 'exceptions'. The values are strings."""
581
582
584 """I hold status for a single BuildStep."""
585
587 """Returns a short string with the name of this step. This string
588 may have spaces in it."""
589
591 """Returns the IBuildStatus object which contains this step."""
592
594 """Returns a tuple of (start, end). 'start' and 'end' are the times
595 (seconds since the epoch) when the Step started and finished. If the
596 step has not yet started, 'start' will be None. If the step is still
597 running, 'end' will be None."""
598
600 """Returns a list of tuples (name, current, target). Each tuple
601 describes a single axis along which the step's progress can be
602 measured. 'name' is a string which describes the axis itself, like
603 'filesCompiled' or 'tests run' or 'bytes of output'. 'current' is a
604 number with the progress made so far, while 'target' is the value
605 that we expect (based upon past experience) to get to when the build
606 is finished.
607
608 'current' will change over time until the step is finished. It is
609 'None' until the step starts. When the build is finished, 'current'
610 may or may not equal 'target' (which is merely the expectation based
611 upon previous builds)."""
612
614 """Returns a dictionary of URLs. Each key is a link name (a short
615 string, like 'results' or 'coverage'), and each value is a URL. These
616 links will be displayed along with the LogFiles.
617 """
618
620 """Returns a list of IStatusLog objects. If the step has not yet
621 finished, this list may be incomplete (asking again later may give
622 you more of them)."""
623
624
626 """Return a boolean. True means the step has finished, False means it
627 is still running."""
628
630 """Return a Deferred that will fire when the step finishes. If the
631 step has already finished, this deferred will fire right away. The
632 callback is given this IBuildStepStatus instance as an argument."""
633
634
635
636
638 """Returns the number of seconds from now in which the step is
639 expected to finish, or None if we can't make a guess. This guess will
640 be refined over time."""
641
642
643
644
646 """Returns a list of strings which describe the step. These are
647 intended to be displayed in a narrow column. If more space is
648 available, the caller should join them together with spaces before
649 presenting them to the user."""
650
652 """Return a tuple describing the results of the step: (result,
653 strings). 'result' is one of the constants in
654 buildbot.status.builder: SUCCESS, WARNINGS, FAILURE, or SKIPPED.
655 'strings' is an optional list of strings that the step wants to
656 append to the overall build's results. These strings are usually
657 more terse than the ones returned by getText(): in particular,
658 successful Steps do not usually contribute any text to the overall
659 build."""
660
661
662
664 """Register an IStatusReceiver to receive new status events. The
665 receiver will be given logStarted and logFinished messages. It will
666 also be given a ETAUpdate message every 'updateInterval' seconds."""
667
669 """Unregister an IStatusReceiver. No further status messgaes will be
670 delivered."""
671
673 """I represent a Builder Event, something non-Build related that can
674 happen to a Builder."""
675
677 """Returns a tuple of (start, end) like IBuildStepStatus, but end==0
678 indicates that this is a 'point event', which has no duration.
679 SlaveConnect/Disconnect are point events. Ping is not: it starts
680 when requested and ends when the response (positive or negative) is
681 returned"""
682
684 """Returns a list of strings which describe the event. These are
685 intended to be displayed in a narrow column. If more space is
686 available, the caller should join them together with spaces before
687 presenting them to the user."""
688
689
690 LOG_CHANNEL_STDOUT = 0
691 LOG_CHANNEL_STDERR = 1
692 LOG_CHANNEL_HEADER = 2
693
695 """I represent a single Log, which is a growing list of text items that
696 contains some kind of output for a single BuildStep. I might be finished,
697 in which case this list has stopped growing.
698
699 Each Log has a name, usually something boring like 'log' or 'output'.
700 These names are not guaranteed to be unique, however they are usually
701 chosen to be useful within the scope of a single step (i.e. the Compile
702 step might produce both 'log' and 'warnings'). The name may also have
703 spaces. If you want something more globally meaningful, at least within a
704 given Build, try::
705
706 '%s.%s' % (log.getStep.getName(), log.getName())
707
708 The Log can be presented as plain text, or it can be accessed as a list
709 of items, each of which has a channel indicator (header, stdout, stderr)
710 and a text chunk. An HTML display might represent the interleaved
711 channels with different styles, while a straight download-the-text
712 interface would just want to retrieve a big string.
713
714 The 'header' channel is used by ShellCommands to prepend a note about
715 which command is about to be run ('running command FOO in directory
716 DIR'), and append another note giving the exit code of the process.
717
718 Logs can be streaming: if the Log has not yet finished, you can
719 subscribe to receive new chunks as they are added.
720
721 A ShellCommand will have a Log associated with it that gathers stdout
722 and stderr. Logs may also be created by parsing command output or
723 through other synthetic means (grepping for all the warnings in a
724 compile log, or listing all the test cases that are going to be run).
725 Such synthetic Logs are usually finished as soon as they are created."""
726
727
729 """Returns a short string with the name of this log, probably 'log'.
730 """
731
733 """Returns the IBuildStepStatus which owns this log."""
734
735
737 """Return a boolean. True means the log has finished and is closed,
738 False means it is still open and new chunks may be added to it."""
739
741 """Return a Deferred that will fire when the log is closed. If the
742 log has already finished, this deferred will fire right away. The
743 callback is given this IStatusLog instance as an argument."""
744
746 """Register an IStatusReceiver to receive chunks (with logChunk) as
747 data is added to the Log. If you use this, you will also want to use
748 waitUntilFinished to find out when the listener can be retired.
749 Subscribing to a closed Log is a no-op.
750
751 If 'catchup' is True, the receiver will immediately be sent a series
752 of logChunk messages to bring it up to date with the partially-filled
753 log. This allows a status client to join a Log already in progress
754 without missing any data. If the Log has already finished, it is too
755 late to catch up: just do getText() instead.
756
757 If the Log is very large, the receiver will be called many times with
758 a lot of data. There is no way to throttle this data. If the receiver
759 is planning on sending the data on to somewhere else, over a narrow
760 connection, you can get a throttleable subscription by using
761 C{subscribeConsumer} instead."""
762
764 """Remove a receiver previously registered with subscribe(). Attempts
765 to remove a receiver which was not previously registered is a no-op.
766 """
767
769 """Register an L{IStatusLogConsumer} to receive all chunks of the
770 logfile, including all the old entries and any that will arrive in
771 the future. The consumer will first have their C{registerProducer}
772 method invoked with a reference to an object that can be told
773 C{pauseProducing}, C{resumeProducing}, and C{stopProducing}. Then the
774 consumer's C{writeChunk} method will be called repeatedly with each
775 (channel, text) tuple in the log, starting with the very first. The
776 consumer will be notified with C{finish} when the log has been
777 exhausted (which can only happen when the log is finished). Note that
778 a small amount of data could be written via C{writeChunk} even after
779 C{pauseProducing} has been called.
780
781 To unsubscribe the consumer, use C{producer.stopProducing}."""
782
783
784
785
786
787
788
790 """Returns True if the LogFile still has contents available. Returns
791 False for logs that have been pruned. Clients should test this before
792 offering to show the contents of any log."""
793
795 """Return one big string with the contents of the Log. This merges
796 all non-header chunks together."""
797
799 """Read lines from one channel of the logfile. This returns an
800 iterator that will provide single lines of text (including the
801 trailing newline).
802 """
803
805 """Return one big string with the contents of the Log. This merges
806 all chunks (including headers) together."""
807
809 """Generate a list of (channel, text) tuples. 'channel' is a number,
810 0 for stdout, 1 for stderr, 2 for header. (note that stderr is merged
811 into stdout if PTYs are in use)."""
812
814 """I am an object which can be passed to IStatusLog.subscribeConsumer().
815 I represent a target for writing the contents of an IStatusLog. This
816 differs from a regular IStatusReceiver in that it can pause the producer.
817 This makes it more suitable for use in streaming data over network
818 sockets, such as an HTTP request. Note that the consumer can only pause
819 the producer until it has caught up with all the old data. After that
820 point, C{pauseProducing} is ignored and all new output from the log is
821 sent directoy to the consumer."""
822
824 """A producer is being hooked up to this consumer. The consumer only
825 has to handle a single producer. It should send .pauseProducing and
826 .resumeProducing messages to the producer when it wants to stop or
827 resume the flow of data. 'streaming' will be set to True because the
828 producer is always a PushProducer.
829 """
830
832 """The previously-registered producer has been removed. No further
833 pauseProducing or resumeProducing calls should be made. The consumer
834 should delete its reference to the Producer so it can be released."""
835
837 """A chunk (i.e. a tuple of (channel, text)) is being written to the
838 consumer."""
839
841 """The log has finished sending chunks to the consumer."""
842
844 """I am an object which can receive build status updates. I may be
845 subscribed to an IStatus, an IBuilderStatus, or an IBuildStatus."""
846
848 """A new BuildSet has been submitted to the buildmaster.
849
850 @type buildset: implementor of L{IBuildSetStatus}
851 """
852
854 """A new BuildRequest has been submitted to the buildmaster.
855
856 @type request: implementor of L{IBuildRequestStatus}
857 """
858
860 """A BuildRequest has been cancelled on the given Builder.
861
862 @type builder: L{buildbot.status.builder.BuilderStatus}
863 @type request: implementor of L{IBuildRequestStatus}
864 """
865
867 """
868 A new Builder has just been added. This method may return an
869 IStatusReceiver (probably 'self') which will be subscribed to receive
870 builderChangedState and buildStarted/Finished events.
871
872 @type builderName: string
873 @type builder: L{buildbot.status.builder.BuilderStatus}
874 @rtype: implementor of L{IStatusReceiver}
875 """
876
878 """Builder 'builderName' has changed state. The possible values for
879 'state' are 'offline', 'idle', and 'building'."""
880
882 """Builder 'builderName' has just started a build. The build is an
883 object which implements IBuildStatus, and can be queried for more
884 information.
885
886 This method may return an IStatusReceiver (it could even return
887 'self'). If it does so, stepStarted and stepFinished methods will be
888 invoked on the object for the steps of this one build. This is a
889 convenient way to subscribe to all build steps without missing any.
890 This receiver will automatically be unsubscribed when the build
891 finishes.
892
893 It can also return a tuple of (IStatusReceiver, interval), in which
894 case buildETAUpdate messages are sent ever 'interval' seconds, in
895 addition to the stepStarted and stepFinished messages."""
896
898 """This is a periodic update on the progress this Build has made
899 towards completion."""
900
902 """A new Change was added to the ChangeMaster. By the time this event
903 is received, all schedulers have already received the change."""
904
906 """A step has just started. 'step' is the IBuildStepStatus which
907 represents the step: it can be queried for more information.
908
909 This method may return an IStatusReceiver (it could even return
910 'self'). If it does so, logStarted and logFinished methods will be
911 invoked on the object for logs created by this one step. This
912 receiver will be automatically unsubscribed when the step finishes.
913
914 Alternatively, the method may return a tuple of an IStatusReceiver
915 and an integer named 'updateInterval'. In addition to
916 logStarted/logFinished messages, it will also receive stepETAUpdate
917 messages about every updateInterval seconds."""
918
919 - def stepTextChanged(build, step, text):
920 """The text for a step has been updated.
921
922 This is called when calling setText() on the step status, and
923 hands in the text list."""
924
925 - def stepText2Changed(build, step, text2):
926 """The text2 for a step has been updated.
927
928 This is called when calling setText2() on the step status, and
929 hands in text2 list."""
930
932 """This is a periodic update on the progress this Step has made
933 towards completion. It gets an ETA (in seconds from the present) of
934 when the step ought to be complete, and a list of expectation tuples
935 (as returned by IBuildStepStatus.getExpectations) with more detailed
936 information."""
937
939 """A new Log has been started, probably because a step has just
940 started running a shell command. 'log' is the IStatusLog object
941 which can be queried for more information.
942
943 This method may return an IStatusReceiver (such as 'self'), in which
944 case the target's logChunk method will be invoked as text is added to
945 the logfile. This receiver will automatically be unsubsribed when the
946 log finishes."""
947
948 - def logChunk(build, step, log, channel, text):
949 """Some text has been added to this log. 'channel' is one of
950 LOG_CHANNEL_STDOUT, LOG_CHANNEL_STDERR, or LOG_CHANNEL_HEADER, as
951 defined in IStatusLog.getChunks."""
952
954 """A Log has been closed."""
955
957 """A step has just finished. 'results' is the result tuple described
958 in IBuildStepStatus.getResults."""
959
961 """
962 A build has just finished. 'results' is the result tuple described
963 in L{IBuildStatus.getResults}.
964
965 @type builderName: string
966 @type build: L{buildbot.status.build.BuildStatus}
967 @type results: tuple
968 """
969
971 """The Builder has been removed."""
972
974 """The slave has connected."""
975
977 """The slave has disconnected."""
978
980 """Verify that there are no other status receivers which conflict with
981 the current one.
982
983 @type otherStatusReceivers: A list of L{IStatusReceiver} objects which
984 will contain self.
985 """
986
987
990 """Add a change to the change queue, for analysis by schedulers."""
991
993 """Retrieve the IBuilderControl object for the given Builder."""
997 """Create a BuildRequest, which will eventually cause a build of the
998 given SourceStamp to be run on this builder. This returns a
999 BuildRequestStatus object via a Deferred, which can be used to keep
1000 track of the builds that are performed."""
1001
1002 - def rebuildBuild(buildStatus, reason="<rebuild, no reason given>"):
1003 """Rebuild something we've already built before. This submits a
1004 BuildRequest to our Builder using the same SourceStamp as the earlier
1005 build. This has no effect (but may eventually raise an exception) if
1006 this Build has not yet finished."""
1007
1009 """
1010 Get a list of L{IBuildRequestControl} objects for this Builder.
1011 Each one corresponds to an unclaimed build request.
1012
1013 @returns: list of objects via Deferred
1014 """
1015
1017 """Attempt to return an IBuildControl object for the given build.
1018 Returns None if no such object is available. This will only work for
1019 the build that is currently in progress: once the build finishes,
1020 there is nothing to control anymore."""
1021
1023 """Attempt to contact the slave and see if it is still alive. This
1024 returns a Deferred which fires with either True (the slave is still
1025 alive) or False (the slave did not respond). As a side effect, adds an
1026 event to this builder's column in the waterfall display containing the
1027 results of the ping. Note that this may not fail for a long time, it is
1028 implemented in terms of the timeout on the underlying TCP connection."""
1035 """Register a callable that will be invoked (with a single
1036 IBuildControl object) for each Build that is created to satisfy this
1037 request. There may be multiple Builds created in an attempt to handle
1038 the request: they may be interrupted by the user or abandoned due to
1039 a lost slave. The last Build (the one which actually gets to run to
1040 completion) is said to 'satisfy' the BuildRequest. The observer will
1041 be called once for each of these Builds, both old and new."""
1043 """Unregister the callable that was registered with subscribe()."""
1045 """Remove the build from the pending queue. Has no effect if the
1046 build has already been started."""
1050 """Return an IBuildStatus object for the Build that I control."""
1052 """Halt the build. This has no effect if the build has already
1053 finished."""
1056 """This is the internal interface to a LogFile, used by the BuildStep to
1057 write data into the log.
1058 """
1066 """The process that is feeding the log file has finished, and no
1067 further data will be added. This closes the logfile."""
1068
1070 """Objects which provide this interface can be used in a BuildStep to
1071 watch the output of a LogFile and parse it incrementally.
1072 """
1073
1074
1079
1080
1081 - def logChunk(build, step, log, channel, text):
1083
1087
1089 """A build slave that is not always running, but can run when requested.
1090 """
1091 substantiated = Attribute('Substantiated',
1092 'Whether the latent build slave is currently '
1093 'substantiated with a real instance.')
1094
1096 """Request that the slave substantiate with a real instance.
1097
1098 Returns a deferred that will callback when a real instance has
1099 attached."""
1100
1101
1102
1104 """Inform the latent build slave that a build has started.
1105
1106 @param sb: a L{LatentSlaveBuilder}. The sb is the one for whom the
1107 build finished.
1108 """
1109
1111 """Inform the latent build slave that a build has finished.
1112
1113 @param sb: a L{LatentSlaveBuilder}. The sb is the one for whom the
1114 build finished.
1115 """
1116
1118 """An object that can be interpolated with properties from a build.
1119 """
1120
1122 """Return a deferred that fires with interpolation with the given properties
1123
1124 @param iprops: the L{IProperties} provider supplying the properties.
1125 """
1127 """
1128 An object providing access to build properties
1129 """
1130
1132 """Get the named property, returning the default if the property does
1133 not exist.
1134
1135 @param name: property name
1136 @type name: string
1137
1138 @param default: default value (default: @code{None})
1139
1140 @returns: property value
1141 """
1142
1144 """Return true if the named property exists.
1145
1146 @param name: property name
1147 @type name: string
1148 @returns: boolean
1149 """
1150
1152 """Deprecated name for L{hasProperty}."""
1153
1155 """Set the given property, overwriting any existing value. The source
1156 describes the source of the value for human interpretation.
1157
1158 @param name: property name
1159 @type name: string
1160
1161 @param value: property value
1162 @type value: JSON-able value
1163
1164 @param source: property source
1165 @type source: string
1166
1167 @param runtime: (optional) whether this property was set during the
1168 build's runtime: usually left at its default value
1169 @type runtime: boolean
1170 """
1171
1173 """Get the L{buildbot.process.properties.Properties} instance storing
1174 these properties. Note that the interface for this class is not
1175 stable, so where possible the other methods of this interface should be
1176 used.
1177
1178 @returns: L{buildbot.process.properties.Properties} instance
1179 """
1180
1182 """Get the L{buildbot.process.build.Build} instance for the current
1183 build. Note that this object is not available after the build is
1184 complete, at which point this method will return None.
1185
1186 Try to avoid using this method, as the API of L{Build} instances is not
1187 well-defined.
1188
1189 @returns L{buildbot.process.build.Build} instance
1190 """
1191
1193 """Render @code{value} as an L{IRenderable}. This essentially coerces
1194 @code{value} to an L{IRenderable} and calls its @L{getRenderingFor}
1195 method.
1196
1197 @name value: value to render
1198 @returns: rendered value
1199 """
1200
1203
1205 """
1206 A scheduler that can be triggered by buildsteps.
1207 """
1208
1209 - def trigger(sourcestamps, set_props=None):
1210 """Trigger a build with the given source stamp and properties.
1211 """
1212
1217