@@ -20,38 +20,108 @@ class ButlerCollectionsSpec(BaseModel):
2020
2121 model_config = SPEC_CONFIG
2222 campaign_input : list [str ] = Field (
23- description = "The campaign source collection" ,
23+ description = "The campaign source collection. The input collection list should not include environment"
24+ " or BPS variables that will be unknown to the CM Service." ,
2425 default_factory = list ,
2526 validation_alias = AliasChoices ("campaign_input" , "in" ),
27+ examples = [["LSSTCam/defaults" ]],
28+ )
29+ ancillary : list [str ] = Field (
30+ default_factory = list ,
31+ deprecated = True ,
32+ description = "A set of collections related to the campaign input collections that will be chained "
33+ "together to create a collection for the campaign." ,
34+ examples = [["refcats" , "skymaps" ]],
2635 )
27- ancillary : list [str ] = Field (default_factory = list )
2836 campaign_public_output : str = Field (
29- description = "The public output collection for this Campaign." ,
37+ description = "The final 'public' campaign *chained* collection; includes the `campaign_output` "
38+ "collection, the Campaign 'input' collection, and any other incidental collections created during "
39+ "the campaign (e.g., resource usage)" ,
3040 default_factory = lambda : uuid4 ().__str__ (),
3141 validation_alias = AliasChoices ("campaign_public_output" , "out" ),
42+ examples = ["u/{operator}/{campaign}" ],
3243 )
3344 campaign_output : str | None = Field (
34- default = None , description = "The private output collection for a campaign; {out}/output"
45+ default = None ,
46+ description = "The 'private' output collection for a campaign; a *chained* collection of "
47+ "each step-specific *output* collection, which itself is a *chained* collection of each step-group's "
48+ "`run` collection." ,
49+ examples = ["u/{operator}/{campaign}/out" ],
50+ )
51+ step_input : str | None = Field (
52+ default = None ,
53+ description = "The *chained* input collection for a step, usually consisting of the campaign input and "
54+ "any ancestor `step_output` collection."
55+ " This is used internally and generally does not need to be configured." ,
56+ examples = ["{campaign_public_output}/{step}/input" ],
57+ )
58+ step_output : str | None = Field (
59+ default = None ,
60+ description = "The *chained* output collection for a step, usually consisting of each step-group's "
61+ "`run` collection."
62+ " This is used internally and generally does not need to be configured." ,
63+ examples = ["{campaign_public_output}/{step}_output" ],
64+ )
65+ step_public_output : str | None = Field (
66+ default = None ,
67+ description = "The *chained* output collection that includes the `step_output` and additional step "
68+ "and/or campaign inputs."
69+ " This is used internally and generally does not need to be configured." ,
70+ examples = ["{campaign_public_output}/{step}" ],
71+ )
72+ group_output : str | None = Field (
73+ default = None ,
74+ description = "A collection name associated with the `payload.output` BPS setting."
75+ " This is used internally and generally does not need to be configured." ,
76+ examples = ["{campaign_public_output}/{step}/{group_nonce}" , "u/{operator}/{payloadName}" ],
3577 )
36- step_input : str | None = Field (default = None , description = "{out}/{step}/input" )
37- step_output : str | None = Field (default = None , description = "{out}/{step}_output" )
38- step_public_output : str | None = Field (default = None , description = "{out}/{step}" )
39- group_output : str | None = Field (default = None , description = "{out}/{step}/{group}" )
4078 run : str | None = Field (
4179 default = None ,
42- description = "The run collection affected by a Node's execution; {out}/{step}/{group}/{job}" ,
80+ description = "The run collection created by a group's execution (the `payload.outputRun` BPS setting)."
81+ " This is used internally and generally does not need to be configured." ,
82+ examples = ["{out}/{step}/{group}/{job}" ],
4383 validation_alias = AliasChoices ("job_run" , "run" ),
4484 )
4585
4686
4787class ButlerSpec (ManifestSpec ):
48- """Spec model for a Butler Manifest."""
88+ """Configuration specification for a Butler Manifest. This is primarily
89+ used to manage collections and group splitting rules throughout a campaign,
90+ as well as populating the `payload` section of a BPS submission file.
91+ """
4992
5093 model_config = SPEC_CONFIG
51- collections : ButlerCollectionsSpec
52- predicates : Sequence [str ] = Field (default_factory = list )
53- repo : str = Field (description = "Name of a Butler known to the application's Butler Factory." )
54- include_files : list [str ] | None = Field (default = None )
94+ collections : ButlerCollectionsSpec = Field (
95+ description = "A butler configuration used to specify collections for "
96+ "various campaign operations. Of particular interest for a Butler"
97+ "manifest are `campaign_input` and `campaign_output`" ,
98+ examples = [
99+ {
100+ "campaign_input" : ["LSSTCam/defaults" ],
101+ "campaign_public_output" : "u/{operator}/{campaign}" ,
102+ "campaign_output" : "u/{operator}/{campaign}/out" ,
103+ }
104+ ],
105+ )
106+ predicates : Sequence [str ] = Field (
107+ default_factory = list ,
108+ description = "A set of data query predicates shared with all users of"
109+ "this manifest. All predicate sets are `AND`-ed together for a final "
110+ "data query" ,
111+ examples = [
112+ ["instrument='LSSTCam'" , "skymap='lsst_cells_v2'" ],
113+ ],
114+ )
115+ repo : str = Field (
116+ description = "Name of a Butler known to the application's Butler Factory." ,
117+ examples = ["/repo/main" , "embargo" ],
118+ )
119+ include_files : list [str ] | None = Field (
120+ default = None ,
121+ description = "A list of files to be added to the BPS submission as include files "
122+ "that are specific to the use of this Butler." ,
123+ examples = ["${DRP_PIPE_DIR}/includes/butler/{butler-tuning}.yaml" ],
124+ )
55125
56126
57127class ButlerManifest (LibraryManifest [ButlerSpec ]): ...
0 commit comments