dballe.Var

Var holds a measured value, which can be integer, float or string, and a `wreport.Varinfo`_ with all available information (description, unit, precision, ...) related to it.

Var objects can be created from a `wreport.Varinfo`_ object, and an optional value. Omitting the value creates an unset variable.

Examples:

v = wreport.Var(table["B12101"], 32.5)
# v.info returns detailed informations about the variable in a Varinfo object.
print("%s: %s %s %s" % (v.code, str(v), v.info.unit, v.info.desc))

dballe.Varinfo

Varinfo object holds all possible information about a variable, such as its measurement unit, description and number of significant digits.

Varinfo objects cannot be instantiated directly, and are created by querying `wreport.Vartable`_ objects.

dballe.Vartable

Collection of Varinfo objects indexed by WMO BUFR/CREX table B code.

A Vartable is instantiated by the name (without extension) of the table file installed in wreport's data directory (normally, /usr/share/wreport/):

table = wreport.Vartable("B0000000000000023000")
print(table["B12101"].desc)

for i in table:
    print(i.code, i.desc)

dballe.Record

A record holds a number of key->value mappings, similar to a dict.

Keys are strings, from a fixed set of keywords defined in DB-All.e and documented in the Fortran API documentation, plus all varcodes from the DB-All.e BUFR/CREX B table. Using unknown keys raises an exception.

Values are values internally stored inside dballe.Var objects, with a dballe.Varinfo corresponding to the key. Record's mapping interface directly exposes the variable values, but the dballe.Var objects are still accessible using Record.var(key).

A Record is used to make queries to the database, and read results.

When creating a new record, keyword arguments can be passed and they are set as if Record.update(**kwargs) had been called.

When setting items, either via __setitem__ and via update(), there are special keys that allow to set many items in a single call:

# Set year, month, day, hour, min, sec
rec["datetime"] = None
rec["datetime"] = datetime.datetime(2015, 06, 21, 12, 0, 0)
# Set yearmin..secmin and yearmax..secmax
rec["datetime"] = (None, None)
rec["datetime"] = (datetime.datetime(2014), None)
rec["datetime"] = (None, datetime.datetime(2015))
rec["datetime"] = (datetime.datetime(2014), datetime.datetime(2015))
# Set leveltype1, l1, leveltype2, l2
rec["level"] = None
rec["level"] = (103, 2000)
rec["level"] = (103, 2000, 103, 10000)
# Set pindicator, p1, p2
rec["trange"] = None
rec["trange"] = (205, 0, 10800)

Examples:

rec = Record(lat=44.05, lon=11.03, B12101=22.1)

# Key lookup returns the value of the corresponding variable
print(rec["lat"], rec["B12101"])

# Use .var() to get the variable itself; note that it can return
# None if the value is not set
print(rec.var("lat").info.desc, rec.var("B12101").info.desc)

# Iterating a record iterates all keys
for key in rec:
    print(key, rec.get(key, "undefined"), rec.var(key).info.desc)

# Use .vars() to get a list of only the varcode keys
for varcode in rec.vars():
    print(varcode, rec.get(varcode, "undefined"), rec.var(varcode).info.desc)

dballe.DB

a DB is used to access the database.

Its members are:

attr_insert_data

Insert new attributes into the database

attr_insert_station

Insert new attributes into the database

attr_query_data

Query attributes

attr_query_station

Query attributes

attr_remove_data

Remove attributes

attr_remove_station

Remove attributes

get_default_format

Get the default DB format

insert_data

Insert data values in the database

insert_station_data

Insert station values in the database

query_station_data

Query the station variables in the database; returns a Cursor

remove_station_data

Remove station variables from the database

set_default_format

Set the default DB format

attr_insert(varcode, attrs, reference_id=None, replace=True)

Insert new attributes into the database

attr_remove(varcode, reference_id, attrs=None)

Remove attributes

connect_from_file(filename)

Create a DB connecting to a SQLite file

connect_from_url(url)

Create a DB as defined in an URL-like string

connect_test()

Create a DB for running the test suite, as configured in the test environment

disappear()

Remove all our traces from the database, if applicable.

export_to_file(query, format, filename, generic=False)

Export data matching a query as bulletins to a named file

insert(record, can_replace=False, can_add_stations=False)

(deprecated)Insert a record in the database

is_url(string)

Checks if a string looks like a DB url

load(file)

load(fp, encoding=None, attrs=False, full_pseudoana=False, overwrite=False)

Load a file object in the database. An encoding can optionally be provided as a string ("BUFR", "CREX", "AOF"). If encoding is None then load will try to autodetect based on the first byte of the file.

query_attrs(varcode, reference_id, attrs=None)

Query attributes

query_data(query)

Query the variables in the database; returns a Cursor

query_stations(query)

Query the station archive in the database; returns a Cursor

query_summary(query)

Query the summary of the results of a query; returns a Cursor

remove(query)

Remove variables from the database

reset([repinfo_filename])

Reset the database, removing all existing Db-All.e tables and re-creating them empty.

vacuum()

Perform database cleanup operations

Examples:

# Connect to a database and run a query
db = dballe.DB.connect_from_file("db.sqlite")
query = dballe.Record(latmin=44.0, latmax=45.0, lonmin=11.0, lonmax=12.0)

# The result is a dballe.Cursor, which can be iterated to get results as
# dballe.Record objects.
# The results always point to the same Record to avoid creating a new one
# for every iteration: if you need to store them, use Record.copy()
for rec in db.query_data(query):
    print rec["lat"], rec["lon"], rec["var"], rec.var().format("undefined")

# Insert 2 new variables in the database
rec = dballe.Record(
    lat=44.5, lon=11.4,
    level=(1,),
    trange=(254,),
    date=datetime.datetime(2013, 4, 25, 12, 0, 0),
    B11101=22.4,
    B12103=17.2,
)
db.insert(rec)

dballe.Cursor

a Cursor is the result of database queries. It is generally not used explicitly and just iterated, but it does have a few members:

attr_query

Query attributes for the current variable

remaining

number of results still to be returned

next()

x.next() -> the next value, or raise StopIteration

query_attrs(attrs=None)

Query attributes for the current variable