# loki.batch.item_factory

Classes

`ItemFactory`() | Utility class to instantiate instances of `Item`

class ItemFactory

  Bases: `object`

  Utility class to instantiate instances of `Item`

  It maintains a `item_cache` for all created items. Most important factory method is `create_from_ir()` to create (or return from the cache) a `Item` object corresponding to an IR node. Other factory methods exist for more bespoke use cases.

  item_cache

    This maps item names to corresponding `Item` objects

    Type:

      `CaseInsensitiveDict`

  create_from_ir(node, scope_ir, config=None, ignore=None)

    Helper method to create items for definitions or dependency

    This is a helper method to determine the fully-qualified item names and item type for a given IR `Node`, e.g., when creating the items for definitions (see `Item.create_definition_items`) or dependencies (see `Item.create_dependency_items`).

    This routine’s responsibility is to determine the item name, and then call `get_or_create_item()` to look-up an existing item or create it.

    Parameters:

      - node (`Node` or `pymbolic.primitives.Expression`) – The Loki IR node for which to create a corresponding `Item`

      - scope_ir (`Scope`) – The scope node in which the IR node is declared or used. Note that this is not necessarily the same as the scope of the created `Item` but serves as the entry point for the lookup mechanism that underpins the creation procedure.

      - config (any:SchedulerConfiguration, optional) – The config object from which a bespoke item configuration will be derived.

      - ignore (list of str, optional) – A list of item names that should be ignored, i.e., not be created as an item.

  get_or_create_item(item_cls, item_name, scope_name, config=None)

    Helper method to instantiate an `Item` of class `item_cls` with name `item_name`.

    This helper method checks for the presence of `item_name` in the `item_cache` and returns that instance. If none is found, an instance of `item_cls` is created and stored in the item cache.

    The `scope_name` denotes the name of the parent scope, under which a parent `Item` has to exist in `self.item_cache` to find the source object to use.

    Item names matching one of the entries in the `config` disable list are skipped. If strict mode is enabled, this raises a `RuntimeError` if no matching parent item can be found in the item cache.

    Parameters:

      - item_cls (subclass of `Item`) – The class of the item to create

      - item_name (str) – The name of the item to create

      - scope_name (str) – The name under which a parent item can be found in the `item_cache` to find the corresponding source

      - config (`SchedulerConfig`, optional) – The config object to use to determine disabled items, and to use when instantiating the new item

    Returns:

      The item object or None if disabled or impossible to create

    Return type:

      `Item` or None

  get_or_create_item_from_item(name, item, config=None)

    Helper method to instantiate an `Item` as a clone of a given `item` with the given new `name`.

    This helper method checks for the presence of `name` in the `item_cache` and returns that instance. If none is in the cache, it tries a lookup via the scope, if applicable. Otherwise, a new item is created as a duplicate.

    This duplication is performed by replicating the corresponding `FileItem` and any enclosing scope items, applying name changes for scopes as implied by `name`.

    Parameters:

      - name (str) – The name of the item to create

      - item (`Item`) – The item to duplicate to create the new item

      - config (`SchedulerConfig`, optional) – The config object to use when instantiating the new item

    Returns:

      The new item object

    Return type:

      `Item`

  get_or_create_file_item_from_path(path, config, frontend_args=None)

    Utility method to create a `FileItem` for a given path

    This is used to instantiate items for the first time during the scheduler’s discovery phase. It will use a cached item if it exists, or parse the source file using the given `frontend_args`.

    Parameters:

      - path (str or pathlib.Path) – The file path of the source file

      - config (`SchedulerConfig`) – The config object from which the item configuration will be derived

      - frontend_args (dict, optional) – Frontend arguments that are given to `Sourcefile.from_file` when parsing the file

  get_or_create_file_item_from_source(source, config)

    Utility method to create a `FileItem` corresponding to a given source object

    This can be used to create a `FileItem` for an already parsed `Sourcefile`, or when looking up the file item corresponding to a `Item` by providing the item’s `source` object.

    Lookup is not performed via the `path` property in `source` but by searching for an existing `FileItem` in the cache that has the same source object. This allows creating clones of source files during transformations without having to ensure their path property is always updated. Only if no item is found in the cache, a new one is created.

    Parameters:

      - source (`Sourcefile`) – The existing sourcefile object for which to create the file item

      - config (`SchedulerConfig`) – The config object from which the item configuration will be derived

  get_or_create_module_definitions_from_candidates(name, config, module_names=None, only=None)

    Utility routine to get definition items matching `name` from a given list of module candidates

    This can be used to find a dependency that has been introduced via an unqualified import statement, where the local name of the dependency is known and a set of candidate modules thanks to the unqualified imports on the use side.

    Parameters:

      - name (str) – Local name of the item(s) in the candidate modules

      - config (`SchedulerConfig`) – The config object from which the item configuration will be derived

      - module_names (list of str, optional) – List of module candidates in which to create the definition items. If not provided, all `ModuleItem` in the cache will be considered.

      - only (list of `Item` classes, optional) – Filter the generated items to include only those of the type provided in the list

    Returns:

      The items matching `name` in the modules given in `module_names`. Ideally, only a single item will be found (or there would be a name conflict).

    Return type:

      tuple of `Item`