oslo.versionedobjects 3.9.0__tar.gz → 3.10.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/.pre-commit-config.yaml +7 -11
  2. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/AUTHORS +1 -0
  3. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/ChangeLog +48 -0
  4. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/PKG-INFO +2 -2
  5. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/conf.py +13 -8
  6. oslo_versionedobjects-3.10.1/doc/source/reference/base.rst +6 -0
  7. oslo_versionedobjects-3.10.1/doc/source/reference/exception.rst +6 -0
  8. oslo_versionedobjects-3.10.1/doc/source/reference/fields.rst +6 -0
  9. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/reference/fixture.rst +3 -3
  10. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/user/index.rst +1 -0
  11. oslo_versionedobjects-3.10.1/doc/source/user/typing.rst +32 -0
  12. oslo_versionedobjects-3.10.1/doc/source/user/usage.rst +405 -0
  13. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/PKG-INFO +2 -2
  14. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/SOURCES.txt +8 -0
  15. oslo_versionedobjects-3.10.1/oslo.versionedobjects.egg-info/pbr.json +1 -0
  16. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/requires.txt +0 -1
  17. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/_i18n.py +0 -1
  18. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/_options.py +3 -1
  19. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/_utils.py +9 -4
  20. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/base.py +656 -278
  21. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/examples/iot_bulb.py +8 -7
  22. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/exception.py +59 -40
  23. oslo_versionedobjects-3.10.1/oslo_versionedobjects/fields.py +1666 -0
  24. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/fixture.py +288 -130
  25. oslo_versionedobjects-3.10.1/oslo_versionedobjects/mypy.py +300 -0
  26. oslo_versionedobjects-3.10.1/oslo_versionedobjects/test.py +130 -0
  27. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/tests/obj_fixtures.py +33 -19
  28. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/tests/test_exception.py +20 -10
  29. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/tests/test_fields.py +470 -303
  30. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/tests/test_fixture.py +329 -225
  31. oslo_versionedobjects-3.10.1/oslo_versionedobjects/tests/test_mypy.py +898 -0
  32. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/tests/test_objects.py +768 -531
  33. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/pyproject.toml +34 -3
  34. oslo_versionedobjects-3.10.1/releasenotes/notes/deprecate-remotable_classmethod-3c7d0f658af39fb6.yaml +18 -0
  35. oslo_versionedobjects-3.10.1/releasenotes/notes/remove-field-staticmethods-62f5a62b2544b603.yaml +6 -0
  36. oslo_versionedobjects-3.10.1/releasenotes/notes/remove-test-helpers-032475d5bc2ec8ca.yaml +11 -0
  37. oslo_versionedobjects-3.10.1/releasenotes/source/2026.1.rst +6 -0
  38. oslo_versionedobjects-3.10.1/releasenotes/source/_templates/.placeholder +0 -0
  39. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/conf.py +23 -13
  40. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/index.rst +1 -0
  41. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/requirements.txt +0 -1
  42. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/setup.py +1 -3
  43. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/test-requirements.txt +1 -0
  44. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/tox.ini +24 -8
  45. oslo_versionedobjects-3.9.0/doc/source/reference/base.rst +0 -6
  46. oslo_versionedobjects-3.9.0/doc/source/reference/exception.rst +0 -6
  47. oslo_versionedobjects-3.9.0/doc/source/reference/fields.rst +0 -6
  48. oslo_versionedobjects-3.9.0/doc/source/user/usage.rst +0 -131
  49. oslo_versionedobjects-3.9.0/oslo.versionedobjects.egg-info/pbr.json +0 -1
  50. oslo_versionedobjects-3.9.0/oslo_versionedobjects/fields.py +0 -1353
  51. oslo_versionedobjects-3.9.0/oslo_versionedobjects/test.py +0 -207
  52. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/.coveragerc +0 -0
  53. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/.mailmap +0 -0
  54. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/.stestr.conf +0 -0
  55. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/.zuul.yaml +0 -0
  56. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/CONTRIBUTING.rst +0 -0
  57. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/HACKING.rst +0 -0
  58. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/LICENSE +0 -0
  59. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/README.rst +0 -0
  60. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/bindep.txt +0 -0
  61. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/requirements.txt +0 -0
  62. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/configuration/index.rst +0 -0
  63. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/contributor/index.rst +0 -0
  64. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/index.rst +0 -0
  65. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/install/index.rst +0 -0
  66. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/reference/index.rst +0 -0
  67. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/user/examples.rst +0 -0
  68. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/doc/source/user/history.rst +0 -0
  69. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/dependency_links.txt +0 -0
  70. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/entry_points.txt +0 -0
  71. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/not-zip-safe +0 -0
  72. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo.versionedobjects.egg-info/top_level.txt +0 -0
  73. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/__init__.py +0 -0
  74. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/examples/__init__.py +0 -0
  75. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/oslo_versionedobjects/locale/en_GB/LC_MESSAGES/oslo_versionedobjects.po +0 -0
  76. /oslo_versionedobjects-3.9.0/oslo_versionedobjects/tests/__init__.py → /oslo_versionedobjects-3.10.1/oslo_versionedobjects/py.typed +0 -0
  77. /oslo_versionedobjects-3.9.0/releasenotes/source/_static/.placeholder → /oslo_versionedobjects-3.10.1/oslo_versionedobjects/tests/__init__.py +0 -0
  78. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/notes/add-reno-996dd44974d53238.yaml +0 -0
  79. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/notes/drop-python27-support-b3e377b0dcfa4f5c.yaml +0 -0
  80. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/notes/remove-py38-f4e8c7ce18a5914b.yaml +0 -0
  81. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/notes/remove-py39-a35bc15c07073b80.yaml +0 -0
  82. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/notes/update_md5_for_fips-e5a8f8f438ac81fb.yaml +0 -0
  83. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2023.1.rst +0 -0
  84. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2023.2.rst +0 -0
  85. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2024.1.rst +0 -0
  86. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2024.2.rst +0 -0
  87. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2025.1.rst +0 -0
  88. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/2025.2.rst +0 -0
  89. {oslo_versionedobjects-3.9.0/releasenotes/source/_templates → oslo_versionedobjects-3.10.1/releasenotes/source/_static}/.placeholder +0 -0
  90. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/locale/en_GB/LC_MESSAGES/releasenotes.po +0 -0
  91. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/ocata.rst +0 -0
  92. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/pike.rst +0 -0
  93. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/queens.rst +0 -0
  94. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/rocky.rst +0 -0
  95. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/stein.rst +0 -0
  96. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/train.rst +0 -0
  97. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/unreleased.rst +0 -0
  98. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/ussuri.rst +0 -0
  99. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/victoria.rst +0 -0
  100. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/wallaby.rst +0 -0
  101. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/xena.rst +0 -0
  102. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/yoga.rst +0 -0
  103. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/releasenotes/source/zed.rst +0 -0
  104. {oslo_versionedobjects-3.9.0 → oslo_versionedobjects-3.10.1}/setup.cfg +0 -0
