.. image:: https://github.com/zopefoundation/zc.beforestorage/workflows/tests/badge.svg
:target: https://github.com/zopefoundation/zc.beforestorage/actions?query=workflow%3Atests
==============
Before Storage
==============
ZODB storages typically store multiple object revisions to support
features such as multi-version concurrency control and undo. In the
case of the mod popular storage implementation, old revisions aren't
discarded until a pack. This feature has often been exploited to
perform time travel, allowing one to look at a database as it existed
in at some point in time. In the past, this has been possible with
file storage by specifying a time at which to open the file
storage. This works fairly well, but is very slow for large databases
because existing index files can't easily be used. Time travel is
also supported for individual objects through the ZODB history
mechanism.
The introduction of multi-version concurrency control provided new
opertunities for time travel. Using the storage loadBefore method,
one can load transaction records written before a given time. ZODB
3.9 will provide an option to the database open method for opening
connections as of a point in time.
Demo storage can be quite useful for testing, and especially staging
applications. In a common configuration, they allow for storing
changes to a base database without changing the underlying database.
Zope functional testing frameworks leverage demo storages to easily
roll-back database state after a test to a non-empty state before a
test. A significant limitation of demo storages is that they can't be
used with base storages that change. This means that they generaly
can't be used with ZEO. It isn't enough to have a read-only
connections, if the underlying database is still being changed by
other clients.
The "before" storage provides another way to leverage the loadBefore
method to support time travel and a means to provide an unchanging
view into a ZEO server. A before storage is a database adapter that
provides a read-only view of an underlying storage as of a particular
point in time.
.. contents::
Using ZConfig to configure Before storages
==========================================
"before" option
---------------
To use before storages from ZConfig configuration files, you need to
import zc.beforestorage and then use a before storage section.
>>> import ZODB.config
>>> storage = ZODB.config.storageFromString("""
...
... %import zc.beforestorage
...
... <before>
... before 2008-01-21
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """)
>>> storage
<Before: my.fs before 2008-01-21 00:00:00.000000>
>>> storage.close()
If we leave off the before option, we'll use the current time:
>>> storage = ZODB.config.storageFromString("""
...
... %import zc.beforestorage
...
... <before>
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """)
>>> storage
<Before: my.fs before 2008-01-21 18:22:49.000000>
>>> storage.close()
We can also give the option 'now' and get the current time.
>>> import ZODB.config
>>> storage = ZODB.config.storageFromString("""
...
... %import zc.beforestorage
...
... <before>
... before now
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """)
>>> storage
<Before: my.fs before 2008-01-21 18:22:53.000000>
>>> storage.close()
We can give the option 'startup' and get the time at startup.
>>> import ZODB.config
>>> storage = ZODB.config.storageFromString("""
...
... %import zc.beforestorage
...
... <before>
... before startup
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """)
>>> storage
<Before: my.fs before 2008-01-21 18:22:43.000000>
>>> import zc.beforestorage
>>> import ZODB.TimeStamp
>>> print(
... str(zc.beforestorage.startup_time_stamp))
2008-01-21 18:22:43.000000
>>> storage.close()
"before-from-file" option
-------------------------
The "before-from-file" option can be used to preserve the changes file between
restarts. It's value is the absolute path to a file. If the file exists, the
"before" time will be read from that file. If the file does not exist,
it will be created and the current UTC time will be written to it
When used with a Changes file that does NOT have the "create=true"
option set, the database will be preserved between restarts.
>>> import os.path
>>> import tempfile
>>> tempdir = tempfile.mkdtemp()
>>> before_file = os.path.join(tempdir, 'before-file')
Currently the file does not exist. So it'll be created and written with the
current time. In order to make this repeatable, we "monkeypatch" the "get_now"
function in the module to return a fixed value:
>>> import datetime
>>> import zc.beforestorage
>>> def fake_get_utcnow():
... return datetime.datetime(2008, 1, 1, 15, 0)
>>> orig_get_utcnow = zc.beforestorage.get_utcnow
>>> zc.beforestorage.get_utcnow = fake_get_utcnow
>>> os.path.exists(before_file)
False
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
>>> storage
<Before: my.fs before 2008-01-01 15:00:00.000000>
>>> storage.close()
The file will now have been created:
>>> os.path.exists(before_file)
True
>>> f = open(before_file)
>>> f.read() == fake_get_utcnow().replace(microsecond=0).isoformat()
True
If we now write a new value to the file, the storage will be started with that
time.
>>> f = open(before_file, 'w')
>>> _ = f.write('1990-01-01T11:11')
>>> f.close()
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
>>> storage
<Before: my.fs before 1990-01-01 11:11:00.000000>
>>> storage.close()
If we restart the storage, the value from the file will be used.
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
>>> storage
<Before: my.fs before 1990-01-01 11:11:00.000000>
>>> storage.close()
This will continue to happen until we remove the file. The "before_from_file"
path is stored on the storage itself, so applications that use it have access
to it.
>>> os.remove(storage.before_from_file)
>>> os.path.exists(before_file)
False
If we restart the storage again, a new file will be created.
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
>>> storage
<Before: my.fs before 2008-01-01 15:00:00.000000>
>>> storage.close()
Note that unlike the "before" option, the "before-from-file" file cannot
contain special values such as "now" or "startup".
>>> f = open(before_file, 'w')
>>> _ = f.write('now')
>>> f.close()
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
Traceback (most recent call last):
...
ValueError: 8-byte array expected
Note that only one of "before" or "before-from-file" options can be specified,
not both:
>>> storage = ZODB.config.storageFromString("""
...
... %%import zc.beforestorage
...
... <before>
... before 2008-01-01
... before-from-file %s
... <filestorage>
... path my.fs
... </filestorage>
... </before>
... """ % before_file)
Traceback (most recent call last):
...
ValueError: Only one of "before" or "before-from-file" options can be specified, not both
Cleanup...
>>> import shutil
>>> shutil.rmtree(tempdir)
>>> zc.beforestorage.get_utcnow = orig_get_utcnow
Demonstration (doctest)
=======================
Note that most people will configure the storage through ZConfig. If
you are one of those people, you may want to stop here. :) The
examples below show you how to use the storage from Python, but they
also exercise lots of details you might not be interested in.
To see how this works at the Python level, we'll create a file
storage, and use a before storage to provide views on it.
>>> import ZODB.FileStorage
>>> fs = ZODB.FileStorage.FileStorage('Data.fs')
>>> from ZODB.DB import DB
>>> db = DB(fs)
>>> conn = db.open()
>>> root = conn.root()
>>> import persistent.mapping
We'll record transaction identifiers, which we'll use to when opening
the before storage.
>>> import transaction
>>> transactions = [root._p_serial]
>>> for i in range(1, 11):
... root[i] = persistent.mapping.PersistentMapping()
... transaction.get().note("trans %s" % i)
... transaction.commit()
... transactions.append(root._p_serial)
We create a before storage by calling the Before constructer
with an existing storage and a timestamp:
>>> import zc.beforestorage
>>> b5 = zc.beforestorage.Before(fs, transactions[5])
>>> db5 = DB(b5)
>>> conn5 = db5.open()
>>> root5 = conn5.root()
>>> len(root5)
4
here we see the database as it was before the 5th transaction was
committed. If we try to access a later object, we'll get a
ReadConflictError:
>>> conn5.get(root[5]._p_oid)
Traceback (most recent call last):
...
ZODB.POSException.ReadConflictError: b'\x00\x00\x00\x00\x00\x00\x00\x05'
Similarly, while we can access earlier object revisions, we can't
access revisions at the before time or later:
>>> _ = b5.loadSerial(root._p_oid, transactions[2])
>>> b5.loadSerial(root._p_oid, transactions[5])
Traceback (most recent call last):
...
POSKeyError: 0x00
Let's run through the storage methods:
>>> (b5.getName() ==
... 'Data.fs before %s' % ZODB.TimeStamp.TimeStamp(transactions[5]))
True
>>> b5.getSize() == fs.getSize()
True
>>> for hd in b5.history(root._p_oid, size=3):
... print(hd['description'].decode('utf-8'))
trans 4
trans 3
trans 2
>>> b5.isReadOnly()
True
>>> transactions[4] <= b5.lastTransaction() < transactions[5]
True
>>> len(b5) == len(fs)
True
>>> p, s1, s2 = b5.loadBefore(root._p_oid, transactions[5])
>>> p == fs.loadSerial(root._p_oid, transactions[4])
True
>>> s1 == transactions[4]
True
>>> s2 is None
True
>>> p, s1, s2 = b5.loadBefore(root._p_oid, transactions[4])
>>> p == fs.loadSerial(root._p_oid, transactions[3])
True
>>> s1 == transactions[3]
True
>>> s2 == transactions[4]
True
>>> b5.getTid(root._p_oid) == transactions[4]
True
>>> b5.tpc_transaction()
>>> try:
... b5.new_oid()
... except Exception as e: # Workaround http://bugs.python.org/issue19138
... print(e.__class__.__name__)
ReadOnlyError
>>> from ZODB.TimeStamp import TimeStamp
>>> try:
... b5.pack(TimeStamp(transactions[3]).timeTime(), lambda p: [])
... except Exception as e:
... print(e.__class__.__name__)
ReadOnlyError
>>> b5.registerDB(db5)
>>> b5.sortKey() == fs.sortKey()
True
>>> try:
... b5.tpc_begin(transaction.get())
... except Exception as e:
... print(e.__class__.__name__)
ReadOnlyError
>>> b5.store(root._p_oid, transactions[4], b5.load(root._p_oid)[0], '',
... transaction.get())
... # doctest: +ELLIPSIS
Traceback (most recent call last):
...
StorageTransactionError: ...
>>> b5.tpc_vote(transaction.get())
... # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ZODB.POSException.StorageTransactionError: ...
>>> b5.tpc_finish(transaction)
... # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ZODB.POSException.StorageTransactionError: ...
>>> b5.tpc_transaction()
>>> b5.tpc_abort(transaction)
Before storages don't support undo:
>>> b5.supportsUndo
Traceback (most recent call last):
...
AttributeError: 'Before' object has no attribute 'supportsUndo'
(Don't even ask about versions. :)
Closing a before storage closes the underlying storage:
>>> b5.close()
>>> fs.load(root._p_oid, '') # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: ...
If we ommit a timestamp when creating a before storage, the current
time will be used:
>>> fs = ZODB.FileStorage.FileStorage('Data.fs')
>>> from ZODB.DB import DB
>>> db = DB(fs)
>>> conn = db.open()
>>> root = conn.root()
>>> bnow = zc.beforestorage.Before(fs)
>>> dbnow = DB(bnow)
>>> connnow = dbnow.open()
>>> rootnow = connnow.root()
>>> for i in range(1, 11):
... root[i] = persistent.mapping.PersistentMapping()
... transaction.get().note("trans %s" % i)
... transaction.commit()
... transactions.append(root._p_serial)
>>> len(rootnow)
10
>>> dbnow.close()
The timestamp may be passed directory, or as an ISO time. For
example:
>>> fs = ZODB.FileStorage.FileStorage('Data.fs')
>>> iso = 'T'.join(str(ZODB.TimeStamp.TimeStamp(transactions[5])).split()
... )[:19]
>>> b5 = zc.beforestorage.Before(fs, iso)
>>> db5 = DB(b5)
>>> conn5 = db5.open()
>>> root5 = conn5.root()
>>> len(root5)
4
>>> b5.close()
Blob Support
------------
Before storage supports blobs if the storage it wraps supports blobs,
and, in fact, it simply exposes the underlying storages loadBlob and
temporaryDirectory methods.
>>> fs = ZODB.FileStorage.FileStorage('Data.fs')
>>> import ZODB.blob
>>> bs = ZODB.blob.BlobStorage('blobs', fs)
>>> db = ZODB.DB(bs)
>>> conn = db.open()
>>> conn.root()['blob'] = ZODB.blob.Blob()
>>> _ = conn.root()['blob'].open('w').write(b'data1')
>>> transaction.commit()
>>> bnow = zc.beforestorage.Before(bs)
>>> dbnow = DB(bnow)
>>> connnow = dbnow.open()
>>> rootnow = connnow.root()
>>> _ = conn.root()['blob'].open('w').write(b'data2')
>>> transaction.commit()
>>> print(rootnow['blob'].open().read().decode('utf-8'))
data1
>>> bnow.temporaryDirectory() == bs.temporaryDirectory()
True
>>> import ZODB.interfaces, zope.interface.verify
>>> zope.interface.verify.verifyObject(
... ZODB.interfaces.IBlobStorage, bnow)
True
>>> bnow.close()
CHANGES
=======
1.0 (2023-02-09)
----------------
- Add support for Python 3.9, 3.10, 3.11.
- Drop support for Python 2.7, 3.5, 3.6.
0.6 (2020-05-14)
----------------
- Add support for Python 3.5 through 3.8.
- Drop support for Python 3.3 and 3.4.
- Fix a long-standing bug in loadBefore´. The bug was revealed by
testing against ZODB 5, for which loadBefore plays a bigger role.
0.5.1 (2013-10-25)
------------------
- Fix broken release
0.5.0 (2013-10-25)
------------------
Added ZODB4 and Python 3 support.
0.4.0 (2010-12-09)
------------------
Added a "before-from-file" option that can be used if the application wants to
preserve beforestorage state between application restarts.
0.3.2 (2008-12-05)
------------------
Updated to work with both ZODB 3.8 and 3.9.
0.3.1 (2008-12-01)
------------------
Renamed lastTid to getTid to conform to the ZEO.interfaces.IServeable
interface.
0.3.0 (2008-12-01)
------------------
Added Blob support.
0.2.0 (2008-03-05)
------------------
Added support for "now" and "startup" values to the before option when
using ZConfig. The "now" value indicates that the before storage should
provide a view of the base storage as of the time the storage is created.
The "startup" value indicates that the before storage should provide a
view of the base stoage as of process startup time. The later is
especially useful when setting up more than once before storage in a
single application, as it allows you to arrange that all of the
storages provide consistent views without having to specify a time.
0.1.1 (2008-02-07)
------------------
Fixed a packaging bug that caused some files to be omitted.
0.1 (2008-01-??)
----------------
Initial release.
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/zc.beforestorage",
"name": "zc.beforestorage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Jim Fulton",
"author_email": "zope-dev@zope.dev",
"download_url": "https://files.pythonhosted.org/packages/9f/37/70b03a946234c3575c9181787d5114db25156f918e7e87c05794d2c521e1/zc.beforestorage-1.0.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/zopefoundation/zc.beforestorage/workflows/tests/badge.svg\n :target: https://github.com/zopefoundation/zc.beforestorage/actions?query=workflow%3Atests\n\n\n==============\nBefore Storage\n==============\n\nZODB storages typically store multiple object revisions to support\nfeatures such as multi-version concurrency control and undo. In the\ncase of the mod popular storage implementation, old revisions aren't\ndiscarded until a pack. This feature has often been exploited to\nperform time travel, allowing one to look at a database as it existed\nin at some point in time. In the past, this has been possible with\nfile storage by specifying a time at which to open the file\nstorage. This works fairly well, but is very slow for large databases\nbecause existing index files can't easily be used. Time travel is\nalso supported for individual objects through the ZODB history\nmechanism.\n\nThe introduction of multi-version concurrency control provided new\nopertunities for time travel. Using the storage loadBefore method,\none can load transaction records written before a given time. ZODB\n3.9 will provide an option to the database open method for opening\nconnections as of a point in time.\n\nDemo storage can be quite useful for testing, and especially staging\napplications. In a common configuration, they allow for storing\nchanges to a base database without changing the underlying database.\nZope functional testing frameworks leverage demo storages to easily\nroll-back database state after a test to a non-empty state before a\ntest. A significant limitation of demo storages is that they can't be\nused with base storages that change. This means that they generaly\ncan't be used with ZEO. It isn't enough to have a read-only\nconnections, if the underlying database is still being changed by\nother clients.\n\nThe \"before\" storage provides another way to leverage the loadBefore\nmethod to support time travel and a means to provide an unchanging\nview into a ZEO server. A before storage is a database adapter that\nprovides a read-only view of an underlying storage as of a particular\npoint in time.\n\n\n.. contents::\n\nUsing ZConfig to configure Before storages\n==========================================\n\n\"before\" option\n---------------\n\nTo use before storages from ZConfig configuration files, you need to\nimport zc.beforestorage and then use a before storage section.\n\n >>> import ZODB.config\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %import zc.beforestorage\n ...\n ... <before>\n ... before 2008-01-21\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\")\n\n >>> storage\n <Before: my.fs before 2008-01-21 00:00:00.000000>\n\n >>> storage.close()\n\nIf we leave off the before option, we'll use the current time:\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %import zc.beforestorage\n ...\n ... <before>\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\")\n\n >>> storage\n <Before: my.fs before 2008-01-21 18:22:49.000000>\n\n >>> storage.close()\n\nWe can also give the option 'now' and get the current time.\n\n >>> import ZODB.config\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %import zc.beforestorage\n ...\n ... <before>\n ... before now\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\")\n\n >>> storage\n <Before: my.fs before 2008-01-21 18:22:53.000000>\n\n >>> storage.close()\n\nWe can give the option 'startup' and get the time at startup.\n\n >>> import ZODB.config\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %import zc.beforestorage\n ...\n ... <before>\n ... before startup\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\")\n\n >>> storage\n <Before: my.fs before 2008-01-21 18:22:43.000000>\n >>> import zc.beforestorage\n >>> import ZODB.TimeStamp\n >>> print(\n ... str(zc.beforestorage.startup_time_stamp))\n 2008-01-21 18:22:43.000000\n >>> storage.close()\n\n\n\"before-from-file\" option\n-------------------------\n\nThe \"before-from-file\" option can be used to preserve the changes file between\nrestarts. It's value is the absolute path to a file. If the file exists, the\n\"before\" time will be read from that file. If the file does not exist,\nit will be created and the current UTC time will be written to it\n\nWhen used with a Changes file that does NOT have the \"create=true\"\noption set, the database will be preserved between restarts.\n\n >>> import os.path\n >>> import tempfile\n\n >>> tempdir = tempfile.mkdtemp()\n >>> before_file = os.path.join(tempdir, 'before-file')\n\nCurrently the file does not exist. So it'll be created and written with the\ncurrent time. In order to make this repeatable, we \"monkeypatch\" the \"get_now\"\nfunction in the module to return a fixed value:\n\n >>> import datetime\n >>> import zc.beforestorage\n\n >>> def fake_get_utcnow():\n ... return datetime.datetime(2008, 1, 1, 15, 0)\n >>> orig_get_utcnow = zc.beforestorage.get_utcnow\n >>> zc.beforestorage.get_utcnow = fake_get_utcnow\n\n >>> os.path.exists(before_file)\n False\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n\n >>> storage\n <Before: my.fs before 2008-01-01 15:00:00.000000>\n\n >>> storage.close()\n\nThe file will now have been created:\n\n >>> os.path.exists(before_file)\n True\n\n >>> f = open(before_file)\n >>> f.read() == fake_get_utcnow().replace(microsecond=0).isoformat()\n True\n\nIf we now write a new value to the file, the storage will be started with that\ntime.\n\n >>> f = open(before_file, 'w')\n >>> _ = f.write('1990-01-01T11:11')\n >>> f.close()\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n\n >>> storage\n <Before: my.fs before 1990-01-01 11:11:00.000000>\n\n >>> storage.close()\n\nIf we restart the storage, the value from the file will be used.\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n\n >>> storage\n <Before: my.fs before 1990-01-01 11:11:00.000000>\n\n >>> storage.close()\n\nThis will continue to happen until we remove the file. The \"before_from_file\"\npath is stored on the storage itself, so applications that use it have access\nto it.\n\n >>> os.remove(storage.before_from_file)\n\n >>> os.path.exists(before_file)\n False\n\nIf we restart the storage again, a new file will be created.\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n\n >>> storage\n <Before: my.fs before 2008-01-01 15:00:00.000000>\n\n >>> storage.close()\n\nNote that unlike the \"before\" option, the \"before-from-file\" file cannot\ncontain special values such as \"now\" or \"startup\".\n\n >>> f = open(before_file, 'w')\n >>> _ = f.write('now')\n >>> f.close()\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n Traceback (most recent call last):\n ...\n ValueError: 8-byte array expected\n\nNote that only one of \"before\" or \"before-from-file\" options can be specified,\nnot both:\n\n >>> storage = ZODB.config.storageFromString(\"\"\"\n ...\n ... %%import zc.beforestorage\n ...\n ... <before>\n ... before 2008-01-01\n ... before-from-file %s\n ... <filestorage>\n ... path my.fs\n ... </filestorage>\n ... </before>\n ... \"\"\" % before_file)\n Traceback (most recent call last):\n ...\n ValueError: Only one of \"before\" or \"before-from-file\" options can be specified, not both\n\n\nCleanup...\n\n >>> import shutil\n >>> shutil.rmtree(tempdir)\n\n >>> zc.beforestorage.get_utcnow = orig_get_utcnow\n\n\nDemonstration (doctest)\n=======================\n\nNote that most people will configure the storage through ZConfig. If\nyou are one of those people, you may want to stop here. :) The\nexamples below show you how to use the storage from Python, but they\nalso exercise lots of details you might not be interested in.\n\nTo see how this works at the Python level, we'll create a file\nstorage, and use a before storage to provide views on it.\n\n >>> import ZODB.FileStorage\n >>> fs = ZODB.FileStorage.FileStorage('Data.fs')\n >>> from ZODB.DB import DB\n >>> db = DB(fs)\n >>> conn = db.open()\n >>> root = conn.root()\n >>> import persistent.mapping\n\nWe'll record transaction identifiers, which we'll use to when opening\nthe before storage.\n\n >>> import transaction\n >>> transactions = [root._p_serial]\n >>> for i in range(1, 11):\n ... root[i] = persistent.mapping.PersistentMapping()\n ... transaction.get().note(\"trans %s\" % i)\n ... transaction.commit()\n ... transactions.append(root._p_serial)\n\nWe create a before storage by calling the Before constructer\nwith an existing storage and a timestamp:\n\n >>> import zc.beforestorage\n >>> b5 = zc.beforestorage.Before(fs, transactions[5])\n >>> db5 = DB(b5)\n >>> conn5 = db5.open()\n >>> root5 = conn5.root()\n >>> len(root5)\n 4\n\nhere we see the database as it was before the 5th transaction was\ncommitted. If we try to access a later object, we'll get a\nReadConflictError:\n\n >>> conn5.get(root[5]._p_oid)\n Traceback (most recent call last):\n ...\n ZODB.POSException.ReadConflictError: b'\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x05'\n\nSimilarly, while we can access earlier object revisions, we can't\naccess revisions at the before time or later:\n\n >>> _ = b5.loadSerial(root._p_oid, transactions[2])\n\n >>> b5.loadSerial(root._p_oid, transactions[5])\n Traceback (most recent call last):\n ...\n POSKeyError: 0x00\n\nLet's run through the storage methods:\n\n >>> (b5.getName() ==\n ... 'Data.fs before %s' % ZODB.TimeStamp.TimeStamp(transactions[5]))\n True\n\n >>> b5.getSize() == fs.getSize()\n True\n\n >>> for hd in b5.history(root._p_oid, size=3):\n ... print(hd['description'].decode('utf-8'))\n trans 4\n trans 3\n trans 2\n\n >>> b5.isReadOnly()\n True\n\n >>> transactions[4] <= b5.lastTransaction() < transactions[5]\n True\n\n >>> len(b5) == len(fs)\n True\n\n >>> p, s1, s2 = b5.loadBefore(root._p_oid, transactions[5])\n >>> p == fs.loadSerial(root._p_oid, transactions[4])\n True\n >>> s1 == transactions[4]\n True\n >>> s2 is None\n True\n\n >>> p, s1, s2 = b5.loadBefore(root._p_oid, transactions[4])\n >>> p == fs.loadSerial(root._p_oid, transactions[3])\n True\n >>> s1 == transactions[3]\n True\n >>> s2 == transactions[4]\n True\n\n >>> b5.getTid(root._p_oid) == transactions[4]\n True\n\n >>> b5.tpc_transaction()\n\n >>> try:\n ... b5.new_oid()\n ... except Exception as e: # Workaround http://bugs.python.org/issue19138\n ... print(e.__class__.__name__)\n ReadOnlyError\n\n >>> from ZODB.TimeStamp import TimeStamp\n >>> try:\n ... b5.pack(TimeStamp(transactions[3]).timeTime(), lambda p: [])\n ... except Exception as e:\n ... print(e.__class__.__name__)\n ReadOnlyError\n\n >>> b5.registerDB(db5)\n\n >>> b5.sortKey() == fs.sortKey()\n True\n\n >>> try:\n ... b5.tpc_begin(transaction.get())\n ... except Exception as e:\n ... print(e.__class__.__name__)\n ReadOnlyError\n\n >>> b5.store(root._p_oid, transactions[4], b5.load(root._p_oid)[0], '',\n ... transaction.get())\n ... # doctest: +ELLIPSIS\n Traceback (most recent call last):\n ...\n StorageTransactionError: ...\n\n >>> b5.tpc_vote(transaction.get())\n ... # doctest: +ELLIPSIS\n Traceback (most recent call last):\n ...\n ZODB.POSException.StorageTransactionError: ...\n\n >>> b5.tpc_finish(transaction)\n ... # doctest: +ELLIPSIS\n Traceback (most recent call last):\n ...\n ZODB.POSException.StorageTransactionError: ...\n\n >>> b5.tpc_transaction()\n >>> b5.tpc_abort(transaction)\n\nBefore storages don't support undo:\n\n >>> b5.supportsUndo\n Traceback (most recent call last):\n ...\n AttributeError: 'Before' object has no attribute 'supportsUndo'\n\n(Don't even ask about versions. :)\n\nClosing a before storage closes the underlying storage:\n\n >>> b5.close()\n >>> fs.load(root._p_oid, '') # doctest: +ELLIPSIS\n Traceback (most recent call last):\n ...\n ValueError: ...\n\nIf we ommit a timestamp when creating a before storage, the current\ntime will be used:\n\n >>> fs = ZODB.FileStorage.FileStorage('Data.fs')\n >>> from ZODB.DB import DB\n >>> db = DB(fs)\n >>> conn = db.open()\n >>> root = conn.root()\n\n >>> bnow = zc.beforestorage.Before(fs)\n >>> dbnow = DB(bnow)\n >>> connnow = dbnow.open()\n >>> rootnow = connnow.root()\n\n >>> for i in range(1, 11):\n ... root[i] = persistent.mapping.PersistentMapping()\n ... transaction.get().note(\"trans %s\" % i)\n ... transaction.commit()\n ... transactions.append(root._p_serial)\n\n >>> len(rootnow)\n 10\n\n >>> dbnow.close()\n\nThe timestamp may be passed directory, or as an ISO time. For\nexample:\n\n >>> fs = ZODB.FileStorage.FileStorage('Data.fs')\n >>> iso = 'T'.join(str(ZODB.TimeStamp.TimeStamp(transactions[5])).split()\n ... )[:19]\n >>> b5 = zc.beforestorage.Before(fs, iso)\n >>> db5 = DB(b5)\n >>> conn5 = db5.open()\n >>> root5 = conn5.root()\n >>> len(root5)\n 4\n\n >>> b5.close()\n\nBlob Support\n------------\n\nBefore storage supports blobs if the storage it wraps supports blobs,\nand, in fact, it simply exposes the underlying storages loadBlob and\ntemporaryDirectory methods.\n\n >>> fs = ZODB.FileStorage.FileStorage('Data.fs')\n >>> import ZODB.blob\n >>> bs = ZODB.blob.BlobStorage('blobs', fs)\n >>> db = ZODB.DB(bs)\n >>> conn = db.open()\n >>> conn.root()['blob'] = ZODB.blob.Blob()\n >>> _ = conn.root()['blob'].open('w').write(b'data1')\n >>> transaction.commit()\n\n >>> bnow = zc.beforestorage.Before(bs)\n >>> dbnow = DB(bnow)\n >>> connnow = dbnow.open()\n >>> rootnow = connnow.root()\n\n >>> _ = conn.root()['blob'].open('w').write(b'data2')\n >>> transaction.commit()\n\n >>> print(rootnow['blob'].open().read().decode('utf-8'))\n data1\n\n >>> bnow.temporaryDirectory() == bs.temporaryDirectory()\n True\n\n >>> import ZODB.interfaces, zope.interface.verify\n >>> zope.interface.verify.verifyObject(\n ... ZODB.interfaces.IBlobStorage, bnow)\n True\n\n >>> bnow.close()\n\n\nCHANGES\n=======\n\n1.0 (2023-02-09)\n----------------\n\n- Add support for Python 3.9, 3.10, 3.11.\n\n- Drop support for Python 2.7, 3.5, 3.6.\n\n\n0.6 (2020-05-14)\n----------------\n\n- Add support for Python 3.5 through 3.8.\n\n- Drop support for Python 3.3 and 3.4.\n\n- Fix a long-standing bug in loadBefore\u00b4. The bug was revealed by\n testing against ZODB 5, for which loadBefore plays a bigger role.\n\n\n0.5.1 (2013-10-25)\n------------------\n\n- Fix broken release\n\n\n0.5.0 (2013-10-25)\n------------------\n\nAdded ZODB4 and Python 3 support.\n\n\n0.4.0 (2010-12-09)\n------------------\n\nAdded a \"before-from-file\" option that can be used if the application wants to\npreserve beforestorage state between application restarts.\n\n0.3.2 (2008-12-05)\n------------------\n\nUpdated to work with both ZODB 3.8 and 3.9.\n\n0.3.1 (2008-12-01)\n------------------\n\nRenamed lastTid to getTid to conform to the ZEO.interfaces.IServeable\ninterface.\n\n\n0.3.0 (2008-12-01)\n------------------\n\nAdded Blob support.\n\n0.2.0 (2008-03-05)\n------------------\n\nAdded support for \"now\" and \"startup\" values to the before option when\nusing ZConfig. The \"now\" value indicates that the before storage should\nprovide a view of the base storage as of the time the storage is created.\nThe \"startup\" value indicates that the before storage should provide a\nview of the base stoage as of process startup time. The later is\nespecially useful when setting up more than once before storage in a\nsingle application, as it allows you to arrange that all of the\nstorages provide consistent views without having to specify a time.\n\n0.1.1 (2008-02-07)\n------------------\n\nFixed a packaging bug that caused some files to be omitted.\n\n0.1 (2008-01-??)\n----------------\n\nInitial release.\n",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "View storage before a given time",
"version": "1.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d98e8c9c7c235f6edbe5b65bdd53eae3890b06c49e3d9cb33406492816a5c9c3",
"md5": "1be7d5ff8bc37ab61c8ad3197e01e278",
"sha256": "740b64a71033a9854ff110515d78c4c5f7a9ce9648d54fa1551999f9cbb3315e"
},
"downloads": -1,
"filename": "zc.beforestorage-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1be7d5ff8bc37ab61c8ad3197e01e278",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14921,
"upload_time": "2023-02-09T11:59:39",
"upload_time_iso_8601": "2023-02-09T11:59:39.198831Z",
"url": "https://files.pythonhosted.org/packages/d9/8e/8c9c7c235f6edbe5b65bdd53eae3890b06c49e3d9cb33406492816a5c9c3/zc.beforestorage-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f3770b03a946234c3575c9181787d5114db25156f918e7e87c05794d2c521e1",
"md5": "be9a6dd4d2dbbad62a88abddf86a29c4",
"sha256": "c7fa98394f9bdae04ef3e7e75347d838361bff16905ae93b987ab66495322f48"
},
"downloads": -1,
"filename": "zc.beforestorage-1.0.tar.gz",
"has_sig": false,
"md5_digest": "be9a6dd4d2dbbad62a88abddf86a29c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18236,
"upload_time": "2023-02-09T11:59:41",
"upload_time_iso_8601": "2023-02-09T11:59:41.397757Z",
"url": "https://files.pythonhosted.org/packages/9f/37/70b03a946234c3575c9181787d5114db25156f918e7e87c05794d2c521e1/zc.beforestorage-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-09 11:59:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "zopefoundation",
"github_project": "zc.beforestorage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "zc.beforestorage"
}
JSON
