oblalex / lazy-string

Python library for defining strings with delayed evaluation

lazy-string

Python library for defining strings with delayed evaluation.

The package provides a LazyString class. Its constructor accepts a callable (say, a function) which will be called when string's value is needed. The constructor also allows to specify positional and keyword arguments for that callable:

def __init__(self, func: Callable[..., str], *args: Tuple, **kwargs: Mapping) -> None:
  ...

The value is re-evaluated on every access.

Installation

Available as a PyPI package:

pip install lazy-string

Usage

Using with a function having no parameters:

from lazy_string import LazyString

def make_foo() -> str:
  return "foo"

s = LazyString(make_foo)

The value is evaluated on demand:

>>> s + " bar"
'foo bar'

>>> str(s)
'foo'

Representation explicitly tells it's a LazyString:

>>> s
LazyString('foo')

It's safe to pass standard strings, as they will be returned as-is:

>>> LazyString("foo bar")
'foo bar'

Supports methods of standard strings:

>>> s.upper()
'FOO'

>>> "f" in s
True

>>> dir(s)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__',
 '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__',
 '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__',
 '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__',
 '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__',
 '__setattr__', '__sizeof__', '__str__', '__subclasshook__',
 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith',
 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha',
 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric',
 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower',
 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust',
 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith',
 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

Supplying parameters for the callable:

def make_foo(arg1, arg2):
  return f"foo {arg1} {arg2}"

s = LazyString(make_foo, 123, arg2=456)

>>> str(s)
'foo 123 456'

Implementation Details

LazyString is inherited from collections.UserString.

>>> LazyString.__mro__
(<class 'lazy_string.LazyString'>, <class 'collections.UserString'>,
 <class 'collections.abc.Sequence'>, <class 'collections.abc.Reversible'>,
 <class 'collections.abc.Collection'>, <class 'collections.abc.Sized'>,
 <class 'collections.abc.Iterable'>, <class 'collections.abc.Container'>,
 <class 'object'>)

Serialization

Pickling

Supported out of the box:

>>> import pickle
>>> s == pickle.loads(pickle.dumps(s))
True

To JSON

Supported with any encoder able to encode collections.UserString:

import json
import collections

class JSONEncoder(json.JSONEncoder):

  def default(self, o):
    if isinstance(o, collections.UserString):
      return str(o)
    return super().default(o)

>>> data = {'s': s}
>>> json.dumps(data, cls=JSONEncoder)
'{"s": "foo"}'

lazy-string's Issues

Maybe add some particularly useful examples to the docs?

Awesome library! I wish I'd thought to google for this when writing dozens of DEBUG log messages with expensive string formatting, usually pprint. For example the following is incomplete, the expensive call to pprint.pformat may still happen for some logging configurations:

if logger.isEnabledFor(logging.DEBUG):
    logger.debug("Processing large data shape:\n%s", pprint.pformat(data_dict))

This might make a good example to include in the docs to help potential users imagine why they might use this. Untested, but in this case the expensive call should never happen unless this logging record is actually going to be emitted:

logger.debug(
    "Processing large data shape:\n%s",
    lazy_string.LazyString(functools.partial(pprint.pformat, data_dict)),
)

LazyString.encode fails with <LazyString broken>

The following code snippet raises a TypeError: 'bytes' object is not callable

from lazy_string import LazyString

def get_abc():
    return "abc"

s = LazyString(get_abc)

print(s.encode('UTF-8'))

Here is the traceback from running this

Traceback (most recent call last):
  File "testls.py", line 8, in <module>
    print(s.encode('UTF-8'))
  File "/usr/local/Cellar/[email protected]/3.7.11/Frameworks/Python.framework/Versions/3.7/lib/python3.7/collections/__init__.py", line 1163, in __str__
    def __str__(self): return str(self.data)
  File "/Users/brian/.virtualenvs/nips3/lib/python3.7/site-packages/lazy_string.py", line 56, in data
    return self._func(*self._args, **self._kwargs)
TypeError: 'bytes' object is not callable