zodburi¶
Overview¶
A library which parses URIs and converts them to ZODB storage objects and database arguments.
It will run under CPython 3.7+ and pypy3. It will not run under Jython. It requires ZODB >= 5.0.0.
Installation¶
Install using pip, e.g. (within a virtualenv):
$ pip install zodburi
Using¶
zodburi
has exactly one api: zodburi.resolve_uri()
. This API
obtains a ZODB storage factory and a set of keyword arguments suitable for
passing to the ZODB.DB.DB
constructor. For example:
1from zodburi import resolve_uri
2
3storage_factory, dbkw = resolve_uri(
4 'zeo://localhost:9001?connection_cache_size=20000')
5
6# factory will be an instance of ClientStorageURIResolver
7# dbkw will be {'connection_cache_size':20000, 'pool_size':7,
8# 'database_name':'unnamed'}
9
10from ZODB.DB import DB
11storage = storage_factory()
12db = DB(storage, **dbkw)
URI Schemes¶
The URI schemes currently recognized in the zodbconn.uri
setting
are file://
, zeo://
, zconfig://
, memory://
and demo:
.
Documentation for these URI scheme syntaxes are below.
In addition to those schemes, the relstorage package adds support for
postgres://
.
file://
URI scheme¶
The file://
URI scheme can be passed as zodbconn.uri
to create a ZODB
FileStorage database factory. The path info section of this scheme should
point at a filesystem file path that should contain the filestorage data.
For example:
file:///my/absolute/path/to/Data.fs
The URI scheme also accepts query string arguments. The query string arguments honored by this scheme are as follows.
Misc¶
- demostorage
boolean (if true, wrap FileStorage in a DemoStorage)
Example¶
An example that combines a path with a query string:
file:///my/Data.fs?connection_cache_size=100&blobstorage_dir=/foo/bar
zeo://
URI scheme¶
The zeo://
URI scheme can be passed as zodbconn.uri
to create a ZODB
ClientStorage database factory. Either the host and port parts of this scheme
should point at a hostname/portnumber combination e.g.:
zeo://localhost:7899
Or the path part should point at a UNIX socket name:
zeo:///path/to/zeo.sock
The URI scheme also accepts query string arguments. The query string arguments honored by this scheme are as follows.
Misc¶
- demostorage
boolean (if true, wrap ClientStorage in a DemoStorage)
Connection-related¶
These arguments relate to connections created from the database.
- connection_cache_size
integer (default 10000)
- connection_pool_size
integer (default 7)
Database-related¶
These arguments relate to the database (as opposed to storage) settings.
- database_name
string
Example¶
An example that combines a path with a query string:
zeo://localhost:9001?connection_cache_size=20000
zconfig://
URI scheme¶
The zconfig://
URI scheme can be passed as zodbconn.uri
to create any
kind of storage that ZODB can load via ZConfig. The path info section of this
scheme should point at a ZConfig file on the filesystem. Use an optional
fragment identifier to specify which database to open. This URI scheme does
not use query string parameters.
Examples¶
An example ZConfig file:
<zodb>
<mappingstorage>
</mappingstorage>
</zodb>
If that configuration file is located at /etc/myapp/zodb.conf, use the following URI to open the database:
zconfig:///etc/myapp/zodb.conf
A ZConfig file can specify more than one database. For example:
<zodb temp1>
<mappingstorage>
</mappingstorage>
</zodb>
<zodb temp2>
<mappingstorage>
</mappingstorage>
</zodb>
In that case, use a URI with a fragment identifier:
zconfig:///etc/myapp/zodb.conf#temp1
memory://
URI scheme¶
The memory://
URI scheme can be passed as zodbconn.uri
to create a
ZODB MappingStorage (memory-based) database factory. The path info section
of this scheme should be a storage name. For example:
memory://storagename
However, the storage name is usually omitted, and the most common form is:
memory://
The URI scheme also accepts query string arguments. The query string arguments honored by this scheme are as follows.
Database-related¶
These arguments relate to the database (as opposed to storage) settings.
- database_name
string
Connection-related¶
These arguments relate to connections created from the database.
- connection_cache_size
integer (default 10000)
- connection_pool_size
integer (default 7)
Example¶
An example that combines a dbname with a query string:
memory://storagename?connection_cache_size=100&database_name=fleeb
demo:
URI scheme¶
The demo:
URI scheme can be passed as zodbconn.uri
to create a
DemoStorage database factory. DemoStorage provides an overlay combining base
and δ ("delta", or in other words, "changes") storages.
The URI scheme contains two parts, base and δ:
demo:(base_uri)/(δ_uri)
an optional fragment specifies arguments for ZODB.DB.DB
constructor:
demo:(base_uri)/(δ_uri)#dbkw
Example¶
An example that combines ZEO with local FileStorage for changes:
demo:(zeo://localhost:9001?storage=abc)/(file:///path/to/Changes.fs)
More Information¶
Reporting Bugs / Development Versions¶
Visit https://github.com/Pylons/zodburi to download development or tagged versions.
Visit https://github.com/Pylons/zodburi/issues to report bugs.
Change Log¶
2.6.0 (2023-05-17)¶
Stop support for ZODB4
Stop support for python<3.7
2.5.0 (2021-05-12)¶
Support both ZODB4 and ZODB5.
Add support for PyPy.
Add support for Python 3.8.
Drop support for Python 3.4.
Add support for
demo:
URI scheme.
2.4.0 (2019-01-11)¶
Add support for Python 3.7.
Fix PendingDeprecationWarning about
cgi.parse_qsl
. (PR #21)
2.3.0 (2017-10-17)¶
Fix parsing of
zeo://
URI with IPv6 address.Drop support for Python 3.3.
Add support for Python 3.6.
2.2.2 (2017-05-05)¶
Fix transposed
install_requires
andtests_require
lists insetup.py
.
2.2.1 (2017-04-18)¶
Fix breakage added in 2.2 to the
zconfig
resolver.
2.2 (2017-04-17)¶
Add support for additional database configuration parameters:
pool_timeout
,cache_size_bytes
,historical_pool_size
,historical_cache_size
,historical_cache_size_bytes
,historical_timeout
, andlarge_record_size
.
2.1 (2017-04-17)¶
Add support for Python 3.4 and 3.5.
Drop support for Python 2.6 and 3.2.
Add missing ClientStorage constructor kw args to resolver.
2.0 (2014-01-05)¶
Update
ZODB3
meta-package dependency toZODB
+ZConfig
+ZEO
. Those releases are what we import, and have final Py3k-compatible releases.Packaging: fix missing
url
argument tosetup()
.
2.0b1 (2013-05-02)¶
Add support for Python 3.2 / 3.3.
Add
setup.py docs
alias (runssetup.py develop
and installs documentation dependencies).Add
setup.py dev
alias (runssetup.py develop
and installs testing dependencies).Automate building the Sphinx docs via
tox
.Fix
zconfig:
URIs under Python 2.7. The code worked around a bug in the stdlib'surlparse.urlsplit
for Python < 2.7; that workaround broke under 2.7. See https://github.com/Pylons/zodburi/issues/5Drop support for Python 2.5.
1.1 (2012-09-12)¶
Remove support for
postgres://
URIs, which will now be provided by therelstorage
package. Thanks to Georges Dubus for the patch!
1.0 (2012-06-07)¶
Add support for
postgres://
URIs. Thanks to Georges Dubus for the patch!Pin dependencies to Python 2.5-compatible versions when testing with tox under Python 2.5.
Update the documentation for publication to ReadTheDocs
1.0b1 (2011-08-21)¶
Initial release.