cachedcomplete 1.0.4

Cached wrapper for python argcomplete

cachedcomplete

Cached wrapper for python argcomplete.

Installation

Use the package manager pip to install cachedcomplete.

pip install cachedcomplete
activate-global-python-argcomplete

Explanation

cachedcomplete wraps argcomplete, and allows caching of its parsers in order to save up time.

cachedcomplete re-caches every time a change was made in itself, or in the files specified by the user.

cachedcomplete caches the parsers using pickle, which implies the parser must be able to be serialized and de-serialized using pickle.

Without any interference argparse's parsers cannot be serialized using pickle, because the default type is defined within the parser's __init__ function. cachedcomplete replaces the default type with an identical type that can be pickled (this is only done when cachedcomplete detects that the default type is still the default identity function).

Usage

Normal Usage

The normal usage is the same as in argcomplete, only changing the import from argcomplete to cachedcomplete.

Note: The usage of PYTHON_ARGCOMPLETE_OK stays the same as in argcomplete

For Example

Using argcomplete:

# PYTHON_ARGCOMPLETE_OK
import argcomplete

# ...

argcomplete.autocomplete()

Using cachedcomplete:

# PYTHON_ARGCOMPLETE_OK
import cachedcomplete

# ...

cachedcomplete.autocomplete()

Usage of custom subclasses of CompletionFinder

In order to use custom CompletionFinders with cachedcomplete, a usage of the decorator cached_completion_finder is required.

For example

Using argcomplete:

import argcomplete

class CustomCompletionFinder(argcomplete.CompletionFinder):
    # ...

completion_finder = CustomCompletionFinder()
# Instead of argcomplete.autocomplete()
completion_finder()

Using cachedcomplete:

import argcomplete
import cachedcomplete

@cachedcomplete.cached_completion_finder
class CustomCompletionFinder(argcomplete.CompletionFinder):
    # ...

completion_finder = CustomCompletionFinder()
# Instead of argcomplete.autocomplete()
completion_finder()

or:

import argcomplete
import cachedcomplete

class CustomCompletionFinder(argcomplete.CompletionFinder):
    # ...

completion_finder = cachedcomplete.cached_completion_finder(CustomCompletionFinder)()
# Instead of argcomplete.autocomplete()
completion_finder()

Specifying what files to track

In order to specify which files to track changes in, add a comment with the wanted files and the prefix CACHEDCOMPLETE_HASH:

# CACHEDCOMPLETE_HASH: file1.py

It also allows multiple files split to multiple comments, or within one comment.

# CACHEDCOMPLETE_HASH: file1.py file2.json
# CACHEDCOMPLETE_HASH: file3.py
# CACHEDCOMPLETE_HASH: "file with spaces.txt"

And also allows passing up a directory to track all the files within

# CACHEDCOMPLETE_HASH: dir

Using environment variables and user directories is also allowed:

# CACHEDCOMPLETE_HASH: $HOME/.cache/my-cache /tmp/${USERNAME}.ini
# CACHEDCOMPLETE_HASH: ~/.cache/my-cache ~gdm/greeter-dconf-defaults

Paths are relative to the calling script, not the current working directory.

cachedcomplete adds an environment variable name pwd to allow accessing the current working directory in the comments. If this variable was already set, it is not overwritten.

# CACHEDCOMPLETE_HASH: $pwd/local-file

Using custom types, completers, actions, etc...

In order to cache a parser that uses your own custom types and functions, they must be defined in a separate module than the main script (that defines the parser).

Note: It is recommended to add these separate modules to the tracked files (As specified with CACHEDCOMPLETE_HASH).

Example:

Won't work:

In my_awesome_script.py

# PYTHON_ARGCOMPLETE_OK

import argparse
import cachedcomplete
import json

def json_file(arg):
    with argparse.FileType()(arg) as f:
        return json.load(f)

p = argparse.ArgumentParser()
p.add_argument('settings', type=json_file)
cachedcomplete.autocomplete(p)

Will work:

In my_awesome_type.py

import json

def json_file(arg):
    with argparse.FileType()(arg) as f:
        return json.load(f)

In my_awesome_script.py

# PYTHON_ARGCOMPLETE_OK
# CACHEDCOMPLETE_HASH: my_awesome_type.py

import argparse
import cachedcomplete

p = argparse.ArgumentParser()
p.add_argument('settings', type=json_file)
cachedcomplete.autocomplete(p)