Overview¶

Wísdómhord is a flat file db format and tool for internal project use.

The goal is to create a flat file db format that produces something that makes sense to check into git - both in the sense that it produces meanginful diffs, and that it is immediately readable.

An example hord looks like:

// INVOKER :: Wísdómhord
// DESCRIPTION :: An example hord
// INCEPT :: 10 Regn 226 // 05.00
// UPDATED :: 10 Regn 226 // 05.40
// COUNT :: 7

[ COL1          | COL2  | COL3  | COL4        | COL6                       ]
[ Hello world   | 12345 | True  | Wé          | 28 Regn 226 // 12.11.15    ]
[ Wes Hál       | 67890 | False | Gárdena     | 10 Mǽdland 226 // 03.43.05 ]
[ Hallo Welt    | 123   | True  | in          | 8 Mist 226 // 23.23.23     ]
[ Saluton mondo | 34.2  | False | géardagum   |                            ]
[ qo' vIvan     | 42    | True  | þéodcyninga | 24 Mǽdland 226 // 01.02.03 ]
[ Suilad ambar  | 1968  |       | þrym        | 1 Wending 226 // 18.45.55  ]
[ Ada mūnok     |       | True  | gefrúnon    | 8 Wæstm 226 // 17.10.00    ]

Contents¶

Using a Hord¶

Wísdómhord currently only supports row insertion and reading. Future versions will support updating existing rows as well as row deletion.

Creation¶

To create a new hord, supply the desired path and the Bisen you wish to use:

hord = wisdomhord.cennan('/home/user/doc.hord', bisen=YourBisen)

This will return a Wisdomhord object ready for you to use. If the file already exists, the cennan will fail.

Loading¶

To load an existing hord, supply the path to the hord as well as the bisen:

hord = wisdomhord.hladan('/home/user/doc.hord', bisen=YourBisen)

Insertion¶

To insert into a hord that you have created or loaded, first define the column value dictionary you want to insert:

row = {'COL1': 'Hello!',
       'COL2': True,
       'COL3': 10,
       'COL4': 20.3,
       'COL5': datetime.datetime(2018, 2, 16, 12, 11, 15),
       'COL6': datarum.wending(226, 5, 28, 12, 11, 15)}

hord.insert(row)

Reading¶

To retrieve the rows from a hord, you can:

rows = hord.get_rows()

This will return all the rows in the hord, ordered by their order in the file.

You can also limit by the number of rows returned:

rows = hord.get_rows(limit=10)

or by the desired columns:

rows = hord.get_rows(cols=['COL2', 'COL3'])

The returned rows can also be sorted by a column:

rows = hord.get_rows(sort_by=['COL3'], reverse_sort=True)

The returned rows can also be filtred by a supplied function:

rows = hord.get_rows(filter_func=lambda x: x['COL2'] == True and x['COL3'] >= 10)

Bisen¶

To create the data file structure, as well as automate casting to and from the file, a model called a Bisen should be created and given to Wísdómhord upon hord creation and loading.

To do this, create a class that inherits from the Bisen class:

class DocumentationBisen(Bisen):

    __invoker__ = 'Wísdómhord Documentation'
    __description__ = 'Example Bisen for Wísdómhord Documentation'

    col1 = Sweor('COL1', wisdomhord.String)
    col2 = Sweor('COL2', wisdomhord.Boolean)
    col3 = Sweor('COL3', wisdomhord.Integer)
    col4 = Sweor('COL4', wisdomhord.Float)
    col5 = Sweor('COL5', wisdomhord.DateTime)
    col6 = Sweor('COL6', wisdomhord.Wending)

Creating and inserting into a hord using this model would produce a hord that looks like:

// INVOKER :: Wísdómhord Insertion Testing
// DESCRIPTION :: Insertion Test For Wísdómhord
// INCEPT :: 28 Regn 226
// UPDATED :: 28 Regn 226
// COUNT :: 1

[ COL1   | COL2 | COL3 | COL4 | COL5                   | COL6                   ]
[ Hello! | True | 10   | 20.3 | 16.02.2018 // 12.11.15 | 28 Regn 226 // 12.11.15]

Reading from this hord while providing this model will return a dictionary for each row where each cell is cast to the appropriate object - for example COL5 will be returned as a Datetime object.

Wísdómhord documentation