ultralightweight/qtils

Qtils is a syntactic sugar library to make sweet Python coding even sweeter.

---

Overview

Qtils - pronounced as cutieels - is a syntactic sugar library to make sweet Python coding even sweeter.

Dedication

This library is dedicated to Pál Hubai, Surfy, my programming Master who spent countless hours answering my questions, providing code examples, and guiding me towards the right approach when I was learning programming as a child.

Features

• Convenient collections qdict, qlist and QEnum
• Self-formatting object in PrettyObject
• Two-way formatter/parser for file sizes, for example '5.4 GB', in DataSize
• Weak reference property decorator weakproperty
• Cached property decorator cachedproperty
• Class logger decorator logged
• Common string transformations in qtils.string_utils

Resources

• Sources are available on GitHub
• Installer is available on PyPI
• Usage guide and more examples are available in the tutorials
• Documentation is available online on ReadTheDocs
• Migrating from sutils? See the sutils migration guide here.
• Contributions are always welcome. Please see the Developer's guide on getting started.

Getting Started

Installation

Installing the latest release from PyPI using pip:

$ pip install qtils

Installing the latest release from PyPI and saving it to requirements.txt using pip:

$ pip install -s requirements.txt qtils

Installing the latest pre-release from GitHub:

$ pip install -e https://github.com/ultralightweight/qtils.git#master

Examples

Attribute dictionary

>>> from qtils import *

>>> d = qdict(hello = "world")
>>> d.hello
'world'
>>> d.answer = 42
>>> d['answer']
42

See more examples in the qdict tutorial, see the API reference here.

Objects with self-formatting capability

>>> class MyObject(PrettyObject):
...     __pretty_fields__ = [
...         'hello',
...         'answer',
...     ]
...     def __init__(self, hello, answer):
...         self.hello = hello
...         self.answer = answer
>>> obj = MyObject('world', 42)
>>> print(obj)
<__main__.MyObject object at ... hello='world', answer=42>

See more examples in the PrettyObject tutorial, see the API reference here

Cached property

>>> class DeepThought(object):
...     @cachedproperty
...     def answer_to_life_the_universe_and_everything(self):
...         print('Deep Thought is thinking')
...         # Deep Thought: Spends a period of 7.5 million years
...         # calculating the answer
...         return 42
...
>>> deep_thougth = DeepThought()
>>> deep_thougth.answer_to_life_the_universe_and_everything     # first call, getter is called
Deep Thought is thinking
42
>>> deep_thougth.answer_to_life_the_universe_and_everything     # second call, getter is not called
42
>>> del deep_thougth.answer_to_life_the_universe_and_everything # removing cached value
>>> deep_thougth.answer_to_life_the_universe_and_everything     # getter is called again
Deep Thought is thinking
42

See more examples in the cachedproperty tutorial, see the API reference here.

Weak reference property

>>> from qtils import weakproperty

>>> class Foo(object):
...     @weakproperty
...     def bar(self, value): pass
>>>

# The code above is the functional equivalent of writing:

>>> import weakref
>>> class Foo(object):
...     @property
...     def bar(self, value):
...         return self._bar() if self._bar is not None else None
...     @bar.setter
...     def bar(self, value):
...         if value is not None:
...             value = weakref.ref(value)
...         self._bar = value
>>>

See more examples in the weakproperty tutorial, see the API reference here.

Formatting and parsing file sizes

>>> print(DataSize(123000))
123 k
>>> DataSize('1.45 megabytes')
1450000
>>> DataSize('1T').format(unit="k", number_format="{:,.0f} {}")
'1,000,000,000 k'

See more examples in the formatting module tutorial, see the API reference here.

Dynamic module exports

>>> from qtils import qlist

>>> __all__ = qlist()

>>> @__all__.register
... class Foo(object):
...     pass

See more examples in the qlist tutorial, see the API reference here.

Adding a class-private logger

>>> @logged
... class LoggedFoo():
...     def __init__(self):
...         self.__logger.info("Hello World from Foo!")
...

See more examples in the logging module tutorial, see the API reference here.

Contributing

Pull requests are always welcome! Please see the Developer's Guide on getting started with qtils development.

Licence

This library is available under GNU Lesser General Public Licence v3.