Quick Start

Here is a brief description of basic usage of PortableTab.

Install

PortableTab requires Python 3.9 or later.

It can be installed using pip.

$ pip install PortableTab

Create Table

First, define the table with the table name and schema.

The table schema must follow the Struct format of Capn’ Proto Schema Language .

>>> from PortableTab import BaseTable
>>> class SampleTable(BaseTable):
...     __tablename__ = "sample"
...     __schema__ = """
...         struct SampleRecord {
...             name @0 :Text;
...             email @1 :Text;
...         }
...     """
...     __record_type__ = "SampleRecord"
...

Next, create this table under the specified directory.

>>> sample_table = SampleTable(db_dir="./db")
>>> sample_table.create()
PosixPath('db/sample')

The create() method creates a subdirectory with the table name sample under the specified directory ./db. It also places the table definition and other files in it.

Finally, prepare a set of records and register them into the table.

>>> sample_table.append_records([
...     {"name": "Bob", "email": "bob@example.com"},
...     {"name": "Alice", "email": "alice@foo.org"},
...     {"name": "Alexa", "email": "alexa@bar.net"},
... ])

Read Table

Open the table by specifying the directory.

>>> sample_table = SampleTable(db_dir="./db")

If the code that wants to read the table does not have the definition of SampleTable class, the base CapnpTable class can be used instead.

>>> from PortableTab import CapnpTable
>>> sample_table = CapnpTable(tablename="sample", db_dir="./db")

The records in the created table can be retrieved by specifying the position of rows (0 origin).

>>> sample_table = SampleTable(db_dir="./db")
>>> for i in range(sample_table.count_records()):
...     print(sample_table.get_record(pos=i, as_dict=True))
...
{'name': 'Bob', 'email': 'bob@example.com'}
{'name': 'Alice', 'email': 'alice@foo.org'}
{'name': 'Alexa', 'email': 'alexa@bar.net'}

TRIE index

You can create a TRIE index for any attribute using create_trie_on().

>>> sample_table.create_trie_on('name')

Once an index is created, records can be searched by their attributes using search_records_on().

>>> sample_table.search_records_on(attr='name', value='Alice')
[<sample.capnp:SampleRecord reader (name = "Alice", email = "alice@foo.org")>]

You can also search for records that begin with a specified string, or match the leading portion of a specified string, specifying funcname parameter of that method.

>>> sample_table.search_records_on(attr='name', value='A', funcname='keys')
[<sample.capnp:SampleRecord reader (name = "Alice", email = "alice@foo.org")>, <sample.capnp:SampleRecord reader (name = "Alexa", email = "alexa@bar.net")>]
>>> sample_table.search_records_on(attr='name', value='Bobson', funcname='prefixes')
[<sample.capnp:SampleRecord reader (name = "Bob", email = "bob@example.com")>]

Attributes that have not been indexed are not searchable.

Note

Indexes that search by arithmetic relationship of values (e.g., b-tree) are not yet implemented.

Delete index and tables

You can delete unnecessary indexes using delete_trie_on().

>>> sample_table.delete_trie_on('name')

The table can be deleted using delete().

>>> sample_table.delete()
>>> del sample_table