Skip to content
Back to top
View this page
Edit this page

# xonsh.commands_cache

Module for caching command & alias names as well as for predicting whether a command will be able to be run in the background.

A background predictor is a function that accepts a single argument list and returns whether or not the process can be run in the background (returns True) or must be run the foreground (returns False).

class xonsh.commands_cache.CaseInsensitiveDict(*args, **kwargs)
  clear(/)

    Remove all items from the dict.

  copy()

    Return a shallow copy of the dict.

  classmethod fromkeys(iterable, value=None, /)

    Create a new dictionary with keys from iterable and values set to value.

  get(key, default=None)

    Return the value for key if key is in the dictionary, else default.

  items()

    Return a set-like object providing a view on the dict’s items.

  keys()

    Return a set-like object providing a view on the dict’s keys.

  pop(key, default=<unrepresentable>, /)

    If the key is not found, return the default if given; otherwise, raise a KeyError.

  popitem(/)

    Remove and return a (key, value) pair as a 2-tuple.

    Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

  setdefault(key, default=None, /)

    Insert key with a value of default if key is not in the dictionary.

    Return the value for key if key is in the dictionary, else default.

  update([E, ]**F) → None. Update D from mapping/iterable E and F.

    If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

  values(/)

    Return an object providing a view on the dict’s values.

class xonsh.commands_cache.CommandsCache(env, aliases=None)

  A lazy cache representing the commands available on the file system. The keys are the command names and the values a tuple of (loc, has_alias) where loc is either a str pointing to the executable on the file system or None (if no executable exists) and has_alias is a boolean flag for whether the command has an alias.

  Note! There is `xonsh.procs.executables` module with resolving executables. Usage `executables` is preferred instead of commands_cache for cases where you just need to locate executable command.

  cached_name(name)

    Returns the name that would appear in the cache, if it exists.

  default_predictor(name, cmd0)

    Default predictor, using predictor from original command if the command is an alias, elseif build a predictor based on binary analysis on POSIX, else return predict_true.

  default_predictor_alias(cmd0)
  default_predictor_readbin(name, cmd0, timeout, failure)

    Make a default predictor by analyzing the content of the binary. Should only works on POSIX. Return failure if the analysis fails.

  get(k[, d]) → D[k] if k in D, else d. d defaults to None.
  get_possible_names(name)
  get_predictor_threadable(cmd0)

    Return the predictor whether a command list is able to be run on a background thread, rather than the main thread.

  is_empty()

    Returns whether the cache is populated or not.

  is_only_functional_alias(name)

    Returns whether or not a command is only a functional alias, and has no underlying executable. For example, the “cd” command is only available as a functional alias.

  items() → a set-like object providing a view on D's items
  iter_commands()

    Wrapper for handling windows path behaviour

  keys() → a set-like object providing a view on D's keys
  lazy_is_only_functional_alias(name) → bool

    Returns whether or not a command is only a functional alias, and has no underlying executable. For example, the “cd” command is only available as a functional alias. This search is performed lazily.

  lazy_locate_binary(name, ignore_alias=False)

    Locates an executable in the cache, without checking its validity.

    NOT RECOMMENDED. Take a look into xonsh.procs.executables.locate_executable before using this function.

    Parameters:
      name str

        name of binary to search for

      ignore_alias bool, optional

        Force return of binary path even if alias of `name` exists (default `False`)

  lazyget(key, default=None)

    A lazy value getter.

  lazyin(key)

    Checks if the value is in the current cache without the potential to update the cache. It just says whether the value is known now. This may not reflect precisely what is on the $PATH.

  lazyiter()

    Returns an iterator over the current cache contents without the potential to update the cache. This may not reflect what is on the $PATH.

  lazylen()

    Returns the length of the current cache contents without the potential to update the cache. This may not reflect precisely what is on the $PATH.

  locate_binary(name, ignore_alias=False)

    Locates an executable on the file system using the cache.

    NOT RECOMMENDED. Take a look into xonsh.procs.executables.locate_executable before using this function.

    Parameters:
      name str

        name of binary to search for

      ignore_alias bool, optional

        Force return of binary path even if alias of `name` exists (default `False`)

  predict_threadable(cmd)

    Predicts whether a command list is able to be run on a background thread, rather than the main thread.

  resolve_symlink(path)
  update_cache()

    The main function to update commands cache. Note! There is `xonsh.procs.executables` module with resolving executables. Usage `executables` is preferred instead of commands_cache for cases where you just need to locate executable command.

  values() → an object providing a view on D's values
  CACHE_FILE = 'path-commands-cache.pickle'
  property all_commands
  property cache_file

    Keeping a property that lies on instance-attribute

xonsh.commands_cache.default_threadable_predictors()

  Generates a new defaultdict for known threadable predictors. The default is to predict true.

xonsh.commands_cache.executables_in(path) → Iterable[str]

  Returns a generator of files in path that the user could execute.

xonsh.commands_cache.predict_env(args, cmd_cache: CommandsCache)

  Predict if env is launching a threadable command or not. The launched command is extracted from env args, and the predictor of lauched command is used.

xonsh.commands_cache.predict_false(_, __)

  Never say the process is threadable.

xonsh.commands_cache.predict_help_ver(args, _)

  Predict the backgroundability of commands that have help & version switches: -h, –help, -v, -V, –version. If either of these options is present, the command is assumed to print to stdout normally and is therefore threadable. Otherwise, the command is assumed to not be threadable. This is useful for commands, like top, that normally enter alternate mode but may not in certain circumstances.

xonsh.commands_cache.predict_hg(args, _)

  Predict if mercurial is about to be run in interactive mode. If it is interactive, predict False. If it isn’t, predict True. Also predict False for certain commands, such as split.

xonsh.commands_cache.predict_shell(args, _)

  Predict the backgroundability of the normal shell interface, which comes down to whether it is being run in subproc mode.

xonsh.commands_cache.predict_true(_, __)

  Always say the process is threadable.