Replace supplementary record/manager classes with mixins

Records in Odoo can have some additional fields that are shared across many different record models using model inheritance.

To support adding these kinds of shared fields (and related methods) to record/manager classes in the OpenStack Odoo Client library in a more modular way,  add support for the use of **mixins** to take advantage of Python's multiple inheritance to add such fields and methods to custom record/manager classes.

**Protocol** classes were created for `RecordBase` (called `RecordProtocol`) and `RecordManagerBase` (called `RecordManagerProtocol`) which contain common attribute/field type hints and method stubs. The mixin classes subclass these protocol classes to provide type hints within mixin classes as if they subclass the record/manager base classes (they can't do this directly for complicated reasons).

The implementations for the record and record manager base classes have been refactored to reduce duplication as part of this work.

The `NamedRecordManagerBase` and `CodedRecordManagerBase` classes have been reimplemented using mixins to not only utilise this paradigm inside the library itself, but also demonstrate its usage in a simple and practical way for anyone looking to write their own mixins.

The `get_by_unique_field` method provided by `RecordManagerWithUniqueFieldBase` has been incorporated into `RecordManagerBase` to make it available for use in any custom manager class.

Finally, a basic unit testing pipeline using `pytest` has been added. Initially a single test to make sure the package can be imported correctly has been added, but the plan is to expand coverage over time.

Author: Callum Dickinson

.github/workflows/main.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "0.9.2"
+          version: "0.9.17"
       - name: Create virtual environment
         run: uv sync --only-dev
       - name: Publish the docs to GitHub Pages

.github/workflows/tag.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "0.9.2"
+          version: "0.9.17"
       - name: Build source dist and wheels
         run: uv build
       - name: Upload source dist and wheels to artifacts
@@ -58,7 +58,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "0.9.2"
+          version: "0.9.17"
       - name: Publish source dist and wheels to PyPI
         run: uv publish
 
@@ -109,7 +109,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "0.9.2"
+          version: "0.9.17"
       - name: Create virtual environment
         run: uv sync --only-dev
       - name: Publish the docs to GitHub Pages

.github/workflows/test.yml

@@ -30,6 +30,34 @@ jobs:
       - name: Run pre-commit hooks
         uses: pre-commit/[email protected]
 
+  test:
+    needs: pre-commit
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python_version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - name: Clone full tree, and checkout branch
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "${{ matrix.python_version }}"
+          cache: "pip"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.17"
+      - name: Run tests
+        run: uv run poe test
+
   build:
     needs: pre-commit
     runs-on: ubuntu-24.04
@@ -46,7 +74,7 @@ jobs:
       - name: Setup uv
         uses: astral-sh/setup-uv@v7
         with:
-          version: "0.9.2"
+          version: "0.9.17"
       - name: Build source dist and wheels
         run: uv build
       - name: Upload source dist and wheels to artifacts

.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+rspec.xml
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -15,20 +15,20 @@ repos:
       - id: check-added-large-files
       - id: check-merge-conflict
   - repo: https://github.com/crate-ci/typos
-    rev: "v1.38.1"
+    rev: "v1.40.0"
     hooks:
       - id: typos
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: "0.9.2"
+    rev: "0.9.17"
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.14.0"
+    rev: "v0.14.9"
     hooks:
       - id: ruff-check
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.18.2"
+    rev: "v1.19.0"
     hooks:
       - id: mypy
         additional_dependencies:

changelog.d/13.changed.md

@@ -0,0 +1 @@
+Replace supplementary record/manager classes with mixins

docs/managers/custom.md

@@ -791,6 +791,230 @@ The following internal attributes are also available for use in methods:
 * `_odoo` (`odoorpc.ODOO`) - The OdooRPC connection object
 * `_env` (`odoorpc.env.Environment`) - The OdooRPC environment object for the model
 
+## Mixins
+
+Python supports [multiple inheritance](https://docs.python.org/3/tutorial/classes.html#multiple-inheritance)
+when creating new classes. A common use case for multiple inheritance is to extend
+functionality of a class through the use of *mixin classes*, which are minimal
+classes that only consist of supplementary attributes and methods, that get added
+to other classes through subclassing.
+
+The OpenStack Odoo Client library for Python supports the use of mixin classes
+to add functionality to custom record and manager classes in a modular way.
+Multiple mixins can be added to record and manager classes to allow mixing and
+matching additional functionality as required.
+
+### Using Mixins
+
+To extend the functionality of your custom record and manager classes,
+append the mixins for the record class and/or record manager class
+**AFTER** the inheritance for `RecordBase` and `RecordManagerBase`.
+You also need to specify the **same** type arguments to the mixins as
+is already being done for `RecordBase` and `RecordManagerBase`.
+
+```python
+from __future__ import annotations
+
+from openstack_odooclient import (
+    NamedRecordManagerMixin,
+    NamedRecordMixin,
+    RecordBase,
+    RecordManagerBase,
+)
+
+class CustomRecord(
+    RecordBase["CustomRecordManager"],
+    NamedRecordMixin["CustomRecordManager"],
+):
+    custom_field: str
+    """Description of the field."""
+
+class CustomRecordManager(
+    RecordManagerBase[CustomRecord],
+    NamedRecordManagerMixin[CustomRecord],
+):
+    env_name = "custom.record"
+    record_class = CustomRecord
+```
+
+That's all that needs to be done. The additional attributes and/or methods
+should now be available on your record and manager objects.
+
+The following mixins are provided with the Odoo Client library.
+
+#### Named Records
+
+If your record model has a unique `name` field on it (of `str` type),
+you can use the `NamedRecordMixin` and `NamedRecordManagerMixin` mixins
+to define the `name` field on the record class, and add the
+`get_by_name` method to your custom record manager class.
+
+```python
+from __future__ import annotations
+
+from openstack_odooclient import (
+    NamedRecordManagerMixin,
+    NamedRecordMixin,
+    RecordBase,
+    RecordManagerBase,
+)
+
+class CustomRecord(
+    RecordBase["CustomRecordManager"],
+    NamedRecordMixin["CustomRecordManager"],
+):
+    custom_field: str
+    """Description of the field."""
+
+    # Added by NamedRecordMixin:
+    #
+    # name: str
+    # """The unique name of the record."""
+
+class CustomRecordManager(
+    RecordManagerBase[CustomRecord],
+    NamedRecordManagerMixin[CustomRecord],
+):
+    env_name = "custom.record"
+    record_class = CustomRecord
+
+    # Added by NamedRecordManagerMixin:
+    #
+    # def get_by_name(...):
+    #     ...
+```
+
+For more information on using record managers with unique `name` fields,
+see [Named Record Managers](index.md#named-record-managers).
+
+#### Coded Records
+
+If your record model has a unique `code` field on it (of `str` type),
+you can use the `CodedRecordMixin` and `CodedRecordManagerMixin` mixins
+to define the `code` field on the record class, and add the
+`get_by_code` method to your custom record manager class.
+
+```python
+from __future__ import annotations
+
+from openstack_odooclient import (
+    CodedRecordManagerMixin,
+    CodedRecordMixin,
+    RecordBase,
+    RecordManagerBase,
+)
+
+class CustomRecord(
+    RecordBase["CustomRecordManager"],
+    CodedRecordMixin["CustomRecordManager"],
+):
+    custom_field: str
+    """Description of the field."""
+
+    # Added by CodedRecordMixin:
+    #
+    # code: str
+    # """The unique name for this record."""
+
+class CustomRecordManager(
+    RecordManagerBase[CustomRecord],
+    CodedRecordManagerMixin[CustomRecord],
+):
+    env_name = "custom.record"
+    record_class = CustomRecord
+
+    # Added by CodedRecordManagerMixin:
+    #
+    # def get_by_code(...):
+    #     ...
+```
+
+For more information on using record managers with unique `code` fields,
+see [Coded Record Managers](index.md#coded-record-managers).
+
+### Creating Mixins
+
+It is possible to create your own custom mixins to incorporate into
+custom record and manager classes.
+
+There are two mixin types: **record mixins** and **record manager mixins**.
+
+#### Record Mixins
+
+Record mixins are used to add custom fields and methods to record classes.
+
+Here is the full implementation of `NamedRecordMixin` as an example
+of a mixin for a record class, that simply adds the `name` field:
+
+```python
+from __future__ import annotations
+
+from typing import Generic
+
+from openstack_odooclient import RM, RecordProtocol
+
+class NamedRecordMixin(RecordProtocol[RM], Generic[RM]):
+    name: str
+    """The unique name of the record."""
+```
+
+A record mixin consists of a class that subclasses `RecordProtocol[RM]`
+(where `RM` is the type variable for a record manager class) to get the type
+hints for a record class' common fields and methods. `Generic[RM]` is also
+subclassed to make the mixin itself a generic class, to allow `RM` to be
+passed when creating a record class with the mixin.
+
+Once you have the class, simply define any fields and methods you'd like
+to add.
+
+You can then use the mixin as shown in [Using Mixins](#using-mixins).
+
+When defining custom methods, in addition to accessing fields/methods
+defined within the mixin, fields/methods from the `RecordBase` class
+are also available:
+
+```python
+from __future__ import annotations
+
+from typing import Generic
+
+from openstack_odooclient import RM, RecordProtocol
+
+class NamedRecordMixin(RecordProtocol[RM], Generic[RM]):
+    name: str
+    """The unique name of the record."""
+
+    def custom_method(self) -> None:
+        self.name  # str
+        self._env.custom_method(self.id)
+```
+
+#### Record Manager Mixins
+
+Record manager mixins are expected to be mainly used to add custom methods
+to a record manager class.
+
+```python
+from __future__ import annotations
+
+from typing import Generic
+
+from openstack_odooclient import R, RecordManagerProtocol
+
+class NamedRecordManagerMixin(RecordManagerProtocol[R], Generic[R]):
+    def custom_method(self, record: int | R) -> None:
+        self._env.custom_method(  # self._env available from RecordManagerBase
+            record if isinstance(record, int) else record.id,
+        )
+```
+
+A record manager mixin consists of a class that subclasses
+`RecordManagerProtocol[R]` (where `R` is the type variable for a record class)
+to get the type hints for a record manager class' common attributes and
+methods. `Generic[R]` is also subclassed to make the mixin itself a generic
+class, to allow `R` to be passed when creating a record manager class
+with the mixin.
+
 ## Extending Existing Record Types
 
 The Odoo Client library provides *limited* support for extending the built-in record types.

docs/managers/index.md

@@ -873,9 +873,7 @@ The managers for these record types have additional methods for querying records
 * [Currencies](currency.md)
 * [OpenStack Customer Groups](customer-group.md)
 * [OpenStack Grant Types](grant-type.md)
-* [Partner Categories](partner-category.md)
 * [Pricelists](pricelist.md)
-* [Product Categories](product-category.md)
 * [OpenStack Reseller Tiers](reseller-tier.md)
 * [Sale Orders](sale-order.md)
 * [OpenStack Support Subscription Types](support-subscription-type.md)

docs/managers/partner-category.md

@@ -99,6 +99,8 @@ name: str
 
 The name of the partner category.
 
+Not guaranteed to be unique, even under the same parent category.
+
 ### `parent_id`
 
 ```python

docs/managers/product-category.md

@@ -89,7 +89,9 @@ The complete product category tree.
 name: str
 ```
 
-Name of the product category.
+The name of the product category.
+
+Not guaranteed to be unique, even under the same parent category.
 
 ### `parent_id`