Utils Module

Utility functions for searchinator.

utils.TIME_FORMAT = '%Y-%m-%dT%H:%M:%S'

Expected string format for datetime.datetime.

utils.load_time(x)

Load a datetime.datetime from str.

Uses TIME_FORMAT to parse a string and load it as a datetime.datetime.

utils.dump_time(x)

Dump a datetime.datetime to str.

Uses TIME_FORMAT to parse a string and load it as a datetime.datetime.

utils.as_inator(dct)

Attempt to construct values of an inator with appropriate types.

This function is intended to be used as the object_hook for json.load() or json.loads(). Whenever a dictionary is decoded from JSON, this function checks whether the dictionary (passed as dct) is an inator record. If it is, the condition and added fields are loaded as datetime.datetime and condition.Condition respectively.

If dct isn’t an inator record, dct is returned unmodified.

Refer to the json.load docs for more details on object_hook.

Parameters:dct (dict) – A dictionary that might be an inator record.
Return type:dict
utils.from_datetime(obj)

Convert datetime.datetime objects to string.

This function is intended to be used as the default for json.dump() or json.dumps(). Whenever an object is to be encoded to JSON, this function checks whether it is an instance of datetime.datetime. If it is, dump_time is called to convert it to a string. The string value is then returned.

If the value is not an instance of datetime.datetime, a TypeError is raised.

Refer to the json.dump docs for more details on default.

Parameters:obj – An object that we might convert to a string
Return type:str
Raises:TypeError – if obj isn’t a datetime.datetime.
@utils.add_data_param(path)

Wrap a function to facilitate data storage.

This function returns a decorator that wraps a function, so that the wrapped function gains an additional parameter: data. data is a dictionary (see Data Dictionary) that contains data loaded from path. After the wrapped function returns, data is written back to path.

The wrapped function is free to modify data. all modifications will be written to path after the wrapped function returns.

Consider the following example:

>>> @add_data_param('/tmp/test.json')
>>> def func(data):
>>>     data['cats'] = 'the best'
>>>
>>> func()  # Accepts zero parameters since *data* is passed by the decorator
>>>
>>> with open('/tmp/test.json') as f:
>>>     print(f.read())
{
    "cats": "the best"
}

This function does not enforce the structure of the data loaded from path. It simply loads it, then stores it.

If the file specified by path doesn’t exist, the data parameter is set to an empty dictionary. After the wrapped function is called, data is always written back to path.

Parameters:str – The path to a JSON-encoded file. It should decode as a dict.
Returns:A decorator that modifies the behavior of a wrapped function as described above.
@utils.uses_template(template)

Wrap a function to add HTML template rendering functionality.

This function returns a decorator that wraps a function, so that the wrapped function’s return value is used to render the HTML template specified by template.

To render the template, the wrapped function must return a dict. The wrapper will use the returned dict as a template context, meaning that its keys/values will be used to fill in template. Check out the Flask docs that show how to render a template.

If the wrapped function’s return value isn’t a dict, the wrapper will simply return the original dict.

If the wrapped function’s return value isn’t a dict, the wrapper will simply return the original return value.

In other words, if the wrapped function returns a dict, then use it to render a template. Otherwise, the wrapper should return the wrapped function’s return value as is.

Parameters:str – The path to the HTML template we should use.
Returns:A decorator that modifies the behavior of a wrapped function as described above.
@utils.login_required

Wrap a function to enforce user authentication.

This function wraps a function, so that the wrapped function is only executed if the user is logged in. That is, if the user is logged in, the wrapped function is called as usual. If the user is not logged in, the user is redirected to ‘/login/’.

We can check if a user is logged in by verifying that the “username” key is present in the user’s session (a dictionary-like object).

If the user is not logged in, we also flash a danger message informing them that they need to log in before they can proceed.