| 1 |
.. _loading-collections: |
| 2 |
|
| 3 |
=================== |
| 4 |
Loading collections |
| 5 |
=================== |
| 6 |
|
| 7 |
The core of Invoke's execution model involves one or more Collection objects. |
| 8 |
While these may be created programmatically, in typical use Invoke will create |
| 9 |
them for you from Python modules it finds or is told to use. |
| 10 |
|
| 11 |
|
| 12 |
.. _collection-discovery: |
| 13 |
|
| 14 |
Task module discovery |
| 15 |
===================== |
| 16 |
|
| 17 |
With no other configuration, simply calling ``invoke`` will look for a single |
| 18 |
Python module or package named ``tasks``, and will treat it as the root |
| 19 |
namespace. ``tasks`` (or any other name given via :ref:`loading configuration |
| 20 |
options <configuring-loading>`) is searched for in the following ways: |
| 21 |
|
| 22 |
* First, if a valid tasks module by that name already exists on Python's |
| 23 |
`sys.path <https://docs.python.org/release/2.7/library/sys.html#sys.path>`_, |
| 24 |
no more searching is done -- that module is selected. |
| 25 |
* Failing that, search towards the root of the local filesystem, starting with |
| 26 |
the user's current working directory (`os.getcwd |
| 27 |
<https://docs.python.org/release/2.7/library/os.html#os.getcwd>`_) and try |
| 28 |
importing again with each directory temporarily added to ``sys.path``. |
| 29 |
|
| 30 |
* Due to how Python's import machinery works, this approach will always |
| 31 |
favor a package directory (``tasks/`` containing an ``__init__.py``) over |
| 32 |
a module file (``tasks.py``) in the same location. |
| 33 |
* If a candidate is found and successfully imported, its parent directory |
| 34 |
will **stay** on ``sys.path`` during the rest of the Python session -- |
| 35 |
this allows task code to make convenient assumptions concerning sibling |
| 36 |
modules' importability. |
| 37 |
|
| 38 |
Candidate modules/packages are introspected to make sure they can actually be |
| 39 |
used as valid task collections. Any that fail are discarded, the ``sys.path`` |
| 40 |
munging done to import them is reverted, and the search continues. |
| 41 |
|
| 42 |
|
| 43 |
.. _configuring-loading: |
| 44 |
|
| 45 |
Configuring the loading process |
| 46 |
=============================== |
| 47 |
|
| 48 |
You can configure the above behavior, requesting that Invoke alter the |
| 49 |
collection name searched for and/or the path where filesystem-level loading |
| 50 |
starts looking. |
| 51 |
|
| 52 |
For example, you may already have a project-level ``tasks.py`` that you can't |
| 53 |
easily rename; or you may want to host a number of tasks collections stored |
| 54 |
outside the project root and make it easy to switch between them; or any number |
| 55 |
of reasons. |
| 56 |
|
| 57 |
Both the sought collection name and the search root can be specified via |
| 58 |
:ref:`configuration file options <config-files>` or as :doc:`runtime CLI flags |
| 59 |
</invoke>`: |
| 60 |
|
| 61 |
- **Change the collection name**: Set the ``tasks.collection_name`` |
| 62 |
configuration option, or use :option:`--collection`. It should be a Python |
| 63 |
module name and not a file name (so ``mytasks``, not ``mytasks.py`` or |
| 64 |
``mytasks/``.) |
| 65 |
- **Change the root search path**: Configure ``tasks.search_root`` or use |
| 66 |
:option:`--search-root`. This value may be any valid directory path. |