Debian Codegraph @

sites/docs/concepts/loading.rst

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