co3.engine module

class co3.engine.Engine(*manager_args, **manager_kwargs)

Bases: object

Engine base class. Used primarily as a Database connection manager, with general methods that can be defined for several kinds of value stores.

Note that this is where the connection hierarchy is supposed to stop. While some derivative Engines, like SQLEngine, mostly just wrap another engine-like object, this is not the rule. That is, inheriting Engine subtypes shouldn’t necessarily expect to rely on another object per se, and if such an object is required, _this_ is the class is meant to be skeleton to supports its creation (and not merely a wrapper for some other type, although it may appear that way when such a type is in fact readily available).

why is this object necessary?

More specifically, why not just have all the functionality here packed into the Database by default? The answer is that, realistically, it could be. The type separation between the Engine and Database is perhaps the least substantiated in CO3. That being said, it still serves a purpose: to make composition of subtypes easier. The Engine is a very lightweight abstraction, but some Engine subtypes (e.g., FileEngines) may be used across several sibling Database types. In this case, we’d have to repeat the Engine-related functionality for such sibling types. Depending instead on a singular, outside object keeps things DRY. If Databases and Engines were uniquely attached type-wise 1-to-1 (i.e., unique Engine type per unique Database type), a separate object here would indeed be a waste, as is the case for any compositional typing scheme.

dev note

This class is now non-generic. It was originally conceived as a generic, depending on a “resource spec type” to be help define expected types on initialization. This simply proved too messy, required generic type propagation to the Database definition, and muddied the otherwise simple args and kwargs forwarding for internal manager creation.

__init__(*manager_args, **manager_kwargs)

connect(timeout=None)

Open a connection to the database specified by the resource. Exactly what the returned connection looks like remains relatively unconstrained given the wide variety of possible database interactions. This function should be invoked in with-statement contexts, constituting an “interaction session” with the database (i.e., allowing several actions to be performed using the same connection).

property manager

Return Engine’s singleton manager, initializing when the first call is made.