Debian Codegraph @

sites/docs/concepts/namespaces.rst

raw
1 .. _task-namespaces:
2
3 =======================
4 Constructing namespaces
5 =======================
6
7 The :doc:`base case </getting-started>` of loading a single module of tasks
8 works fine initially, but advanced users typically need more organization, such
9 as separating tasks into a tree of nested namespaces.
10
11 The `.Collection` class provides an API for organizing tasks (and :ref:`their
12 configuration <collection-configuration>`) into a tree-like structure. When
13 referenced by strings (e.g. on the CLI or in pre/post hooks) tasks in nested
14 namespaces use a dot-separated syntax, e.g. ``docs.build``.
15
16 In this section, we show how building namespaces with this API is flexible but
17 also allows following Python package layouts with minimal boilerplate.
18
19
20 Starting out
21 ============
22
23 One unnamed ``Collection`` is always the namespace root; in the implicit base
24 case, Invoke creates one for you from the tasks in your tasks module. Create
25 your own, named ``namespace`` or ``ns``, to set up an explicit namespace (i.e.
26 to skip the default "pull in all Task objects" behavior)::
27
28 from invoke import Collection
29
30 ns = Collection()
31 # or: namespace = Collection()
32
33 Add tasks with `.Collection.add_task`. `~.Collection.add_task` can take an
34 `.Task` object, such as those generated by the `.task` decorator::
35
36 from invoke import Collection, task
37
38 @task
39 def release(c):
40 c.run("python setup.py sdist register upload")
41
42 ns = Collection()
43 ns.add_task(release)
44
45 Our available tasks list now looks like this::
46
47 $ invoke --list
48 Available tasks:
49
50 release
51
52
53 Naming your tasks
54 =================
55
56 By default, a task's function name is used as its namespace identifier, but you
57 may override this by giving a ``name`` argument to either `@task <.task>` (i.e.
58 at definition time) or `.Collection.add_task` (i.e. at binding/attachment
59 time).
60
61 For example, say you have a variable name collision in your tasks module --
62 perhaps you want to expose a ``dir`` task, which shadows a Python builtin.
63 Naming your function itself ``dir`` is a bad idea, but you can name the
64 function something like ``dir_`` and then tell ``@task`` the "real" name::
65
66 @task(name='dir')
67 def dir_(c):
68 # ...
69
70 On the other side, you might have obtained a task object that doesn't fit with
71 the names you want in your namespace, and can rename it at attachment time.
72 Maybe we want to rename our ``release`` task to be called ``deploy`` instead::
73
74 ns = Collection()
75 ns.add_task(release, name='deploy')
76
77 The result::
78
79 $ invoke --list
80 Available tasks:
81
82 deploy
83
84 .. note::
85 The ``name`` kwarg is the 2nd argument to `~.Collection.add_task`, so those
86 in a hurry can phrase it as::
87
88 ns.add_task(release, 'deploy')
89
90 Aliases
91 -------
92
93 Tasks may have additional names or aliases, given as the ``aliases`` keyword
94 argument; these are appended to, instead of replacing, any implicit or explicit
95 ``name`` value::
96
97 ns.add_task(release, aliases=('deploy', 'pypi'))
98
99 Result, with three names for the same task::
100
101 $ invoke --list
102 Available tasks:
103
104 release
105 deploy
106 pypi
107
108 .. note::
109 The convenience decorator `@task <.task>` is another method of
110 setting aliases (e.g. ``@task(aliases=('foo', 'bar'))``, and is useful for
111 ensuring a given task always has some aliases set no matter how it's added
112 to a namespace.
113
114 .. _dashes-vs-underscores:
115
116 Dashes vs underscores
117 ---------------------
118
119 In the common case of functions-as-tasks, you'll often find yourself writing
120 task names that contain underscores::
121
122 @task
123 def my_awesome_task(c):
124 print("Awesome!")
125
126 Similar to how task arguments are processed to turn their underscores into
127 dashes (since that's a common command-line convention) all underscores in task
128 or collection names are interpreted to be dashes instead, by default::
129
130 $ inv --list
131 Available tasks:
132
133 my-awesome-task
134
135 $ inv my-awesome-task
136 Awesome!
137
138 If you'd prefer the underscores to remain instead, you can update your
139 configuration to set ``tasks.auto_dash_names`` to ``False`` in one of the
140 non-runtime :ref:`config files <config-files>` (system, user, or project.) For
141 example, in ``~/.invoke.yml``::
142
143 tasks:
144 auto_dash_names: false
145
146 .. note::
147 In the interests of avoiding confusion, this setting is "exclusive" in
148 nature - underscored version of task names *are not valid* on the CLI
149 unless ``auto_dash_names`` is disabled. (However, at the pure function
150 level within Python, they must continue to be referenced with underscores,
151 as dashed names are not valid Python syntax!)
152
153
154 Nesting collections
155 ===================
156
157 The point of namespacing is to have sub-namespaces; to do this in Invoke,
158 create additional `.Collection` instances and add them to their parent
159 collection via `.Collection.add_collection`. For example, let's say we have a
160 couple of documentation tasks::
161
162 @task
163 def build_docs(c):
164 c.run("sphinx-build docs docs/_build")
165
166 @task
167 def clean_docs(c):
168 c.run("rm -rf docs/_build")
169
170 We can bundle them up into a new, named collection like so::
171
172 docs = Collection('docs')
173 docs.add_task(build_docs, 'build')
174 docs.add_task(clean_docs, 'clean')
175
176 And then add this new collection under the root namespace with
177 ``add_collection``::
178
179 ns.add_collection(docs)
180
181 The result (assuming for now that ``ns`` currently just contains the original
182 ``release`` task)::
183
184 $ invoke --list
185 Available tasks:
186
187 release
188 docs.build
189 docs.clean
190
191 As with tasks, collections may be explicitly bound to their parents with a
192 different name than they were originally given (if any) via a ``name`` kwarg
193 (also, as with ``add_task``, the 2nd regular arg)::
194
195 ns.add_collection(docs, 'sphinx')
196
197 Result::
198
199 $ invoke --list
200 Available tasks:
201
202 release
203 sphinx.build
204 sphinx.clean
205
206
207 Importing modules as collections
208 ================================
209
210 A simple tactic which Invoke itself uses in the trivial, single-module
211 case is to use `.Collection.from_module` -- a classmethod
212 serving as an alternate ``Collection`` constructor which takes a Python module
213 object as its first argument.
214
215 Modules given to this method are scanned for ``Task`` instances, which are
216 added to a new ``Collection``. By default, this collection's name is taken from
217 the module name (the ``__name__`` attribute), though it can also be supplied
218 explicitly.
219
220 .. note::
221 As with the default task module, you can override this default loading
222 behavior by declaring a ``ns`` or ``namespace`` `.Collection` object at top
223 level in the loaded module.
224
225 For example, let's reorganize our earlier single-file example into a Python
226 package with several submodules. First, ``tasks/release.py``::
227
228 from invoke import task
229
230 @task
231 def release(c):
232 c.run("python setup.py sdist register upload")
233
234 And ``tasks/docs.py``::
235
236 from invoke import task
237
238 @task
239 def build(c):
240 c.run("sphinx-build docs docs/_build")
241
242 @task
243 def clean(c):
244 c.run("rm -rf docs/_build")
245
246 Tying them together is ``tasks/__init__.py``::
247
248 from invoke import Collection
249
250 import release, docs
251
252 ns = Collection()
253 ns.add_collection(Collection.from_module(release))
254 ns.add_collection(Collection.from_module(docs))
255
256 This form of the API is a little unwieldy in practice. Thankfully there's a
257 shortcut: ``add_collection`` will notice when handed a module object as its
258 first argument and call ``Collection.from_module`` for you internally::
259
260 ns = Collection()
261 ns.add_collection(release)
262 ns.add_collection(docs)
263
264 Either way, the result::
265
266 $ invoke --list
267 Available tasks:
268
269 release.release
270 docs.build
271 docs.clean
272
273
274 Default tasks
275 =============
276
277 Tasks may be declared as the default task to invoke for the collection they
278 belong to, e.g. by giving ``default=True`` to `@task <.task>` (or to
279 `.Collection.add_task`.) This is useful when you have a bunch of related tasks
280 in a namespace but one of them is the most commonly used, and maps well to the
281 namespace as a whole.
282
283 For example, in the documentation submodule we've been experimenting with so
284 far, the ``build`` task makes sense as a default, so we can say things like
285 ``invoke docs`` as a shortcut to ``invoke docs.build``. This is easy to do::
286
287 @task(default=True)
288 def build(c):
289 # ...
290
291 When imported into the root namespace (as shown above) this alters the output
292 of ``--list``, highlighting the fact that ``docs.build`` can be invoked as
293 ``docs`` if desired::
294
295 $ invoke --list
296 Available tasks:
297
298 release.release
299 docs.build (docs)
300 docs.clean
301
302 Default subcollections
303 ----------------------
304
305 As of version 1.5, this functionality is also extended to subcollections: a
306 subcollection can be specified as the default when being added to its parent
307 collection, and that subcollection's own default task (or sub-subcollection!)
308 will be invoked as the default for the parent.
309
310 An example probably makes that clearer. Here's a tiny inline task tree with two
311 subcollections, each with their own default task::
312
313 from invoke import Collection, task
314
315 @task(default=True)
316 def build_all(c):
317 print("build ALL THE THINGS!")
318
319 @task
320 def build_wheel(c):
321 print("Just the wheel")
322
323 build = Collection(all=build_all, wheel=build_wheel)
324
325 @task(default=True)
326 def build_docs(c):
327 print("Code without docs is no code at all")
328
329 docs = Collection(build_docs)
330
331 Then we tie those into one top level collection, setting the ``build``
332 subcollection as the overall default::
333
334 ns = Collection()
335 ns.add_collection(build, default=True)
336 ns.add_collection(docs)
337
338 The result is that ``build.all`` becomes the absolute default task::
339
340 $ invoke
341 build ALL THE THINGS!
342
343 Mix and match
344 =============
345
346 You're not limited to the specific tactics shown above -- now that you know
347 the basic tools of ``add_task`` and ``add_collection``, use whatever approach
348 best fits your needs.
349
350 For example, let's say you wanted to keep things organized into submodules, but
351 wanted to "promote" ``release.release`` back to the top level for convenience's
352 sake. Just because it's stored in a module doesn't mean we must use
353 ``add_collection`` -- we could instead import the task itself and use
354 ``add_task`` directly::
355
356 from invoke import Collection
357
358 import docs
359 from release import release
360
361 ns = Collection()
362 ns.add_collection(docs)
363 ns.add_task(release)
364
365 Result::
366
367 $ invoke --list
368 Available tasks:
369
370 release
371 docs.build
372 docs.clean
373
374
375 More shortcuts
376 ==============
377
378 Finally, you can even skip ``add_collection`` and ``add_task`` if your needs
379 are simple enough -- `.Collection`'s constructor will take
380 unknown arguments and build the namespace from their values as
381 appropriate::
382
383 from invoke import Collection
384
385 import docs, release
386
387 ns = Collection(release.release, docs)
388
389 Notice how we gave both a task object (``release.release``) and a module
390 containing tasks (``docs``). The result is identical to the above::
391
392 $ invoke --list
393 Available tasks:
394
395 release
396 docs.build
397 docs.clean
398
399 If given as keyword arguments, the keywords act like the ``name`` arguments do
400 in the ``add_*`` methods. Naturally, both can be mixed together as well::
401
402 ns = Collection(docs, deploy=release.release)
403
404 Result::
405
406 $ invoke --list
407 Available tasks:
408
409 deploy
410 docs.build
411 docs.clean
412
413 .. note::
414 You can still name these ``Collection`` objects with a leading string
415 argument if desired, which can be handy when building sub-collections.