dballe messages I/O

class dballe.BinaryMessage

Binary message.

This is basically a simple wrapper around a bytes() object, providing extra information about the filename, offset and index where the message data was read. Is it used by dballe.File to return the binary messages it reads.

encoding

message encoding

index

index of the message in the input file, or None if unknown

offset

offset of the message in the input file, or None if unknown

pathname

pathname of the file the message came from, or None if unknown

class dballe.File

Read-only access to files with weather bulletins in BUFR or CREX format.

No write functions are supported: to write files, you can simply write dballe.BinaryMessage objects or encoded messages to normal Python files.

Constructor: File(file: Union[str, File], encoding: str=None)

Parameters
  • file – can be a file name, or a file-like object. If a file-like object supports fileno(), that file descriptor is dup()-ed and used for efficient reading. Otherwise, file.read() is called to load the data to read in memory.

  • encoding – if omitted, it is auto detected by looking at the first byte of the file only. Files with leading padding data will not be detected properly, and you need to explicitly specify the encoding to read them.

Example usage:

with dballe.File("test.bufr", "BUFR") as f:
    for binmsg in f:
        print("#{m.index}: {m.pathname}:{m.offset}: {m.encoding} message".format(m=binmsg))
encoding

get the file encoding

name

get the file name

class dballe.Message

The contents of a decoded BUFR or CREX message.

DB-All.e can interpret the contents of most weather messages commonly in use, and represent them as variables identified by dballe.Level, dballe.Trange, datetime, coordinates, network, and mobile station identifier.

A message contains only one reference station (coordinates, network, mobile station identifier), only one reference datetime, and many (level, trange, varcode, value) variables.

Variables that describe the station are accessible using None for level and trange.

Constructor: Message(type: str)

Parameters

type

a string identifying the message type, and it will affect how the message will be encoded by the exporter.

Available values are:
  • generic

  • synop

  • pilot

  • temp

  • temp_ship

  • airep

  • amdar

  • acars

  • ship

  • buoy

  • metar

  • sat

Example usage:

importer = dballe.Importer("BUFR")
with importer.from_file("test.bufr") as f:
    for msgs in f:
        for msg in msgs:
            print("{m.report},{m.coords},{m.ident},{m.datetime},{m.type}".format(m=msg))
coords

message coordinates

datetime

message datetime

get(level: dballe.Level, trange: dballe.Trange, code: str) → Union[dballe.Var, None]

Get a Var given its level, timerange, and varcode; returns None if not found

get_named(name: str) → Union[dballe.Var, None]

Get a Var given its shortcut name; returns None if not found

See Message shortcuts for the list of available shortcuts.

ident

message mobile station identifier

query_data(query: Dict[str, Any]) → dballe.CursorData

Query the data in the message

Returns

a cursor to iterate the query results (see dballe.CursorData)

query_station_data(query: Dict[str, Any]) → dballe.CursorStationData

Query the constant station data in the message

Returns

a cursor to iterate the query results (see dballe.CursorStationData)

query_stations(query: Dict[str, Any]) → dballe.CursorStation

Query the stations in the message

Returns

a cursor to iterate the query results (see dballe.CursorStation)

report

message report

set(level: dballe.Level, trange: dballe.Trange, var: dballe.Var)

Set a Var given level and timerange

set_named(name: str, value: Union[dballe.Var, int, str, double])

Set a Var given its shortcut name.

See Message shortcuts for the list of available shortcuts.

type

message type

class dballe.Importer

Message importer.

This is the engine that decodes binary messages and interprets their contents using a uniform data model.

Note that one binary message is often decoded to multiple data messages, in case, for example, of compressed BUFR files.

Constructor: Importer(encoding: str, simplified: bool=True, domain_errors=”raise”)

Parameters
  • encoding – can be "BUFR" or "CREX".

  • simplified – controls whether messages are constructed using standard levels and time ranges, or using the exact levels and time ranges contained in the input. For example, a simplified intepretation of a synop message will place the temperature at 2M above ground, regardless of the reported sensor height. A non-simplified import will place the temperature reading at the reported sensor height.

  • domain_errors – controls what to do when a value in the message is outside the range for its variable. “raise” (the default) raises an exception. “unset” changes the value to be unset. “clamp” changes the value to the nearest valid extreme of the domain. “tag” changes the value to the nearest valid extreme of the domain and sets attribute B33192=0

When a message is imported in simplified mode, the actual context information will be stored as data attributes.

Example usage:

importer = dballe.Importer("BUFR")
with importer.from_file("test.bufr") as f:
    for msgs in f:
        for msg in msgs:
            print("{m.report},{m.coords},{m.ident},{m.datetime},{m.type}".format(m=msg))

importer = dballe.Importer("BUFR")
with dballe.File("test.bufr", "BUFR") as f:
    for binmsg in f:
        msgs = importer.from_binary(binmsg)
        for msg in msgs:
            print("#{b.index}: {m.report},{m.coords},{m.ident},{m.datetime},{m.type}".format(b=binmsg, m=msg))
from_binary(binmsg: dballe.BinaryMessage) → Sequence[dballe.BinaryMessage]

Decode a BinaryMessage to a tuple of dballe.Message objects

from_file(file: Union[dballe.File, str, File]) → dballe.ImporterFile

Wrap a dballe.File into a sequence of tuples of dballe.Message objects.

file can be a dballe.File, a file name, or a file-like object. A dballe.File is automatically constructed if needed, using the importer encoding.

class dballe.ImporterFile

Message importer iterating over the contents of a a dballe.File.

This is never instantiated explicitly, but is returned by Importer.from_file().

It can be used in a context manager, and it is an iterable that yields tuples of dballe.Message objects.

class dballe.Exporter

Message exporter.

This is the engine that can reconstruct a standard BUFR or CREX message from the contents of a dballe.Message.

to_binary(contents: Union[dballe.Message, Sequence[dballe.Message], Iterable[dballe.Message]]) → bytes

Encode a dballe.Message or a sequence of dballe.Message into a bytes object.