Metadata-Version: 2.1
Name: cachedcomplete
Version: 1.0.3
Summary: Cached wrapper for python argcomplete
Home-page: https://github.com/Roynecro97/cachedcomplete
Author: 
Author-email: 
License: MIT License
Project-URL: Source Code, https://github.com/Roynecro97/cachedcomplete
Description: # cachedcomplete
        
        Cached wrapper for python argcomplete.
        
        ## Installation
        
        Use the package manager pip to install cachedcomplete.
        
        ```bash
        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
        # PYTHON_ARGCOMPLETE_OK
        import argcomplete
        
        # ...
        
        argcomplete.autocomplete()
        ```
        
        **Using cachedcomplete:**
        
        ```python
        # 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:**
        
        ```python
        import argcomplete
        
        class CustomCompletionFinder(argcomplete.CompletionFinder):
            # ...
        
        completion_finder = CustomCompletionFinder()
        # Instead of argcomplete.autocomplete()
        completion_finder()
        ```
        
        **Using cachedcomplete:**
        
        ```python
        import argcomplete
        import cachedcomplete
        
        @cachedcomplete.cached_completion_finder
        class CustomCompletionFinder(argcomplete.CompletionFinder):
            # ...
        
        completion_finder = CustomCompletionFinder()
        # Instead of argcomplete.autocomplete()
        completion_finder()
        ```
        
        **or:**
        
        ```python
        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:
        
        ```python
        # CACHEDCOMPLETE_HASH: file1.py
        ```
        
        It also allows multiple files split to multiple comments, or within one comment.
        
        ```python
        # 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
        
        ```python
        # CACHEDCOMPLETE_HASH: dir
        ```
        
        Using environment variables and user directories is also allowed:
        
        ```python
        # 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.
        
        ```python
        # 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
        # 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`
        
        ```python
        import json
        
        def json_file(arg):
            with argparse.FileType()(arg) as f:
                return json.load(f)
        ```
        
        In `my_awesome_script.py`
        
        ```python
        # 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)
        ```
        
Platform: MacOS X
Platform: Posix
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Terminals
Description-Content-Type: text/markdown
