Introduction to Odoo Components

One of the greatest strength of Odoo, besides its active community, is the extensibility provided through modules.

At the core of this extensibility is the model inheritance, with a concept of re-openable models.

Models extensions

A simplified definition of the partner model:

from odoo import models

class ResPartner(models.Model)
    _name = "res.partner"

    name = fields.Char(required=True)
    # ... other fields

    def _address_fields(self):
        """Returns the list of address fields that are synced from the parent."""
        return list(ADDRESS_FIELDS)

Any module can extend the model, add fields or methods. Here, the module partner_address_street3 which adds a third street field:

class ResPartner(models.Model):
    _inherit = "res.partner"

    street3 = fields.Char('Street 3')

    def _address_fields(self):
        fields = super()._address_fields()[:]
        fields.append('street3')
        return fields

If you are familiar with Odoo development, you probably already know this. If this is new to you and are interested in more details, you may start from the beginning.

The extensions possibilities are powerful, but they also have a weakness, encouraged by the framework, to grow what some would call fat models. Every module adds their own methods and logic in the models, which can lead to issues like namespace collisions, bad readability due to mixing of responsibities or duplicated logic.

I like the single responsibility principle and the idea of composition over inheritance when it makes sense. Well decoupled classes are easier to test as well.

That being said, we can say that what I am looking for is a way to define "Service classes", classes which can do one thing and do it well. Using a bare Python class would not be a solution, as it would not be extensible by other Odoo modules. But... Odoo has this already.

It is not widely used for this purpose, but the class models.AbstractModel can be described as a model which is not backed by a database table, therefore, it has no fields, only pure Python logic. Its name can be confusing, because it is not "abstract" in the pure OOP definition of a class that cannot be instantiated. It really is about the database storage.

The two main purposes I have seen for Abstract Models are:

