openstack/openstacksdk
Code Issues Proposed changes
openstacksdk/doc/source/contributor/layout.rst
Monty Taylor 4bad718783
Rework config and rest layers 
This is a large and invasive change to the underlying guts. Most casual
use should not notice a difference, but advanced users, especially those
using the Profile or Authenticator interfaces or making use of pluggable
providers will be broken.

The overall intent is to align directly on top of the mechanisms that
came from os-client-config for config and to use keystoneauth1's Adapter
interface to make use of the canonical implementations of such things as
service and version discovery. The end goal is that openstacksdk
provides the REST interaction layer for python-openstackclient, shade,
Ansible and nodepool.

Replace profile with openstack.config

os-client-config is used by shade and python-openstackclient to read
and process configuration. openstacksdk also can use the
os-client-config interface, but translates it internally into the
Profile object. As os-client-config has been injested into
openstack.config, remove Profile and just use the config classes.

Make proxy subclass of adapter

This gives every service a generic passthrough for REST calls, which
means we can map unknown service-type values to a generic proxy.

Strip endpoint_filter

We're passing Adapters around, not sessions. Doing so means that
self.service and endpoint_filter have become unnecessary.

Rename _Request.uri to _Request.url

This is a stepping-stone to replacing _Request with requests.Request and
using requests.Session.prepare_request inside of _prepare_request.

Rename service proxy instances to match their official service-type.

Aliases are kept for the old versions, but make the canonical versions
match the official name.

Rename bare_metal to baremetal
Rename cluster to clustering
Rename block_store to block_storage
Rename telemetry to meter

Create generic proxies for all services in STA

Every service listed in service types authority is an OpenStack service.
Even if we don't know about it in SDK, we should at the very least have
a low-level Adapter for it so that people can use REST calls while
waiting on the SDK to add higher-level constructs.

The pypy jobs are happily green. Run them as voting rather than
non-voting.

Add syntatic sugar alias for making connections

Typing:

  import openstack.connection
  conn = openstack.connection.Connection(cloud='example')

is annoying. This allows:

  import openstack
  conn = openstack.connect(cloud='example')

Use task_manager and Adapter from shade

As a stepping-stone towards shade and sdk codepaths being rationalized,
we need to get SDK using the Adapter from shade that submits requests
into the TaskManager. For normal operation this is a passthrough/no-op
sort of thing, but it's essential for high-volume consumers such as
nodepool.

This exposes a bunch of places in tests where we're mocking a bit too
deeply. We should go back through and fix all of those via
requests_mock, but that's WAY too much for today.

This was a 'for later' task, but it turns out that the move to Adapter
was causing exceptions to be thrown that were not the exceptions that
were intended to be caught in the SDK layer, which was causing
functional tests of things like GET operations to fail. So it became a
today task.

Change-Id: I7b46e263a76d84573bdfbbece57b1048764ed939
2017-11-15 11:46:50 -06:00

4.2 KiB
Raw Blame History

How the SDK is organized

The following diagram shows how the project is laid out.

layout.txt

Resource

The openstack.resource.Resource base class is the building block of any service implementation. Resource objects correspond to the resources each service's REST API works with, so the openstack.compute.v2.server.Server subclass maps to the compute service's https://openstack:1234/v2/servers resource.

The base Resource contains methods to support the typical CRUD operations supported by REST APIs, and handles the construction of URLs and calling the appropriate HTTP verb on the given Adapter.

Values sent to or returned from the service are implemented as attributes on the Resource subclass with type openstack.resource.prop. The prop is created with the exact name of what the API expects, and can optionally include a type to be validated against on requests. You should choose an attribute name that follows PEP-8, regardless of what the server-side expects, as this prop becomes a mapping between the two.:

is_public = resource.prop('os-flavor-access:is_public', type=bool)

There are six additional attributes which the Resource class checks before making requests to the REST API. allow_create, allow_retreive, allow_update, allow_delete, allow_head, and allow_list are set to True or False, and are checked before making the corresponding method call.

The base_path attribute should be set to the URL which corresponds to this resource. Many base_paths are simple, such as "/servers". For base_paths which are composed of non-static information, Python's string replacement is used, e.g., base_path = "/servers/%(server_id)s/ips".

resource_key and resources_key are attributes to set when a Resource returns more than one item in a response, or otherwise requires a key to obtain the response value. For example, the Server class sets resource_key = "server" as an individual Server is stored in a dictionary keyed with the singular noun, and resource_keys = "servers" as multiple Servers are stored in a dictionary keyed with the plural noun in the response.

Proxy

Each service implements a Proxy class, within the openstack/<program_name>/vX/_proxy.py module. For example, the v2 compute service's Proxy exists in openstack/compute/v2/_proxy.py.

This Proxy class contains a ~keystoneauth1.adapter.Adapter and provides a higher-level interface for users to work with via a ~openstack.connection.Connection instance. Rather than requiring users to maintain their own Adapter and work with lower-level ~openstack.resource.Resource objects, the Proxy interface offers a place to make things easier for the caller.

Each Proxy class implements methods which act on the underlying Resource classes which represent the service. For example:

def list_flavors(self, **params):
    return flavor.Flavor.list(self.session, **params)

This method is operating on the openstack.compute.v2.flavor.Flavor.list method. For the time being, it simply passes on the Adapter maintained by the Proxy, and returns what the underlying Resource.list method does.

The implementations and method signatures of Proxy methods are currently under construction, as we figure out the best way to implement them in a way which will apply nicely across all of the services.

Connection

The openstack.connection.Connection class builds atop a os_client_config.config.CloudConfig object, and provides a higher level interface constructed of Proxy objects from each of the services.

The Connection class' primary purpose is to act as a high-level interface to this SDK, managing the lower level connecton bits and exposing the Resource objects through their corresponding Proxy object.

If you've built proper Resource objects and implemented methods on the corresponding Proxy object, the high-level interface to your service should now be exposed.