/PyEverything

Python bindings for the Everything Service API

Primary LanguageC++OtherNOASSERTION

PyEverything

Python bindings for the Everything Service API

Everything is a windows-based program that lets a user index and very quickly search on the order of millions of files. There is an SDK for the program, which is written in C.

PyEverything is exactly what the name suggests: Python bindings for the C functionality so that python scripters can leverage this extremely powerful service.

Requirements

  1. Python 3.7 64-bit or later.
  2. Windows
  3. Everything Service 1.4.1+ installed https://www.voidtools.com/

Installation

pip install git+https://github.com/nambread/PyEverything#egg=PyEverything

This will pull the latest release. Add "@vx.x.x" after the url to pull a specific version. Eg:

pip install git+https://github.com/nambread/PyEverything@v0.4.0#egg=PyEverything

If your version of python is not officially supported, but you still wish to use it, follow the "Building from Source" instructions.

Usage

Basic API usages involves three main phases:

  1. Set up the query search state
  2. Submit the query
  3. Iterate over the resulting data via index

example

import PyEverything

PyEverything.SetSearch("example")
PyEverything.Query()
for i in PyEverything.GetNumResults():
    print(PyEverything.GetResultFullPathName(i))
    #results will get printed out here.

The full Everything SDK is here: https://www.voidtools.com/support/everything/sdk/ There are some key differences between the python SDK and the C one.

Python Key Differences

Return Types

There are several functions that provide some data in the C API, and do so by requiring a pointer to a buffer that the API then fills. For example, on https://www.voidtools.com/support/everything/sdk/everything_getresultfullpathname/

TCHAR buf[MAX_PATH];  

// set the search text to abc AND 123  
Everything_SetSearch("abc 123");  

// execute the query  
Everything_Query(TRUE);  

// Get the full path and file name of the first visible result.  
Everything_GetResultFullPathName(0,buf,sizeof(buf) / sizeof(TCHAR));

In PyEverything, this will be a returned string:

#set the search text to abc AND 123  
PyEverything.SetSearch("abc 123")

#execute the query  
PyEverything.Query(True)

#Get the full path and file name of the first visible result.  
result = PyEverything.GetResultFullPathName(0)

Functions that return a date will return None if that data could not be queried. (Which might be the case with incomplete indexes of drives that are no longer available.)

GetResultDateAccessed()
GetResultDateCreated()
GetResultDateModified()
GetResultDateRecentlyChanged()
GetResultDateRun()

Error Handling

A large portion of the C API returns error codes, which the user must handle. For example, on https://www.voidtools.com/support/everything/sdk/everything_getlasterror/

// execute the query  
if (!Everything_Query(true))  
{  
    DWORD dwLastError = Everything_GetLastError();  
    if (dwLastError == EVERYTHING_ERROR_IPC)  
	{  
	    // IPC not available.  
    }  
}

In Python, this is instead a RuntimeError:

>>> import PyEverything
>>> PyEverything.SetSearch("abc 123")
>>> PyEverything.Query() #Raises PyEverything.ERROR_IPC
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
RuntimeError: Everything API returned error code: 2

The numerical value of the exception is the same as on the above GetLastError page.

Namespaces

C lacks namespaces, so all Everything SDK methods and variables have the "Everything_" prefix. the "PyEverything" package is already a namespace, so this prefix has been dropped everywhere that it appears. Keyboard switches are expensive, you shouldn't wear them out!

Building from Source

Building from source is done via python and setuptools. The extension module is created with pybind11, a super easy to use library that lets users wrap complex C code and expose it in a .pyd file.

dependencies

Instructions

  1. Clone this repo and initialise submodules:
    • git clone --recurse-submodules https://github.com/nambread/PyEverything
  2. Activate your virtual environment of choice.
  3. CD to the root repo folder and run python setup.py bdist_wheel
  4. You should get a wheel for your python version put in the newly created .\dist folder.
  5. pip install path/to/wheel.whl