Guewen Baconnier

Posted on 19 juin 2021 • Updated on 21 juin 2021

9 2
Introduction to Odoo Components
#odoo #python #oca
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.
Behind the scene
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 classmodels.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
OCA / connector
Odoo generic connector framework (jobs queue, asynchronous tasks, channels)

🔥 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 thiswork_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.
Want more?

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 , which means all models.
None

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 _inheritis 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).
Want more?

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 s are global, but for a given usage, components will eventually
_name
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 of Odoo but for Components.
env

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() .
Want more?

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!
Top comments (3)
Guewen Baconnier • 21 juin 21
Glad it helped!
Now, this article is about "bare" components, connectors should be the matter of
another entire post ;)
Also the idea I want to promote is that eventually the design of a connector or other
module based on components should be adapted to the use case and the way you see
it. An implementation should not be distorted only to fit in a pattern. Hence,
 understanding the components is the most useful thing, then you can pick or not some
pieces of the connector module if they help, or write your own.
Coding Dodo • 21 juin 21
Great in-depth article !👏 👏
Code of Conduct • Report abuse

Tidelift PROMOTED

Learn from Open Source Leaders at GitHub (and other

great companies)
A 100% virtual, completely free event bringing together like-minded application
developers, open source project maintainers, and the extended network of people
who care most about their work.
Register Now

Guewen Baconnier
500 Internal Error
LOCATION
Switzerland
WORK
Software Developer
JOINED
8 juin 2020

More from Guewen Baconnier

Using a domain stored in a field for a Many2one
#odoo #oca

Tidelift PROMOTED

Secure Your Open Source Project & More Great Topics 🎁

👥 4,500 Open source community participants
📚 50+ Speakers, including leading maintainers and industry experts
​📺 100s of on-demand talks from three years of Upstream
Register