diff --git a/CHANGELOG.md b/CHANGELOG.md index fc1d10fda43c4c0dd9e883972cb11efe5f4abdd2..eae855073d3c64a28e62393ceba0f47766dd7990 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,3 +3,4 @@ * unit testing engine changed from nose2 to pytest, since nose2 couldn't run tests on multiple threads It's much faster this way. * added extra wait for the futures in `sync_threadpool` +* added `satella.dao` diff --git a/docs/dao.rst b/docs/dao.rst new file mode 100644 index 0000000000000000000000000000000000000000..30da9b4c2838f67cbc5d76e33d69e3a61970c22f --- /dev/null +++ b/docs/dao.rst @@ -0,0 +1,17 @@ +=== +DAO +=== + +This is for objects that are meant to represent a database entry, +and are lazily loadable. + +It's constructor expects identifier and a keyword argument of load_lazy, which will control +when will the object be fetched from DB. + +If True, then it will be fetched at constructor time, ie. the constructor will call .refresh(). +If False, then it will be fetched when it is first requested, via `must_be_loaded` decorator. + +.. autoclass:: satella.dao.Loadable + :members: + +.. autofunction:: satella.dao.must_be_loaded diff --git a/docs/index.rst b/docs/index.rst index 72ccf786cecab3edc9382bb7e6c89da128176b62..7e77d41f2d9dba4a65e4f76ae007d77ef0001f2f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ Visit the project's page at GitHub_! instrumentation/memory instrumentation/metrics exception_handling + dao json posix import diff --git a/satella/__init__.py b/satella/__init__.py index 5d0387b356cc5d919197803e787de63f21130f74..f1f3d0f44142110b8357ff8ed01f171d125594e4 100644 --- a/satella/__init__.py +++ b/satella/__init__.py @@ -1 +1 @@ -__version__ = '2.11.20_a2' +__version__ = '2.11.20' diff --git a/satella/dao/__init__.py b/satella/dao/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..201492fdcc20fd1f9694badc02da3628cb25eae1 --- /dev/null +++ b/satella/dao/__init__.py @@ -0,0 +1,53 @@ +from abc import ABCMeta, abstractmethod + +from satella.coding.decorators.decorators import wraps + +__all__ = ['Loadable', 'must_be_loaded'] + +class Loadable(metaclass=ABCMeta): + """ + Any class that can be loaded lazily. + + It's keyword argument, load_lazy is expected to control lazy loading. If set to True, + DB will be hit as a part of this object's constructor. + + If False, you will need to load it on-demand via must_be_loaded decorator. + """ + + __slots__ = ('_loaded',) + + def __init__(self, load_lazy: bool = False): + self._loaded: bool = False + if not load_lazy: + self.refresh() + + @abstractmethod + def refresh(self, load_from=None) -> None: + """ + Optionally provide a class to load this class from. + + Override me, calling me in a super method. + + :param load_from: serialized object. If not given, the DB will be hit + """ + self._loaded = True + + +def must_be_loaded(fun): + """ + A decorator for Loadable's methods. + + Assures that .refresh() is called prior to executing that method, ie. the object + is loaded from the DB + """ + + @wraps(fun) + def inner(self, *args, **kwargs): + assert isinstance(self, + Loadable), 'must_be_loaded called with a class that does not subclass ' \ + 'Loadable' + if not self._loaded: + self.refresh() + return fun(self, *args, **kwargs) + + return inner diff --git a/tests/test_dao.py b/tests/test_dao.py new file mode 100644 index 0000000000000000000000000000000000000000..7d37808b1f2231a74d249f8cf12088044abd1480 --- /dev/null +++ b/tests/test_dao.py @@ -0,0 +1,20 @@ +import unittest + +from satella.dao import Loadable, must_be_loaded + + +class TestDAO(unittest.TestCase): + def test_something(self): + class Load(Loadable): + def __init__(self, load_lazy=False): + super().__init__(load_lazy=load_lazy) + + @must_be_loaded + def method_accessed(self): + assert self._loaded + + def refresh(self, load_from=None) -> None: + super().refresh(load_from=load_from) + + l = Load() + l.method_accessed()