From 34ec3536b2d1cab61222d2f2993e74988728a027 Mon Sep 17 00:00:00 2001 From: Manjeet Singh Bhatia Date: Fri, 5 Aug 2016 00:24:26 +0000 Subject: [PATCH] Add devref for Relocating DB models This patch will add devref for relocating db models and it also explains why that change is required. It will also add a directory named models under tree neutron/db/. Change-Id: I160cecb76fb736307e5937122c84cdc0546207b6 Related-Bug: #1597913 --- doc/source/devref/db_models.rst | 49 +++++++++++++++++++++++++++++++++ neutron/db/models/README | 4 +++ neutron/db/models/__init__.py | 0 3 files changed, 53 insertions(+) create mode 100644 doc/source/devref/db_models.rst create mode 100644 neutron/db/models/README create mode 100644 neutron/db/models/__init__.py diff --git a/doc/source/devref/db_models.rst b/doc/source/devref/db_models.rst new file mode 100644 index 00000000000..e48d35de534 --- /dev/null +++ b/doc/source/devref/db_models.rst @@ -0,0 +1,49 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + +Relocation of Database Models +============================= + +This document is intended to track and notify developers that db models in +neutron will be centralized and moved to a new tree under neutron/db/models. +This was discussed in [1]. The reason for relocating db models is to solve +the cyclic import issue while implementing oslo versioned objects for +resources in neutron. + +The reason behind this relocation is Mixin class and db models for some +resources in neutron are in same module. In Mixin classes, there are methods +which provide functionality of fetching, adding, updating and deleting data +via queries. These queries will be replaced with use of versioned objects and +definition of versioned object will be using db models. So object files will +be importing models and Mixin need to import those objects which will end up +in cyclic import. + +Structure of Model Definitions +------------------------------ + +We have decided to move all models definitions to neutron/db/models/ +with no futher nesting after that point. The deprecation method to move +models is already been added to avoid breakage of third party plugins using +those models. All relocated models need to use deprecate method that +will generate a warning and return new class for use of old class. Some +examples of relocated models [2] and [3]. In future if you define new models +please make sure they are separated from mixins and are under tree +neutron/db/models/ . + +References +~~~~~~~~~~ + +[1]. https://www.mail-archive.com/openstack-dev@lists.openstack.org/msg88910.html +[2]. https://review.openstack.org/#/c/348562/ +[3]. https://review.openstack.org/#/c/348757/ diff --git a/neutron/db/models/README b/neutron/db/models/README new file mode 100644 index 00000000000..639d8fc69dc --- /dev/null +++ b/neutron/db/models/README @@ -0,0 +1,4 @@ +This directory is designed to contain all SQLAlchemy models shipped with core +Neutron. The expected directory structure is flat, meaning there should be no +subdirectories. Module names should use singular forms for nouns (port.py, not +ports.py). diff --git a/neutron/db/models/__init__.py b/neutron/db/models/__init__.py new file mode 100644 index 00000000000..e69de29bb2d