@@ -12,18 +12,14 @@ repos:
12
12
  - id: debug-statements
13
13
  - id: check-yaml
14
14
  files: .*\.(yaml|yml)$
15
+ - repo: https://github.com/astral-sh/ruff-pre-commit
16
+ rev: v0.15.4
17
+ hooks:
18
+ - id: ruff-check
19
+ args: ['--fix', '--unsafe-fixes']
20
+ - id: ruff-format
15
21
  - repo: https://opendev.org/openstack/hacking
16
- rev: 7.0.0
22
+ rev: 8.0.0
17
23
  hooks:
18
24
  - id: hacking
19
25
  additional_dependencies: []
20
- - repo: https://github.com/PyCQA/bandit
21
- rev: 1.8.6
22
- hooks:
23
- - id: bandit
24
- args: ['-c', 'pyproject.toml']
25
- - repo: https://github.com/asottile/pyupgrade
26
- rev: v3.20.0
27
- hooks:
28
- - id: pyupgrade
29
- args: [--py310-plus]
@@ -43,6 +43,7 @@ Armando Migliaccio <armando.migliaccio@eu.citrix.com>
43
43
  Attila Fazekas <afazekas@redhat.com>
44
44
  Avishay Traeger <avishay@il.ibm.com>
45
45
  Balazs Gibizer <balazs.gibizer@ericsson.com>
46
+ Balazs Gibizer <gibi@redhat.com>
46
47
  Belmiro Moreira <moreira.belmiro.email.lists@gmail.com>
