OpenStackClient Plugin Library

4.4.0 · active · verified Sun Apr 12

osc-lib is a Python library that provides common support modules for writing plugins for the OpenStackClient (OSC), the unified command-line client for OpenStack. It offers functionalities like command definitions, session management, and utility functions that plugin developers can leverage. The library is actively maintained and currently at version 4.4.0, with regular updates aligning with OpenStack development cycles.

Warnings

breaking Many core modules and classes, such as `Command`, `Session`, and API utilities, were relocated from the `openstackclient.*` namespace to `osc_lib.*` after OpenStackClient 2.4.0. Direct imports from the old `openstackclient` paths for these components will cause `ImportError` or unexpected behavior in newer versions of `osc-lib`.
Fix: Update import statements from `openstackclient.api.api`, `openstackclient.api.auth`, `openstackclient.common.command`, `openstackclient.common.commandmanager`, `openstackclient.common.exceptions`, `openstackclient.common.logs`, `openstackclient.common.session`, `openstackclient.common.utils`, etc., to their corresponding `osc_lib` paths, e.g., `from osc_lib.command.command import Command`.
gotcha `osc-lib` is a library for developing plugins and extensions for the OpenStackClient, not a standalone client for direct interaction with OpenStack APIs. Attempting to use `osc-lib` directly as a full client without the OpenStackClient framework will lead to missing dependencies and incorrect usage patterns.
Fix: Utilize `osc-lib` components within the context of an OpenStackClient plugin. For direct OpenStack API interaction, use the `openstacksdk` library.
deprecated The `osc_lib.utils.backward_compat_col_lister` function explicitly logs warnings when older, deprecated column names are used in CLI output. While the function provides backward compatibility, relying on deprecated column names for parsing or display in plugins may lead to future breakage once full support is removed.
Fix: Review and update plugin code to use the current, recommended column names as defined by OpenStackClient and its services, rather than relying on backward-compatible names. Monitor `osc-lib` release notes for details on specific column deprecations.

Install

pip install osc-lib Install from PyPI

Imports

Command
```
from osc_lib.command.command import Command
```
Many core components, including 'Command' and 'Lister', were moved from the 'openstackclient.common' namespace to 'osc_lib.command' after OpenStackClient 2.4.0.
Session
```
from osc_lib.session import Session
```
Session management utilities were relocated to 'osc_lib.session' for plugin development.
APIClient
```
from osc_lib.api.api import APIClient
```
API interaction utilities moved from 'openstackclient.api' to 'osc_lib.api'.
build_auth_plugins_option_parser
```
from osc_lib.api.auth import build_auth_plugins_option_parser
```
Authentication-related functions and parsers were moved to 'osc_lib.api.auth'.
backward_compat_col_lister
```
from osc_lib.utils import backward_compat_col_lister
```
Common utilities, including those for column handling, are now found under 'osc_lib.utils'.

Quickstart

This quickstart demonstrates how to define a custom OpenStackClient command using `osc-lib`. It outlines extending `osc_lib.command.command.Command` to create a new CLI action, including argument parsing and action execution. Note that `osc-lib` is primarily for building plugins, so this code requires an OpenStackClient environment to run fully, but the example shows the core structure for plugin development. The `MockApp` and `MockAppArgs` classes are included to make the example runnable for demonstrating the `take_action` logic, though they don't replicate a full OpenStackClient runtime environment.

import argparse
from osc_lib.command.command import Command

class MyCustomCommand(Command):
    """My custom OpenStackClient command."""

    def get_parser(self, prog_name):
        parser = super(MyCustomCommand, self).get_parser(prog_name)
        parser.add_argument(
            'name',
            metavar='<name>',
            help='Name to greet'
        )
        return parser

    def take_action(self, parsed_args):
        # In a real OpenStackClient plugin, 'self.app' and 'self.client_manager'
        # would provide access to OpenStack services and configuration.
        # For this example, we'll simulate the output.
        greeting = f"Hello, {parsed_args.name}! This is a custom command from osc-lib."
        return {}, {'Result': greeting}

# Example of how to instantiate and call (for demonstration, not runnable without OSC context)
if __name__ == '__main__':
    # Simulate `app` and `app_args` that `cliff` (which OSC uses) would pass
    class MockApp:
        NAME = 'openstack'
        def __init__(self):
            self.options = argparse.Namespace()
            self.options.debug = False
    
    class MockAppArgs:
        pass

    mock_app = MockApp()
    mock_app_args = MockAppArgs()

    cmd_instance = MyCustomCommand(mock_app, mock_app_args)
    
    # Simulate parsed arguments
    parsed_args = cmd_instance.get_parser('my_command').parse_args(['World'])
    
    # Execute the command's action
    # In a real setup, this would be called by the OpenStackClient framework
    _columns, _data = cmd_instance.take_action(parsed_args)
    print(f"Command output: {_data['Result']}")

view raw JSON →