B Brightway Common Database API

[cmutel]

One big barrier to adapting Brightway to other databases is its tight coupling between projects, the default database backend, and the IO library. To decouple these, we first need to define data formats, interfaces, and endpoints.

The interface is easy to define - we will use Python, with normal data structures, either built in or with attrs or similar.

The data format will be eILCD. eILCD is an XML format for life cycle inventory and impact category data. We are choosing eILCD instead of developing something on our own, or using a different existing format, because:

• eILCD is the only format really battle tested with multiple implementations and use in a variety of contexts
• eILCD is the transfer format for GLAD and PEF
• eILCD is extensively documented, both with XSD files and guidance

Don't get the wrong impression, eILCD is everything you hate about XML, but arguably even worse than usual as it was mostly designed by scientists instead of programmers. But it is still better than the alternatives.

The hardest part are the API endpoints. These are Python methods or functions which programs can use to interface with any database backend that follow the Brightway common database standard; database implementors can choose to only support part of this standard, but we should define this standard in a parsimonious fashion, such that open source implementations do choose to implement the whole standard.

Based on the current default database backend, the following CRUD endpoints should be considered:

• Node (Can be called activity or process)
• Edge (Can be called exchange)
• Impact category
• Characterization factor

It might also be necessary to have a common endpoint for bw_projects for when a project is activated.

After finishing this section, programmers will be able to choose whatever database and schema they want, and will know exactly which functions are expected by bw_io such that the IO classes can write or update data. There will also be a reference implementation, compatible with existing bw2data code and semantics, which will demonstrate how users can import data from bw_io, and query data from an ORM.

Specific tasks:

• B1 Choose, document, and justify the data structures used for passing data following the common API
• B2 Adapt eILCD to a standard Python data structures. Any deviations from eILCD nomenclature or structures must be documented and justified.
• B3 Design a set of Python signals to be emitted by database backends on CRUD operations. This is needed for search indices or other integrated platforms. Follow Activity Browser signals when possible to maximize compatibility.
• B4 Specify and provide a reference implementation of the Brightway Common Database standard
• B5 Port bw2data to the standard as bw_data

Nice-to-have:

• B6 Reference common database implementation against a different type of database (e.g. graph database)