=================
Spec Driven Model
=================
..
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! This file is generated by oca-gen-addon-readme !!
!! changes will be overwritten. !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! source digest: sha256:679e4226015ad6864c3f8b368aa8da5362f402ee5c3be629b6b829944f304546
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
:target: https://odoo-community.org/page/development-status
:alt: Beta
.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
:target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
:alt: License: LGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--brazil-lightgray.png?logo=github
:target: https://github.com/OCA/l10n-brazil/tree/16.0/spec_driven_model
:alt: OCA/l10n-brazil
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
:target: https://translation.odoo-community.org/projects/l10n-brazil-16-0/l10n-brazil-16-0-spec_driven_model
:alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
:target: https://runboat.odoo-community.org/builds?repo=OCA/l10n-brazil&target_branch=16.0
:alt: Try me on Runboat
|badge1| |badge2| |badge3| |badge4| |badge5|
Intro
-----
This module is a databinding framework for Odoo and XML data: it allows
to go from XML to Odoo objects back and forth. While having no hard
dependency with it, it has been designed to be used along with xsdata.
So a good starting point is to read `the xsdata documentation
here <https://xsdata.readthedocs.io/>`__.
But what if instead of only generating Python structures from XML files
you could actually generate full blown Odoo objects or serialize Odoo
objects back to XML? This is what this module is for!
First you should generate xsdata Python binding libraries you would
generate for your specific XSD grammar, the Brazilian Electronic
Invoicing for instance, or UBL or any XSD files...
Second you should generate Odoo abstract mixins for all these pure
Python bindings. This can be achieved using
`xsdata-odoo <https://github.com/akretion/xsdata-odoo>`__. An example is
OCA/l10n-brazil/l10n_br_nfe_spec for the Brazilian Electronic Invoicing.
SpecModel
---------
Now that you have generated these Odoo abstract bindings you should tell
Odoo how to use them. For instance you may want that your abstract model
for the recipient of the electronic invoice matches the Odoo
``res.partner`` object. This is fairly easy, you mostly need to define
an override like:
.. code:: python
from odoo.addons.spec_driven_model.models import spec_models
class ResPartner(spec_models.SpecModel):
_inherit = [
'res.partner',
'partner.binding.mixin',
]
Notice you should inherit from spec_models.SpecModel and not the usual
models.Model.
**Field mapping**: You can then define two ways mapping between fields
by overriding fields from Odoo or from the binding using \_compute= ,
\_inverse= or simply related=.
**Relational fields**: simple fields are easily mapped this way. However
what about relational fields? In your XSD schema, your electronic
invoice is related to the partner.binding.mixin not to an Odoo
res.partner. Don't worry, when SpecModel classes are instanciated for
all relational fields, we look if their comodel have been injected into
some existing Odoo model and if so we remap them to the proper Odoo
model.
**Field prefixes**: to avoid field collision between the Odoo fields and
the XSD fields, the XSD fields are prefixed with the name of the schema
and a few digits representing the schema version (typically 2 digits).
So if your schema get a minor version upgrade, the same fields and
classes are used. For a major upgrade however new fields and classes may
be used so data of several major versions could co-exist inside your
Odoo database.
StackedModel
------------
Sadly real life XML is a bit more complex than that. Often XML
structures are deeply nested just because it makes it easier for XSD
schemas to validate them! for instance an electronic invoice line can be
a nested structure with lots of tax details and product details. In a
relational model like Odoo however you often want flatter data
structures instead. This is where StackedModel comes to the rescue! It
inherits from SpecModel and when you inherit from StackedModel you can
inherit from all the generated mixins corresponding to the nested XML
tags below some tag (here invoice.line.binding.mixin). All the fields
corresponding to these XML tag attributes will be collected in your
model and the XML parsing and serialization will happen as expected.
Here is an example inspired from the Brazilian Electronic Invoice where
the schema is called ``nfe`` and where we use the 2 digits ``40`` for
its short version:
.. code:: python
from odoo.addons.spec_driven_model.models import spec_models
class InvoiceLine(spec_models.StackedModel):
_inherit = [
'account.move.line',
'nfe.40.det',
]
_nfe40_spec_settings = {
"module": "odoo.addons.l10n_br_nfe_spec.models.v4_0.leiaute_nfe_v4_00",
"stacking_mixin": "nfe.40.det",
"stacking_points": {},
# all m2o below this level will be stacked even if not required:
"stacking_force_paths": ("det.imposto.",),
"stacking_skip_paths": ("nfe40_det_infNFe_id",),
}
All many2one fields that are required in the XSD (xsd_required=True)
will get their model stacked automatically and recursively. You can also
force non required many2one fields to be stacked using the
``stacking_force_paths`` attribute. On the contrary, you can avoid some
required many2one fields to be stacked using the ``stacking_skip_paths``
attribute.
Initialization hook
-------------------
Because XSD schemas can define lot's of different models,
spec_driven_model comes with a handy ``_register_hook`` override (in
``spec.mixin``) that will automatically make all XSD mixins turn into
concrete Odoo model (eg with a table) if you didn't inject them into
existing Odoo models already.
**Table of contents**
.. contents::
:local:
Installation
============
Configuration
=============
Usage
=====
See my detailed OCA Days explanations here:
https://www.youtube.com/watch?v=6gFOe7Wh8uA
You are also encouraged to look at the tests directory which features a
full blown example from the famous PurchaseOrder.xsd from Microsoft
tutorials.
Known issues / Roadmap
======================
Migrate from generateDS to xsdata; see the xsdata Pull Requests in the
repo.
Changelog
=========
Bug Tracker
===========
Bugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-brazil/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/l10n-brazil/issues/new?body=module:%20spec_driven_model%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
Do not contact contributors directly about support or help with technical issues.
Credits
=======
Authors
-------
* Akretion
Contributors
------------
- `AKRETION <https://akretion.com/pt-BR/>`__:
- Raphaël Valyi <raphael.valyi@akretion.com.br>
- `KMEE <https://kmee.com.br>`__:
- Gabriel Cardoso de Faria <gabriel.cardoso@kmee.com.br>
Maintainers
-----------
This module is maintained by the OCA.
.. image:: https://odoo-community.org/logo.png
:alt: Odoo Community Association
:target: https://odoo-community.org
OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.
.. |maintainer-rvalyi| image:: https://github.com/rvalyi.png?size=40px
:target: https://github.com/rvalyi
:alt: rvalyi
Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
|maintainer-rvalyi|
This module is part of the `OCA/l10n-brazil <https://github.com/OCA/l10n-brazil/tree/16.0/spec_driven_model>`_ project on GitHub.
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
Raw data
{
"_id": null,
"home_page": "https://github.com/OCA/l10n-brazil",
"name": "odoo-addon-spec-driven-model",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Akretion, Odoo Community Association (OCA)",
"author_email": "support@odoo-community.org",
"download_url": null,
"platform": null,
"description": "=================\nSpec Driven Model\n=================\n\n.. \n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n !! This file is generated by oca-gen-addon-readme !!\n !! changes will be overwritten. !!\n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n !! source digest: sha256:679e4226015ad6864c3f8b368aa8da5362f402ee5c3be629b6b829944f304546\n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n\n.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png\n :target: https://odoo-community.org/page/development-status\n :alt: Beta\n.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png\n :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html\n :alt: License: LGPL-3\n.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--brazil-lightgray.png?logo=github\n :target: https://github.com/OCA/l10n-brazil/tree/16.0/spec_driven_model\n :alt: OCA/l10n-brazil\n.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png\n :target: https://translation.odoo-community.org/projects/l10n-brazil-16-0/l10n-brazil-16-0-spec_driven_model\n :alt: Translate me on Weblate\n.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png\n :target: https://runboat.odoo-community.org/builds?repo=OCA/l10n-brazil&target_branch=16.0\n :alt: Try me on Runboat\n\n|badge1| |badge2| |badge3| |badge4| |badge5|\n\nIntro\n-----\n\nThis module is a databinding framework for Odoo and XML data: it allows\nto go from XML to Odoo objects back and forth. While having no hard\ndependency with it, it has been designed to be used along with xsdata.\nSo a good starting point is to read `the xsdata documentation\nhere <https://xsdata.readthedocs.io/>`__.\n\nBut what if instead of only generating Python structures from XML files\nyou could actually generate full blown Odoo objects or serialize Odoo\nobjects back to XML? This is what this module is for!\n\nFirst you should generate xsdata Python binding libraries you would\ngenerate for your specific XSD grammar, the Brazilian Electronic\nInvoicing for instance, or UBL or any XSD files...\n\nSecond you should generate Odoo abstract mixins for all these pure\nPython bindings. This can be achieved using\n`xsdata-odoo <https://github.com/akretion/xsdata-odoo>`__. An example is\nOCA/l10n-brazil/l10n_br_nfe_spec for the Brazilian Electronic Invoicing.\n\nSpecModel\n---------\n\nNow that you have generated these Odoo abstract bindings you should tell\nOdoo how to use them. For instance you may want that your abstract model\nfor the recipient of the electronic invoice matches the Odoo\n``res.partner`` object. This is fairly easy, you mostly need to define\nan override like:\n\n.. code:: python\n\n from odoo.addons.spec_driven_model.models import spec_models\n\n\n class ResPartner(spec_models.SpecModel):\n _inherit = [\n 'res.partner',\n 'partner.binding.mixin',\n ]\n\nNotice you should inherit from spec_models.SpecModel and not the usual\nmodels.Model.\n\n**Field mapping**: You can then define two ways mapping between fields\nby overriding fields from Odoo or from the binding using \\_compute= ,\n\\_inverse= or simply related=.\n\n**Relational fields**: simple fields are easily mapped this way. However\nwhat about relational fields? In your XSD schema, your electronic\ninvoice is related to the partner.binding.mixin not to an Odoo\nres.partner. Don't worry, when SpecModel classes are instanciated for\nall relational fields, we look if their comodel have been injected into\nsome existing Odoo model and if so we remap them to the proper Odoo\nmodel.\n\n**Field prefixes**: to avoid field collision between the Odoo fields and\nthe XSD fields, the XSD fields are prefixed with the name of the schema\nand a few digits representing the schema version (typically 2 digits).\nSo if your schema get a minor version upgrade, the same fields and\nclasses are used. For a major upgrade however new fields and classes may\nbe used so data of several major versions could co-exist inside your\nOdoo database.\n\nStackedModel\n------------\n\nSadly real life XML is a bit more complex than that. Often XML\nstructures are deeply nested just because it makes it easier for XSD\nschemas to validate them! for instance an electronic invoice line can be\na nested structure with lots of tax details and product details. In a\nrelational model like Odoo however you often want flatter data\nstructures instead. This is where StackedModel comes to the rescue! It\ninherits from SpecModel and when you inherit from StackedModel you can\ninherit from all the generated mixins corresponding to the nested XML\ntags below some tag (here invoice.line.binding.mixin). All the fields\ncorresponding to these XML tag attributes will be collected in your\nmodel and the XML parsing and serialization will happen as expected.\nHere is an example inspired from the Brazilian Electronic Invoice where\nthe schema is called ``nfe`` and where we use the 2 digits ``40`` for\nits short version:\n\n.. code:: python\n\n from odoo.addons.spec_driven_model.models import spec_models\n\n\n class InvoiceLine(spec_models.StackedModel):\n _inherit = [\n 'account.move.line',\n 'nfe.40.det',\n ]\n _nfe40_spec_settings = {\n \"module\": \"odoo.addons.l10n_br_nfe_spec.models.v4_0.leiaute_nfe_v4_00\",\n \"stacking_mixin\": \"nfe.40.det\",\n \"stacking_points\": {},\n # all m2o below this level will be stacked even if not required:\n \"stacking_force_paths\": (\"det.imposto.\",),\n \"stacking_skip_paths\": (\"nfe40_det_infNFe_id\",),\n }\n\nAll many2one fields that are required in the XSD (xsd_required=True)\nwill get their model stacked automatically and recursively. You can also\nforce non required many2one fields to be stacked using the\n``stacking_force_paths`` attribute. On the contrary, you can avoid some\nrequired many2one fields to be stacked using the ``stacking_skip_paths``\nattribute.\n\nInitialization hook\n-------------------\n\nBecause XSD schemas can define lot's of different models,\nspec_driven_model comes with a handy ``_register_hook`` override (in\n``spec.mixin``) that will automatically make all XSD mixins turn into\nconcrete Odoo model (eg with a table) if you didn't inject them into\nexisting Odoo models already.\n\n**Table of contents**\n\n.. contents::\n :local:\n\nInstallation\n============\n\n\n\nConfiguration\n=============\n\n\n\nUsage\n=====\n\nSee my detailed OCA Days explanations here:\nhttps://www.youtube.com/watch?v=6gFOe7Wh8uA\n\nYou are also encouraged to look at the tests directory which features a\nfull blown example from the famous PurchaseOrder.xsd from Microsoft\ntutorials.\n\nKnown issues / Roadmap\n======================\n\nMigrate from generateDS to xsdata; see the xsdata Pull Requests in the\nrepo.\n\nChangelog\n=========\n\n\n\nBug Tracker\n===========\n\nBugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-brazil/issues>`_.\nIn case of trouble, please check there if your issue has already been reported.\nIf you spotted it first, help us to smash it by providing a detailed and welcomed\n`feedback <https://github.com/OCA/l10n-brazil/issues/new?body=module:%20spec_driven_model%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.\n\nDo not contact contributors directly about support or help with technical issues.\n\nCredits\n=======\n\nAuthors\n-------\n\n* Akretion\n\nContributors\n------------\n\n- `AKRETION <https://akretion.com/pt-BR/>`__:\n\n - Rapha\u00ebl Valyi <raphael.valyi@akretion.com.br>\n\n- `KMEE <https://kmee.com.br>`__:\n\n - Gabriel Cardoso de Faria <gabriel.cardoso@kmee.com.br>\n\nMaintainers\n-----------\n\nThis module is maintained by the OCA.\n\n.. image:: https://odoo-community.org/logo.png\n :alt: Odoo Community Association\n :target: https://odoo-community.org\n\nOCA, or the Odoo Community Association, is a nonprofit organization whose\nmission is to support the collaborative development of Odoo features and\npromote its widespread use.\n\n.. |maintainer-rvalyi| image:: https://github.com/rvalyi.png?size=40px\n :target: https://github.com/rvalyi\n :alt: rvalyi\n\nCurrent `maintainer <https://odoo-community.org/page/maintainer-role>`__:\n\n|maintainer-rvalyi| \n\nThis module is part of the `OCA/l10n-brazil <https://github.com/OCA/l10n-brazil/tree/16.0/spec_driven_model>`_ project on GitHub.\n\nYou are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.\n",
"bugtrack_url": null,
"license": "LGPL-3",
"summary": "XML binding for Odoo: XML to Odoo models and models to XML.",
"version": "16.0.2.0.0",
"project_urls": {
"Homepage": "https://github.com/OCA/l10n-brazil"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c18d6b5e15c1763adf5a214cbc266324a7220c331b9d5059e41cb2de23cebdd9",
"md5": "2d5ec8d4a6f213cda07518edbd6819b4",
"sha256": "58890bda956c5839426aba364494f85f55d70ee654ed2bd872916b4e62a561ab"
},
"downloads": -1,
"filename": "odoo_addon_spec_driven_model-16.0.2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d5ec8d4a6f213cda07518edbd6819b4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 58657,
"upload_time": "2025-01-15T06:09:26",
"upload_time_iso_8601": "2025-01-15T06:09:26.080535Z",
"url": "https://files.pythonhosted.org/packages/c1/8d/6b5e15c1763adf5a214cbc266324a7220c331b9d5059e41cb2de23cebdd9/odoo_addon_spec_driven_model-16.0.2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 06:09:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OCA",
"github_project": "l10n-brazil",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "brazilcep",
"specs": []
},
{
"name": "brazilfiscalreport",
"specs": []
},
{
"name": "email-validator",
"specs": []
},
{
"name": "erpbrasil.assinatura",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "erpbrasil.base",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "erpbrasil.edoc.pdf",
"specs": []
},
{
"name": "erpbrasil.edoc",
"specs": [
[
">=",
"2.5.2"
]
]
},
{
"name": "erpbrasil.transmissao",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "nfelib",
"specs": [
[
"<=",
"2.0.7"
]
]
},
{
"name": "nfselib.barueri",
"specs": []
},
{
"name": "nfselib.ginfes",
"specs": []
},
{
"name": "nfselib.paulistana",
"specs": []
},
{
"name": "num2words",
"specs": []
},
{
"name": "phonenumbers",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "satcomum",
"specs": []
},
{
"name": "unidecode",
"specs": []
},
{
"name": "workalendar",
"specs": []
}
],
"lcname": "odoo-addon-spec-driven-model"
}
JSON
