5
.. py:currentmodule:: happybase
7
**HappyBase** is a developer-friendly `Python <http://python.org/>`_ library to
8
interact with `Apache HBase <http://hbase.apache.org/>`_. HappyBase is designed
9
for use in standard HBase setups, and offers application developers a Pythonic
10
API to interact with HBase.
12
The example below illustrates basic usage of the library. The :doc:`tutorial
13
<tutorial>` contains many more examples.
19
connection = happybase.Connection('hostname')
20
table = connection.table('table-name')
22
table.put('row-key', {'family:qual1': 'value1',
23
'family:qual2': 'value2'})
25
row = table.row('row-key')
26
print row['family:qual1'] # prints 'value1'
28
for key, data in table.rows(['row-key-1', 'row-key-2']):
29
print key, data # prints row key and data for each row
31
for key, data in table.scan(row_prefix='row'):
32
print key, data # prints 'value1' and 'value2'
34
row = table.delete('row-key')
36
Below the surface, HappyBase uses the `Python Thrift library
37
<http://pypi.python.org/pypi/thrift>`_ to connect to HBase using its `Thrift
38
<http://thrift.apache.org/>`_ gateway, which is included in the standard HBase
39
0.9x releases. While this HBase Thrift API can be used directly from Python
40
using (automatically generated) HBase Thrift service classes, application code
41
doing so is very verbose, cumbersome to write, and hence error-prone. The
42
reason for this is that the HBase Thrift API is a flat, language-agnostic
43
interface API closely tied to the RPC going over the wire-level protocol. In
44
practice, this means that applications using Thrift directly need to deal with
45
many imports, sockets, transports, protocols, clients, Thrift types and
46
mutation objects. For instance, look at the code required to connect to HBase
47
and store two values::
49
from thrift import Thrift
50
from thrift.transport import TSocket, TTransport
51
from thrift.protocol import TBinaryProtocol
53
from hbase import ttypes
54
from hbase.Hbase import Client, Mutation
56
sock = TSocket.TSocket('hostname', 9090)
57
transport = TTransport.TBufferedTransport(sock)
58
protocol = TBinaryProtocol.TBinaryProtocol(transport)
59
client = Client(protocol)
62
mutations = [Mutation(column='family:qual1', value='value1'),
63
Mutation(column='family:qual2', value='value2')]
64
client.mutateRow('table-name', 'row-key', mutations)
66
:pep:`20` taught us that simple is better than complex, and as you can see,
67
Thrift is certainly complex. HappyBase hides all the Thrift cruft below a
68
friendly API. The resulting application code will be cleaner, more productive
69
to write, and more maintainable. With HappyBase, the example above can be
74
connection = happybase.Connection('hostname')
75
table = connection.table('table-name')
76
table.put('row-key', {'family:qual1': 'value1',
77
'family:qual2': 'value2'})
79
If you're not convinced and still think the Thrift API is not that bad, please
80
try to accomplish some other common tasks, e.g. retrieving rows and scanning
81
over a part of a table, and compare that to the HappyBase equivalents. If
82
you're still not convinced by then, we're sorry to inform you that HappyBase is
83
not the project for you, and we wish you all of luck maintaining your code ‒ or
84
is it just Thrift boilerplate?
87
.. rubric:: Next steps
89
Follow the :doc:`installation guide <installation>` and continue with the
90
:doc:`tutorial <tutorial>`.
93
.. vim: set spell spelllang=en:
added
removed
doc/introduction.rst
