Skip to content

Z
ZODB
Commit 10e1326a authored by Jim Fulton's avatar Jim Fulton Committed by GitHub
Browse files
Options

Merge pull request #101 from zopefoundation/reference-docs 

Reference docs
parents 8a4d763a bed11cba
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 386 additions and 70 deletions
src/ZODB/Connection.py
View file @ 10e1326a
......@@ -78,9 +78,13 @@ def className(obj):
IPersistentDataManager,
ISynchronizer)
class Connection(ExportImport, object):
"""Connection to ZODB for loading and storing objects."""
"""Connection to ZODB for loading and storing objects.
Connections manage object state in collaboration with transaction
managers. They're created by calling the
:meth:`~ZODB.DB.open` method on :py:class:`database
<ZODB.DB>` objects.
"""
_code_timestamp = 0
......
src/ZODB/DB.py
View file @ 10e1326a
This diff is collapsed.
src/ZODB/DemoStorage.py
View file @ 10e1326a
......@@ -40,10 +40,52 @@ from .utils import load_current, maxtid
ZODB.interfaces.IStorageIteration,
)
class DemoStorage(ConflictResolvingStorage):
"""A storage that stores changes against a read-only base database
This storage was originally meant to support distribution of
application demonstrations with populated read-only databases (on
CDROM) and writable in-memory databases.
Demo storages are extemely convenient for testing where setup of a
base database can be shared by many tests.
Demo storages are also handy for staging appplications where a
read-only snapshot of a production database (often accomplished
using a `beforestorage
<https://pypi.python.org/pypi/zc.beforestorage>`_) is combined
with a changes database implemented with a
:class:`~ZODB.FileStorage.FileStorage.FileStorage`.
"""
def __init__(self, name=None, base=None, changes=None,
close_base_on_close=None, close_changes_on_close=None):
"""Create a demo storage
:param str name: The storage name used by the
:meth:`~ZODB.interfaces.IStorage.getName` and
:meth:`~ZODB.interfaces.IStorage.sortKey` methods.
:param object base: base storage
:param object changes: changes storage
:param bool close_base_on_close: A Flag indicating whether the base
database should be closed when the demo storage is closed.
:param bool close_changes_on_close: A Flag indicating whether the
changes database should be closed when the demo storage is closed.
If a base database isn't provided, a
:class:`~ZODB.MappingStorage.MappingStorage` will be
constructed and used.
If ``close_base_on_close`` isn't specified, it will be ``True`` if
a base database was provided and ``False`` otherwise.
If a changes database isn't provided, a
:class:`~ZODB.MappingStorage.MappingStorage` will be
constructed and used and blob support will be provided using a
temporary blob directory.
If ``close_changes_on_close`` isn't specified, it will be ``True`` if
a changes database was provided and ``False`` otherwise.
"""
if close_base_on_close is None:
if base is None:
......@@ -51,6 +93,8 @@ class DemoStorage(ConflictResolvingStorage):
close_base_on_close = False
else:
close_base_on_close = True
elif base is None:
base = ZODB.MappingStorage.MappingStorage()
self.base = base
self.close_base_on_close = close_base_on_close
......@@ -285,10 +329,17 @@ class DemoStorage(ConflictResolvingStorage):
raise
def pop(self):
"""Close the changes database and return the base.
"""
self.changes.close()
return self.base
def push(self, changes=None):
"""Create a new demo storage using the storage as a base.
The given changes are used as the changes for the returned
storage and ``False`` is passed as ``close_base_on_close``.
"""
return self.__class__(base=self, changes=changes,
close_base_on_close=False)
......
src/ZODB/FileStorage/FileStorage.py
View file @ 10e1326a
......@@ -140,7 +140,8 @@ class FileStorage(
ConflictResolvingStorage,
BaseStorage,
):
"""Storage that saves data in a file
"""
# Set True while a pack is in progress; undo is blocked for the duration.
_pack_is_in_progress = False
......@@ -148,6 +149,82 @@ class FileStorage(
def __init__(self, file_name, create=False, read_only=False, stop=None,
quota=None, pack_gc=True, pack_keep_old=True, packer=None,
blob_dir=None):
"""Create a file storage
:param str file_name: Path to store data file
:param bool create: Flag indicating whether a file should be
created even if it already exists.
:param bool read_only: Flag indicating whether the file is
read only. Only one process is able to open the file
non-read-only.
:param bytes stop: Time-travel transaction id
When the file is opened, data will be read up to the given
transaction id. Transaction ids correspond to times and
you can compute transaction ids for a given time using
:class:`~ZODB.TimeStamp.TimeStamp`.
:param int quota: File-size quota
:param bool pack_gc: Flag indicating whether garbage
collection should be performed when packing.
:param bool pack_keep_old: flag indicating whether old data
files should be retained after packing as a ``.old`` file.
:param callable packer: An alternative
:interface:`packer <ZODB.FileStorage.interfaces.IFileStoragePacker>`.
:param str blob_dir: A blob-directory path name.
Blobs will be supported if this option is provided.
A file storage stores data in a single file that behaves like
a traditional transaction log. New data records are appended
to the end of the file. Periodically, the file is packed to
free up space. When this is done, current records as of the
pack time or later are copied to a new file, which replaces
the old file.
FileStorages keep in-memory indexes mapping object oids to the
location of their current records in the file. Back pointers to
previous records allow access to non-current records from the
current records.
In addition to the data file, some ancillary files are
created. These can be lost without affecting data
integrity, however losing the index file may cause extremely
slow startup. Each has a name that's a concatenation of the
original file and a suffix. The files are listed below by
suffix:
.index
Snapshot of the in-memory index. This are created on
shutdown, packing, and after rebuilding an index when one
was not found. For large databases, creating a
file-storage object without an index file can take very
long because it's necessary to scan the data file to build
the index.
.lock
A lock file preventing multiple processes from opening a
file storage on non-read-only mode.
.tmp
A file used to store data being committed in the first phase
of 2-phase commit
.index_tmp
A temporary file used when saving the in-memory index to
avoid overwriting an existing index until a new index has
been fully saved.
.pack
A temporary file written while packing containing current
records as of and after the pack time.
.old
The previous database file after a pack.
When the database is packed, current records as of the pack
time and later are written to the ``.pack`` file. At the end
of packing, the ``.old`` file is removed, if it exists, and
the data file is renamed to the ``.old`` file and finally the
``.pack`` file is rewritten to the data file.
"""
if read_only:
self._is_read_only = True
......
src/ZODB/FileStorage/interfaces.py
View file @ 10e1326a
......@@ -16,18 +16,27 @@ import zope.interface
class IFileStoragePacker(zope.interface.Interface):
def __call__(storage, referencesf, stop, gc):
"""Pack the file storage into a new file
r"""Pack the file storage into a new file
:param FileStorage storage: The storage object to be packed
:param callable referencesf: A function that extracts object
references from a pickle bytes string. This is usually
``ZODB.serialize.referencesf``.
:param bytes stop: A transaction id representing the time at
which to stop packing.
:param bool gc: A flag indicating whether garbage collection
should be performed.
The new file will have the same name as the old file with
'.pack' appended. (The packer can get the old file name via
``.pack`` appended. (The packer can get the old file name via
storage._file.name.) If blobs are supported, if the storages
blob_dir attribute is not None or empty, then a .removed file
most be created in the blob directory. This file contains of
the form:
must be created in the blob directory. This file contains records of
the form::
(oid+serial).encode('hex')+'\n'
or, of the form:
or, of the form::
oid.encode('hex')+'\n'
......
src/ZODB/MappingStorage.py
View file @ 10e1326a
......@@ -32,8 +32,22 @@ import zope.interface
ZODB.interfaces.IStorageIteration,
)
class MappingStorage(object):
"""In-memory storage implementation
Note that this implementation is somewhat naive and inefficient
with regard to locking. Its implementation is primarily meant to
be a simple illustration of storage implementation. It's also
useful for testing and exploration where scalability and efficiency
are unimportant.
"""
def __init__(self, name='MappingStorage'):
"""Create a mapping storage
The name parameter is used by the
:meth:`~ZODB.interfaces.IStorage.getName` and
:meth:`~ZODB.interfaces.IStorage.sortKey` methods.
"""
self.__name__ = name
self._data = {} # {oid->{tid->pickle}}
self._transactions = BTrees.OOBTree.OOBTree() # {tid->TransactionRecord}
......
src/ZODB/component.xml
View file @ 10e1326a
......@@ -18,7 +18,7 @@
<description>
If supplied, the file storage will provide blob support and this
is the name of a directory to hold blob data. The directory will
be created if it doeesn't exist. If no value (or an empty value)
be created if it doesn't exist. If no value (or an empty value)
is provided, then no blob support will be provided. (You can still
use a BlobStorage to provide blob support.)
</description>
......@@ -69,7 +69,13 @@
<sectiontype name="mappingstorage" datatype=".MappingStorage"
implements="ZODB.storage">
<key name="name" default="Mapping Storage"/>
<key name="name" default="Mapping Storage">
<description>
The storage name, used by the
:meth:`~ZODB.interfaces.IStorage.getName` and
:meth:`~ZODB.interfaces.IStorage.sortKey` methods.
</description>
</key>
</sectiontype>
<!-- The BDB storages probably need to be revised somewhat still.
......@@ -187,14 +193,14 @@
<key name="read-only-fallback" datatype="boolean" default="off">
<description>
A flag indicating whether a read-only remote storage should be
acceptable as a fallback when no writable storages are
acceptable as a fall-back when no writable storages are
available. Defaults to false. At most one of read_only and
read_only_fallback should be true.
</description>
</key>
<key name="username" required="no">
<description>
The authentication username of the server.
The authentication user name of the server.
</description>
</key>
<key name="password" required="no">
......@@ -205,7 +211,7 @@
<key name="realm" required="no">
<description>
The authentication realm of the server. Some authentication
schemes use a realm to identify the logic set of usernames
schemes use a realm to identify the logic set of user names
that are accepted by this server.
</description>
</key>
......@@ -225,7 +231,13 @@
<sectiontype name="demostorage" datatype=".DemoStorage"
implements="ZODB.storage">
<key name="name" />
<key name="name">
<description>
The storage name, used by the
:meth:`~ZODB.interfaces.IStorage.getName` and
:meth:`~ZODB.interfaces.IStorage.sortKey` methods.
</description>
</key>
<multisection type="ZODB.storage" name="*" attribute="factories" />
</sectiontype>
......@@ -233,11 +245,12 @@
<sectiontype name="zodb" datatype=".ZODBDatabase"
implements="ZODB.database">
<section type="ZODB.storage" name="*" attribute="storage"/>
<key name="cache-size" datatype="integer" default="5000"/>
<key name="cache-size" datatype="integer" default="5000">
<description>
Target size, in number of objects, of each connection's
object cache.
</description>
</key>
<key name="cache-size-bytes" datatype="byte-size" default="0">
<description>
Target size, in total estimated size for objects, of each connection's
......@@ -245,8 +258,14 @@
"0" means no limit.
</description>
</key>
<key name="large-record-size" datatype="byte-size" />
<key name="pool-size" datatype="integer" default="7"/>
<key name="large-record-size" datatype="byte-size" default="16MB">
<description>
When object records are saved
that are larger than this, a warning is issued,
suggesting that blobs should be used instead.
</description>
</key>
<key name="pool-size" datatype="integer" default="7">
<description>
The expected maximum number of simultaneously open connections.
There is no hard limit (as many connections as are requested
......@@ -255,21 +274,25 @@
and exceeding twice pool-size connections causes a critical
message to be logged.
</description>
<key name="pool-timeout" datatype="time-interval"/>
</key>
<key name="pool-timeout" datatype="time-interval">
<description>
The minimum interval that an unused (non-historical)
connection should be kept.
</description>
<key name="historical-pool-size" datatype="integer" default="3"/>
</key>
<key name="historical-pool-size" datatype="integer" default="3">
<description>
The expected maximum total number of historical connections
simultaneously open.
</description>
<key name="historical-cache-size" datatype="integer" default="1000"/>
</key>
<key name="historical-cache-size" datatype="integer" default="1000">
<description>
Target size, in number of objects, of each historical connection's
object cache.
</description>
</key>
<key name="historical-cache-size-bytes" datatype="byte-size" default="0">
<description>
Target size, in total estimated size of objects, of each historical connection's
......@@ -285,12 +308,12 @@
</key>
<key name="database-name">
<description>
When multidatabases are in use, this is the name given to this
When multi-databases are in use, this is the name given to this
database in the collection. The name must be unique across all
databases in the collection. The collection must also be given
a mapping from its databases' names to their databases, but that
cannot be specified in a ZODB config file. Applications using
multidatabases typical supply a way to configure the mapping in
multi-databases typical supply a way to configure the mapping in
their own config files, using the "databases" parameter of a DB
constructor.
</description>
......
src/ZODB/config.py
View file @ 10e1326a
......@@ -42,13 +42,33 @@ def getStorageSchema():
return _s_schema
def databaseFromString(s):
"""Create a database from a database-configuration string.
The string must contain one or more :ref:`zodb
<database-text-configuration>` sections.
The database defined by the first section is returned.
If :ref:`more than one zodb section is provided
<multidatabase-text-configuration>`, a multi-database
configuration will be created and all of the databases will be
available in the returned database's ``databases`` attribute.
"""
return databaseFromFile(StringIO(s))
def databaseFromFile(f):
"""Create a database from a file object that provides configuration.
See :func:`databaseFromString`.
"""
config, handle = ZConfig.loadConfigFile(getDbSchema(), f)
return databaseFromConfig(config.database)
def databaseFromURL(url):
"""Load a database from URL (or file name) that provides configuration.
See :func:`databaseFromString`.
"""
config, handler = ZConfig.loadConfig(getDbSchema(), url)
return databaseFromConfig(config.database)
......@@ -63,13 +83,20 @@ def databaseFromConfig(database_factories):
return first
def storageFromString(s):
"""Create a storage from a storage-configuration string.
"""
return storageFromFile(StringIO(s))
def storageFromFile(f):
"""Create a storage from a file object providing storage-configuration.
"""
config, handle = ZConfig.loadConfigFile(getStorageSchema(), f)
return storageFromConfig(config.storage)
def storageFromURL(url):
"""\
Create a storage from a URL (or file name) providing storage-configuration.
"""
config, handler = ZConfig.loadConfig(getStorageSchema(), url)
return storageFromConfig(config.storage)
......
src/ZODB/interfaces.py
View file @ 10e1326a
......@@ -437,7 +437,6 @@ class IStorage(Interface):
"""A storage is responsible for storing and retrieving data of objects.
Consistency and locking
-----------------------
When transactions are committed, a storage assigns monotonically
increasing transaction identifiers (tids) to the transactions and
......@@ -472,6 +471,9 @@ class IStorage(Interface):
Finalize the storage, releasing any external resources. The
storage should not be used after this method is called.
Note that databses close their storages when they're closed, so
this method isn't generally called from application code.
"""
def getName():
......
src/ZODB/valuedoc.py 0 → 100644
View file @ 10e1326a
"""Work around an issue with defining class attribute documentation.
See http://stackoverflow.com/questions/9153473/sphinx-values-for-attributes-reported-as-none/39276413
"""
class ValueDoc:
def __init__(self, text):
self.text = text
def __repr__(self):
return self.text
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7