Fix quota usage and reservation display

Fix `openstack quota show --usage` to correctly display resource usage
and reservations by applying proper name normalization for corresponding
sections of data.
Previously, name normalization was applied only for "limits" which is
the root section, leaving 'usage' and 'reservation' sections untouched.

Change-Id: Id14fe894b30a74b9b8d78b00c3d4ff151f8b4210
Closes-bug: #2137636
Signed-off-by: Andriy Kurilin <andr.kurilin@gmail.com>

.coveragerc

@@ -1,7 +1,7 @@
 [run]
 branch = True
 source = openstackclient
-omit = openstackclient/openstack/*
+omit = openstackclient/tests/*
 
 [report]
-ignore-errors = True
+ignore_errors = True

.git-blame-ignore-revs

@@ -0,0 +1,13 @@
+# You can configure git to automatically use this file with the following config:
+# git config --global blame.ignoreRevsFile .git-blame-ignore-revs
+
+c5b772db76c071e493a81105c7d8c0def08b2264  # trivial: Prepare for pyupgrade pre-commit hook
+ed0314ac76ae58a6621077feb742efd5c14c3a62  # Blacken everything else
+ac64fdb93c32972575a4523ccb23d0279ef584f5  # Blacken openstackclient.api
+a3778109d0051a25901569e7bafe54915ab25f82  # Blacken openstack.common
+53476e1f73d8af172207ac7089fb85fc0221859f  # Blacken openstackclient.image
+c51e4ef1bc350905a04690eb019d53e68fe3d633  # Blacken openstackclient.object
+af6ea07703ed1c12b86995b97a9618bfa70721ee  # Blacken openstackclient.identity
+1face4f48b07fbc51824980e989687adaf453f0e  # Blacken openstackclient.network
+1ca77acc9118b433c14e03bf9fd28f2b1639c430  # Blacken openstackclient.volume
+4bbf3bd3846cb3d85e243199910de82df25d35e0  # Blacken openstackclient.compute

.gitignore

@@ -7,12 +7,20 @@
 *.swp
 *~
 .coverage
-.openstackclient-venv
+.idea
+.stestr/
 .testrepository
 .tox
-.venv
 AUTHORS
 build
 ChangeLog
 dist
+# Doc related
 doc/build
+doc/source/contributor/api/
+# Development environment files
+.project
+.pydevproject
+cover
+# Files created by releasenotes build
+releasenotes/build

.gitreview

@@ -1,4 +1,4 @@
 [gerrit]
-host=review.openstack.org
+host=review.opendev.org
 port=29418
 project=openstack/python-openstackclient.git

.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ['--fix', 'lf']
+        exclude: '.*\.(svg)$'
+      - id: fix-byte-order-marker
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: check-yaml
+        files: .*\.(yaml|yml)$
+        args: ['--unsafe']
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff-check
+        args: ['--fix', '--unsafe-fixes']
+      - id: ruff-format
+  - repo: https://opendev.org/openstack/hacking
+    rev: 7.0.0
+    hooks:
+      - id: hacking
+        additional_dependencies: []
+        exclude: '^(doc|releasenotes)/.*$'
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-requests
+        # keep this in-sync with '[tool.mypy] exclude' in 'pyproject.toml'
+        exclude: |
+          (?x)(
+            doc/.*
+            | examples/.*
+            | hacking/.*
+            | releasenotes/.*
+          )

.stestr.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+test_path=${OS_TEST_PATH:-./openstackclient/tests/unit}
+top_dir=./
+group_regex=([^\.]+\.)+

.testr.conf

@@ -1,4 +0,0 @@
-[DEFAULT]
-test_command=OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 ${PYTHON:-python} -m subunit.run discover -t ./ . $LISTOPT $IDOPTION
-test_id_option=--load-list $IDFILE
-test_list_option=--list

.zuul.yaml

@@ -0,0 +1,187 @@
+---
+- job:
+    name: osc-tox-unit-tips
+    parent: openstack-tox
+    description: |
+      Run unit tests for OpenStackClient with master branch of important libs.
+
+      Takes advantage of the base tox job's install-siblings feature.
+    irrelevant-files: &common-irrelevant-files
+      - ^.*\.rst$
+      - ^doc/.*$
+      - ^releasenotes/.*$
+      - ^\.pre-commit-config\.yaml$
+    required-projects:
+      - openstack/cliff
+      - openstack/keystoneauth
+      - openstack/openstacksdk
+      - openstack/osc-lib
+      - openstack/python-openstackclient
+    vars:
+      # Set work dir to openstackclient so that if it's triggered by one of the
+      # other repos the tests will run in the same place
+      zuul_work_dir: src/opendev.org/openstack/python-openstackclient
+
+- job:
+    name: osc-tox-py310-tips
+    parent: openstack-tox-py310
+    description: |
+      Run unit tests for OpenStackClient with master branch of important libs.
+
+      Takes advantage of the base tox job's install-siblings feature.
+    # The job only tests the latest and shouldn't be run on the stable branches
+    branches: ^master$
+    required-projects:
+      - openstack/cliff
+      - openstack/keystoneauth
+      - openstack/openstacksdk
+      - openstack/osc-lib
+      - openstack/python-openstackclient
+    vars:
+      # Set work dir to openstackclient so that if it's triggered by one of the
+      # other repos the tests will run in the same place
+      zuul_work_dir: src/opendev.org/openstack/python-openstackclient
+
+- job:
+    name: osc-tox-py313-tips
+    parent: openstack-tox-py313
+    description: |
+      Run unit tests for OpenStackClient with master branch of important libs.
+
+      Takes advantage of the base tox job's install-siblings feature.
+    # The job only tests the latest and shouldn't be run on the stable branches
+    branches: ^master$
+    required-projects:
+      - openstack/cliff
+      - openstack/keystoneauth
+      - openstack/openstacksdk
+      - openstack/osc-lib
+      - openstack/python-openstackclient
+    vars:
+      # Set work dir to openstackclient so that if it's triggered by one of the
+      # other repos the tests will run in the same place
+      zuul_work_dir: src/opendev.org/openstack/python-openstackclient
+
+- job:
+    name: osc-functional-devstack
+    parent: devstack-tox-functional
+    description: |
+      Run functional tests for OpenStackClient.
+    timeout: 7800
+    irrelevant-files:
+      - ^.*\.rst$
+      - ^doc/.*$
+      - ^releasenotes/.*$
+    required-projects:
+      - openstack/python-openstackclient
+    vars:
+      devstack_localrc:
+        LIBS_FROM_GIT: python-openstackclient
+        # NOTE(dtroyer): Functional tests need a bit more volume headroom
+        VOLUME_BACKING_FILE_SIZE: 20G
+        Q_AGENT: openvswitch
+        Q_ML2_TENANT_NETWORK_TYPE: vxlan
+        Q_ML2_PLUGIN_MECHANISM_DRIVERS: openvswitch
+      devstack_plugins:
+        # NOTE(amotoki): Some neutron features are enabled by devstack plugin
+        neutron: https://opendev.org/openstack/neutron
+      devstack_services:
+        s-account: true
+        s-container: true
+        s-object: true
+        s-proxy: true
+        # Disable OVN services
+        br-ex-tcpdump: false
+        br-int-flows: false
+        ovn-controller: false
+        ovn-northd: false
+        ovs-vswitchd: false
+        ovsdb-server: false
+        q-ovn-metadata-agent: false
+        # Neutron services
+        q-agt: true
+        q-dhcp: true
+        q-l3: true
+        q-meta: true
+        neutron-network-segment-range: true
+        neutron-segments: true
+        q-metering: true
+        q-qos: true
+        neutron-tag-ports-during-bulk-creation: true
+        neutron-conntrack-helper: true
+        neutron-ndp-proxy: true
+        q-trunk: true
+      osc_environment:
+        PYTHONUNBUFFERED: 'true'
+        OS_CLOUD: devstack-admin
+      tox_envlist: functional
+      zuul_work_dir: src/opendev.org/openstack/python-openstackclient
+
+- job:
+    name: osc-functional-devstack-tips
+    parent: osc-functional-devstack
+    description: |
+      Run functional tests for OpenStackClient with master branch of important libs.
+
+      Takes advantage of the base tox job's install-siblings feature.
+    timeout: 7800
+    required-projects:
+      - openstack/cliff
+      - openstack/keystoneauth
+      - openstack/openstacksdk
+      - openstack/osc-lib
+      - openstack/python-openstackclient
+    vars:
+      devstack_localrc:
+        LIBS_FROM_GIT: python-openstackclient,openstacksdk,osc-lib,cliff
+      tox_envlist: functional
+      tox_install_siblings: true
+
+- job:
+    name: osc-build-image
+    parent: opendev-build-docker-image
+    description: Build Docker images.
+    allowed-projects: openstack/python-openstackclient
+    requires:
+      - python-builder-3.11-bookworm-container-image
+      - python-base-3.11-bookworm-container-image
+    provides: osc-container-image
+    vars:
+      docker_images:
+        - context: .
+          tags: []
+
+- project-template:
+    name: osc-tox-unit-tips
+    check:
+      jobs:
+        - osc-tox-py310-tips
+        - osc-tox-py313-tips
+    gate:
+      jobs:
+        - osc-tox-py310-tips
+        - osc-tox-py313-tips
+
+- project:
+    templates:
+      - openstackclient-plugin-jobs
+      - osc-tox-unit-tips
+      - openstack-cover-jobs
+      - openstack-python3-jobs
+      - publish-openstack-docs-pti
+      - check-requirements
+      - release-notes-jobs-python3
+    check:
+      jobs:
+        - openstackclient-check-plugins:
+            voting: true
+        - osc-build-image:
+            voting: false
+        - osc-functional-devstack
+        - osc-functional-devstack-tips:
+            # The functional-tips job only tests the latest and shouldn't be run
+            # on the stable branches
+            branches: ^master$
+    gate:
+      jobs:
+        - osc-functional-devstack

CONTRIBUTING.rst

@@ -0,0 +1,27 @@
+The source repository for this project can be found at:
+
+   https://opendev.org/openstack/python-openstackclient
+
+Pull requests submitted through GitHub are not monitored.
+
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
+
+   https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
+
+Bugs should be filed on Launchpad:
+
+   https://bugs.launchpad.net/python-openstackclient
+
+Developers should also join the discussion on the mailing list, at:
+
+  https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/
+
+or join the IRC channel on
+
+  #openstack-sdks on OFTC (irc.oftc.net)
+
+For more specific information about contributing to this repository, see the
+openstacksdk contributor guide:
+
+   https://docs.openstack.org/openstacksdk/latest/contributor/index.html

Dockerfile

@@ -0,0 +1,36 @@
+# Copyright (c) 2020 Red Hat, Inc.
+#
+# 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.
+
+FROM docker.io/opendevorg/python-builder:3.12-bookworm AS builder
+
+COPY . /tmp/src
+RUN assemble
+
+FROM docker.io/opendevorg/python-base:3.12-bookworm
+
+LABEL org.opencontainers.image.title="python-openstackclient"
+LABEL org.opencontainers.image.description="Client for OpenStack services."
+LABEL org.opencontainers.image.licenses="Apache License 2.0"
+LABEL org.opencontainers.image.url="https://www.openstack.org/"
+LABEL org.opencontainers.image.documentation="https://docs.openstack.org/python-openstackclient/latest/"
+LABEL org.opencontainers.image.source="https://opendev.org/openstack/python-openstackclient"
+
+COPY --from=builder /output/ /output
+RUN /output/install-from-bindep
+
+# Trigger entrypoint loading to trigger stevedore entrypoint caching
+RUN openstack --help >/dev/null 2>&1
+
+CMD ["/usr/local/bin/openstack"]

HACKING.rst

@@ -1,12 +1,13 @@
 OpenStack Style Commandments
 ============================
 
-Step 0: Read https://github.com/openstack-dev/hacking/blob/master/HACKING.rst
-Step 1: Read http://www.python.org/dev/peps/pep-0008/ one more time
-Step 2: Read on
+- Step 1: Read the OpenStack Style Commandments
+  https://docs.openstack.org/hacking/latest/
+- Step 2: Read on
 
 General
 -------
+
 - thou shalt not violate causality in our time cone, or else
 
 Docstrings
@@ -27,11 +28,11 @@ Calling Methods
 ---------------
 
 Deviation! When breaking up method calls due to the 79 char line length limit,
-use the alternate 4 space indent.  With the frist argument on the succeeding
+use the alternate 4 space indent.  With the first argument on the succeeding
 line all arguments will then be vertically aligned.  Use the same convention
 used with other data structure literals and terminate the method call with
 the last argument line ending with a comma and the closing paren on its own
-line indented to the starting line level.
+line indented to the starting line level.  ::
 
     unnecessarily_long_function_name(
         'string one',
@@ -39,68 +40,3 @@ line indented to the starting line level.
         kwarg1=constants.ACTIVE,
         kwarg2=['a', 'b', 'c'],
     )
-
-Text encoding
--------------
-
-Note: this section clearly has not been implemented in this project yet, it is
-the intention to do so.
-
-All text within python code should be of type 'unicode'.
-
-    WRONG:
-
-    >>> s = 'foo'
-    >>> s
-    'foo'
-    >>> type(s)
-    <type 'str'>
-
-    RIGHT:
-
-    >>> u = u'foo'
-    >>> u
-    u'foo'
-    >>> type(u)
-    <type 'unicode'>
-
-Transitions between internal unicode and external strings should always
-be immediately and explicitly encoded or decoded.
-
-All external text that is not explicitly encoded (database storage,
-commandline arguments, etc.) should be presumed to be encoded as utf-8.
-
-    WRONG:
-
-    mystring = infile.readline()
-    myreturnstring = do_some_magic_with(mystring)
-    outfile.write(myreturnstring)
-
-    RIGHT:
-
-    mystring = infile.readline()
-    mytext = s.decode('utf-8')
-    returntext = do_some_magic_with(mytext)
-    returnstring = returntext.encode('utf-8')
-    outfile.write(returnstring)
-
-Python 3.x Compatibility
-------------------------
-
-OpenStackClient strives to be Python 3.3 compatibile.  Common guidelines:
-
-* Convert print statements to functions: print statements should be converted
-  to an appropriate log or other output mechanism.
-* Use six where applicable: x.iteritems is converted to six.iteritems(x)
-  for example.
-
-Running Tests
--------------
-
-Note: Oh boy, are we behing on writing tests.  But they are coming!
-
-The testing system is based on a combination of tox and testr. If you just
-want to run the whole suite, run `tox` and all will be fine. However, if
-you'd like to dig in a bit more, you might want to learn some things about
-testr itself. A basic walkthrough for OpenStack can be found at
-http://wiki.openstack.org/testr

LICENSE

@@ -174,29 +174,3 @@
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
 
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   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.

MANIFEST.in

@@ -1,12 +0,0 @@
-include AUTHORS
-include ChangeLog
-include LICENSE
-include README.rst
-
-recursive-include doc *
-recursive-include tests *
-
-exclude .gitignore
-exclude .gitreview
-
-global-exclude *.pyc

README.rst

@@ -1,122 +1,229 @@
-================
-OpenStack Client
-================
+===============
+OpenStackClient
+===============
 
-python-openstackclient is a unified command-line client for the OpenStack APIs.
-It is a thin wrapper to the stock python-*client modules that implement the
-actual REST API client actions.
+.. image:: https://img.shields.io/pypi/v/python-openstackclient.svg
+    :target: https://pypi.org/project/python-openstackclient/
+    :alt: Latest Version
 
-This is an implementation of the design goals shown in
-http://wiki.openstack.org/UnifiedCLI.  The primary goal is to provide
-a unified shell command structure and a common language to describe
-operations in OpenStack.
+OpenStackClient (OSC) is a command-line client for OpenStack that brings
+the command set for Compute, Identity, Image, Network, Object Store and Block
+Storage APIs together in a single shell with a uniform command structure.
+Support for additional service APIs is provided via plugins.
 
-python-openstackclient is designed to add support for API extensions via a
-plugin mechanism.
-
-For release management::
-
-   * https://launchpad.net/python-openstackclient
-
-For blueprints and feature specifications::
-
-   * https://blueprints.launchpad.net/python-openstackclient
-
-For issue tracking::
-
-   * https://bugs.launchpad.net/python-openstackclient
-
-Note
-====
-
-OpenStackClient is considered to be alpha release quality as of the 0.2 release;
-no assurances are made at this point for ongoing compatibility in command forms
-or output.  We do not, however, expect any major changes at this point.
+The primary goal is to provide a unified shell command structure and a common
+language to describe operations in OpenStack.
 
 Getting Started
 ===============
 
-We recommend using a virtualenv to install the client. This description
-uses the `install_venv.py`_ script to create the virtualenv::
+OpenStack Client can be installed from PyPI using pip:
 
-   python tools/install_venv.py
-   source .venv/bin/activate
-   python setup.py develop
+.. code-block:: shell
 
-Unit tests can be ran simply by running::
+    python3 -m pip install python-openstackclient
 
-   run_tests.sh
+You can use ``--help`` or the ``help`` command to get a list of global options
+and supported commands:
 
-The client can be called interactively by simply typing::
+.. code-block:: shell
 
-   openstack
+    openstack --help
+    openstack help
 
-Alternatively command line parameters can be called non-interactively::
+You can also get help for a specific command:
 
-   openstack --help
+.. code-block:: shell
+
+    openstack server create --help
+    openstack help server create
+
+You can add support for additional services by installing their clients. For
+example, to add support for the DNS service (designate):
+
+.. code-block:: shell
+
+    python3 -m pip install python3-designateclient
+
+A ``Dockerfile`` is provided for your convenience in the repository. You can
+use this to build your own container images:
+
+.. code-block:: shell
+
+    git clone https://opendev.org/openstack/python-openstackclient
+    cd python-openstackclient
+    podman build . -t example.com/myuser/openstackclient
+
+For more information the available options and commands, refer to the `Users
+Guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html
 
 Configuration
 =============
 
-The CLI is configured via environment variables and command-line
-options as listed in https://wiki.openstack.org/wiki/OpenStackClient/Authentication.
+OpenStack Client must be configured with authentication information in order to
+communicate with a given OpenStack cloud. This configuration can be achieved
+via a ``clouds.yaml`` file, a set of environment variables (often shared via an
+``openrc`` file), a set of command-line options, or a combination of all three.
+Your cloud provider or deployment tooling will typically provide either a
+``clouds.yaml`` file or ``openrc`` file for you. If using a ``clouds.yaml``
+file, OpenStack Client expects to find it in one of the following locations:
 
-The 'password flow' variation is most commonly used::
+* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment
+  variable
+* ``.`` (the current directory)
+* ``$HOME/.config/openstack``
+* ``/etc/openstack``
 
-   export OS_AUTH_URL=<url-to-openstack-identity>
-   export OS_PROJECT_NAME=<project-name>
-   export OS_USERNAME=<user-name>
-   export OS_PASSWORD=<password>  # (optional)
-   export OS_USE_KEYRING=true  # (optional)
+The options you should set will depend on the configuration of your cloud and
+the authentication mechanism(s) supported. For example, consider a cloud that
+supports username/password authentication. Configuration for this cloud using a
+``clouds.yaml`` file would look like so:
 
-The corresponding command-line options look very similar::
+.. code-block:: yaml
 
-   --os-auth-url <url>
-   --os-project-name <project-name>
-   --os-username <user-name>
-   [--os-password <password>]
-   [--os-use-keyring]
+    clouds:
+      my-cloud:
+        auth:
+          auth_url: '<url-to-openstack-identity>'
+          project_name: '<project-name>'
+          project_domain_name: '<project-domain-name>'
+          username: '<username>'
+          user_domain_name: '<user-domain-name>'
+          password: '<password>'  # (optional)
+        region_name: '<region>'
 
-If a password is not provided above (in plaintext), you will be interactively
-prompted to provide one securely. If keyring is enabled, the password entered
-in the prompt is stored in keyring. From next time, the password is read from
-keyring, if it is not provided above (in plaintext).
+The corresponding environment variables would look very similar:
 
-The token flow variation for authentication uses an already-aquired token
-and a URL pointing directly to the service API that presumably was acquired
-from the Service Catalog::
+.. code-block:: shell
 
-    export OS_TOKEN=<token>
-    export OS_URL=<url-to-openstack-service>
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_REGION_NAME=<region>
+    export OS_PROJECT_NAME=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_USERNAME=<username>
+    export OS_USER_DOMAIN_NAME=<user-domain-name>
+    export OS_PASSWORD=<password>  # (optional)
 
-The corresponding command-line options look very similar::
+Likewise, the corresponding command-line options would look very similar:
 
-    --os-token <token>
-    --os-url <url-to-openstack-service>
+::
 
-Additional command-line options and their associated environment variables
-are listed here::
+    openstack
+    --os-auth-url <url-to-openstack-identity>
+    --os-region <region>
+    --os-project-name <project-name>
+    --os-project-domain-name <project-domain-name>
+    --os-username <username>
+    --os-user-domain-name <user-domain-name>
+    [--os-password <password>]
 
-   --debug             # turns on some debugging of the API conversation
-   --verbose | -v      # Increase verbosity of output. Can be repeated.
-   --quiet | -q        # suppress output except warnings and errors
-   --help | -h         # show a help message and exit
+.. note::
 
-Building Documentation
-======================
+    If a password is not provided above (in plaintext), you will be
+    interactively prompted to provide one securely.
 
-This documentation is written by contributors, for contributors.
+Some clouds use federated authentication. If this is the case, your
+configuration will be slightly more involved. For example, to configure
+username/password authentication for a federated user using a ``clouds.yaml``
+file:
 
-The source is maintained in the ``doc/source`` folder using
-`reStructuredText`_ and built by `Sphinx`_
+.. code-block:: yaml
 
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _Sphinx: http://sphinx.pocoo.org/
+    clouds:
+      my-cloud:
+        auth:
+          auth_url: '<url-to-openstack-identity>'
+          project_name: '<project-name>'
+          project_domain_name: '<project-domain-name>'
+          username: '<username-in-idp>'
+          user_domain_name: '<user-domain-name>'
+          password: '<password-in-idp>'
+          identity_provider: '<the-desired-idp-in-keystone>'
+          client_id: '<the-client-id-configured-in-the-idp>'
+          client_secret: '<the-client-secret-configured-in-the-idp>'
+          openid_scope: '<the-scopes-of-desired-attributes-to-claim-from-idp>'
+          protocol: '<the-protocol-used-in-the-apache2-oidc-proxy>'
+          access_token_type: '<the-access-token-type-used-by-your-idp>'
+          discovery_endpoint: '<the-well-known-endpoint-of-the-idp>'
+        auth_type: 'v3oidcpassword'
+        region_name: '<region>'
 
-* Building Manually::
+The corresponding environment variables would look very similar:
 
-    $ export DJANGO_SETTINGS_MODULE=local.local_settings
-    $ python doc/generate_autodoc_index.py
-    $ sphinx-build -b html doc/source build/sphinx/html
+.. code-block:: shell
 
-Results are in the `build/sphinx/html` directory.
+    export OS_PROJECT_NAME=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_IDENTITY_API_VERSION=3
+    export OS_AUTH_TYPE=v3oidcpassword
+    export OS_USERNAME=<username-in-idp>
+    export OS_PASSWORD=<password-in-idp>
+    export OS_IDENTITY_PROVIDER=<the-desired-idp-in-keystone>
+    export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
+    export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
+    export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
+    export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
+    export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
+    export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
+
+Likewise, the corresponding command-line options would look very similar:
+
+.. code-block:: shell
+
+    --os-project-name <project-name>
+    --os-project-domain-name <project-domain-name>
+    --os-auth-url <url-to-openstack-identity>
+    --os-identity-api-version 3
+    --os-auth-plugin openid
+    --os-auth-type v3oidcpassword
+    --os-username <username-in-idp>
+    --os-password <password-in-idp>
+    --os-identity-provider <the-desired-idp-in-keystone>
+    --os-client-id <the-client-id-configured-in-the-idp>
+    --os-client-secret <the-client-secred-configured-in-the-idp>
+    --os-openid-scope <the-scopes-of-desired-attributes-to-claim-from-idp>
+    --os-protocol <the-protocol-used-in-the-apache2-oidc-proxy>
+    --os-access-token-type <the-access-token-type-used-by-your-idp>
+    --os-discovery-endpoint <the-well-known-endpoint-of-the-idp>
+
+For more information on configuring authentication, including an overview of
+the many authentication mechanisms supported, refer to the `Authentication
+guide`__. For more information on configuration in general, refer to the
+`Configuration guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
+.. __: https://docs.openstack.org/python-openstackclient/latest/configuration/index.html
+
+Contributing
+============
+
+You can clone the repository from opendev.org::
+
+    git clone https://opendev.org/openstack/python-openstackclient
+    cd python-openstackclient
+
+OpenStack Client uses the same contributor process as other OpenStack projects.
+For information on this process, including help on setting up you Gerrit
+account and an overview of the CI process, refer to the `OpenStack Contributors
+Guide`__.
+
+For more information on contributing to OpenStack Client itself, including
+guidance on how to design new commands and how to report bugs, refer to the
+`Contributors Guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html
+.. __: https://docs.opendev.org/opendev/infra-manual/latest/developers.html
+
+Links
+-----
+
+* `Issue Tracker <https://bugs.launchpad.net/python-openstackclient>`_
+* `Code Review <https://review.opendev.org/#/q/status:open+project:openstack/openstacksdk,n,z>`_
+* `Documentation <https://docs.openstack.org/python-openstackclient/latest/>`_
+* `PyPi <https://pypi.org/project/python-openstackclient>`_
+* `Mailing list <https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/>`_
+* `Release Notes <https://docs.openstack.org/releasenotes/python-openstackclient>`_
+* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) <irc://irc.oftc.net/openstack-sdks>`_

bindep.txt

@@ -0,0 +1,11 @@
+# This is a cross-platform list tracking distribution packages needed by tests;
+# see https://docs.openstack.org/infra/bindep/ for additional information.
+
+gcc [compile test]
+libc6-dev [compile test platform:dpkg]
+libffi-devel [platform:rpm]
+libffi-dev [compile test platform:dpkg]
+libssl-dev [compile test platform:dpkg]
+python3-dev [compile test platform:dpkg]
+python3-devel [compile test platform:rpm]
+libpcre3-dev [test platform:dpkg]

doc/requirements.txt

@@ -0,0 +1,27 @@
+openstackdocstheme>=2.2.1 # Apache-2.0
+reno>=3.1.0 # Apache-2.0
+sphinx>=2.0.0,!=2.1.0 # BSD
+sphinxcontrib-apidoc>=0.2.0 # BSD
+
+# redirect tests in docs
+whereto>=0.4.0 # Apache-2.0
+
+# Install these to generate sphinx autodocs
+aodhclient>=0.9.0 # Apache-2.0
+gnocchiclient>=3.3.1 # Apache-2.0
+osc-placement>=1.7.0 # Apache-2.0
+python-barbicanclient>=4.5.2 # Apache-2.0
+python-cyborgclient>=1.2.1 # Apache-2.0
+python-designateclient>=2.7.0 # Apache-2.0
+python-heatclient>=1.10.0 # Apache-2.0
+python-ironicclient>=2.3.0 # Apache-2.0
+python-ironic-inspector-client>=1.5.0 # Apache-2.0
+python-magnumclient>=2.3.0 # Apache-2.0
+python-manilaclient>=2.0.0 # Apache-2.0
+python-mistralclient!=3.2.0,>=3.1.0 # Apache-2.0
+python-neutronclient>=6.7.0 # Apache-2.0
+python-octaviaclient>=1.11.0 # Apache-2.0
+python-troveclient>=3.1.0 # Apache-2.0
+python-watcherclient>=2.5.0 # Apache-2.0
+python-zaqarclient>=1.0.0 # Apache-2.0
+python-zunclient>=3.6.0 # Apache-2.0

doc/source/_extra/.htaccess

@@ -0,0 +1,16 @@
+# Redirect docs from the old to new location following the Great Docs Migration of 2017
+
+redirectmatch 301 ^/python-openstackclient/([^/]+)/command-objects/([^/.]+).html$ /python-openstackclient/$1/cli/command-objects/$2.html
+
+redirectmatch 301 ^/python-openstackclient/([^/]+)/(authentication|backward-incompatible|command-list|commands|decoder|interactive).html$ /python-openstackclient/$1/cli/$2.html
+redirectmatch 301 ^/python-openstackclient/([^/]+)/plugin-commands.html$ /python-openstackclient/$1/cli/plugin-commands/index.html
+
+redirectmatch 301 ^/python-openstackclient/([^/]+)/specs/([^/.]+).html$ /python-openstackclient/$1/contributor/specs/$2.html
+
+redirectmatch 301 ^/python-openstackclient/([^/]+)/(command-(beta|errors|logs|options|wrappers)|developing|humaninterfaceguide|plugins).html$ /python-openstackclient/$1/contributor/$2.html
+redirectmatch 301 ^/python-openstackclient/([^/]+)/cli/plugin-commands.html$ /python-openstackclient/$1/cli/plugin-commands/index.html
+# For common subcommand names:
+# - identity pages were split into -v2 and -v3
+# - image pages were split into -v1 and -v2
+# The unversioned page is hidden but contains links to the versioned pages so links in the wild redirect somewhere sane.
+redirectmatch 301 ^/python-openstackclient/([^/]+)/cli/command-objects/(ec2-credentials|endpoint|image|project|role|service|token|user).html$ /python-openstackclient/$1/cli/_hidden/$2.html

doc/source/cli/_hidden/ec2-credentials.rst

@@ -0,0 +1,13 @@
+===============
+ec2 credentials
+===============
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/ec2-credentials-v2
+   ../command-objects/ec2-credentials-v3

doc/source/cli/_hidden/endpoint.rst

@@ -0,0 +1,13 @@
+========
+endpoint
+========
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/endpoint-v2
+   ../command-objects/endpoint-v3

doc/source/cli/_hidden/image.rst

@@ -0,0 +1,13 @@
+=====
+image
+=====
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously image v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/image-v1
+   ../command-objects/image-v2

doc/source/cli/_hidden/project.rst

@@ -0,0 +1,13 @@
+=======
+project
+=======
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/project-v2
+   ../command-objects/project-v3

doc/source/cli/_hidden/role.rst

@@ -0,0 +1,13 @@
+====
+role
+====
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/role-v2
+   ../command-objects/role-v3

doc/source/cli/_hidden/service.rst

@@ -0,0 +1,13 @@
+=======
+service
+=======
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/service-v2
+   ../command-objects/service-v3

doc/source/cli/_hidden/token.rst

@@ -0,0 +1,13 @@
+=====
+token
+=====
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/token-v2
+   ../command-objects/token-v3

doc/source/cli/_hidden/user.rst

@@ -0,0 +1,13 @@
+====
+user
+====
+
+.. NOTE(efried): This page is hidden from the main TOC; it's here so links in
+   the wild redirect somewhere sane, because previously identity v2 and v3 were
+   combined in a single page.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../command-objects/user-v2
+   ../command-objects/user-v3

doc/source/cli/authentication.rst

@@ -0,0 +1,377 @@
+.. _authentication:
+
+==============
+Authentication
+==============
+
+OpenStackClient leverages `python-keystoneclient`_ authentication
+plugins to support a number of different authentication methods.
+
+.. _`python-keystoneclient`: https://docs.openstack.org/python-keystoneclient/latest/using-sessions.html#sharing-authentication-plugins
+
+Authentication Process
+----------------------
+
+The user provides some number of authentication credential options.
+If an authentication type is not provided (``--os-auth-type``), the
+authentication options are examined to determine if one of the default
+types can be used. If no match is found an error is reported and OSC exits.
+
+Note that the authentication call to the Identity service has not yet
+occurred. It is deferred until the last possible moment in order to
+reduce the number of unnecessary queries to the server, such as when further
+processing detects an invalid command.
+
+Authentication Plugins
+----------------------
+
+The Keystone client library implements the base set of plugins. Additional
+plugins may be available from the Keystone project or other sources.
+
+There are at least three authentication types that are always available:
+
+* **Password**: A project, username and password are used to identify the
+  user.  An optional domain may also be included. This is the most common
+  type and is the default any time a username is supplied.  An authentication
+  URL for the Identity service is also required. [Required: ``--os-auth-url``,
+  ``--os-project-name``, ``--os-username``; Optional: ``--os-password``]
+* **Token**: This is slightly different from the usual token authentication
+  in that a token and an authentication
+  URL are supplied and the plugin retrieves a new token.
+  [Required: ``--os-auth-url``, ``--os-token``]
+* **Others**: Other authentication plugins such as SAML, Kerberos, and OAuth1.0
+  are under development and also supported. To use them, they must be selected
+  by supplying the ``--os-auth-type`` option.
+
+Detailed Process
+----------------
+
+The authentication process in OpenStackClient is all contained in and handled
+by the ``ClientManager`` object.
+
+* On import ``api.auth``:
+
+  * obtains the list of installed Keystone authentication
+    plugins from the ``keystoneclient.auth.plugin`` entry point.
+  * builds a list of authentication options from the plugins.
+
+* The command line arguments are processed and a configuration is loaded from
+  :file:`clouds.yaml` if ``--os-cloud`` is provided.
+
+* A new ``ClientManager`` is created and supplied with the set of options from the
+  command line, environment and/or :file:`clouds.yaml`:
+
+  * If ``--os-auth-type`` is provided and is a valid and available plugin
+      it is used.
+  * If ``--os-auth-type`` is not provided an authentication plugin
+    is selected based on the existing options.  This is a short-circuit
+    evaluation, the first match wins.
+
+    * If ``--os-username`` is supplied ``password`` is selected
+    * If ``--os-token`` is supplied ``token`` is selected
+    * If no selection has been made by now exit with error
+
+  * Load the selected plugin class.
+
+* When an operation that requires authentication is attempted ``ClientManager``
+  makes the actual initial request to the Identity service.
+
+  * if ``--os-auth-url`` is not supplied for any of the types except
+    Token/Endpoint, exit with an error.
+
+Authenticating using Identity Server API v3
+-------------------------------------------
+
+To authenticate against an Identity Server API v3, the
+``OS_IDENTITY_API_VERSION`` environment variable or
+``--os-identity-api-version`` option must be changed to ``3``, instead of the
+default ``2.0``. Similarly ``OS_AUTH_URL`` or ``os-auth-url`` should also be
+updated.
+
+.. code-block:: bash
+
+    $ export OS_IDENTITY_API_VERSION=3 (Defaults to 2.0)
+    $ export OS_AUTH_URL=http://localhost:5000/v3
+
+Since Identity API v3 authentication is a bit more complex, there are additional
+options that may be set, either as command line options or environment
+variables. The most common case will be a user supplying both user name and
+password, along with the project name; previously in v2.0 this would be
+sufficient, but since the Identity API v3 has a ``Domain`` component, we need
+to tell the client in which domain the user and project exists.
+
+If using a user name and password to authenticate, specify either it's owning
+domain name or ID.
+
+* ``--os-user-domain-name`` or ``OS_USER_DOMAIN_NAME``
+
+* ``--os-user-domain-id`` or ``OS_USER_DOMAIN_ID``
+
+If using a project name as authorization scope, specify either it's owning
+domain name or ID.
+
+* ``--os-project-domain-name`` or ``OS_PROJECT_DOMAIN_NAME``
+
+* ``--os-project-domain-id`` or ``OS_PROJECT_DOMAIN_ID``
+
+If using a domain as authorization scope, set either it's name or ID.
+
+* ``--os-domain-name`` or ``OS_DOMAIN_NAME``
+
+* ``--os-domain-id`` or ``OS_DOMAIN_ID``
+
+Note that if the user and project share the same domain, then simply setting
+``--os-default-domain`` or ``OS_DEFAULT_DOMAIN`` to the domain ID is sufficient.
+
+Thus, a minimal set of environment variables would be:
+
+.. code-block:: bash
+
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://localhost:5000/v3
+    $ export OS_DEFAULT_DOMAIN=default
+    $ export OS_USERNAME=admin
+    $ export OS_PASSWORD=secret
+    $ export OS_PROJECT_NAME=admin
+
+Federated users support
+-----------------------
+
+The OpenStackClient also allows the use of Federated users to log in.
+It enables one to use the identity providers credentials such as Google or
+Facebook to log in the OpenStackClient instead of using the Keystone
+credentials.
+
+This is useful in a Federated environment where one credential give access
+to many applications/services that the Federation supports. To check how to
+configure the OpenStackClient to allow Federated users to log in, please check
+the :ref:`Authentication using federation. <manpage>`
+
+Examples
+--------
+
+.. todo: It would be nice to add more examples here, particularly for
+   complicated things like oauth2
+
+``v3password``
+~~~~~~~~~~~~~~
+
+Using ``clouds.yaml``:
+
+.. code-block:: yaml
+
+    clouds:
+      demo:
+        auth:
+          auth_url: http://openstack.dev/identity
+          project_name: demo
+          project_domain_name: default
+          user_domain_name: default
+          username: demo
+          password: password
+        auth_type: v3password
+
+or, using command line options:
+
+.. code-block:: bash
+
+    $ openstack \
+      --os-auth-url "http://openstack.dev/identity" \
+      --os-project-name demo \
+      --os-project-domain-name default \
+      --os-user-domain-name default \
+      --os-auth-type=v3password \
+      --os-username demo \
+      --os-password password \
+      server list
+
+or, using environment variables:
+
+.. code-block:: bash
+
+    $ export OS_AUTH_URL="http://openstack.dev/identity"
+    $ export OS_PROJECT_NAME=demo
+    $ export OS_PROJECT_DOMAIN_NAME=default
+    $ export OS_AUTH_TYPE=v3password
+    $ export OS_USERNAME=demo
+    $ export OS_PASSWORD=password
+    $ openstack server list
+
+.. note::
+
+    If a password is not provided, you will be prompted for one.
+
+``v3applicationcredential``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using ``clouds.yaml``:
+
+.. code-block:: yaml
+
+    clouds:
+      demo:
+        auth:
+          auth_url: http://openstack.dev/identity
+          application_credential_id: ${APP_CRED_ID}
+          application_credential_secret: ${APP_CRED_SECRET}
+        auth_type: v3applicationcredential
+
+or, using command line options:
+
+.. code-block:: bash
+
+    $ openstack \
+      --os-auth-url "http://openstack.dev/identity" \
+      --os-auth-type=v3applicationcredential \
+      --os-application-credential-id=${APP_CRED_ID} \
+      --os-application-credential-secret=${APP_CRED_SECRET}
+      server list
+
+or, using environment variables:
+
+.. code-block:: bash
+
+    $ export OS_AUTH_URL="http://openstack.dev/identity"
+    $ export OS_AUTH_TYPE=v3applicationcredential
+    $ export OS_APPLICATION_CREDENTIAL_ID=${APP_CRED_ID}
+    $ export OS_APPLICATION_CREDENTIAL_SECRET=${APP_CRED_SECRET}
+    $ openstack server list
+
+.. note::
+
+    You can generate application credentials using the :program:`openstack
+    application credential create` command:
+
+    .. code-block:: bash
+
+       $ readarray -t lines <<< $(openstack application credential create test -f value -c id -c secret)
+       $ APP_CRED_ID=${lines[0]}
+       $ APP_CRED_SECRET=${lines[1]}
+
+``v3token``
+~~~~~~~~~~~
+
+Using ``clouds.yaml``:
+
+.. code-block:: yaml
+
+    clouds:
+      demo:
+        auth:
+          auth_url: http://openstack.dev/identity
+          project_name: demo
+          project_domain_name: default
+          token: ${TOKEN}
+        auth_type: v3token
+
+or, using command line options:
+
+.. code-block:: bash
+
+    $ openstack \
+      --os-auth-url "http://openstack.dev/identity" \
+      --os-project-name demo \
+      --os-project-domain-name default \
+      --os-auth-type=v3token \
+      --os-token ${TOKEN} \
+      server list
+
+or, using environment variables:
+
+.. code-block:: bash
+
+    $ export OS_AUTH_URL="http://openstack.dev/identity"
+    $ export OS_PROJECT_NAME=demo
+    $ export OS_PROJECT_DOMAIN_NAME=default
+    $ export OS_AUTH_TYPE=v3token
+    $ export OS_TOKEN=${TOKEN}
+    $ openstack server list
+
+.. note::
+
+    You can generate tokens using the :program:`openstack token issue` command:
+
+    .. code-block:: bash
+
+       $ TOKEN=$(openstack token issue -f value -c id)
+
+.. note::
+
+    The above examples assume you require a project-scoped token. You can omit
+    the project-related configuration if your user has a default project ID set.
+    Conversely, if requesting domain-scoped or system-scoped, you should update
+    these examples accordingly. If the user does not have a default project
+    configured and no scoping information is provided, the resulting token will
+    be unscoped.
+
+``v3totp``
+~~~~~~~~~~
+
+.. note::
+
+    The TOTP mechanism is poorly suited to command line-driven API
+    interactions. Where the TOTP mechanism is configured for a cloud, it is
+    expected that it is to be used for initial authentication and to create a
+    token or application credential, which can then be used for future
+    interactions.
+
+.. note::
+
+    The TOTP mechanism is often combined with other mechanisms to enable
+    Multi-Factor Authentication, or MFA. The authentication type
+    ``v3multifactor`` is used in this case, while the ``v3totp`` authentication
+    type is specified alongside the other mechanisms in ``auth_methods``.
+
+Using ``clouds.yaml``:
+
+.. code-block:: yaml
+
+    clouds:
+      demo:
+        auth:
+          auth_url: http://openstack.dev/identity
+          project_name: demo
+          project_domain_name: default
+          user_domain_name: default
+          username: demo
+          passcode: ${PASSCODE}
+        auth_type: v3totp
+
+or, using command line options:
+
+.. code-block:: bash
+
+    $ openstack \
+      --os-auth-url "http://openstack.dev/identity" \
+      --os-project-name demo \
+      --os-project-domain-name default \
+      --os-user-domain-name default \
+      --os-auth-type=v3totp \
+      --os-username demo \
+      --os-passcode ${PASSCODE} \
+      server list
+
+or, using environment variables:
+
+.. code-block:: bash
+
+    $ export OS_AUTH_URL="http://openstack.dev/identity"
+    $ export OS_PROJECT_NAME=demo
+    $ export OS_PROJECT_DOMAIN_NAME=default
+    $ export OS_AUTH_TYPE=v3totp
+    $ export OS_USERNAME=demo
+    $ export OS_PASSCODE=${PASSCODE}
+    $ openstack server list
+
+.. note::
+
+    The passcode will be generated by an authenticator application such FreeOTP
+    or Google Authenticator. Refer to your cloud provider's documentation for
+    information on how to configure an authenticator application, or to the
+    `Keystone documentation`__ if you are configuring this for your own cloud.
+
+    .. __: https://docs.openstack.org/keystone/latest/admin/auth-totp.html
+
+.. note::
+
+    If a passcode is not provided, you will be prompted for one.

doc/source/cli/backwards-incompatible.rst

@@ -0,0 +1,392 @@
+==============================
+Backwards Incompatible Changes
+==============================
+
+Despite our best efforts, sometimes the OpenStackClient team may introduce a
+backwards incompatible change. For user convenience we are tracking any such
+changes here (as of the 1.0.0 release).
+
+Should positional arguments for a command need to change, the OpenStackClient
+team attempts to make the transition as painless as possible. Look for
+deprecation warnings that indicate the new commands (or options) to use.
+
+Commands labeled as a beta according to :ref:`command-beta` are exempt
+from this backwards incompatible change handling.
+
+Backwards Incompatible Changes
+==============================
+
+Release 4.0
+-----------
+
+1. Remove ``ip fixed add|remove`` commands.
+
+   Use ``server add|remove fixed ip`` commands instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/612781
+
+2. Remove ``ip floating add|remove`` commands.
+
+   Use ``server add|remove floating ip`` commands instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/612781
+
+3. Remove ``service create`` option ``--type``.  Service type is
+   a positional argument.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/612798
+
+4. Remove ``role list`` options ``--project`` and ``--user``.
+
+   Use ``role assignment list`` options ``--project`` and ``--user`` instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/612798
+
+5. Remove ``user role list`` command.
+
+   Use ``role assignment list`` options ``--project`` and ``--user`` instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/612798
+
+6. Remove ``image create|set`` option ``--owner``.
+
+   Use ``--project`` option instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/659431
+
+7. Remove ``port create|set`` options ``--device-id`` and ``--host-id``.
+
+   Use ``--device`` and ``--host`` instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/613644
+
+8. Remove ``router set`` option ``--clear-routes``.
+
+   Use ``no-route`` option instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/613644
+
+9. Remove ``security group rule create`` options ``--src-ip`` and ``--src-group``.
+
+   Use ``--remote-ip`` and ``--remote-group`` options instead.
+
+   * Removed in: 4.0
+   * Commit: https://review.opendev.org/613644
+
+10. Remove ``backup`` commands.
+
+    Use ``volume backup`` commands instead.
+
+    * Removed in: 4.0
+    * Commit: https://review.opendev.org/612751
+
+11. Remove ``snapshot`` commands.
+    Use ``volume snapshot`` commands instead.
+
+    * Removed in: 4.0
+    * Commit: https://review.opendev.org/612751
+
+12. Remove ``volume create`` options ``--project``, ``--user``, ``--multi-attach``.
+
+    * Removed in: 4.0
+    * Commit: https://review.opendev.org/612751
+
+13. Change ``volume transfer request accept`` to use new option ``--auth-key``
+    rather than a second positional argument.
+
+    * Removed in: 4.0
+    * Commit: https://review.opendev.org/612751
+
+14. Remove 'Token/Endpoint' auth plugin support (type ``token_endpoint``).
+
+    This remained as a compatibility for the ``admin_token`` auth type to
+    support the ``--url`` global option.  That option is also now removed,
+    use ``--endpoint`` instead.
+
+    * Removed in: 4.0
+    * Commit: https://review.opendev.org/<tbd>
+
+Release 3.12
+------------
+
+1. Replace ``Display Name`` by ``Name`` in volume list.
+
+   Change column name ``Display Name`` to ``Name`` in ``volume list`` output.
+   Current ``volume list --name`` command uses ``display_name`` as search_opts
+   to send to cinder API, and show the result table with ``Display Name``
+   as column title. Replace all ``Display Name`` by ``Name`` to be consistent
+   with other list commands.
+
+   Support a mapping for volume list -c ``Display Name`` (Volume v1 and v2)
+   and volume create/show -c ``display_name`` (Volume v1) to maintain backward
+   compatibility until the next major release.
+
+   * In favor of: ``openstack volume list -c Name``
+   * As of: 3.12.0
+   * Removed in: n/a
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1657956
+   * Commit: https://review.opendev.org/#/c/423081/
+
+Release 3.10
+------------
+
+1. The ``network create`` command now requires the ``--subnet`` option when used
+   with nova-network clouds.
+
+   * As of: 3.10
+   * Commit: https://review.opendev.org/460679
+
+2. The positional argument ``<snapshot-name>`` of the ``volume snapshot create``
+   command is no longer optional.
+
+   Previously when the ``--volume`` option was
+   present ``<snapshot-name>`` defaulted to the ``--volume`` value.  When the
+   ``--volume`` option is not present now it defaults to the value of
+   ``<snapshot-name>``.
+
+   * As of: 3.10
+   * Bug: 1659894
+   * Commit: https://review.opendev.org/440497
+
+Release 3.0
+-----------
+
+1. Remove the ``osc_password`` authentication plugin.
+
+   This was the 'last-resort' plugin default that worked around an old default
+   Keystone configuration for the ``admin_endpoint`` and ``public_endpoint``.
+
+   * In favor of: ``password``
+   * As of: 3.0
+   * Removed in: n/a
+   * Bug: n/a
+   * Commit: https://review.opendev.org/332938
+
+
+Releases Before 3.0
+-------------------
+
+1. Rename command `openstack project usage list`
+
+   The `project` part of the command was pointless.
+
+   * In favor of: `openstack usage list` instead.
+   * As of: 1.0.2
+   * Removed in: TBD
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1406654
+   * Commit: https://review.opendev.org/#/c/147379/
+
+2. <type> should not be optional for command `openstack service create`
+
+   Previously, the command was `openstack service create <name> --type <type>`,
+   whereas now it is: `openstack service create <type> --name <name>`.
+   This bug also affected python-keystoneclient, and keystone.
+
+   * In favor of: making <type> a positional argument.
+   * As of: 1.0.2
+   * Removed in: TBD
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1404073
+   * Commit: https://review.opendev.org/#/c/143242/
+
+3. Command `openstack security group rule delete` now requires rule id
+
+   Previously, the command was `openstack security group rule delete --proto
+   <proto> [--src-ip <ip-address> --dst-port <port-range>] <group>`,
+   whereas now it is: `openstack security group rule delete <rule>`.
+
+   * In favor of: Using `openstack security group rule delete <rule>`.
+   * As of: 1.2.1
+   * Removed in: NA
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1450872
+   * Commit: https://review.opendev.org/#/c/179446/
+
+4. Command `openstack image create` does not update already existing image
+
+   Previously, the image create command updated already existing image if it had
+   same name. It disabled possibility to create multiple images with same name
+   and lead to potentially unwanted update of existing images by image create
+   command.
+   Now, update code was moved from create action to set action.
+
+   * In favor of: Create multiple images with same name (as glance does).
+   * As of: 1.5.0
+   * Removed in: NA
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1461817
+   * Commit: https://review.opendev.org/#/c/194654/
+
+5. Command `openstack network list --dhcp` has been removed
+
+   The --dhcp option to network list is not a logical use case of listing
+   networks, it lists agents.  Another command should be added in the future
+   to provide this functionality.  It is highly unlikely anyone uses this
+   feature as we don't support any other agent commands.  Use neutron
+   dhcp-agent-list-hosting-net command instead.
+
+   * In favor of: Create network agent list command in the future
+   * As of: 1.6.0
+   * Removed in: NA
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/472613
+   * Commit: https://review.opendev.org/#/c/194654/
+
+6. Plugin interface change for default API versions
+
+   Previously, the default version was set in the parsed arguments,
+   but this makes it impossible to tell what has been passed in at the
+   command line, set in an environment variable or is just the default.
+   Now, the module should have a DEFAULT_API_VERSION that contains the
+   value and it will be set after command line argument, environment
+   and OCC file processing.
+
+   * In favor of: DEFAULT_API_VERSION
+   * As of: 1.2.1
+   * Removed in: NA
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1453229
+   * Commit: https://review.opendev.org/#/c/181514/
+
+7. `image set` commands will no longer return the modified resource
+
+   Previously, modifying an image would result in the new image being displayed
+   to the user. To keep things consistent with other `set` commands, we will
+   no longer be showing the modified resource.
+
+   * In favor of: Use `set` then `show`
+   * As of: NA
+   * Removed in: NA
+   * Bug: NA
+   * Commit: NA
+
+8. `region` commands no longer support `url`
+
+   The Keystone team removed support for the `url` attribute from the client
+   and server side. Changes to the `create`, `set` and `list` commands for
+   regions have been affected.
+
+   * In favor of: NA
+   * As of 1.9.0
+   * Removed in: NA
+   * Bug: https://launchpad.net/bugs/1506841
+   * Commit: https://review.opendev.org/#/c/236736/
+
+9. `flavor set/unset` commands will no longer return the modified resource
+
+   Previously, modifying a flavor would result in the new flavor being displayed
+   to the user. To keep things consistent with other `set/unset` commands, we
+   will no longer be showing the modified resource.
+
+   * In favor of: Use `set/unset` then `show`
+   * As of: NA
+   * Removed in: NA
+   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065
+   * Commit: https://review.opendev.org/#/c/280663/
+
+10. `security group set` commands will no longer return the modified resource
+
+    Previously, modifying a security group would result in the new security group
+    being displayed to the user. To keep things consistent with other `set`
+    commands, we will no longer be showing the modified resource.
+
+    * In favor of: Use `set` then `show`
+    * As of: NA
+    * Removed in: NA
+    * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065
+    * Commit: https://review.opendev.org/#/c/281087/
+
+11. `compute agent set` commands will no longer return the modified resource
+
+    Previously, modifying an agent would result in the new agent being displayed
+    to the user. To keep things consistent with other `set` commands, we will
+    no longer be showing the modified resource.
+
+    * In favor of: Use `set` then `show`
+    * As of: NA
+    * Removed in: NA
+    * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065
+    * Commit: https://review.opendev.org/#/c/281088/
+
+12. `<version> <url> <md5hash>` should be optional for command `openstack
+    compute agent set`
+
+    Previously, the command was `openstack compute agent set <id> <version> <url>
+    <md5hash>`, whereas now it is: `openstack compute agent set <id> --version
+    <version> --url <url> --md5hash <md5hash>`.
+
+    * In favor of: making <version> <url> <md5hash> optional.
+    * As of: NA
+    * Removed in: NA
+    * Bug: NA
+    * Commit: https://review.opendev.org/#/c/328819/
+
+13. `aggregate set` commands will no longer return the modified resource
+
+    Previously, modifying an aggregate would result in the new aggregate being
+    displayed to the user. To keep things consistent with other `set` commands,
+    we will no longer be showing the modified resource.
+
+    * In favor of: Use `set` then `show`
+    * As of: NA
+    * Removed in: NA
+    * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065
+    * Commit: https://review.opendev.org/#/c/281089/
+
+14. Output of `ip floating list` command has changed.
+
+    When using Compute v2, the original output is:
+
+    .. code-block:: bash
+
+        # ip floating list
+
+        +----+--------+------------+----------+-------------+
+        | ID | Pool   | IP         | Fixed IP | Instance ID |
+        +----+--------+-----------------------+-------------+
+        |  1 | public | 172.24.4.1 | None     | None        |
+        +----+--------+------------+----------+-------------+
+
+    Now it changes to:
+
+    .. code-block:: bash
+
+        # ip floating list
+
+        +----+---------------------+------------------+-----------+--------+
+        | ID | Floating IP Address | Fixed IP Address | Server ID | Pool   |
+        +----+---------------------+------------------+-----------+--------+
+        |  1 | 172.24.4.1          | None             | None      | public |
+        +----+---------------------+------------------+-----------+--------+
+
+    When using Network v2, which is different from Compute v2. The output is:
+
+    .. code-block:: bash
+
+        # ip floating list
+
+        +--------------------------------------+---------------------+------------------+------+
+        | ID                                   | Floating IP Address | Fixed IP Address | Port |
+        +--------------------------------------+---------------------+------------------+------+
+        | 1976df86-e66a-4f96-81bd-c6ffee6407f1 | 172.24.4.3          | None             | None |
+        +--------------------------------------+---------------------+------------------+------+
+
+    * In favor of: Use `ip floating list` command
+    * As of: NA
+    * Removed in: NA
+    * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1519502
+    * Commit: https://review.opendev.org/#/c/277720/
+
+For Developers
+==============
+
+If introducing a backwards incompatible change, then add the tag:
+``BackwardsIncompatibleImpact`` to your git commit message, and if possible,
+update this file.
+
+To review all changes that are affected, use the following query:
+
+https://review.opendev.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z

doc/source/cli/command-list.rst

@@ -0,0 +1,11 @@
+.. _command-list:
+
+============
+Command List
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   command-objects/*

doc/source/cli/command-objects/access-rules.rst

@@ -0,0 +1,19 @@
+===========
+access rule
+===========
+
+Identity v3
+
+Access rules are fine-grained permissions for application credentials. An access
+rule comprises of a service type, a request path, and a request method. Access
+rules may only be created as attributes of application credentials, but they may
+be viewed and deleted independently.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: access rule delete
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: access rule list
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: access rule show

doc/source/cli/command-objects/access-token.rst

@@ -0,0 +1,10 @@
+============
+access token
+============
+
+An **access token** is used by the Identity service's OS-OAUTH1 extension. It
+is used by the **consumer** to request new Identity API tokens on behalf of the
+authorizing **user**. Applicable to Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: access token create

doc/source/cli/command-objects/address-group.rst

@@ -0,0 +1,12 @@
+=============
+address group
+=============
+
+An **address group** is a group of IPv4 or IPv6 address blocks which could be
+referenced as a remote source or destination when creating a security group
+rule.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: address group *

doc/source/cli/command-objects/address-scope.rst

@@ -0,0 +1,11 @@
+=============
+address scope
+=============
+
+An **address scope** is a scope of IPv4 or IPv6 addresses that belongs
+to a given project and may be shared between projects.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: address scope *

doc/source/cli/command-objects/aggregate.rst

@@ -0,0 +1,11 @@
+=========
+aggregate
+=========
+
+Host aggregates provide a mechanism to group hosts according to certain
+criteria.
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: aggregate *

doc/source/cli/command-objects/application-credentials.rst

@@ -0,0 +1,13 @@
+======================
+application credential
+======================
+
+Identity v3
+
+With application credentials, a user can grant their applications limited
+access to their cloud resources. Once created, users can authenticate with an
+application credential by using the ``v3applicationcredential`` auth type.
+
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: application credential *

doc/source/cli/command-objects/availability-zone.rst

@@ -0,0 +1,11 @@
+=================
+availability zone
+=================
+
+An **availability zone** is a logical partition of cloud block storage,
+compute and network services.
+
+Block Storage v2, Compute v2, Network v2
+
+.. autoprogram-cliff:: openstack.common
+   :command: availability zone list

doc/source/cli/command-objects/block-storage-cleanup.rst

@@ -0,0 +1,8 @@
+=============
+block storage
+=============
+
+Block Storage v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage cleanup

doc/source/cli/command-objects/block-storage-cluster.rst

@@ -0,0 +1,8 @@
+=====================
+block storage cluster
+=====================
+
+Block Storage v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage cluster *

doc/source/cli/command-objects/block-storage-log-level.rst

@@ -0,0 +1,8 @@
+=======================
+Block Storage Log Level
+=======================
+
+Block Storage v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage log level *

doc/source/cli/command-objects/block-storage-manage.rst

@@ -0,0 +1,11 @@
+====================
+Block Storage Manage
+====================
+
+Block Storage v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage volume manageable list
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage snapshot manageable list

doc/source/cli/command-objects/block-storage-resource-filter.rst

@@ -0,0 +1,8 @@
+=============================
+block storage resource filter
+=============================
+
+Block Storage v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: block storage resource filter *

doc/source/cli/command-objects/catalog.rst

@@ -0,0 +1,9 @@
+=======
+catalog
+=======
+
+A **catalog** lists OpenStack services that are available on the cloud.
+Applicable to Identity v2 and v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: catalog *

doc/source/cli/command-objects/command.rst

@@ -0,0 +1,10 @@
+=======
+command
+=======
+
+Internal
+
+Installed commands in the OSC process.
+
+.. autoprogram-cliff:: openstack.cli
+   :command: command *

doc/source/cli/command-objects/complete.rst

@@ -0,0 +1,28 @@
+========
+complete
+========
+
+The ``complete`` command is inherited from the `python-cliff` library, it can
+be used to generate a bash-completion script. Currently, the command will
+generate a script for bash versions 3 or 4. The bash-completion script is
+printed directly to standard out.
+
+Typical usage for this command is::
+
+  openstack complete | sudo tee /etc/bash_completion.d/osc.bash_completion > /dev/null
+
+It is highly recommended to install ``python-openstackclient`` from a package
+(``apt-get`` or ``yum``). In some distributions the package ``bash-completion`` is shipped
+as dependency, and the `openstack complete` command will be run as a post-install action,
+however not every distribution include this dependency and you might need to install
+``bash-completion`` package to enable autocomplete feature.
+
+complete
+--------
+
+print bash completion command
+
+.. program:: complete
+.. code:: bash
+
+    openstack complete

doc/source/cli/command-objects/compute-agent.rst

@@ -0,0 +1,8 @@
+=============
+compute agent
+=============
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: compute agent *

doc/source/cli/command-objects/compute-service.rst

@@ -0,0 +1,8 @@
+===============
+compute service
+===============
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: compute service *

doc/source/cli/command-objects/configuration.rst

@@ -0,0 +1,10 @@
+=============
+configuration
+=============
+
+Available for all services
+
+.. _configuration-show:
+
+.. autoprogram-cliff:: openstack.common
+   :command: configuration show

doc/source/cli/command-objects/consistency-group-snapshot.rst

@@ -0,0 +1,17 @@
+==========================
+consistency group snapshot
+==========================
+
+Block Storage v2, v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group snapshot create
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group snapshot delete
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group snapshot list
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group snapshot show

doc/source/cli/command-objects/consistency-group.rst

@@ -0,0 +1,26 @@
+=================
+consistency group
+=================
+
+Block Storage v2, v3
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group add volume
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group create
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group delete
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group list
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group remove volume
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group set
+
+.. autoprogram-cliff:: openstack.volume.v3
+   :command: consistency group show

doc/source/cli/command-objects/console-connection.rst

@@ -0,0 +1,10 @@
+==================
+console connection
+==================
+
+Server console connection information
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: console connection show

doc/source/cli/command-objects/console-log.rst

@@ -0,0 +1,10 @@
+===========
+console log
+===========
+
+Server console text dump
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: console log *

doc/source/cli/command-objects/console-url.rst

@@ -0,0 +1,10 @@
+===========
+console url
+===========
+
+Server remote console URL
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: console url *

doc/source/cli/command-objects/consumer.rst

@@ -0,0 +1,10 @@
+========
+consumer
+========
+
+An **consumer** is used by the Identity service's OS-OAUTH1 extension. It
+is used to create a **request token** and **access token**. Applicable to
+Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: consumer *

doc/source/cli/command-objects/container.rst

@@ -0,0 +1,26 @@
+=========
+container
+=========
+
+A **container** defines a namespace for **objects**. Applies to Object Storage v1
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container create
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container delete
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container list
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container save
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container set
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container show
+
+.. autoprogram-cliff:: openstack.object_store.v1
+   :command: container unset

doc/source/cli/command-objects/credential.rst

@@ -0,0 +1,8 @@
+==========
+credential
+==========
+
+Identity v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: credential *

doc/source/cli/command-objects/default-security-group-rule.rst

@@ -0,0 +1,11 @@
+===========================
+default security group rule
+===========================
+
+A **default security group rule** specifies the template of the security group
+rules which will be used by neutron to create rules in every new security group.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: default security group rule *

doc/source/cli/command-objects/domain.rst

@@ -0,0 +1,22 @@
+======
+domain
+======
+
+A **domain** is a collection of **users**, **groups**, and **projects**. Each
+**group** and **project** is owned by exactly one **domain**. Applies to
+Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: domain create
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: domain delete
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: domain list
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: domain set
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: domain show

doc/source/cli/command-objects/ec2-credentials-v2.rst

@@ -0,0 +1,6 @@
+=============================
+ec2 credentials (Identity v2)
+=============================
+
+.. autoprogram-cliff:: openstack.identity.v2
+   :command: ec2 credentials *

doc/source/cli/command-objects/ec2-credentials-v3.rst

@@ -0,0 +1,6 @@
+=============================
+ec2 credentials (Identity v3)
+=============================
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: ec2 credentials *

doc/source/cli/command-objects/endpoint-v2.rst

@@ -0,0 +1,6 @@
+======================
+endpoint (Identity v2)
+======================
+
+.. autoprogram-cliff:: openstack.identity.v2
+   :command: endpoint *

doc/source/cli/command-objects/endpoint-v3.rst

@@ -0,0 +1,24 @@
+======================
+endpoint (Identity v3)
+======================
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint add project
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint create
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint delete
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint list
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint remove project
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint set
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint show

doc/source/cli/command-objects/endpoint_group.rst

@@ -0,0 +1,10 @@
+==============
+endpoint group
+==============
+
+A **endpoint group** is used to create groups of endpoints that then
+can be used to filter the endpoints that are available to a project.
+Applicable to Identity v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: endpoint group *

doc/source/cli/command-objects/extension.rst

@@ -0,0 +1,10 @@
+=========
+extension
+=========
+
+Many OpenStack server APIs include API extensions that enable
+additional functionality.
+
+
+.. autoprogram-cliff:: openstack.common
+   :command: extension *

doc/source/cli/command-objects/federation-domain-project.rst

@@ -0,0 +1,11 @@
+=========================
+federation domain/project
+=========================
+
+Identity v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: federation domain *
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: federation project *

doc/source/cli/command-objects/federation-protocol.rst

@@ -0,0 +1,10 @@
+===================
+federation protocol
+===================
+
+A **federation protocol** is used by the Identity service's OS-FEDERATION
+extension. It is used by **identity providers** and **mappings**. Applicable to
+Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: federation protocol *

doc/source/cli/command-objects/flavor.rst

@@ -0,0 +1,8 @@
+======
+flavor
+======
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: flavor *

doc/source/cli/command-objects/floating-ip-pool.rst

@@ -0,0 +1,8 @@
+================
+floating ip pool
+================
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip pool *

doc/source/cli/command-objects/floating-ip-port-forwarding.rst

@@ -0,0 +1,9 @@
+===========================
+floating ip port forwarding
+===========================
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip port forwarding *
+

doc/source/cli/command-objects/floating-ip.rst

@@ -0,0 +1,26 @@
+===========
+floating ip
+===========
+
+Network v2
+
+.. NOTE(efried): have to list these out one by one; 'floating ip' pulls in
+                 ... pool and ... port forwarding.
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip create
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip delete
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip list
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip set
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip show
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: floating ip unset

doc/source/cli/command-objects/group.rst

@@ -0,0 +1,8 @@
+=====
+group
+=====
+
+Identity v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: group *

doc/source/cli/command-objects/host.rst

@@ -0,0 +1,10 @@
+====
+host
+====
+
+Compute v2
+
+The physical computer running a hypervisor.
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: host *

doc/source/cli/command-objects/hypervisor-stats.rst

@@ -0,0 +1,8 @@
+================
+hypervisor stats
+================
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: hypervisor stats *

doc/source/cli/command-objects/hypervisor.rst

@@ -0,0 +1,14 @@
+==========
+hypervisor
+==========
+
+Compute v2
+
+.. NOTE(efried): have to list these out one by one; 'hypervisor *' pulls in
+                 ... stats.
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: hypervisor list
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: hypervisor show

doc/source/cli/command-objects/identity-provider.rst

@@ -0,0 +1,10 @@
+=================
+identity provider
+=================
+
+An **identity provider** is used by the Identity service's OS-FEDERATION
+extension. It is used by **federation protocols** and **mappings**. Applicable
+to Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: identity provider *

doc/source/cli/command-objects/image-member.rst

@@ -0,0 +1,14 @@
+============
+image member
+============
+
+Image v2
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image add project
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image remove project
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image member list

doc/source/cli/command-objects/image-metadef.rst

@@ -0,0 +1,50 @@
+=============
+image metadef
+=============
+
+Image v2
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef namespace create
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef namespace delete
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef namespace list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef namespace set
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef namespace show
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef resource type list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object create
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object show
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object delete
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object update
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef object property show
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef property create
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef property list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image metadef property show

doc/source/cli/command-objects/image-task.rst

@@ -0,0 +1,11 @@
+==========
+image task
+==========
+
+Image v2
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image task list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image task show

doc/source/cli/command-objects/image-v1.rst

@@ -0,0 +1,6 @@
+========
+image v1
+========
+
+.. autoprogram-cliff:: openstack.image.v1
+   :command: image *

doc/source/cli/command-objects/image-v2.rst

@@ -0,0 +1,32 @@
+=====
+image
+=====
+
+Image v2
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image create
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image delete
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image list
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image save
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image set
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image unset
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image show
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image stage
+
+.. autoprogram-cliff:: openstack.image.v2
+   :command: image import

doc/source/cli/command-objects/implied_role.rst

@@ -0,0 +1,8 @@
+============
+implied role
+============
+
+Identity v3
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: implied role *

doc/source/cli/command-objects/ip-availability.rst

@@ -0,0 +1,8 @@
+===============
+ip availability
+===============
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: ip availability *

doc/source/cli/command-objects/keypair.rst

@@ -0,0 +1,13 @@
+=======
+keypair
+=======
+
+The badly named keypair is really the public key of an OpenSSH key pair to be
+used for access to created servers. You can also create a private key for
+access to a created server by not passing any argument to the keypair create
+command.
+
+Compute v2
+
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: keypair *

doc/source/cli/command-objects/limit.rst

@@ -0,0 +1,10 @@
+=====
+limit
+=====
+
+Identity v3
+
+Limits are used to specify project-specific limits thresholds of resources.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: limit *

doc/source/cli/command-objects/limits.rst

@@ -0,0 +1,11 @@
+======
+limits
+======
+
+The Compute and Block Storage APIs have resource usage limits.
+
+Block Storage v2, v3; Compute v2
+
+
+.. autoprogram-cliff:: openstack.common
+   :command: limits *

doc/source/cli/command-objects/local-ip-association.rst

@@ -0,0 +1,11 @@
+=============================================
+Local IP Associations (local_ip_associations)
+=============================================
+
+The resource lets users assign Local IPs to user Ports.
+This is a sub-resource of the Local IP resource.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: local ip association *

doc/source/cli/command-objects/local-ip.rst

@@ -0,0 +1,12 @@
+=====================
+Local IPs (local_ips)
+=====================
+
+Extension that allows users to create a virtual IP that can later be assigned
+to multiple ports/VMs (similar to anycast IP) and is guaranteed to only be
+reachable within the same physical server/node boundaries
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: local ip *

doc/source/cli/command-objects/mapping.rst

@@ -0,0 +1,10 @@
+=======
+mapping
+=======
+
+A **mapping** is used by the Identity service's OS-FEDERATION
+extension. It is used by **federation protocols** and **identity providers**.
+Applicable to Identity v3.
+
+.. autoprogram-cliff:: openstack.identity.v3
+   :command: mapping *

doc/source/cli/command-objects/module.rst

@@ -0,0 +1,10 @@
+======
+module
+======
+
+Internal
+
+Installed Python modules in the OSC process.
+
+.. autoprogram-cliff:: openstack.cli
+   :command: module *

doc/source/cli/command-objects/network-agent.rst

@@ -0,0 +1,14 @@
+=============
+network agent
+=============
+
+A **network agent** is an agent that handles various tasks used to
+implement virtual networks. These agents include neutron-dhcp-agent,
+neutron-l3-agent, neutron-metering-agent, and neutron-lbaas-agent,
+among others. The agent is available when the alive status of the
+agent is "True".
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network agent *

doc/source/cli/command-objects/network-auto-allocated-topology.rst

@@ -0,0 +1,14 @@
+===============================
+network auto allocated topology
+===============================
+
+An **auto allocated topology** allows admins to quickly set up external
+connectivity for end-users. Only one auto allocated topology is allowed per
+project. For more information on how to set up the resources required
+for auto allocated topology review :neutron-doc:`the documentation
+<admin/config-auto-allocation>`.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network auto allocated topology *

doc/source/cli/command-objects/network-flavor-profile.rst

@@ -0,0 +1,15 @@
+======================
+network flavor profile
+======================
+
+A **network flavor profile** allows administrators to create, delete, list,
+show and update network service profile, which details a framework to enable
+operators to configure and users to select from different abstract
+representations of a service implementation in the Networking service.
+It decouples the logical configuration from its instantiation enabling
+operators to create user options according to deployment needs.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor profile *

doc/source/cli/command-objects/network-flavor.rst

@@ -0,0 +1,33 @@
+==============
+network flavor
+==============
+
+A **network flavor** extension allows the user selection of operator-curated
+flavors during resource creations. It allows administrators to create network
+service flavors.
+
+Network v2
+
+.. NOTE(efried): have to list these out one by one; 'network flavor' pulls in
+                 ... profile *.
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor add profile
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor create
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor delete
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor list
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor remove profile
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor set
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network flavor show

doc/source/cli/command-objects/network-l3-conntrack-helper.rst

@@ -0,0 +1,8 @@
+===========================
+network l3 conntrack helper
+===========================
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network l3 conntrack helper *

doc/source/cli/command-objects/network-meter-rule.rst

@@ -0,0 +1,13 @@
+==================
+network meter rule
+==================
+
+A **meter rule** sets the rule for
+a meter to measure traffic for a specific IP range.
+The following uses **meter** and requires the L3
+metering extension.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network meter rule *

doc/source/cli/command-objects/network-meter.rst

@@ -0,0 +1,24 @@
+=============
+network meter
+=============
+
+A **network meter** allows operators to measure
+traffic for a specific IP range. The following commands
+are specific to the L3 metering extension.
+
+Network v2
+
+.. NOTE(efried): have to list these out one by one; 'network meter *' pulls in
+                 ... rule *.
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network meter create
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network meter delete
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network meter list
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network meter show

doc/source/cli/command-objects/network-qos-policy.rst

@@ -0,0 +1,11 @@
+==================
+network qos policy
+==================
+
+A **Network QoS policy** groups a number of Network QoS rules, applied to a
+network or a port.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos policy *

doc/source/cli/command-objects/network-qos-rule-type.rst

@@ -0,0 +1,11 @@
+=====================
+network qos rule type
+=====================
+
+A **Network QoS rule type** is a specific Network QoS rule type available to be
+used.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule type *

doc/source/cli/command-objects/network-qos-rule.rst

@@ -0,0 +1,28 @@
+================
+network qos rule
+================
+
+A **Network QoS rule** specifies a rule defined in a Network QoS policy; its
+type is defined by the parameter 'type'. Can be assigned, within a Network QoS
+policy, to a port or a network. Each Network QoS policy can contain several
+rules, each of them
+
+Network v2
+
+.. NOTE(efried): have to list these out one by one; 'network qos rule *' pulls
+                 network qos rule type *.
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule create
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule delete
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule list
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule set
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network qos rule show

doc/source/cli/command-objects/network-rbac.rst

@@ -0,0 +1,12 @@
+============
+network rbac
+============
+
+A **network rbac** is a Role-Based Access Control (RBAC) policy for
+network resources. It enables both operators and users to grant access
+to network resources for specific projects.
+
+Network v2
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network rbac *

doc/source/cli/command-objects/network-segment.rst

@@ -0,0 +1,28 @@
+===============
+network segment
+===============
+
+A **network segment** is an isolated Layer 2 segment within a network.
+A network may contain multiple network segments. Depending on the
+network configuration, Layer 2 connectivity between network segments
+within a network may not be guaranteed.
+
+Network v2
+
+.. NOTE(efried): have to list these out one by one; 'network segment *' pulls
+                 ... range *.
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network segment create
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network segment delete
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network segment list
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network segment set
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network segment show

doc/source/cli/command-objects/network-service-provider.rst

@@ -0,0 +1,13 @@
+========================
+network service provider
+========================
+
+A **network service provider** is a particular driver that implements a
+networking service
+
+Network v2
+
+.. _network_service_provider_list:
+
+.. autoprogram-cliff:: openstack.network.v2
+   :command: network service provider list