Package: web.db
© 2009-2019 Alice Bevan-McGregor and contributors.https://github.com/marrow/web.dbIntroductionDatabase access is often central to any web application or service. To offer the maximum flexibility, theWebCore web
frameworkuses a light-weight yet highly modular and fully dependency graphed
extension system. The database connection layer passes through the full capability of this extension system down to an
organized and named collection of database interfaces.This extension is available with the namedbin theweb.extplugin namespace.This extension adds adbserver and requestcontext attribute.This extension provides thesqlalchemy,mongoengine,dbapi, andsqlite3plugins in theweb.dbplugin namespace.InstallationInstallingweb.dbis easy, just execute the following in a terminal:pip install web.dbNote:Westronglyrecommend always using a container, virtualization, or sandboxing environment of some kind when
developing using Python; installing things system-wide is yucky (for a variety of reasons) nine times out of ten.  We
prefer light-weightvirtualenv, others prefer solutions as
robust asVagrant.If you addweb.dbto theinstall_requiresargument of the call tosetup()in your
application’ssetup.pyfile, this extension will be automatically installed and made available when your own
application or library is installed.  We recommend using “less than” version numbers to ensure there are no
unintentional side-effects when updating.  Useweb.db<2.1` to get all bugfixes for the current release, and ``web.db<3.0to get bugfixes and feature updates while ensuring that large breaking changes are not
installed.There are a few “extras” you can require (by adding a comma separated list of these tags within square brackets after
the dependency name, e.g.:web.db[foo,bar]development- installs all testing requirements and optional componentssql- installsSQLAlchemymongoengine- installsMongoEngine(Note:this engine is not yet production quality.)Development VersionDevelopment takes place onGitHubin theweb.dbproject.  Issue tracking, documentation, and
downloads are provided there.Installing the current development version requiresGit, a distributed source code management
system.  If you have Git you can run the following to download andlinkthe development version into your Python
runtime:git clone https://github.com/marrow/web.db.git
pip install -e 'web.db[development]'You can then upgrade to the latest version at any time:(cd web.db; git pull; pip install -U -e '.[development]')If you would like to make changes and contribute them back to the project, fork the GitHub project, make your changes,
and submit a pull request.  This process is beyond the scope of this documentation; for more information seeGitHub’s documentation.UsageTheweb.dbextension (providing thedbfeature flag for extension dependency graphing and plugin with that
name in theweb.extnamespace) is utilized in a few different contexts.ConfigurationThis happens before the web application has “started” and is ready to service requests. You enable the extension by
including an instance of it in theextensionsargument to the instantiation of aweb.core:Applicationobject:from web.ext.db import DatabaseExtension

app = Application("Hi.", extensions=[
        DatabaseExtension(),
    ])The initializer for the database extension uses the arguments provided to declare named database interfaces, which you
instantiate and pass in by name. Additionally, the namedefaulthas special meaning, and may be passed as the
first (and only) positional parameter.ApplicationAt the application context, that is, in extension callbacks where thecontextis an ApplicationContext object,
outside of the request cycle, adbattribute is added to contain any contributions made by database adapters.Please refer to the documentation for individual adapters as to what values they assign for themselves and when.AdaptersThere is a limited set of adapters provided built-in.Native DB API 2.0Many SQL or SQL-like database adapters in Python are available which expose aPEP 249 DB API
2.0-compliant interface. These can be utilized directly once a few
properties of the adapter are known.First, you need to know the location of the adapter’sconnectfunction. Pass this as the first positional
argument to theDBAPIConnectionconstructor as a string in dot-colon notation. The second positional argument
is the URI to pass through as the target to connect the engine to. Behaviour may vary from adapter to adapter.As an example, Python often ships with an adapter for SQLite. You might utilize it by initializing your application
with this extension arrangement:from web.ext.db import DatabaseExtension
from web.db.dbapi import DBAPIConnection

app = Application("Hi.", extensions=[
        DatabaseExtension(DBAPIConnection(
                'sqlite3:connect',  # A dot-colon path, module:name.
                ':memory:',  # Use the in-memory temporary store.
            ))
    ])Because this engine is built-in and common, a shortcut is provided by way of theSQLite3Connectionsubclass:from web.ext.db import DatabaseExtension
from web.db.dbapi import SQLite3Connection

app = Application("Hi.", extensions=[
        DatabaseExtension(SQLite3Connection(':memory:'))
    ])Either way, additional keyword arguments are passed along through to the underlyingconnectfunction. For the
generic adapter, two additional arguments have a significant impact on when the interface performs actions.Ifsafeis truthy (the default) then the adapter is treated as thread safe. It is “connected” on application start
and “disconnected” on application shutdown. Otherwise the interface is “connected” at the beginning of a request and
“disconnected” at the end of the request, after all content has been returned to the user.MongoDBAn adapter is provided for plain MongoDB connections, as provided by thepymongopackage. Extended capabilities are provided beyond a typicalMongoClientconnection, and the database with its collection attributes are exposed via thecontext.dbattribute.To get started, you need a URL to connect to, and need to construct aMongoDBConnectioninstance to pass to
theDatabaseExtensionduring application configuration:from web.ext.db import DatabaseExtesion
from web.db.mongo import MongoDBConnection

app = Application("Hi.", extensions=[
        DatabaseExtension(MongoDBConnection('mongodb://localhost/test'))
    ])With a confguration like this, attributes ofcontext.dbwill represent pymongoCollectioninstances.SQLAlchemyDuring startup, you can utilize the SQLAlchemy engine object contained within the context to perform global-level
operations such as DDL manipulation. One such example with an SQLAlchemy adapter configured as the defualt interface
would be:class ApplicationExtension:
    needs = {'db'}

    def start(self, context):
        SomeDeclarativeBase.metadata.create_all(context.db.default)Within the context of a request, the interface exposed via the context is a request-local scoped session. You can use
this to prepare and commit transactions, issue queries, etc.Currently no transactional behaviour, auto-commit, etc. are supported.ExtendingWriting new adapters is nearly identical to writing WebCore extensions. All of the same rules apply: must be a class,
offers callback registration through the use of named methods, can registerneedsandusesandprovides,
etc. Please see theWebCoredocumentation and examples.The only major difference is that the database interface is expected to populate an attribute or mapping item with a
name defined by analiasattribute.  Several examples are provided in the source, and are documented so as to
provide examples.Version HistoryVersion 3.0Updated minimum Python version.Marrow Package now requires Python 3.6 or later.Removed Python 2 support and version specific code.The project has been updated to modern Python packaging standards, including modern namespace use. Modern namespaces are wholly incompatible with the previous namespacing mechanism; this project can not be simultaneously installed with any Marrow project that is Python 2 compatible.Version 2.0.1Updated theREADMEand metaproject layout to current Marrow standards.Removed extraneous imports and slots where unhelpful or causing issues, such as in the SQLAlchemy adapter. (Thanks
bmillham!)MigratedMongoDBConnectionfrommarrow.mongo.Version 2.0Extract of the database mechanism from WebCore.Version 1.xProcess fully integrated in the WebCore web framework.Licenseweb.db has been released under the MIT Open Source license.The MIT LicenseCopyright © 2009-2019 Alice Bevan-McGregor and contributors.Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the “Software”), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.