Metadata-Version: 2.1
Name: string-path-search
Version: 0.3.3
Summary: Search a directory path for any of a list of strings.
Home-page: https://github.com/j-lawrence-b1/string_path_search
Author: Larry Barnett
Author-email: JLawrenceB1@gmail.com
License: MIT
Description: 
        # string-path-search
         Walk a directory tree, searching for files containing any of a set of text strings.
        
        **Note:** The different naming conventions for projects on GitHub vs packages in Python results 
        in some unnecessary confusion: "string-path-search" (with hyphens) is the name of the project on
         GitHub. This project provides the "string_path_search" (with underscores) Python package. 
         Please bear with me.
         
        ## Why not just use ***find*** and ***grep***?
        * Avoids long, hard-to-debug shell commands with lots of backticks and parentheses.
        * Works on Windows without needing to install a unix work-alike like Cygwin.
        * Searches for a bunch of different strings in one go.
        * Searches within (possibly compressed) jar, tar, or zip archives.
        * Outputs results in CSV or Excel format. 
        
        ## System requirements
        * Tested on Windows 10, Linux, and Windows 10/cygwin. May also work on other platforms
         supported by Python.
        * Python 3.4 or later (https://www.python.org/downloads/).
        * A Python pip module appropriate to the installed Python version
         (https://pip.pypa.io/en/stable/installing/). It is *possible* to install Python packages, 
         including string_path_search, without pip, but it's a lot harder without it.
         
        ## A note about installing python and pip
        Some Linux systems (also Cygwin on Windows) come with python 2
        pre-installed. You have to install python 3 yourself. There are gotchas
        involved:
        1. The "python" and "pip" packages may be reserved for version 2. It may not be as easy as 
         "apt-get install python3" either. The latest package might be called "python3.7" or similar.
          Ditto with pip.
        2.  Once installed, the python 3 binary may be called "python3", not
            "python". Ditto with pip.
          
        ## Installation from pypi:
        <pre>
        > python -m pip install --user string-path-search 
        </pre>
        
        ## Installation from GitHub
        You can also download string-path-search with your browser as a .zip or .tgz archive from 
        https://github.com/j-lawrence-b1/string-path-search/releases/latest 
         into any convenient directory. Once unpacked, you can install string_path_search and its 
         dependencies using the included setup.py script (which uses pip internally!).
        <pre>
        > chdir &lt;my-downloads-dir&gt;\\string-path-search-0.3.2
        > python setup.py build install --user 
        </pre>
        **Note:** Installing with the '--user' option will install the string_path_search Python package
        under your login's HOME directory (C:/Users/<user-name>/.local/Scripts on 
        Windows or /home/<user-name>/.local/bin on Linux). If you plan to run the
         provided string_path_search.exe directly, you should add this directory to you
         your shell's execution path.
        ## Usage
        Although you can import and use this package in other Python scripts,
        string_path_search is primarily intended to be invoked as a console app:
        <pre>
            $ python -m string_path_search [OPTIONS] &lt;scan-root&gt; [&lt;search-term&gt; [...]]
        </pre>
        or, you can add run the standalone string_path_search.exe directly (see **Note,** above).
        <pre>
            $ ~/.local/bin/string_path_search [OPTIONS] &lt;scan-root&gt; [&lt;search-term&gt; [...]]
        </pre>
        where:
        <pre>
            -a, --scan-archives = Unpack and scan within archives
                (Default: Skip arhive files. Only jar, tar, and zip archives will be
                    unpacked. Tar bzip2, gzip, and xz compression is supported.
            -B, --branding-text=&lt;branding-text&gt; = A string of text containing
                company or other information to add above the column headers in
                scan reports (Default: no text).
            -b, --branding-logo=&lt;branding-logo&gt; = (MS Excel only) An image
                file containing a corporate logo or other graphic to add above the
                column headers in scan reports (Default: no logo).
            -h, --help = Print usage information and exit.
            -e, --excel-output = Generate Microsoft Excel 2007 (.xlsx) output
                (Default: Generate comma-separated-value (CSV) text output)
            -i  --ingore-case = Ignore UPPER/lowercase differences when matching strings
                (Default: case differences are significant).
            -o, --output-dir=&lt;output-dir&gt; = Location for output (Default:
                &lt;current working directory&gt;).
            -s, --search-strings-file=&lt;search-strings&gt; = A file containing strings to
                search for, one per line (Default: Get search strings from the command line).
            -q, --quiet = Decrease logging verbosity (may repeat). -qqqq will suppress all logging.
            -t, --temp-dir=&lt;temp-dir&gt; = Location for unpacking archives
                (Default: &lt;output_dir&gt;/temp).
            -v, --verbose = Increase logging verbosity.
            -x, --exclusions-file=&lt;exclusion-file&gt; = A file containing (base) filenames to
                exclude from the search results, one per line (Default: Include all results).
        &lt;scan-root&gt; = Directory to scan.
        &lt;search-term&gt; ... = One or more terms to search for in &lt;scan-root&gt;.
        </pre>
        ## Examples
        
        Perform a caseless search of the test/data directory for any occurrence of
        'copyright', 'gpl', 'foo', 'bar', or 'baz' and output the results to a
        file called 'scan-&lt;timestamp>.csv' in the current working directory.
        <pre>$ python -m string_path_search -i tests/data "copyright (c)" gpl foo bar baz</pre>
         
        Same as example 1, except output to an Excel spreadsheet:
        <pre>$ python -m string_path_search -i -e tests/data "copyright (c)" gpl foo bar baz</pre>
        
        **Gotcha:** Use double-quotes for multi-word search strings. For some reason,
        single quotes screw up the command line parser.
        ## License
        string_path_search is distributed under the
        [MIT License](http://github.com/j-lawrence-b1/string-path-search/blob/master/LICENSE).
        
        ## Disclaimer regarding the test data:
        
        The files in the test/data folder were randomly downloaded from publicly 
        available Open Source projects. Distributing these materials with string_path_search as 
        test data may or may not be in violation of the applicable licenses.
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.4.0
Description-Content-Type: text/markdown
