Metadata-Version: 1.1
Name: django-idmap
Version: 1.0
Summary: An identity mapper for the Django ORM
Home-page: https://bitbucket.org/tkhyn/django-idmap
Author: Thomas Khyn
Author-email: thomas@ksytek.com
License: UNKNOWN
Description: django-idmap
        ============
        
        |copyright| 2014-2017 Thomas Khyn
        |copyright| 2009 David Cramer
        
        An identity mapper for the Django ORM. This is a fork of django-idmapper_,
        which is no longer maintained.
        
        ``django-idmap`` has been tested against django 1.8 and 1.9 and the latest
        minor versions of Python (2.7 and 3.5). Using it with django versions older
        than 1.8 is possible only with `version 0.3.3`_.
        
        If you like ``django-idmap`` and are looking for a way to thank me and/or
        encourage future development, you can send a few mBTC at this Bitcoin address:
        ``1EwENyR8RV6tMc1hsLTkPURtn5wJgaBfG9``.
        
        
        What is it?
        -----------
        
        ``django-idmap`` is a Django application which:
        
        - loads only once the instances in memory the first time they are needed
        - shares them throughout your interpreter until the request is finished
        
        Indeed, the default Django behavior is to expose different instances for the
        same database entry between the start and the end of the request. It has one
        main consequence: the temporary attributes you may set are lost if you want
        to access the same database object in another place in your code.
        
        .. warning::
        
           Deserialization (such as from the cache) will *not* use the identity mapper.
        
        Tested with django 1.8+ and latest minor versions of python 2 and 3.
        
        Installation
        ------------
        
        As straightforward as it can be, using pip::
        
           pip install django-idmap
        
        You also need to add ``'idmap'`` to the ``INSTALLED_APPS`` setting.
        
        
        Quick start
        -----------
        
        To enable the identity mapper for a model, you simply need to make it inherit
        from ``idmap.models.IdMapModel`` instead of ``django.db.models.Model``.
        
        .. tip::
        
           You can import ``idmap.models`` as you would import ``django.db.models``.
           ``idmap.models`` exposes all that is exposed by ``django.db.models`` plus
           the ``IdMapModel`` model class.
        
        You may of course mix and match ``IdMapModel`` and ``Model``::
        
            from idmap import models
        
            class MyModel(models.IdMapModel):
                name = models.CharField(...)
                fkey = models.ForeignKey('Other')
        
            class Other(models.Model):
                name = models.CharField(...)
        
        2 caching modes are available:
        
        - Weak references mode: the instance will be removed from the cache once there
          are no more references to it. This is the default behavior
        - Strong references mode: the instance will be loaded only once from the
          database and will be removed from the cache when it is flushed
        
        If you want to use strong references for a particular model, simply set
        ``use_strong_refs`` to ``True`` in the derived model class::
        
           from idmap import models
        
           class MyModel(models.IdMapModel):
              class Meta:
                 use_strong_refs = True
              [...]
        
        
        Manual operations
        -----------------
        
        In most cases, that's all there is to do with ``django-idmap``. Sometimes, you
        may need to flush the cache manually before the request is finished.
        
        You can use:
        
        - ``idmap.flush()`` to erase the whole cache
        - ``IdMapModel.flush_instance_cache()`` to erase the cache for one model
        - ``IdMapModel.flush_cached_instance(instance)`` to erase one instance
          from the cache
        
        Signals
        -------
        
        ``idmap.signals.pre_flush`` and ``idmap.signals.post_flush`` are sent before -
        respectively after - the cache is flushed. Connect handlers to these if you
        need to run code at these moments.
        
        .. warning:
        
           ``pre_flush`` and ``post_flush`` are only sent when the ``flush`` function
           is used or when the cache is automatically flushed (when the request ends).
        
        
        ``django-idmap`` flushes the cache when the ``request_finished`` or
        ``post_migrate`` signal are sent. This default behavior may be modified (at
        your own risk!) by disconnecting the ``idmap.signals.flush_idmap`` handler
        from these signals.
        
        
        Multiple database support
        -------------------------
        
        In some cases, you may need to store instances of the same model in several
        databases. It is possible to tell ``django-idmap`` to also take the database
        into account when creating or getting instances::
        
           class MyModel(models.IdMapModel):
              class Meta:
                 multi_db = True
              [...]
        
        This way, ``instance1_1`` with primary key ``1`` in database ``db1`` will be
        different from ``instance2_1`` with primary key ``1`` in database ``db2``::
        
           >>> MyModel.objects.using('db1').create(pk=1)
           >>> MyModel.objects.using('db2').create(pk=1)
           >>> idmap.flush()
           >>> instance1_1 = MyModel.objects.using('db1').get(pk=1)
           >>> instance2_1 = MyModel.objects.using('db2').get(pk=1)
           >>> assert instance1_1 is instance 2_1
           AssertionError
        
        When using multiple databases, you may also flush only one database by
        providing its name to ``idmap.flush()``::
        
           >>> idmap.flush('db1')
        
        will only flush instances that were retrieved using the database ``db1``.
        ``IdMapModel.flush_instance_cache`` can also take a ``db`` argument.
        
        Similarly, a keyword-argument ``db`` is provided when the ``pre_flush`` and
        ``post_flush`` signals are sent. ``db`` is ``None`` if all databases are
        flushed (i.e. if no database alias was provided).
        
        
        Proxy models
        ------------
        
        All instances of models and proxy models using the same base concrete class
        (let's call this a proxy family) are stored in the same cache, and are
        accessible through all the members of the proxy family::
        
           >>> class MyProxyModel(MyModel):
           >>>     class Meta:
           >>>         proxy = True
           >>> original = MyModel.objects.create(pk=1)
           >>> proxy = MyProxyModel.objects.create(pk=2)
           >>> assert original is MyProxyModel.get(pk=1)
        
        
        Inheritance catch-ups
        ---------------------
        
        In case you need to use a custom manager or custom metaclass on a model based
        on ``IdMapModel``, you need to derive them from ``idmap``'s own manager and
        metaclass::
        
           >>> class MyModelBase(models.IdMapModelBase):
           >>>     [...]
           >>> class MyManager(models.IdMapManager):
           >>>     [...]
           >>> class MyModel(models.IdMapModel,
                             metaclass=MyModelBase): # on python 3
           >>>     __metaclass__ = MyModelBase  # on python 2
           >>>     objects = MyManager()
        
        
        References
        ----------
        
        David Cramer's django-idmapper_
        
        Original code and concept: http://code.djangoproject.com/ticket/17
        
        .. |copyright| unicode:: 0xA9
        .. _django-idmapper: https://github.com/dcramer/django-idmapper
        .. _`version 0.3.3`: https://pypi.python.org/pypi/django-idmap/0.3.3
        
Keywords: django,identity,mapper
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Topic :: Database
