The guano Python Module

This is the Python reference implementation for reading and writing GUANO metadata.

GUANO is the “Grand Unified Acoustic Notation Ontology”, an extensible metadata format for representing bat acoustics data.

Import this Python module as:

import guano

This module utilizes the Python logging framework for issuing warnings and debug messages. Application code may wish to enable logging with the logging.basicConfig() function.

class guano.GuanoFile(filename=None, strict=True)

An abstraction of a .WAV file with GUANO metadata.

A GuanoFile object behaves like a normal Python dict, where keys can either be well-known metadata keys, namespaced keys, or a tuple of (namespace, key).

Well-known keys will have their values coerced into the correct data type. The parser may be configured to coerce new namespaced keys with the register() function.

Example usage:

gfile = GuanoFile('myfile.wav')
print gfile['GUANO|Version']
>>> '1.0'
gfile['Species Manual ID'] = 'Mylu'
gfile['Note'] = 'I love GUANO!'
gfile.write()

Though reading, writing, and editing .WAV files is the target usage, this class may also be used independent from the .WAV file format. GUANO metadata can be written into an Anabat-format file or to a sidecar file, for example, by populating a GuanoFile object and then using the serialize() method to produce correctly formatted UTF-8 encoded metadata.

Variables:

• filename (str) – path to the file which this object represents, or None if a “new” file
• strict_mode (bool) – whether the GUANO parser is configured for strict or lenient parsing
• wav_data (bytes) – the data subchunk of a .WAV file consisting of its actual audio data, lazily-loaded and cached for performance
• wav_params (wavparams) – namedtuple of .WAV parameters (nchannels, sampwidth, framerate, nframes, comptype, compname)

classmethod from_string(metadata_str, *args, **kwargs)

Create a GuanoFile instance from a GUANO metadata string

Parameters:metadata_str – a string (or string-like buffer) of GUANO metadata Return type:GuanoFile

get_namespaces()

Get list of all namespaces represented by this metadata. This includes the ‘GUANO’ namespace, and the ‘’ (empty string) namespace for well-known fields.

items(namespace=None)

Iterate over (key, value) for entire metadata or for specified namespace of fields

items_namespaced()

Iterate over (namespace, key, value) for entire metadata

classmethod register(namespace, keys, coerce_function, serialize_function=<type 'str'>)

Configure the GUANO parser to recognize new namespaced keys.

Parameters:

• namespace – vendor namespace which the keys belong to
• keys – a key or sequence of keys under the specified vendor namespace
• coerce_function (callable) – a function for coercing the UTF-8 value to any desired data type
• serialize_function (callable) – an optional function for serializing the value to UTF-8 string

serialize(pad='\n')

Serialize the GUANO metadata as UTF-8 encoded bytes

to_string()

Represent the GUANO metadata as a Unicode string

wav_data

Actual audio data from the wav data chunk. Lazily loaded and cached.

well_known_items()

Iterate over (key, value) for all the well-known (defined) fields

write(make_backup=True)

Write the GUANO .WAV file to disk.

Parameters:make_backup (bool) – create a backup file copy before writing changes or not (default: True); backups will be saved to a folder named GUANO_BACKUP Raises:ValueError – if this GuanoFile doesn’t represent a valid .WAV by having appropriate values for self.wav_params (see wave.Wave_write.setparams()) and self.wav_data (see wave.Wave_write.writeframes())