• "Real" abstract models which are then included in normal Models to share and provide additional fields or logic (mixin / multiple inheritance's way)
• Services, which is related the topic of this article

Here is how a service based on an Abstract Model could be defined:

class SettlePaymentService(models.AbstractModel):
    _name = "settle.payment.service"

    def settle(self, payment):
        client = self._psp_client()
        client.settle(payment.id)

    # ...

And a model could then use this service with:

class PaymentTransaction(models.Model):
    _inherit = "payment.transaction"

    def button_settle(self):
        self.env["settle.payment.service"].settle(self)

If I'm speaking about services, this is because this is what Components are about. Are Abstract Models enough for this use case? Yes, they are. No, they aren't. "It depends." is often a pretty good answer to a technical question. I'll describe what they can do, and let you judge if you need them or not.

Let's begin with components

A bit of context

The Components are provided by an Odoo Community Association module. You can find it on GitHub

🔥 It is not only for developing connectors, it is hosted in this project because it was born from this use case, and is a dependency for the Connector module.

It has a long history, as I started working on the first version of Connector in 2013, but it had a very different form by then. I wrote the Component module and reimplemented the Connector module on top of it in 2017, which means it was available since Odoo 10.0.

Some of the modules implemented on Components on top of my head are various connectors for different services (Jira, Magento, ...) the Odoo REST framework, the EDI project for Odoo, the storage suite, the barcode scanner application of the OCA WMS project... Let me know in the comments about the uses cases you know!

How to define a component?

The definition of a Component is much like a model:

from odoo.addons.component.core import Component

class SettlePayment(Component)
    _name = "settle.payment.service"

    def settle(self, payment):
        client = self._psp_client()
        client.settle(payment.id)

And the inheritance works the same way across modules:

class SettlePayment(Component)
    _inherit = "settle.payment.service"

    def settle(self, payment):
        _logger.info("added a logger when we settle")
        super().settle(payment)

You will have noted that until there, it looks pretty similar to the examples with Models above, with reason. The classes and inheritance mechanism are the same but:

• The Component classes never have any database table.
• There is no _inherits as it only makes sense for models with tables. _inherit works the same way.
• There is no equivalent to TransientModel, it would not make any sense without table.
• There is an AbstractComponent class, which can not be instanciated, it is only used as a "base interface / base implementation" for other Components to depend on.

You can get a component by its name from a Model, a bit like when you get a Model from self.env:

class PaymentTransaction(models.Model):
    _inherit = "payment.transaction"

    def button_settle(self):
        with self.env["payment.collection"].work_on(self._name) as work:
            settle_service = work.component_by_name("settle.payment.service")
            settle_service.settle(self)

But this is not really how it is meant to be used!
Also, I promise I'll get back later to what this work_on() is about.

Component matching by usage

This is where we really start, hang on!

Using models.AbstractModel for services is nice until you need more dynamic things.

For instance: if the type of the payment is "bank", use service BankExportService, if the type is "creditcard", use SettlePaymentService. Or, the export of a "res.partner" must be done using a CSV to a sFTP service, and the export of a "product.product" using a REST API.

This can be totally fine with some conditions in the model that would call one of the service. Or you can use the dynamic properties of Components. In the first case, the caller is responsible to choose the service, with components, the service is selected at runtime depending on the context without intervention on the caller's side.

Each Component gets assigned a _usage. Real life usages are "record.exporter", "record.importer", "search", "record.validator", "webservice.request", ... This is what will be used to find the component you need for the action you want to run.

With this new learning, let's write a Component again:

class RecordExporter(Component):
    _name = "generic.record.exporter"
    _usage = "record.exporter"

    def export(self, record):
        _logger.info("the generic exporter only logs data: %s", record.read())

The caller of the component:

class ResUsers(models.Model):
    _inherit = "res.users"

    def button_export(self):
        self.ensure_one()
        with self.env["my.collection"].work_on(self._name) as work:
            work.component(usage="record.exporter").export(self)

Why is it better to find my component by usage rather than by name? Because the name is fixed and is what is used to define the dependencies. If a module that I don't control defines base components and they are get by name in the middle of a chunk of code, I'm stuck. If they are get by usage, I can use the inheritance (_inherit) to modify the usage of the initial component, and create an entirely new or variant of the component with the expected usage (_usage). This is also what allows dynamic dispatching of components, as we will see in the next section.

In less words: the name defines the inheritance, the usage defines which component is used at runtime.

Apply on... models?

As I was speaking about dynamic dispatch (maybe a language abuse, but I have no better words), here is an example.

On the components, the _apply_on attribute defines on which models a component may be used. The default value is None, which means all models.

I keep using the generic exporter defined above, but I will add a different exporter for products:

class CSVRecordExporter(Component):
    _name = "csv.record.exporter"
    _inherit = "generic.record.exporter"
    _usage = "record.exporter"

    _apply_on = ["res.partner"]

    def export(self, record):
        csv_data = self._generate_csv(record)
        self._export_to_sftp(csv_data)

The export method here builds a CSV and pushes it to a sFTP. The _inherit is not strictly mandatory, but often makes sense. The real addition for the example is _apply_on.

And the caller of the component... didn't change:

class ResPartner(models.Model):
    _inherit = "res.partner"

    def button_export(self):
        self.ensure_one()
        with self.env["my.collection"].work_on(self._name) as work:
            work.component(usage="record.exporter").export(self)

The code is 100% the same as the code we had for Users right? And yet, when we call button_export, the data will only be logged for users, and be exported as CSV for partners.

The _name of the 2 exporters is different, but we didn't had to change the caller of the service. Hopefully, you should start to see the potential for code sharing and extensibility (in a real example, button_export could then be added in an abstract model and included both in the users and the partner models, then the same method returns the appropriate component for each model).

class BankExportService(Component):
    _name = "bank.exporter"
    _usage = "payment.exporter"

    @classmethod
    def _component_match(cls, work):
        return work.collection.payment_type == 'bank'

class PaymentTransaction(models.Model):
    _inherit = "payment.transaction"

    def button_export(self):
        self.ensure_one()
        with self.env["my.collection"].work_on(self._name, payment_type=self.type) as work:
            work.component(usage="payment.exporter").export(self)

Collection and work_on()

I promised I would get back to this work_on we saw in the earlier code fragments.

To explain this, let's start from the reason it has to exist. As the Components are very polyvalent, used for many different use cases, by different classes of modules, a problem I had to avoid was namespace collisions. What if I install a module A that defines a record.exporter, and module B does the same? We could have manually added prefixes in the usages, but it feels clunky.

An additional attribute exists on Components... the Collection.

Every component is assigned to a collection. Generally the base module for an implementation of a connector, of a generic framework such as REST or EDI... A collection could be "magento.backend" or "edi.backend".

In other terms, each collection has its own set of components. A collection is a Registry of components.
The Components _names are global, but for a given usage, components will eventually be filtered on the current collection.

A component with the collection set:

class RecordExporter(Component):
    _name = "record.exporter"
    _collection = "foo.collection"

🌈 you will pretty often see the words collection and backend used interchangeably, because historically, the Connector module was using solely the term "Backend". The latter did not really made sense for the more generic Component system, so it became Collection.

What then from this collection? It relates to a Model, which will be the reference for this collection. It can be a Model or an AbstractModel depending of the need. The benefit of a Model is that it can store fields, such as the URL of the service, the credentials, ...

class FooCollection(models.Model):
    _name = 'foo.collection'
    _inherit = 'collection.base'

The _name of the model has to match the _collection of its components, and the model has to _inherit from collection.base.

Now to the work_on context manager. It is made available by collection.base. It initializes and returns a WorkContext, which is the container for the current context (collection, model, env and arbitrary values) that makes the glue between the current "Context" (not the Odoo context, but the collection, model and values we want to use in components).

✨ The WorkContext is a bit like the env of Odoo but for Components.

work_on() bridges the gap between Odoo Models and Components. From a model, this is needed to be able to reach components.

class FooCollection(models.Model):
    _name = 'foo.collection'
    _inherit = 'collection.base'

    def export_all(self, records):
        with self.work_on(records._name) as work:
            work.component(usage="export.batch").export(records)

Or from another model:

class ResPartner(models.Model):
    _inherit = 'res.partner'

    def sync_from_foo(self):
        with self.env["foo.collection"].work_on("res.partner") as work:
            work.component(usage="sync").run_sync(self)

Once in a component, work_on() is not needed anymore, as every component holds the WorkContext and is able to reach other components.

Here is a simplified example that would use other components to export a record:

class FooSync(Component):
    _name = "foo.sync"
    _collection = "foo.collection"
    _usage = "sync"

    def run_sync(self, record):
        api_client = self.component(usage="webservice")
        data = api_client.read(record.id)
        odoo_data = self.component(usage="mapper").map(data)
        record.write(odoo_data)

This minimal component shows that we can split the work in small services, with their own responsibilities. Here, we have one service reading data from a webservice, and a second service which maps the external data to a dictionary that we can feed to write().

            def export_all(self, records):
                api_client = self._client()
                api_client.connect()
                with self.work_on(records._name, api_client=api_client) as work:
                    work.component(usage="export.batch").export(records)

            def export(self, records):
                api_client = self.work.api_client
                api_client.xxx

Summary

Components are used to build service classes. They are registered in Collections (registries of components). They have an inheritance system similar as the Model classes.

To be able to work with components, we use the context manager work_on() on the Collection. When we ask a component for a given usage, the collection's registry will match the components in this order:

• Find a matching Component for the given usage (_usage) for the current collection (_collection) and model (_apply_on)
• Find a matching Component for the given usage (_usage) for the current collection (_collection) and any model (no _apply_on on component)
• Find a matching Component for the given usage (_usage) for any collection (no _collection on component) and any model (no _apply_on on component)

In any of the steps above, in case of multiple candidates, the method _component_match is called on each candidate to restrict further the match.

AbstractComponent are never returned by the dispatch mechanism, they can be used to share code in concrete components.

Next?

Maybe you are wondering what is "Connector" then? Maybe I should write about it one day, but in a few words: the Connector module is a set of pre-defined components specialized to implement connectors with external services.

Thank you for reading this far!