47
48
  Ben Nemec <bnemec@redhat.com>
48
49
  Ben Nemec <openstack@nemebean.com>
@@ -1,6 +1,54 @@
1
1
  CHANGES
2
2
  =======
3
3
 
4
+ 3.10.1
5
+ ------
6
+
7
+ * Accept context passed by kwarg
8
+ * typing: Resolve ObjectField and ListOfObjectsField to concrete types
9
+ * Rename args -> kwargs
10
+ * Remove unecessary try-except login in mypy plugin
11
+ * Remove some duplication in the mypy plugin
12
+
13
+ 3.10.0
14
+ ------
15
+
16
+ * Remove webob dependency
17
+ * Add strict typing
18
+ * Drop useless override of assertNotIsInstance
19
+ * typing: Add type hints to oslo\_versionedobjects.base
20
+ * typing: Add type hints to oslo\_versionedobjects.test
21
+ * typing: Add type hints to oslo\_versionedobjects.\_utils
22
+ * typing: Add type hints to oslo\_versionedobjects.\_options
23
+ * typing: Add type hints to oslo\_versionedobjects.exception
24
+ * typing: Add type hints to oslo\_versionedobjects.fixtures
25
+ * typing: Add type hints to oslo\_versionedobjects.fields
26
+ * Add initial typing
27
+ * Add support for nested types
28
+ * Add tests for mypy plugin
29
+ * Add mypy plugin
30
+ * tests: Remove dead code
31
+ * exceptions: Remove unused attribute
32
+ * Remove eventlet monkey-patch from test base class
33
+ * trivial: Split up remoteable decorator
34
+ * trivial: Disable H904 check
35
+ * base: Deprecate remotable\_classmethod
36
+ * base: Swap location of remoteable decorators
37
+ * fields: Move Coerced\* helpers
38
+ * fields: Remove unnecessary indentation
39
+ * fields: Remove use of staticmethod
40
+ * Update master for stable/2026.1
41
+ * tests: Fix tz-naive test
42
+ * tests: Replace reference to invalid field
43
+ * tests: Add usedforsecurity
44
+ * tests: Correct attribute type
45
+ * trivial: Fix logging issues
46
+ * tests: Rewrap strings
47
+ * Add ruff
48
+ * pre-commit: Bump dependencies
49
+ * docs: Expand usage guide with worked example
50
+ * docs: Rework reference, usage docs
51
+
4
52
  3.9.0
5
53
  -----
6
54
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: oslo.versionedobjects
3
- Version: 3.9.0
3
+ Version: 3.10.1
4
4
  Summary: Oslo Versioned Objects library
5
5
  Author-email: OpenStack <openstack-discuss@lists.openstack.org>
6
6
  License: Apache-2.0
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
17
17
  Classifier: Programming Language :: Python :: 3.11
18
18
  Classifier: Programming Language :: Python :: 3.12
19
19
  Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
20
21
  Requires-Python: >=3.10
21
22
  Description-Content-Type: text/x-rst
22
23
  License-File: LICENSE
@@ -28,7 +29,6 @@ Requires-Dist: oslo.serialization>=2.18.0
28
29
  Requires-Dist: oslo.utils>=7.4.0
29
30
  Requires-Dist: oslo.log>=3.36.0
30
31
  Requires-Dist: oslo.i18n>=3.15.3
31
- Requires-Dist: WebOb>=1.7.1
32
32
  Requires-Dist: netaddr>=0.7.18
33
33
  Dynamic: license-file
34
34
  Dynamic: requires-dist
@@ -46,7 +46,7 @@ master_doc = 'index'
46
46
  # General information about the project.
47
47
  project = 'oslo.versionedobjects'
48
48
  copyright = '2014, OpenStack Foundation'
49
- source_tree = 'https://opendev.org/openstack/%s' % project
49
+ source_tree = f'https://opendev.org/openstack/{project}'
50
50
 
51
51
  # If true, '()' will be appended to :func: etc. cross-reference text.
52
52
  add_function_parentheses = True
@@ -57,8 +57,10 @@ add_module_names = True
57
57
 
58
58
  # Shortened external links.
59
59
  extlinks = {
60
- 'example': (source_tree +
61
- '/%s/examples/%%s.py' % project.replace(".", "_"), None),
60
+ 'example': (
61
+ source_tree + '/{}/examples/%s.py'.format(project.replace(".", "_")),
62
+ None,
63
+ ),
62
64
  }
63
65
 
64
66
  # The name of the Pygments (syntax highlighting) style to use.
@@ -75,14 +77,17 @@ html_theme = 'openstackdocs'
75
77
 
76
78
 
77
79
  # Output file base name for HTML help builder.
78
- htmlhelp_basename = '%sdoc' % project
80
+ htmlhelp_basename = f'{project}doc'
79
81
 
80
82
  # Grouping the document tree into LaTeX files. List of tuples
81
83
  # (source start file, target name, title, author, documentclass
82
84
  # [howto/manual]).
83
85
  latex_documents = [
84
- ('index',
85
- '%s.tex' % project,
86
- '%s Documentation' % project,
87
- 'OpenStack Foundation', 'manual'),
86
+ (
87
+ 'index',
88
+ f'{project}.tex',
89
+ f'{project} Documentation',
90
+ 'OpenStack Foundation',
91
+ 'manual',
92
+ ),
88
93
  ]
@@ -0,0 +1,6 @@
1
+ ==========================
2
+ oslo_versionedobjects.base
3
+ ==========================
4
+
5
+ .. automodule:: oslo_versionedobjects.base
6
+ :members:
@@ -0,0 +1,6 @@
1
+ ===============================
2
+ oslo_versionedobjects.exception
3
+ ===============================
4
+
5
+ .. automodule:: oslo_versionedobjects.exception
6
+ :members:
@@ -0,0 +1,6 @@
1
+ ============================
2
+ oslo_versionedobjects.fields
3
+ ============================
4
+
5
+ .. automodule:: oslo_versionedobjects.fields
6
+ :members:
@@ -1,6 +1,6 @@
1
- =========
2
- Fixture
3
- =========
1
+ =============================
2
+ oslo_versionedobjects.fixture
3
+ =============================
4
4
 
5
5
  .. automodule:: oslo_versionedobjects.fixture
6
6
  :members:
@@ -7,6 +7,7 @@ Using oslo.versionedobjects
7
7
 
8
8
  usage
9
9
  examples
10
+ typing
10
11
 
11
12
  .. history contains a lot of sections, toctree with maxdepth 1 is used.
12
13
  .. toctree::
@@ -0,0 +1,32 @@
1
+ ======
2
+ Typing
3
+ ======
4
+
5
+ oslo.versionedobjects ships a mypy plugin that improves type checking of
6
+ projects that use oslo.versionedobjects.
7
+
8
+ .. note::
9
+
10
+ The plugin is a temporary solution pending a larger rework. It is only
11
+ supported when used with the mypy type checker.
12
+
13
+ Enabling the plugin
14
+ -------------------
15
+
16
+ To enable the plugin, add the following to your ``pyproject.toml``:
17
+
18
+ .. code-block:: toml
19
+
20
+ [tool.mypy]
21
+ plugins = ["oslo_versionedobjects.mypy"]
22
+
23
+ What the plugin does
24
+ --------------------
25
+
26
+ oslo.versionedobjects dynamically generates attributes on versioned object
27
+ classes from the ``fields`` dict defined in the class body. This means mypy
28
+ cannot infer the types of these attributes without additional help.
29
+
30
+ The plugin inspects the ``fields`` dict of each versioned object class and
31
+ inserts typed attribute definitions into the class, allowing mypy to type-check
32
+ code that accesses these attributes.
@@ -0,0 +1,405 @@
1
+ =======
2
+ Usage
3
+ =======
4
+
5
+ Incorporating *oslo.versionedobjects* into your project can be accomplished in
6
+ the following steps:
7
+
8
+ Initial scaffolding
9
+ -------------------
10
+
11
+ By convention, objects reside in the `<project>/objects` directory. This is the
12
+ place from which all objects should be imported.
13
+
14
+ Start the implementation by creating `objects/base.py` with a subclass of the
15
+ :class:`oslo_versionedobjects.base.VersionedObject`. This class will form the
16
+ base class for all objects in the project. You need to populate the
17
+ ``OBJ_PROJECT_NAMESPACE`` property.
18
+
19
+ .. note::
20
+
21
+ ``OBJ_SERIAL_NAMESPACE`` is used only for backward compatibility and
22
+ should not be set in new projects.
23
+
24
+ You may also wish to optionally include the following mixins:
25
+
26
+ * :class:`oslo_versionedobjects.base.VersionedPersistentObject`
27
+
28
+ A mixin class for persistent objects can be created, defining repeated
29
+ fields like ``created_at``, ``updated_at``. Fields are defined in the fields
30
+ property (which is a dict).
31
+
32
+ * :class:`oslo_versionedobjects.base.VersionedObjectDictCompat`
33
+
34
+ If objects were previously passed as dicts (a common situation), this class
35
+ can be used as a mixin class to support dict operations.
36
+
37
+ A minimal ``objects/base.py`` looks like this:
38
+
39
+ .. code:: python
40
+
41
+ from oslo_versionedobjects import base as ovo_base
42
+ from oslo_versionedobjects import fields as ovo_fields
43
+
44
+
45
+ class MyProjectObjectRegistry(ovo_base.VersionedObjectRegistry):
46
+ def registration_hook(self, cls, index):
47
+ # Make registered objects accessible as myproject.objects.Foo
48
+ from myproject import objects
49
+ setattr(objects, cls.obj_name(), cls)
50
+
51
+
52
+ class MyProjectObject(ovo_base.VersionedObject):
53
+ OBJ_PROJECT_NAMESPACE = 'myproject'
54
+
55
+
56
+ class MyProjectPersistentObject:
57
+ """Mixin for objects that are stored in the database."""
58
+ fields = {
59
+ 'created_at': ovo_fields.DateTimeField(nullable=True),
60
+ 'updated_at': ovo_fields.DateTimeField(nullable=True),
61
+ 'deleted_at': ovo_fields.DateTimeField(nullable=True),
62
+ 'deleted': ovo_fields.BooleanField(default=False),
63
+ }
64
+
65
+ Once you have your base class defined, you can define your actual object
66
+ classes. Objects classes should be created for all resources/objects passed via
67
+ RPC as IDs or dicts in order to:
68
+
69
+ * spare the database (or other resource) from extra calls
70
+ * pass objects instead of dicts, which are tagged with their version
71
+ * handle all object versions in one place (the ``obj_make_compatible`` method)
72
+
73
+ To make sure all objects are accessible at all times, you should import them in
74
+ ``__init__.py`` in the ``objects/`` directory and expose them via a
75
+ ``register_all()`` function. This function is called at service startup to
76
+ ensure objects are registered before any RPC communication takes place.
77
+
78
+ A typical ``objects/__init__.py`` looks like this:
79
+
80
+ .. code:: python
81
+
82
+ # NOTE: When objects are registered, an attribute is set on this module
83
+ # automatically, pointing to the newest/latest version of the object.
84
+ # This allows callers to use myproject.objects.Foo without importing
85
+ # the specific module.
86
+
87
+
88
+ def register_all():
89
+ # NOTE: You must make sure your object gets imported in this function
90
+ # in order for it to be registered by services that may need to receive
91
+ # it via RPC.
92
+ __import__('myproject.objects.thing')
93
+
94
+ Finally, you should create an object registry by subclassing
95
+ :class:`oslo_versionedobjects.base.VersionedObjectRegistry`. The object
96
+ registry is the place where all objects are registered. All object classes
97
+ should be registered by the
98
+ :attr:`oslo_versionedobjects.base.ObjectRegistry.register` class decorator.
99
+
100
+ Defining objects
101
+ ----------------
102
+
103
+ Each object class represents a versioned resource type. At minimum, an object
104
+ must declare its ``VERSION``, a ``fields`` dictionary, and be decorated with
105
+ the registry's ``@register`` decorator.
106
+
107
+ A concrete object with database interaction looks like this:
108
+
109
+ .. code:: python
110
+
111
+ from oslo_versionedobjects import base as ovo_base
112
+
113
+ from myproject.db import api as dbapi
114
+ from myproject.objects import base
115
+ from myproject.objects import fields as object_fields
116
+
117
+
118
+ @base.MyProjectObjectRegistry.register
119
+ class Thing(base.MyProjectObject, base.MyProjectPersistentObject,
120
+ ovo_base.VersionedObjectDictCompat):
121
+ # Version 1.0: Initial version
122
+ # Version 1.1: Added 'description' field
123
+ VERSION = '1.1'
124
+
125
+ fields = {
126
+ 'id': object_fields.IntegerField(),
127
+ 'uuid': object_fields.UUIDField(nullable=True),
128
+ 'name': object_fields.StringField(nullable=True),
129
+ 'description': object_fields.StringField(nullable=True),
130
+ 'extra': object_fields.FlexibleDictField(nullable=True),
131
+ }
132
+
133
+ @classmethod
134
+ @ovo_base.remotable
135
+ def get_by_uuid(cls, context, uuid):
136
+ db_thing = dbapi.get_thing_by_uuid(uuid)
137
+ return cls._from_db_object(context, cls(), db_thing)
138
+
139
+ @classmethod
140
+ @ovo_base.remotable
141
+ def list(cls, context, limit=None, marker=None):
142
+ db_things = dbapi.get_thing_list(limit=limit, marker=marker)
143
+ return cls._from_db_object_list(context, db_things)
144
+
145
+ @ovo_base.remotable
146
+ def create(self, context=None):
147
+ values = self.obj_get_changes()
148
+ db_thing = dbapi.create_thing(values)
149
+ self._from_db_object(self._context, self, db_thing)
150
+
151
+ @ovo_base.remotable
152
+ def save(self, context=None):
153
+ updates = self.obj_get_changes()
154
+ db_thing = dbapi.update_thing(self.uuid, updates)
155
+ self._from_db_object(self._context, self, db_thing)
156
+
157
+ @ovo_base.remotable
158
+ def destroy(self, context=None):
159
+ dbapi.destroy_thing(self.uuid)
160
+ self.obj_reset_changes()
161
+
162
+ def obj_make_compatible(self, primitive, target_version):
163
+ super().obj_make_compatible(primitive, target_version)
164
+ target_version = versionutils.convert_version_to_tuple(target_version)
165
+ if target_version < (1, 1) and 'description' in primitive:
166
+ del primitive['description']
167
+
168
+ The ``_from_db_object`` static method is responsible for mapping a database row
169
+ to the object's fields and resetting the change-tracking state:
170
+
171
+ .. code:: python
172
+
173
+ @staticmethod
174
+ def _from_db_object(context, obj, db_object, fields=None):
175
+ fields = fields or obj.fields
176
+ for field in fields:
177
+ setattr(obj, field, db_object[field])
178
+ obj._context = context
179
+ obj.obj_reset_changes()
180
+ return obj
181
+
182
+ The ``obj_make_compatible`` method is the key mechanism for rolling upgrades:
183
+ it is called when an object needs to be sent to a service running an older
184
+ version of the code. It must strip or transform any fields that did not exist
185
+ in the target version.
186
+
187
+ List objects
188
+ ~~~~~~~~~~~~
189
+
190
+ Resources that can be retrieved as a collection should have a corresponding
191
+ list object. A list object uses
192
+ :class:`oslo_versionedobjects.base.ObjectListBase` and its ``fields``
193
+ dictionary contains a single entry, ``objects``, which is a
194
+ :class:`oslo_versionedobjects.fields.ListOfObjectsField`:
195
+
196
+ .. code:: python
197
+
198
+ @base.MyProjectObjectRegistry.register
199
+ class ThingList(base.ObjectListBase, base.MyProjectObject):
200
+ # Version 1.0: Initial version
201
+ # Thing <= version 1.1
202
+ VERSION = '1.0'
203
+
204
+ fields = {
205
+ 'objects': object_fields.ListOfObjectsField('Thing'),
206
+ }
207
+
208
+ @classmethod
209
+ @ovo_base.remotable
210
+ def get_all(cls, context):
211
+ db_things = dbapi.get_thing_list()
212
+ return ovo_base.obj_make_list(context, cls(context),
213
+ Thing, db_things)
214
+
215
+ The list object's version should be bumped whenever the version of the
216
+ contained object type is bumped.
217
+
218
+ Using custom field types
219
+ ------------------------
220
+
221
+ New field types can be implemented by inheriting from
222
+ :class:`oslo_versionedobjects.field.Field` and overwriting the `from_primitive`
223
+ and `to_primitive` methods.
224
+
225
+ By subclassing :class:`oslo_versionedobjects.fields.AutoTypedField` you can
226
+ stack multiple fields together, making sure even nested data structures are
227
+ being validated.
228
+
229
+ A common pattern is a ``FlexibleDictField`` that accepts both strings and dicts
230
+ (useful for data stored as JSON blobs in the database):
231
+
232
+ .. code:: python
233
+
234
+ import ast
235
+ from oslo_versionedobjects import fields as ovo_fields
236
+
237
+
238
+ class FlexibleDict(ovo_fields.FieldType):
239
+ def coerce(self, obj, attr, value):
240
+ if isinstance(value, str):
241
+ value = ast.literal_eval(value)
242
+ return dict(value)
243
+
244
+
245
+ class FlexibleDictField(ovo_fields.AutoTypedField):
246
+ AUTO_TYPE = FlexibleDict()
247
+
248
+ For enumerated types, inherit from :class:`oslo_versionedobjects.fields.Enum`
249
+ and then wrap it in a :class:`oslo_versionedobjects.fields.BaseEnumField`:
250
+
251
+ .. code:: python
252
+
253
+ from oslo_versionedobjects import fields as ovo_fields
254
+
255
+
256
+ class ThingState(ovo_fields.Enum):
257
+ ACTIVE = 'active'
258
+ PENDING = 'pending'
259
+ ERROR = 'error'
260
+
261
+ ALL = (ACTIVE, PENDING, ERROR)
262
+
263
+ def __init__(self):
264
+ super().__init__(valid_values=ThingState.ALL)
265
+
266
+
267
+ class ThingStateField(ovo_fields.BaseEnumField):
268
+ AUTO_TYPE = ThingState()
269
+
270
+ Custom fields should be defined in a ``fields.py`` module within the
271
+ ``objects/`` package, and re-exported from there. Projects typically also
272
+ re-export the standard oslo.versionedobjects field types from this module to
273
+ provide a single import point for all field types:
274
+
275
+ .. code:: python
276
+
277
+ # objects/fields.py
278
+ from oslo_versionedobjects import fields as ovo_fields
279
+
280
+ # Re-export standard field types
281
+ IntegerField = ovo_fields.IntegerField
282
+ UUIDField = ovo_fields.UUIDField
283
+ StringField = ovo_fields.StringField
284
+ BooleanField = ovo_fields.BooleanField
285
+ DateTimeField = ovo_fields.DateTimeField
286
+ ListOfStringsField = ovo_fields.ListOfStringsField
287
+ ObjectField = ovo_fields.ObjectField
288
+ ListOfObjectsField = ovo_fields.ListOfObjectsField
289
+
290
+ # Project-specific field types
291
+ class FlexibleDictField(ovo_fields.AutoTypedField):
292
+ ...
293
+
294
+ Configure serialization
295
+ -----------------------
296
+
297
+ To transfer objects by RPC, subclass the
298
+ :class:`oslo_versionedobjects.base.VersionedObjectSerializer` setting the
299
+ OBJ_BASE_CLASS property to the previously defined Object class.
300
+
301
+ .. code:: python
302
+
303
+ # objects/base.py (add to existing file)
304
+ from oslo_versionedobjects import base as ovo_base
305
+
306
+
307
+ class MyProjectObjectSerializer(ovo_base.VersionedObjectSerializer):
308
+ OBJ_BASE_CLASS = MyProjectObject
309
+
310
+ The serializer is then passed to oslo.messaging when creating RPC servers and
311
+ clients. For example, to use a custom serializer with `oslo_messaging`__:
312
+
313
+ .. code:: python
314
+
315
+ # common/rpc_service.py
316
+ import oslo_messaging as messaging
317
+ from myproject.objects import base as objects_base
318
+
319
+
320
+ class RPCService:
321
+ def start(self):
322
+ serializer = objects_base.MyProjectObjectSerializer()
323
+ target = messaging.Target(topic=self.topic, server=self.host)
324
+ endpoints = [self.manager]
325
+ self.rpcserver = messaging.get_rpc_server(
326
+ transport, target, endpoints, serializer=serializer)
327
+ self.rpcserver.start()
328
+
329
+ .. __: https://docs.openstack.org/oslo.messaging/latest/
330
+
331
+ Implement the indirection API
332
+ -----------------------------
333
+
334
+ *oslo.versionedobjects* supports "remotable" method calls. These are calls of
335
+ the object methods and classmethods which can be executed locally or remotely
336
+ depending on the configuration. Setting the ``indirection_api`` as a property
337
+ of an object relays the calls to decorated methods through the defined RPC API.
338
+ The attachment of the ``indirection_api`` should be handled by configuration at
339
+ startup time.
340
+
341
+ The second function of the indirection API is backporting. When the object
342
+ serializer attempts to deserialize an object with a future version not
343
+ supported by the current instance, it calls the ``object_backport`` method in
344
+ an attempt to backport the object to a version which can then be handled as
345
+ normal.
346
+
347
+ The :class:`oslo_versionedobjects.base.VersionedObjectIndirectionAPI` class
348
+ provides a base class for implementing your own indirection API.
349
+
350
+ A typical implementation delegates to the conductor service's RPC API, so that
351
+ object methods decorated with ``@remotable`` are executed on the conductor:
352
+
353
+ .. code:: python
354
+
355
+ # objects/indirection.py
356
+ from oslo_versionedobjects import base as ovo_base
357
+
358
+ from myproject.conductor import rpcapi as conductor_api
359
+
360
+
361
+ class MyProjectObjectIndirectionAPI(ovo_base.VersionedObjectIndirectionAPI):
362
+ def __init__(self):
363
+ super().__init__()
364
+ self._conductor = conductor_api.ConductorAPI()
365
+
366
+ def object_action(self, context, objinst, objmethod, args, kwargs):
367
+ return self._conductor.object_action(
368
+ context, objinst, objmethod, args, kwargs)
369
+
370
+ def object_class_action_versions(self, context, objname, objmethod,
371
+ object_versions, args, kwargs):
372
+ return self._conductor.object_class_action_versions(
373
+ context, objname, objmethod, object_versions, args, kwargs)
374
+
375
+ def object_backport_versions(self, context, objinst, object_versions):
376
+ return self._conductor.object_backport_versions(
377
+ context, objinst, object_versions)
378
+
379
+ The indirection API is then attached to the base object class at service
380
+ startup. Services that act as clients (e.g. the API tier) attach the
381
+ indirection API so that ``@remotable`` calls are forwarded to the conductor.
382
+ Services that act as servers (e.g. the conductor itself) leave it unset or set
383
+ it to ``None`` so that ``@remotable`` calls are executed locally:
384
+
385
+ .. code:: python
386
+
387
+ # command/api.py (API service entry point)
388
+ from myproject.objects import base as objects_base
389
+ from myproject.objects import indirection
390
+
391
+
392
+ def main():
393
+ # Attach the indirection API so that remotable object methods
394
+ # are executed on the conductor via RPC.
395
+ objects_base.MyProjectObject.indirection_api = (
396
+ indirection.MyProjectObjectIndirectionAPI()
397
+ )
398
+ # ... start the WSGI server
399
+
400
+
401
+ # command/conductor.py (conductor service entry point)
402
+ def main():
403
+ # The conductor executes remotable methods locally; no indirection API.
404
+ # objects_base.MyProjectObject.indirection_api = None (default)
405
+ # ... start the RPC server
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: oslo.versionedobjects
3
- Version: 3.9.0
3
+ Version: 3.10.1
4
4
  Summary: Oslo Versioned Objects library
5
5
  Author-email: OpenStack <openstack-discuss@lists.openstack.org>
6
6
  License: Apache-2.0
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
17
17
  Classifier: Programming Language :: Python :: 3.11
18
18
  Classifier: Programming Language :: Python :: 3.12
19
19
  Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
20
21
  Requires-Python: >=3.10
21
22
  Description-Content-Type: text/x-rst
22
23
  License-File: LICENSE
@@ -28,7 +29,6 @@ Requires-Dist: oslo.serialization>=2.18.0
28
29
  Requires-Dist: oslo.utils>=7.4.0
29
30
  Requires-Dist: oslo.log>=3.36.0
30
31
  Requires-Dist: oslo.i18n>=3.15.3
31
- Requires-Dist: WebOb>=1.7.1
32
32
  Requires-Dist: netaddr>=0.7.18
33
33
  Dynamic: license-file
34
34
  Dynamic: requires-dist