Documentation for pulsar 0.9.2. For development docs, go here.
Tha main component for pulsar datastore clients is the Store
class which encapsulates the essential API for communicating and executing
commands on remote servers.
A Store
can also implement several methods for managing
the higher level object data mapper.
To create a data Store
client one uses the create_store()
function with a valid connection string:
>>> from pulsar.apps.data import create_store
>>> store = create_store('redis://user:password@127.0.0.1:6500/11')
>>> store.name
'redis'
>>> store.database
'11'
>>> store.dns
'redis://user:password@127.0.0.1:6500/11'
Additional parameters can be passed via the connection string or as key-valued parameters. For example:
>>> store = create_store('redis://user:password@127.0.0.1:6500/11',
namespace='test_')
>>> store.dns
'redis://user:password@127.0.0.1:6500/11?namespace=test_'
The connection string is a way to specify the various parameters for the
data store connection. All Store
support a connection string
of the form:
<scheme>://<username>:<password>@<host>/<database>?param1=...¶m2=...
where:
schema
is the store namedatabase
is the database name (or number for redis)username
is an optional database usernamepassword
is an optional database passwordWhen implementing a new Store
there are several methods which need
to be covered:
ping()
to check if the server is availableconnect()
to create a new connectionexecute()
to execute a command on the store serverThese additional methods must be implemented only if the store supports the object data mapper:
execute_transaction()
execute a transactionA new store needs to be registered via the register_store()
function.
All registered data stores are stored in the data_stores
dictionary:
from pulsar.apps.data import data_stores
Pulsar provides two implementations, the redis client and the pulsards client.
The main component of the data store API is the create_store()
function which creates in one function call a new Store
object which can be used to interact directly with the backend database
or indirectly via the object data mapper.
pulsar.apps.data.store.
create_store
(url, **kw)[source]¶Create a new Store
for a valid url
.
Parameters: |
|
---|---|
Returns: | a |
pulsar.apps.data.stores.pulsards.startds.
start_store
(*args, **kwargs)[source]¶Equivalent to create_store()
for most cases excepts when the
url
is for a pulsar store not yet started.
In this case, a PulsarDS
is started.
pulsar.apps.data.store.
Store
(name, host, loop=None, database=None, user=None, password=None, encoding=None, **kw)[source]¶Base class for an asynchronous data stores.
It is an Producer
for accessing and retrieving
data from remote data servers such as redis, couchdb and so forth.
A Store
should not be created directly, the high level
create_store()
function should be used instead.
_host
¶The remote host, tuple or string
_user
¶The user name
_password
¶The user password
name
¶Store name
database
¶Database name/number associated with this store.
encoding
¶Store encoding (usually utf-8
)
dns
¶Domain name server
create_database
(dbname=None, **kw)[source]¶Create a new database in this store.
By default it does nothing, stores must implement this method only if they support database creation.
Parameters: | dbname – optional database name. If not supplied a
database with database is created. |
---|
delete_database
(dbname=None)[source]¶Delete a database dbname
By default it does nothing, stores must implement this method only if they support database deletion.
Parameters: | dbname – optional database name. If not supplied a
database named database is deleted. |
---|
encode_bytes
(data)[source]¶Encode bytes data
Parameters: | data – a bytes string |
---|---|
Returns: | bytes or string |
create_table
(model, remove_existing=False)[source]¶Create the table for model
.
This method is used by the object data mapper. By default it does nothing.
drop_table
(model, remove_existing=False)[source]¶Drop the table for model
.
This method is used by the object data mapper. By default it does nothing.
create_model
(manager, *args, **kwargs)[source]¶Create a new model from a manager
Method used by the Manager
callable method.
execute_transaction
(transaction)[source]¶Execute a transaction()
in a multi-store
Transaction
.
THis methid is used by the object data mapper and should not be invoked directly. It returns a list of models committed to the backend server.
compile_query
(query)[source]¶Compile the Query
query
.
Method required by the Object data mapper
.
Returns: | an instance of CompiledQuery if implemented |
---|
get_model
(manager, pkvalue)[source]¶Fetch an instance of a model
with primary key pkvalue
.
This method required by the object data mapper.
Parameters: |
|
---|
has_query
(query_type)[source]¶Check if this Store
supports query_type
.
Parameters: | query_type – a string indicating the query type to check
(filter , exclude , search ). |
---|
This method is used by the object data mapper.
pulsar.apps.data.store.
Command
(args, action=0)[source]¶A command executed during a in a execute_transaction()
action
¶Type of action: * 0 custom command * 1 equivalent to an SQL INSERT * 2 equivalent to an SQL DELETE
pulsar.apps.data.store.
PubSub
(store, protocol=None)[source]¶A Publish/Subscriber interface.
A PubSub
handler is never initialised directly, instead,
the pubsub()
method of a data Store
is used.
To listen for messages one adds clients to the handler:
def do_somethind(channel, message):
...
pubsub = client.pubsub()
pubsub.add_client(do_somethind)
pubsub.subscribe('mychannel')
You can add as many listening clients as you like. Clients are functions
which receive two parameters only, the channel
sending the message
and the message
.
A PubSub
handler can be used to publish messages too:
pubsub.publish('mychannel', 'Hello')
An additional protocol
object can be supplied. The protocol must
implement the encode
and decode
methods.
count
(*channels)[source]¶Returns the number of subscribers (not counting clients subscribed to patterns) for the specified channels.
channels
(pattern=None)[source]¶Lists the currently active channels.
An active channel is a Pub/Sub channel with one ore more subscribers
(not including clients subscribed to patterns).
If no pattern
is specified, all the channels are listed,
otherwise if pattern
is specified only channels matching the
specified glob-style pattern are listed.
add_client
(client)[source]¶Add a new client
to the set of all clients
.
Clients must be callable accepting two parameters, the channel and
the message. When a new message is received
from the publisher, the broadcast()
method will notify all
clients
via the callable
method.