Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Z
ZODB
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
nexedi
ZODB
Commits
86ed6e9d
Commit
86ed6e9d
authored
Sep 07, 2016
by
Jim Fulton
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Finished the install-and-run topic and added docs for ZODB.config
parent
86b04522
Changes
6
Hide whitespace changes
Inline
Side-by-side
Showing
6 changed files
with
169 additions
and
9 deletions
+169
-9
documentation/guide/index.rst
documentation/guide/index.rst
+4
-0
documentation/guide/install-and-run.rst
documentation/guide/install-and-run.rst
+147
-7
documentation/guide/writing-persistent-objects.rst
documentation/guide/writing-persistent-objects.rst
+3
-1
documentation/reference/storages.rst
documentation/reference/storages.rst
+2
-0
documentation/reference/zodb.rst
documentation/reference/zodb.rst
+12
-1
zodbdocumentationtests/tests.py
zodbdocumentationtests/tests.py
+1
-0
No files found.
documentation/guide/index.rst
View file @
86ed6e9d
...
...
@@ -12,7 +12,11 @@ If you haven't yet, you should read the :ref:`Tutorial <tutorial-label>`.
.. toctree::
:maxdepth: 2
install-and-run
writing-persistent-objects.rst
.. todo:
transaction.rst
storages.rst
configuration.rst
...
...
documentation/guide/install-and-run.rst
View file @
86ed6e9d
...
...
@@ -29,8 +29,8 @@ For more complex configurations, you'll probably find ZODB's
configuration
language
easier
to
use
.
To
understand
database
setup
,
it
's important to understand ZODB'
s
architecture
.
In
particular
,
ZODB
separates
database
functionality
from
low
-
level
storage
concerns
.
When
you
create
a
database
object
,
architecture
.
ZODB
separates
database
functionality
from
storage
concerns
.
When
you
create
a
database
object
,
you
specify
a
storage
object
for
it
to
use
,
as
in
::
import
ZODB
,
ZODB
.
FileStorage
...
...
@@ -45,7 +45,7 @@ a database.
Sometimes, storages are created through composition. For example, if
we want to save space, we could layer a ``ZlibStorage``
[#zlibstorage
_
]_ over the file storage::
[#zlibstorage
fn
]_ over the file storage::
import ZODB, ZODB.FileStorage, zc.zlibstorage
...
...
@@ -61,11 +61,11 @@ Python configuration
--------------------
To set up a database with Python, you'
ll
construct
a
storage
using
the
ref
:`
storage
APIs
<
included
-
storages
-
label
>`,
and
then
pass
the
storage
to
the
class
:`~
ZODB
.
DB
`
class
to
create
a
database
,
as
shown
:
ref
:`
storage
APIs
<
included
-
storages
-
label
>`,
and
then
pass
the
storage
to
the
:
class
:`~
ZODB
.
DB
`
class
to
create
a
database
,
as
shown
in
the
examples
in
the
previous
section
.
The
class
:`~
ZODB
.
DB
`
class
also
accepts
a
string
path
name
as
it
's
The
:
class
:`~
ZODB
.
DB
`
class
also
accepts
a
string
path
name
as
it
's
storage argument to automatically create a file storage. You can also
pass ``None`` as the storage to automatically use a
:class:`~ZODB.MappingStorage.MappingStorage`, which is convenient when
...
...
@@ -73,7 +73,147 @@ exploring ZODB::
db = ZODB.DB(None) # Create an in-memory database.
Text configuration
------------------
.. [#zlibstorage_] `zc.zlibstorage
ZODB supports a text-based configuration language. It uses a syntax
similar to Apache configuration files. The syntax was chosen to be
familiar to site administrators.
ZODB'
s
text
configuration
uses
`
ZConfig
<
https
://
pypi
.
python
.
org
/
pypi
/
ZConfig
/
3.1.0
>`
_
.
You
can
use
ZConfig
to
create
your
application
's configuration, but it'
s
more
common
to
include
ZODB
configuration
strings
in
their
own
files
or
embedded
in
simpler
configuration
files
,
such
as
`
configarser
<
https
://
docs
.
python
.
org
/
3
/
library
/
configparser
.
html
#
module
-
configparser
>`
_
files
.
A
database
configuration
string
has
a
``
zodb
``
section
wrapping
a
storage
section
,
as
in
::
<
zodb
>
cache
-
size
-
bytes
100
MB
<
mappingstorage
>
</
mappingstorage
>
</
zodb
>
..
->
snippet
In
the
example
above
,
the
:
ref
:`
mappingstorage
<
mappingstorage
-
text
-
configuration
>`
section
defines
the
storage
used
by
the
database
.
To
create
a
database
from
a
string
,
use
:
func
:`
ZODB
.
config
.
databaseFromString
`::
>>>
import
ZODB
.
config
>>>
db
=
ZODB
.
config
.
databaseFromString
(
snippet
)
To
load
databases
from
file
names
or
URLs
,
use
:
func
:`
ZODB
.
config
.
databaseFromURL
`.
Using
databases
:
connections
============================
Once
you
have
a
database
,
you
need
to
get
a
database
connection
to
to
much
of
anything
.
Connections
take
care
of
loading
and
saving
objects
and
manage
object
caches
.
Each
connection
has
it
's own cache
[#caches-are-expensive]_.
Getting connections
-------------------
Amongst [#amongst]_ the common ways of getting a connection:
db.open()
The database :meth:`~ZODB.DB.open` method opens a
connection, returning a connection object::
>>> conn = db.open()
It'
s
up
to
the
application
to
call
:
meth
:`~
ZODB
.
Connection
.
Connection
.
close
`
when
the
application
is
done
using
the
connection
.
If
changes
are
made
,
the
application
:
ref
:`
commits
transactions
<
commit
-
transactions
>`
to
make
them
permanent
.
db
.
transaction
()
The
database
:
meth
:`~
ZODB
.
DB
.
transaction
`
method
returns
a
context
manager
that
can
be
used
with
the
`
python
with
statement
<
https
://
docs
.
python
.
org
/
3
/
reference
/
compound_stmts
.
html
#
grammar
-
token
-
with_stmt
>`
_
to
execute
a
block
of
code
in
a
transaction
::
with
db
.
transaction
()
as
connection
:
connection
.
root
.
foo
=
1
..
->
src
>>>
exec
(
src
)
>>>
with
db
.
transaction
()
as
connection
:
...
print
connection
.
root
.
foo
1
>>>
_
=
conn
.
transaction_manager
.
begin
()
#
get
updates
on
conn
In
the
example
above
,
we
used
``
as
connection
``
to
get
the
database
connection
used
in
the
variable
``
connection
``.
some_object
.
_p_jar
For
code
that
's already running in the context of an open
connection, you can get the current connection as the ``_p_jar``
attribute of some persistent object that was accessed via the
connection.
Getting objects
---------------
Once you have a connection, you access objects by traversing the
object graph form the root object.
The database root object is a mapping object that holds the top level
objects in the database. There should only be a small number of
top-level (often only one). You can get the root object by calling a
connection'
s
``
root
``
attribute
::
>>>
root
=
conn
.
root
()
>>>
root
{
'foo'
:
1
}
>>>
root
[
'foo'
]
1
For
convenience
[#
root
-
convenience
]
_
,
you
can
also
get
top
-
level
objects
by
accessing
attributes
of
the
connection
root
object
:
>>>
conn
.
root
.
foo
1
Once
you
have
a
top
-
level
object
,
you
use
it
's methods, attributes, or
operations to access other objects and so on to get the objects you
need. Often indexing data structures like BTrees_ are used to
make it possible to search objects in large collections.
.. [#zlibstoragefn] `zc.zlibstorage
<https://pypi.python.org/pypi/zc.zlibstorage>`_ is an optional
package that you need to install separately.
.. [#caches-are-expensive] ZODB can be very efficient at caching data
in memory, especially if your `working set
<https://en.wikipedia.org/wiki/Working_set>`_, because the cache is
simply an object tree and accessing a cached object typically
requires no database interaction. Because each connection has it'
s
own
cache
,
connections
can
be
expensive
,
depending
on
their
cache
sizes
.
For
this
reason
,
you
'll generally want to limit the number
of open connections you have at any one time. Connections are
pooled, so opening a connection is inexpensive.
.. [#amongst] https://www.youtube.com/watch?v=7WJXHY2OXGE
.. [#root-convenience] The ability to access top-level objects of the
database as root attributes is a recent convenience. Originally,
the ``root()`` method was used to access the root object which was
then accessed as a mapping. It'
s
still
potentially
useful
to
access
top
-
level
objects
using
the
mapping
interface
if
their
names
aren
't valid attribute names.
.. _BTrees: https://pythonhosted.org/BTrees/
documentation/guide/writing-persistent-objects.rst
View file @
86ed6e9d
...
...
@@ -157,7 +157,7 @@ record from the book record and is managed by ZODB independent of the
management
of
the
book
.
In
addition
to
``
PersistentList
``
and
``
PersistentMapping
``,
general
persistent
data
structures
are
provided
by
the
``
BTrees
``
package
,
persistent
data
structures
are
provided
by
the
BTrees_
package
,
most
notably
``
BTree
``
and
``
TreeSet
``
objects
.
Unlike
``
PersistentList
``
and
``
PersistentMapping
``,
``
BTree
``
and
``
TreeSet
``
objects
are
scalable
and
can
easily
hold
millions
of
...
...
@@ -566,3 +566,5 @@ framework for managing schema-migration scripts.
<https://pypi.python.org/pypi/zope.cachedescriptors>`_ package
provides some descriptors that help implement attributes that cache
data.
.. _BTrees: https://pythonhosted.org/BTrees/
documentation/reference/storages.rst
View file @
86ed6e9d
...
...
@@ -89,6 +89,8 @@ MappingStorage
.. autoclass:: ZODB.MappingStorage.MappingStorage
:members: __init__
.. _mappingstorage-text-configuration:
MappingStorage text configuration
---------------------------------
...
...
documentation/reference/zodb.rst
View file @
86ed6e9d
...
...
@@ -31,6 +31,8 @@ Databases
supportsUndo, undoLog, undoInfo, undoMultiple, undo,
transaction, storage
.. _database-text-configuration:
Database text configuration
---------------------------
...
...
@@ -38,7 +40,7 @@ Databases are configured with ``zodb`` sections::
<zodb>
cache-size-bytes 100MB
<mappingstorage
<mappingstorage
>
</mappingstorage>
</zodb>
...
...
@@ -47,6 +49,8 @@ storage and any of the following options:
.. zconfigsectionkeys:: ZODB component.xml zodb
.. _multidatabase-text-configuration:
For a multi-database configuration, use multiple ``zodb`` sections and
give the sections names::
...
...
@@ -136,3 +140,10 @@ TimeStamp (transaction ids)
.. method:: year()
Return the time stamp's year.
Loading configuration
=====================
.. automodule:: ZODB.config
:members: databaseFromString, databaseFromFile, databaseFromURL,
storageFromString, storageFromFile, storageFromURL
zodbdocumentationtests/tests.py
View file @
86ed6e9d
...
...
@@ -40,6 +40,7 @@ def test_suite():
manuel
.
testing
.
TestSuite
(
manuel
.
doctest
.
Manuel
()
+
manuel
.
capture
.
Manuel
(),
join
(
guide
,
'writing-persistent-objects.rst'
),
join
(
guide
,
'install-and-run.rst'
),
join
(
reference
,
'zodb.rst'
),
join
(
reference
,
'storages.rst'
),
setUp
=
setUp
,
tearDown
=
tearDown
,
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment