.pre-commit-config.yaml

@@ -1,10 +1,7 @@
 ---
-default_language_version:
-  # force all unspecified python hooks to run python3
-  python: python3
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: trailing-whitespace
       - id: mixed-line-ending
@@ -18,45 +15,36 @@ repos:
         files: .*\.(yaml|yml)$
         exclude: '^zuul.d/.*$'
   - repo: https://github.com/PyCQA/doc8
-    rev: v1.1.1
+    rev: v1.1.2
     hooks:
       - id: doc8
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.2
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
     hooks:
-      - id: pyupgrade
-        args: ['--py38-plus']
-  - repo: https://github.com/psf/black
-    rev: 24.4.0
-    hooks:
-      - id: black
-        args: ['-S', '-l', '79']
+      - id: ruff
+        args: ['--fix', '--unsafe-fixes']
+      - id: ruff-format
   - repo: https://opendev.org/openstack/hacking
-    rev: 6.1.0
+    rev: 7.0.0
     hooks:
       - id: hacking
         additional_dependencies:
           - flake8-import-order~=0.18.2
         exclude: '^(doc|releasenotes|tools)/.*$'
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.15.0
     hooks:
       - id: mypy
         additional_dependencies:
+          - keystoneauth1>=5.10.0
           - types-decorator
           - types-PyYAML
           - types-requests
           - types-simplejson
         # keep this in-sync with '[mypy] exclude' in 'setup.cfg'
         exclude: |
           (?x)(
-            openstack/tests/ansible/.*
-            | openstack/tests/functional/.*
-            | openstack/tests/unit/.*
-            | openstack/tests/fixtures.py
-            | openstack/cloud/.*
-            | openstack/fixture/.*
-            | doc/.*
+            doc/.*
             | examples/.*
             | releasenotes/.*
           )

doc/source/conf.py

@@ -13,7 +13,6 @@
 
 import os
 import sys
-import warnings
 
 sys.path.insert(0, os.path.abspath('../..'))
 sys.path.insert(0, os.path.abspath('.'))

doc/source/user/config/configuration.rst

@@ -139,6 +139,21 @@ as a result of a chosen plugin need to go into the auth dict. For password
 auth, this includes `auth_url`, `username` and `password` as well as anything
 related to domains, projects and trusts.
 
+API Settings
+------------
+
+The following settings are passed to keystoneauth and are common to
+all services.
+
+``api_timeout``
+    A timeout for API requests. This should be a numerical value
+    indicating some amount (or fraction) of seconds or 0 for no
+    timeout. (optional, defaults to 0)
+
+``collect_timing``
+    Whether or not to collect per-method timing information for each
+    API call. (optional, defaults to False)
+
 Splitting Secrets
 -----------------
 
@@ -497,3 +512,127 @@ In the above example, the ``project_id`` configuration values will be ignored
 in favor of the ``project_name`` configuration values, and the higher-level
 project will be chosen over the auth-specified project. So the actual project
 used will be ```myfavoriteproject```.
+
+
+Examples
+--------
+
+``auth``
+~~~~~~~~
+
+.. rubric:: Password-based authentication (project-scoped)
+
+.. code-block:: yaml
+
+    example:
+        auth:
+            auth_url: http://example.com/identity
+            password: password
+            project_domain_id: default
+            project_name: admin
+            user_domain_id: default
+            username: admin
+        region_name: RegionOne
+
+.. rubric:: Password-based authentication (domain-scoped)
+
+.. code-block:: yaml
+
+    example:
+        auth:
+            auth_url: http://example.com/identity
+            domain_id: default
+            password: password
+            username: admin
+        region_name: RegionOne
+
+.. rubric:: Password-based authentication (trust-scoped)
+
+.. code-block:: yaml
+
+    example-trust:
+        auth:
+            auth_url: http://example.com/identity
+            password: password
+            username: admin
+            trust_id: 95946f9eef864fdc993079d8fe3e5747
+        region_name: RegionOne
+
+.. rubric:: Password-based authentication (system-scoped)
+
+.. code-block:: yaml
+
+    example-system:
+        auth:
+            auth_url: http://example.com/identity
+            password: password
+            system_scope: all
+            username: admin
+        region_name: RegionOne
+
+.. rubric:: Application credential-based authentication
+
+.. code-block:: yaml
+
+    example-appcred:
+        auth:
+            auth_url: http://example.com/identity
+            application_credential_id: 9da0a8da3d394d09bf49dfc27014d254
+            application_credential_secret: pKfDSvUOFwO2t2_XxCajAFhzCKAVHI7yfqPb6xjshVDnMUHF7ifju8gMdhHTI4Eo56UP_hEc8ssmgA1NNtKMpA
+        auth_type: v3applicationcredential
+        region_name: RegionOne
+
+.. rubric:: Token-based authentication
+
+.. code-block:: yaml
+
+    example-token:
+        auth:
+            auth_url: http://example.com/identity
+            token: gAAAAABl32ptw2PN6L9JyBeO16PwQU1SrdMUvUz8Eon7LC2PFItdGRWFpOkK0qwH3JkukTuEM5qbYK9ucowRXET1RBMjZlfVpUa8Nz3qjQdzXw7pBKH4w1e4tekvDCOKfn15ZoujBOvdGqgtpW-febVGaW9oJzf6R3WTMDxWz3YRJjmiOBpwcN8
+            project_id: 1fd93a4455c74d2ea94b929fc5f0e488
+        auth_type: v3token
+        region_name: RegionOne
+
+.. note::
+
+    This is a toy example: by their very definition tokens are short-lived.
+    You are unlikely to store them in a ``clouds.yaml`` file.
+    Instead, you would likely pass the TOTP token via the command line
+    (``--os-token``) or as an environment variable (``OS_TOKEN``).
+
+.. rubric:: TOTP-based authentication
+
+.. code-block:: yaml
+
+    example-totp:
+        auth:
+            auth_url: http://example.com/identity
+            passcode: password
+            project_domain_id: default
+            project_name: admin
+            user_domain_id: default
+            username: admin
+        auth_type: v3totp
+        region_name: RegionOne
+
+.. note::
+
+    This is a toy example: by their very definition TOTP tokens are
+    short-lived. You are unlikely to store them in a ``clouds.yaml`` file.
+    Instead, you would likely pass the TOTP token via the command line
+    (``--os-passcode``) or as an environment variable (``OS_PASSCODE``).
+
+.. rubric:: OAuth1-based authentication
+
+.. code-block:: yaml
+
+    example-oauth:
+        auth:
+            auth_url: http://example.com/identity
+            consumer_key: foo
+            consumer_secret: secret
+            access_key: bar
+            access_secret: secret
+        auth_type: v3oauth1
+        region_name: RegionOne

doc/source/user/guides/dns.rst

@@ -5,14 +5,105 @@ Before working with the DNS service, you'll need to create a connection
 to your OpenStack cloud by following the :doc:`connect` user guide. This will
 provide you with the ``conn`` variable used in the examples below.
 
-.. TODO(gtema): Implement this guide
+.. contents:: Table of Contents
+   :local:
+
+The primary resource of the DNS service is the server.
 
 List Zones
 ----------
 
+**Zone** is a logical grouping of DNS records for a domain, allowing for the
+centralized management of DNS resources, including domain names,
+nameservers, and DNS queries.
+
 .. literalinclude:: ../examples/dns/list.py
    :pyobject: list_zones
 
 Full example: `dns resource list`_
 
+List Recordsets
+---------------
+
+**Recordsets** allow for the centralized management of various DNS records
+within a Zone, helping to define how a domain responds to different types
+of DNS queries.
+
+.. literalinclude:: ../examples/dns/list.py
+   :pyobject: list_recordsets
+
+Full example: `dns resource list`_
+
+Create Zone
+-----------
+
+Create a zone.
+It allows users to define and manage the DNS namespace for a particular domain.
+
+.. literalinclude:: ../examples/dns/create.py
+   :pyobject: create_zone
+
+Full example: `dns resource list`_
+
+Create Recordset
+----------------
+
+Create a recordset. It accepts several parameters that define the DNS
+record's properties and sends an API request to OpenStack to create the
+recordset within a specified DNS zone.
+
+.. literalinclude:: ../examples/dns/create.py
+   :pyobject: create_recordset
+
+Full example: `dns resource list`_
+
+Delete Zone
+-----------
+
+Delete a zone.
+It allows users to completely delete the DNS management for a specified domain.
+
+.. literalinclude:: ../examples/dns/delete.py
+   :pyobject: delete_zone
+
+Full example: `dns resource list`_
+
+Delete Recordset
+----------------
+
+Delete a recordset.
+
+.. literalinclude:: ../examples/dns/delete.py
+   :pyobject: delete_recordset
+
+Full example: `dns resource list`_
+
+Find Zone
+---------
+
+The find_zone function searches for and returns a DNS zone by its name
+using a given connection object.
+
+.. literalinclude:: ../examples/dns/find.py
+   :pyobject: find_zone
+
+Full example: `dns resource list`_
+
+Find Recordset
+--------------
+
+The find_recordset function searches for a DNS recordset
+with a specific name and type
+within a given zone. If multiple recordsets
+with the same name exist,
+the record type can be specified to find the exact match.
+
+.. literalinclude:: ../examples/dns/find.py
+   :pyobject: find_recordset
+
+Full example: `dns resource list`_
+
 .. _dns resource list: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/dns/list.py
+.. _dns resource create: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/dns/create.py
+.. _dns resource delete: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/dns/delete.py
+.. _dns resource find: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/dns/find.py

doc/source/user/guides/object_store.rst

@@ -77,12 +77,12 @@ To set the metadata for a container, use the
 :meth:`~openstack.object_store.v1._proxy.Proxy.set_container_metadata` method.
 This method takes a :class:`~openstack.object_store.v1.container.Container`
 object. For example, to grant another user write access to this container,
-you can set the
-:attr:`~openstack.object_store.v1.container.Container.write_ACL` on a
-resource and pass it to `set_container_metadata`. ::
+you can call `set_container_metadata` passing it the `Container` to update
+and keyward argument key/value pairs representing the metadata name and
+value to set. ::
 
-    >>> cont.write_ACL = "big_project:another_user"
-    >>> conn.object_store.set_container_metadata(cont)
+    >>> acl = "big_project:another_user"
+    >>> conn.object_store.set_container_metadata(cont, write_ACL=acl)
     openstack.object_store.v1.container.Container: {'content-length': '0',
     'x-container-object-count': '0',
     'name': u'my new container', 'accept-ranges': 'bytes',

doc/source/user/proxies/accelerator.rst

@@ -10,20 +10,19 @@ The accelerator high-level interface is available through the ``accelerator``
 member of a :class:`~openstack.connection.Connection` object.
 The ``accelerator`` member will only be added if the service is detected.
 
-
-Device Operations
-^^^^^^^^^^^^^^^^^
+Deployable Operations
+^^^^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: openstack.accelerator.v2._proxy.Proxy
   :noindex:
-  :members: devices, get_device
+  :members: deployables, get_deployable, update_deployable
 
-Deployable Operations
-^^^^^^^^^^^^^^^^^^^^^
+Device Operations
+^^^^^^^^^^^^^^^^^
 
 .. autoclass:: openstack.accelerator.v2._proxy.Proxy
   :noindex:
-  :members: deployables, get_deployable, update_deployable
+  :members: devices, get_device
 
 Device Profile Operations
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -41,3 +40,17 @@ Accelerator Request Operations
   :members: accelerator_requests, get_accelerator_request,
             create_accelerator_request, delete_accelerator_request,
             update_accelerator_request
+
+Attribute Operations
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.accelerator.v2._proxy.Proxy
+  :noindex:
+  :members: attributes, create_attribute, delete_attribute, get_attribute
+
+Helpers
+^^^^^^^
+
+.. autoclass:: openstack.accelerator.v2._proxy.Proxy
+   :noindex:
+   :members: wait_for_status, wait_for_delete