Fluvo

A powerful Python library for defining robust, repeatable, and high-performance data import/export workflows for Odoo. It replaces complex, manual data preparation with a clean, "configuration-as-code" approach.

---

Key Features

• Declarative Transformations: Use simple Python scripts and a rich set of mapper functions to transform any source CSV or XML data into an Odoo-ready format.
• Intelligent Import Engine: A smart, multi-threaded importer that automatically uses the best strategy for your data. Features a load -> create fallback to rescue good records from failed batches and provide precise error feedback.
• Automatic Two-Pass Imports: Automatically detects and handles interdependent relationships (e.g., parent/child records in the same file), eliminating a whole class of complex import-order errors without manual configuration.
• High-Performance CLI: A clean, modern command-line interface with parallel processing (--worker), batching (--size), and deadlock prevention (--groupby).
• Direct Server-to-Server Migration: Perform a complete export, transform, and import from one Odoo instance to another in a single, in-memory step with the migrate command.
• Post-Import Workflows: Run automated actions on your data after it has been imported (e.g., validating invoices) using the powerful workflow command.
• High-Performance Streaming Exports: Export massive datasets from Odoo with confidence using a streaming pipeline and the Polars engine for multi-threaded data processing.
• Multiple Data Sources: Natively supports CSV and XML files. Easily extendable to support other sources like databases or APIs.
• Data Validation: Ensure data integrity before it even reaches Odoo.

Installation

You can install Fluvo via uv or pip from PyPI:

$ uv pip install fluvo

Quick Usage Example

The core workflow involves two simple steps:

1. Transform your source data with a Python script. Create a transform.py file to define the mapping from your source file to Odoo's format.

# transform.py
from fluvo.lib.transform import Processor
from fluvo.lib import mapper

my_mapping = {
    'id': mapper.concat('prod_', 'SKU'),
    'name': mapper.val('ProductName'),
    'list_price': mapper.num('Price'),
}

processor = Processor('origin/products.csv')
processor.process(my_mapping, 'data/products_clean.csv', {'model': 'product.product'})
processor.write_to_file("load.sh")

...

$ python transform.py

2. Load the clean data into Odoo using the CLI. The transform.py script generates a load.sh file containing the correct CLI command.

# Contents of the generated load.sh
fluvo import --connection-file conf/connection.conf --file data/products_clean.csv --model product.product ...

Then execute the script.

$ bash load.sh

When the import command runs, it automatically detects the data structure. If it finds relational data like parent_id fields, it will automatically switch to a robust two-pass strategy to ensure the import succeeds.

Documentation

For a complete user guide, tutorials, and API reference, please see the full documentation on Read the Docs. Please see the Command-line Reference for details.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the LGPL 3.0 license, Fluvo is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This development of project is financially supported by stefcy.com.