{"id":5000,"library":"osc-lib","title":"OpenStackClient Plugin Library","description":"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.","status":"active","version":"4.4.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/osc-lib","tags":["openstack","client","plugin","cli","library"],"install":[{"cmd":"pip install osc-lib","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"Many core components, including 'Command' and 'Lister', were moved from the 'openstackclient.common' namespace to 'osc_lib.command' after OpenStackClient 2.4.0.","wrong":"from openstackclient.common.command import Command","symbol":"Command","correct":"from osc_lib.command.command import Command"},{"note":"Session management utilities were relocated to 'osc_lib.session' for plugin development.","wrong":"from openstackclient.common.session import Session","symbol":"Session","correct":"from osc_lib.session import Session"},{"note":"API interaction utilities moved from 'openstackclient.api' to 'osc_lib.api'.","wrong":"from openstackclient.api.api import APIClient","symbol":"APIClient","correct":"from osc_lib.api.api import APIClient"},{"note":"Authentication-related functions and parsers were moved to 'osc_lib.api.auth'.","wrong":"from openstackclient.api.auth import build_auth_plugins_option_parser","symbol":"build_auth_plugins_option_parser","correct":"from osc_lib.api.auth import build_auth_plugins_option_parser"},{"note":"Common utilities, including those for column handling, are now found under 'osc_lib.utils'.","wrong":"from openstackclient.common.utils import backward_compat_col_lister","symbol":"backward_compat_col_lister","correct":"from osc_lib.utils import backward_compat_col_lister"}],"quickstart":{"code":"import argparse\nfrom osc_lib.command.command import Command\n\nclass MyCustomCommand(Command):\n    \"\"\"My custom OpenStackClient command.\"\"\"\n\n    def get_parser(self, prog_name):\n        parser = super(MyCustomCommand, self).get_parser(prog_name)\n        parser.add_argument(\n            'name',\n            metavar='<name>',\n            help='Name to greet'\n        )\n        return parser\n\n    def take_action(self, parsed_args):\n        # In a real OpenStackClient plugin, 'self.app' and 'self.client_manager'\n        # would provide access to OpenStack services and configuration.\n        # For this example, we'll simulate the output.\n        greeting = f\"Hello, {parsed_args.name}! This is a custom command from osc-lib.\"\n        return {}, {'Result': greeting}\n\n# Example of how to instantiate and call (for demonstration, not runnable without OSC context)\nif __name__ == '__main__':\n    # Simulate `app` and `app_args` that `cliff` (which OSC uses) would pass\n    class MockApp:\n        NAME = 'openstack'\n        def __init__(self):\n            self.options = argparse.Namespace()\n            self.options.debug = False\n    \n    class MockAppArgs:\n        pass\n\n    mock_app = MockApp()\n    mock_app_args = MockAppArgs()\n\n    cmd_instance = MyCustomCommand(mock_app, mock_app_args)\n    \n    # Simulate parsed arguments\n    parsed_args = cmd_instance.get_parser('my_command').parse_args(['World'])\n    \n    # Execute the command's action\n    # In a real setup, this would be called by the OpenStackClient framework\n    _columns, _data = cmd_instance.take_action(parsed_args)\n    print(f\"Command output: {_data['Result']}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":"Post OpenStackClient 2.4.0 and all `osc-lib` versions."},{"fix":"Utilize `osc-lib` components within the context of an OpenStackClient plugin. For direct OpenStack API interaction, use the `openstacksdk` library.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Versions with `osc_lib.utils.backward_compat_col_lister` (e.g., 4.x.x)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}