| 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. |