``persistent``:  automatic persistence for Python objects
=========================================================

.. image:: https://travis-ci.org/zopefoundation/persistent.svg?branch=master
        :target: https://travis-ci.org/zopefoundation/persistent

.. image:: https://coveralls.io/repos/github/zopefoundation/persistent/badge.svg?branch=master
        :target: https://coveralls.io/github/zopefoundation/persistent?branch=master

.. image:: https://readthedocs.org/projects/persistent/badge/?version=latest
        :target: http://persistent.readthedocs.org/en/latest/
        :alt: Documentation Status

.. image:: https://img.shields.io/pypi/v/persistent.svg
        :target: https://pypi.org/project/persistent
        :alt: Latest release

.. image:: https://img.shields.io/pypi/pyversions/persistent.svg
        :target: https://pypi.org/project/persistent
        :alt: Python versions

This package contains a generic persistence implementation for Python. It
forms the core protocol for making objects interact "transparently" with
a database such as the ZODB.

Please see the Sphinx documentation (``docs/index.rst``) for further
information, or view the documentation at Read The Docs, for either
the latest (``http://persistent.readthedocs.io/en/latest/``) or stable
release (``http://persistent.readthedocs.io/en/stable/``).

.. note::

   Use of this standalone ``persistent`` release is not recommended or
   supported with ZODB < 3.11.  ZODB 3.10 and earlier bundle their own
   version of  the ``persistent`` package.


``persistent`` Changelog
========================

4.6.4 (2020-03-26)
------------------

- Fix an overly specific test failure using zope.interface 5. See
  `issue 144 <https://github.com/zopefoundation/persistent/issues/144>`_.
- Fix two reference leaks that could theoretically occur as the result
  of obscure errors. See `issue 143 <https://github.com/zopefoundation/persistent/issues/143>`_.

4.6.3 (2020-03-18)
------------------

- Fix a crash in the test suite under a 32-bit CPython on certain
  32-bit platforms. See `issue 137
  <https://github.com/zopefoundation/persistent/issues/137>`_. Fix by
  `Jerry James <https://github.com/jamesjer>`_.


4.6.2 (2020-03-12)
------------------

- Fix an ``AssertionError`` clearing a non-empty ``PersistentMapping``
  that has no connection. See `issue 139
  <https://github.com/zopefoundation/persistent/issues/139>`_.


4.6.1 (2020-03-06)
------------------

- Stop installing C header files on PyPy (which is what persistent before 4.6.0
  used to do), fixes `issue 135
  <https://github.com/zopefoundation/persistent/issues/135>`_.


4.6.0 (2020-03-05)
------------------

- Fix slicing of ``PersistentList`` to always return instances of the
  same class. It was broken on Python 3 prior to 3.7.4.

- Fix copying  of ``PersistentList`` and ``PersistentMapping`` using
  ``copy.copy`` to also copy the underlying data object. This was
  broken prior to Python 3.7.4.

- Update the handling of the ``PURE_PYTHON`` environment variable.
  Now, a value of "0" requires that the C extensions be used; any other
  non-empty value prevents the extensions from being used. Also, all C
  extensions are required together or none of them will be used. This
  prevents strange errors that arise from a mismatch of Python and C
  implementations. See `issue 131 <https://github.com/zopefoundation/persistent/issues/131>`_.

  Note that some private implementation details such as the names of
  the pure-Python implementations have changed.

- Fix ``PersistentList`` to mark itself as changed after calling
  ``clear`` (if needed). See `PR 115
  <https://github.com/zopefoundation/persistent/pull/115/>`_.

- Fix ``PersistentMapping.update`` to accept keyword arguments like
  the native ``UserDict``. Previously, most uses of keyword arguments
  resulted in ``TypeError``; in the undocumented and extremely
  unlikely event of a single keyword argument called ``b`` that
  happens to be a dictionary, the behaviour will change. Also adjust
  the signatures of ``setdefault`` and ``pop`` to match the native
  version.

- Fix ``PersistentList.clear``, ``PersistentMapping.clear`` and
  ``PersistentMapping.popitem`` to no longer mark the object as
  changed if it was empty.

- Add preliminary support for Python 3.9a3+.
  See `issue 124 <https://github.com/zopefoundation/persistent/issues/124>`_.

- Fix the Python implementation of the PickleCache to be able to store
  objects that cannot be weakly referenced. See `issue 133
  <https://github.com/zopefoundation/persistent/issues/133>`_.

  Note that ``ctypes`` is required to use the Python implementation
  (except on PyPy).

4.5.1 (2019-11-06)
------------------

- Add support for Python 3.8.

- Update documentation to Python 3.


4.5.0 (2019-05-09)
------------------

- Fully test the C implementation of the PickleCache, and fix
  discrepancies between it and the Python implementation:

  - The C implementation now raises ``ValueError`` instead of
    ``AssertionError`` for certain types of bad inputs.
  - The Python implementation uses the C wording for error messages.
  - The C implementation properly implements ``IPickleCache``; methods
    unique to the Python implementation were moved to
    ``IExtendedPickleCache``.
  - The Python implementation raises ``AttributeError`` if a
    persistent class doesn't have a ``p_jar`` attribute.

  See `issue 102
  <https://github.com/zopefoundation/persistent/issues/102>`_.

- Allow sweeping cache without ``cache_size``. ``cache_size_bytes``
  works with ``cache_size=0``, no need to set ``cache_size`` to a
  large value.

- Require ``CFFI`` on CPython for pure-Python operation. This drops
  support for Jython (which was untested). See `issue 77
  <https://github.com/zopefoundation/persistent/issues/77>`_.

- Fix DeprecationWarning about ``PY_SSIZE_T_CLEAN``.
  See `issue 108 <https://github.com/zopefoundation/persistent/issues/108>`_.

- Drop support for Python 3.4.


4.4.3 (2018-10-22)
------------------

- Fix the repr of the persistent objects to include the module name
  when using the C extension. This matches the pure-Python behaviour
  and the behaviour prior to 4.4.0. See `issue 92
  <https://github.com/zopefoundation/persistent/issues/92>`_.

- Change the repr of persistent objects to format the OID as in
  integer in hexadecimal notation if it is an 8-byte byte string, as
  ZODB does. This eliminates some issues in doctests. See `issue 95
  <https://github.com/zopefoundation/persistent/pull/95>`_.


4.4.2 (2018-08-28)
------------------

- Explicitly use unsigned constants for packing and unpacking C
  timestamps, fixing an arithmetic issue for GCC when optimizations
  are enabled and ``-fwrapv`` is *not* enabled. See `issue 86
  <https://github.com/zopefoundation/persistent/issues/86>`_.


4.4.1 (2018-08-23)
------------------

- Fix installation of source packages on PyPy. See `issue 88
  <https://github.com/zopefoundation/persistent/issues/88>`_.


4.4.0 (2018-08-22)
------------------

- Use unsigned constants when doing arithmetic on C timestamps,
  possibly avoiding some overflow issues with some compilers or
  compiler settings. See `issue 86
  <https://github.com/zopefoundation/persistent/issues/86>`_.

- Change the default representation of ``Persistent`` objects to
  include the representation of their OID and jar, if set. Also add
  the ability for subclasses to implement ``_p_repr()`` instead of
  overriding ``__repr__`` for better exception handling. See `issue 11
  <https://github.com/zopefoundation/persistent/issues/11>`_.

- Reach and maintain 100% test coverage.

- Simplify ``__init__.py``, including removal of an attempted legacy
  import of ``persistent.TimeStamp``. See `PR 80
  <https://github.com/zopefoundation/persistent/pull/80>`_.

- Add support for Python 3.7 and drop support for Python 3.3.

- Build the CFFI modules (used on PyPy or when PURE_PYTHON is set) `at
  installation or wheel building time
  <https://cffi.readthedocs.io/en/latest/cdef.html#ffibuilder-set-source-preparing-out-of-line-modules>`_
  when CFFI is available. This replaces `the deprecated way
  <https://cffi.readthedocs.io/en/latest/overview.html#abi-versus-api>`_
  of building them at import time. If binary wheels are distributed,
  it eliminates the need to have a functioning C compiler to use PyPy.
  See `issue 75
  <https://github.com/zopefoundation/persistent/issues/75>`_.

- Fix deleting the ``_p_oid`` of a pure-Python persistent object when
  it is in a cache.

- Fix deleting special (``_p``) attributes of a pure-Python persistent
  object that overrides ``__delattr__`` and correctly calls ``_p_delattr``.

- Remove some internal compatibility shims that are no longer
  necessary. See `PR 82 <https://github.com/zopefoundation/persistent/pull/82>`_.

- Make the return value of ``TimeStamp.second()`` consistent across C
  and Python implementations when the ``TimeStamp`` was created from 6
  arguments with floating point seconds. Also make it match across
  trips through ``TimeStamp.raw()``. Previously, the C version could
  initially have erroneous rounding and too much false precision,
  while the Python version could have too much precision. The raw/repr
  values have not changed. See `issue 41
  <https://github.com/zopefoundation/persistent/issues/41>`_.


4.3.0 (2018-07-30)
------------------

- Fix the possibility of a rare crash in the C extension when
  deallocating items. See https://github.com/zopefoundation/persistent/issues/66

- Change cPickleCache's comparison of object sizes to determine
  whether an object can go in the cache to use ``PyObject_TypeCheck()``.
  This matches what the pure Python implementation does and is a
  stronger test that the object really is compatible with the cache.
  Previously, an object could potentially include ``cPersistent_HEAD``
  and *not* set ``tp_base`` to ``cPersistenceCAPI->pertype`` and still
  be eligible for the pickle cache; that is no longer the case. See
  `issue 69 <https://github.com/zopefoundation/persistent/issues/69>`_.


4.2.4.2 (2017-04-23)
--------------------

- Packaging-only release: fix Python 2.7 ``manylinux`` wheels.


4.2.4.1 (2017-04-21)
--------------------

- Packaging-only release:  get ``manylinux`` wheel built automatically.


4.2.4 (2017-03-20)
------------------

- Avoid raising a ``SystemError: error return without exception set``
  when loading an object with slots whose jar generates an exception
  (such as a ZODB ``POSKeyError``) in ``setstate``.


4.2.3 (2017-03-08)
------------------

- Fix the hashcode of Python ``TimeStamp`` objects on 64-bit Python on
  Windows. See https://github.com/zopefoundation/persistent/pull/55

- Stop calling ``gc.collect`` every time ``PickleCache.incrgc`` is called (every
  transaction boundary) in pure-Python mode (PyPy). This means that
  the reported size of the cache may be wrong (until the next GC), but
  it is much faster. This should not have any observable effects for
  user code.

- Stop clearing the dict and slots of objects added to
  ``PickleCache.new_ghost`` (typically these values are passed to
  ``__new__`` from the pickle data) in pure-Python mode (PyPy). This
  matches the behaviour of the C code.

- Add support for Python 3.6.

- Fix ``__setstate__`` interning when ``state`` parameter is not a built-in dict


4.2.2 (2016-11-29)
------------------

- Drop use of ``ctypes`` for determining maximum integer size, to increase
  pure-Python compatibility. See https://github.com/zopefoundation/persistent/pull/31

- Ensure that ``__slots__`` attributes are cleared when a persistent
  object is ghostified.  (This excluses classes that override
  ``__new__``.  See
  https://github.com/zopefoundation/persistent/wiki/Notes_on_state_new_and_slots
  if you're curious.)


4.2.1 (2016-05-26)
------------------

- Fix the hashcode of C ``TimeStamp`` objects on 64-bit Python 3 on
  Windows.


4.2.0 (2016-05-05)
------------------

- Fixed the Python(/PYPY) implementation ``TimeStamp.timeTime`` method
  to have subsecond precision.

- When testing ``PURE_PYTHON`` environments under ``tox``, avoid poisoning
  the user's global wheel cache.

- Add support for Python 3.5.

- Drop support for Python 2.6 and 3.2.


4.1.1 (2015-06-02)
------------------

- Fix manifest and re-upload to fix stray files included in 4.1.0.


4.1.0 (2015-05-19)
------------------

- Make the Python implementation of ``Persistent`` and ``PickleCache``
  behave more similarly to the C implementation. In particular, the
  Python version can now run the complete ZODB and ZEO test suites.