# Resource

Base resource class.

The `Resource` class is a base class that represent a remote resource. The attributes that comprise a request or response for this resource are specified as class members on the Resource subclass where their values are of a component type, including `Body`, `Header`, and `URI`.

For update management, `Resource` employs a series of `_ComponentManager` instances to look after the attributes of that particular component type. This is particularly useful for Body and Header types, so that only the values necessary are sent in requests to the server.

When making requests, each of the managers are looked at to gather the necessary URI, body, and header data to build a request to be sent via keystoneauth’s sessions. Responses from keystoneauth are then converted into this Resource class’ appropriate components and types and then returned to the caller.

## Components

class openstack.resource.Body(name, type=None, default=None, alias=None, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=None)

class openstack.resource.Header(name, type=None, default=None, alias=None, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=None)

class openstack.resource.URI(name, type=None, default=None, alias=None, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=None)

## The Resource class

class openstack.resource.Resource(_synchronized=False, connection=None, **attrs)

  The base resource

  Parameters:

    - _synchronized (bool) – This is not intended to be used directly. See `new()` and `existing()`.

    - connection (openstack.connection.Connection) – Reference to the Connection being used. Defaults to None to allow Resource objects to be used without an active Connection, such as in unit tests. Use of `self._connection` in Resource code should protect itself with a check for None.

  resource_key = None

    Singular form of key for resource.

  resources_key = None

    Plural form of key for resource.

  pagination_key = None

    Key used for pagination links

  id

    The ID of this resource.

  name

    The name of this resource.

  location

    The OpenStack location of this resource.

  base_path = ''

    The base part of the URI for this resource.

  allow_create = False

    Allow create operation for this resource.

  allow_fetch = False

    Allow get operation for this resource.

  allow_commit = False

    Allow update operation for this resource.

  allow_delete = False

    Allow delete operation for this resource.

  allow_list = False

    Allow list operation for this resource.

  allow_head = False

    Allow head operation for this resource.

  allow_patch = False

    Allow patch operation for this resource.

  allow_empty_commit = False

    Commits happen without header or body being dirty.

  commit_method = 'PUT'

    Method for committing a resource (PUT, PATCH, POST)

  create_method = 'POST'

    Method for creating a resource (POST, PUT)

  commit_jsonpatch = False

    Whether commit uses JSON patch format.

  requires_id = True

    Do calls for this resource require an id

  create_requires_id = None

    Whether create requires an ID (determined from method if None).

  create_exclude_id_from_body = False

    Whether create should exclude ID in the body of the request.

  has_body = True

    Do responses for this resource have bodies

  create_returns_body = None

    Does create returns a body (if False requires ID), defaults to has_body

  microversion = None

    API microversion (string or None) this Resource was loaded with

  keys()

    Return a set-like object providing a view on the dict’s keys.

  items()

    Return a set-like object providing a view on the dict’s items.

  classmethod new(**kwargs)

    Create a new instance of this resource.

    When creating the instance set the `_synchronized` parameter of `Resource` to `False` to indicate that the resource does not yet exist on the server side. This marks all attributes passed in `**kwargs` as “dirty” on the resource, and thusly tracked as necessary in subsequent calls such as `update()`.

    Parameters:

      kwargs (dict) – Each of the named arguments will be set as attributes on the resulting Resource object.

  classmethod existing(connection=None, **kwargs)

    Create an instance of an existing remote resource.

    When creating the instance set the `_synchronized` parameter of `Resource` to `True` to indicate that it represents the state of an existing server-side resource. As such, all attributes passed in `**kwargs` are considered “clean”, such that an immediate `update()` call would not generate a body of attributes to be modified on the server.

    Parameters:

      kwargs (dict) – Each of the named arguments will be set as attributes on the resulting Resource object.

  to_dict(body=True, headers=True, computed=True, ignore_none=False, original_names=False, _to_munch=False)

    Return a dictionary of this resource’s contents

    Parameters:

      - body (bool) – Include the `Body` attributes in the returned dictionary.

      - headers (bool) – Include the `Header` attributes in the returned dictionary.

      - computed (bool) – Include the `Computed` attributes in the returned dictionary.

      - ignore_none (bool) – When True, exclude key/value pairs where the value is None. This will exclude attributes that the server hasn’t returned.

      - original_names (bool) – When True, use attribute names as they were received from the server.

      - _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

    Returns:

      A dictionary of key/value pairs where keys are named as they exist as attributes of this class.

  toDict(body=True, headers=True, computed=True, ignore_none=False, original_names=False, _to_munch=False)

    Return a dictionary of this resource’s contents

    Parameters:

      - body (bool) – Include the `Body` attributes in the returned dictionary.

      - headers (bool) – Include the `Header` attributes in the returned dictionary.

      - computed (bool) – Include the `Computed` attributes in the returned dictionary.

      - ignore_none (bool) – When True, exclude key/value pairs where the value is None. This will exclude attributes that the server hasn’t returned.

      - original_names (bool) – When True, use attribute names as they were received from the server.

      - _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

    Returns:

      A dictionary of key/value pairs where keys are named as they exist as attributes of this class.

  copy(body=True, headers=True, computed=True, ignore_none=False, original_names=False, _to_munch=False)

    Return a dictionary of this resource’s contents

    Parameters:

      - body (bool) – Include the `Body` attributes in the returned dictionary.

      - headers (bool) – Include the `Header` attributes in the returned dictionary.

      - computed (bool) – Include the `Computed` attributes in the returned dictionary.

      - ignore_none (bool) – When True, exclude key/value pairs where the value is None. This will exclude attributes that the server hasn’t returned.

      - original_names (bool) – When True, use attribute names as they were received from the server.

      - _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

    Returns:

      A dictionary of key/value pairs where keys are named as they exist as attributes of this class.

  create(session, prepend_key=True, base_path=None, *, resource_request_key=None, resource_response_key=None, microversion=None, **params)

    Create a remote resource based on this instance.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - prepend_key – A boolean indicating whether the resource_key should be prepended in a resource creation request. Default to True.

      - base_path (str) – Base part of the URI for creating resources, if different from `base_path`.

      - resource_request_key (str) – Overrides the usage of self.resource_key when prepending a key to the request body. Ignored if prepend_key is false.

      - resource_response_key (str) – Overrides the usage of self.resource_key when processing response bodies. Ignored if prepend_key is false.

      - microversion (str) – API version to override the negotiated one.

      - params (dict) – Additional params to pass.

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_create` is not set to `True`.

  classmethod bulk_create(session, data, prepend_key=True, base_path=None, *, microversion=None, **params)

    Create multiple remote resources based on this class and data.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - data – list of dicts, which represent resources to create.

      - prepend_key – A boolean indicating whether the resource_key should be prepended in a resource creation request. Default to True.

      - base_path (str) – Base part of the URI for creating resources, if different from `base_path`.

      - microversion (str) – API version to override the negotiated one.

      - params (dict) – Additional params to pass.

    Returns:

      A generator of `Resource` objects.

    Raises:

      `MethodNotSupported` if `Resource.allow_create` is not set to `True`.

  fetch(session, requires_id=True, base_path=None, error_message=None, skip_cache=False, *, resource_response_key=None, microversion=None, **params)

    Get a remote resource based on this instance.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - requires_id (boolean) – A boolean indicating whether resource ID should be part of the requested URI.

      - base_path (str) – Base part of the URI for fetching resources, if different from `base_path`.

      - error_message (str) – An Error message to be returned if requested object does not exist.

      - skip_cache (bool) – A boolean indicating whether optional API cache should be skipped for this invocation.

      - resource_response_key (str) – Overrides the usage of self.resource_key when processing the response body.

      - microversion (str) – API version to override the negotiated one.

      - params (dict) – Additional parameters that can be consumed.

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_fetch` is not set to `True`.

    Raises:

      `NotFoundException` if the resource was not found.

  head(session, base_path=None, *, microversion=None)

    Get headers from a remote resource based on this instance.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - base_path (str) – Base part of the URI for fetching resources, if different from `base_path`.

      - microversion (str) – API version to override the negotiated one.

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_head` is not set to `True`.

    Raises:

      `NotFoundException` if the resource was not found.

  property requires_commit

    Whether the next commit() call will do anything.

  commit(session, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None, *, microversion=None, **kwargs)

    Commit the state of the instance to the remote resource.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - prepend_key – A boolean indicating whether the resource_key should be prepended in a resource update request. Default to True.

      - retry_on_conflict (bool) – Whether to enable retries on HTTP CONFLICT (409). Value of `None` leaves the Adapter defaults.

      - base_path (str) – Base part of the URI for modifying resources, if different from `base_path`.

      - microversion (str) – API version to override the negotiated one.

      - kwargs (dict) – Parameters that will be passed to _prepare_request()

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_commit` is not set to `True`.

  patch(session, patch=None, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None, *, microversion=None)

    Patch the remote resource.

    Allows modifying the resource by providing a list of JSON patches to apply to it. The patches can use both the original (server-side) and SDK field names.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - patch – Additional JSON patch as a list or one patch item. If provided, it is applied on top of any changes to the current resource.

      - prepend_key – A boolean indicating whether the resource_key should be prepended in a resource update request. Default to True.

      - retry_on_conflict (bool) – Whether to enable retries on HTTP CONFLICT (409). Value of `None` leaves the Adapter defaults.

      - base_path (str) – Base part of the URI for modifying resources, if different from `base_path`.

      - microversion (str) – API version to override the negotiated one.

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_patch` is not set to `True`.

  delete(session, error_message=None, *, microversion=None, **kwargs)

    Delete the remote resource based on this instance.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - microversion (str) – API version to override the negotiated one.

      - kwargs (dict) – Parameters that will be passed to _prepare_request()

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_commit` is not set to `True`.

    Raises:

      `NotFoundException` if the resource was not found.

  classmethod list(session, paginated=True, base_path=None, allow_unknown_params=False, *, microversion=None, headers=None, max_items=None, **params)

    This method is a generator which yields resource objects.

    This resource object list generator handles pagination and takes query params for response filtering.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - paginated (bool) – `True` if a GET to this resource returns a paginated series of responses, or `False` if a GET returns only one page of data. When paginated is False only one page of data will be returned regardless of the API’s support of pagination.

      - base_path (str) – Base part of the URI for listing resources, if different from `base_path`.

      - allow_unknown_params (bool) – `True` to accept, but discard unknown query parameters. This allows getting list of ‘filters’ and passing everything known to the server. `False` will result in validation exception when unknown query parameters are passed.

      - microversion (str) – API version to override the negotiated one.

      - headers (dict) – Additional headers to inject into the HTTP request.

      - max_items (int) – The maximum number of items to return. Typically this must be used with `paginated=True`.

      - params (dict) – These keyword arguments are passed through the `_transpose()` method to find if any of them match expected query parameters to be sent in the params argument to `get()`. They are additionally checked against the `base_path` format string to see if any path fragments need to be filled in by the contents of this argument. Parameters supported as filters by the server side are passed in the API call, remaining parameters are applied as filters to the retrieved results.

    Returns:

      A generator of `Resource` objects.

    Raises:

      `MethodNotSupported` if `Resource.allow_list` is not set to `True`.

    Raises:

      `InvalidResourceQuery` if query contains invalid params.

  classmethod find(session, name_or_id, ignore_missing=True, list_base_path=None, *, microversion=None, all_projects=None, **params)

    Find a resource by its name or id.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - name_or_id – This resource’s identifier, if needed by the request. The default is `None`.

      - ignore_missing (bool) – When set to `False` `NotFoundException` will be raised when the resource does not exist. When set to `True`, None will be returned when attempting to find a nonexistent resource.

      - list_base_path (str) – base_path to be used when need listing resources.

      - microversion (str) – API version to override the negotiated one.

      - params (dict) – Any additional parameters to be passed into underlying methods, such as to `existing()` in order to pass on URI parameters.

    Returns:

      The `Resource` object matching the given name or id or None if nothing matches.

    Raises:

      `openstack.exceptions.DuplicateResource` if more than one resource is found for this request.

    Raises:

      `openstack.exceptions.NotFoundException` if nothing is found and ignore_missing is `False`.

this page last updated: 2026-01-16 23:06:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.