oslo-specs

who is not already on the oslo-core team

from oslo_service import wsgi
from oslo_service import service
from oslo_service import loopingcall
...

from oslo_service.threading import service

from oslo_service import service

oslo_service
├── eventlet_backdoor.py
├── fixture.py
├── _i18n.py
├── __init__.py
├── locale
│   └── .. (ignored)
├── loopingcall.py
├── _options.py
├── periodic_task.py
├── service.py
├── sslutils.py
├── systemd.py
├── tests
│   └── .. (ignored)
├── threadgroup.py
├── version.py
└── wsgi.py

oslo_service
├── backends
│   ├── eventlet
│   │   ├── eventlet_backdoor.py
│   │   ├── fixture.py
│   │   ├── __init__.py
│   │   ├── loopingcall.py
│   │   ├── periodic_task.py
│   │   ├── service.py
│   │   ├── sslutils.py
│   │   ├── threadgroup.py
│   │   └── wsgi.py
│   └── threading
│       ├── __init__.py
│       ├── loopingcall.py
│       ├── periodic_task.py
│       ├── service.py
│       └── threadgroup.py
├── eventlet_backdoor.py
├── fixture.py
├── _i18n.py
├── __init__.py
├── locale
│   └── .. (ignored)
├── loopingcall.py
├── _options.py
├── periodic_task.py
├── service.py
├── sslutils.py
├── systemd.py
├── tests
│   └── .. (ignored)
├── threadgroup.py
├── version.py
└── wsgi.py

if _options.backend == "threading":
    from oslo_service.threading import service
else
    from oslo_service.eventlet import service

debtcollector.deprecate(
    """
    The WSGI module is no longer supported
    You see this deprecation warning because you are importing
    the oslo.service wsgi module. This module is deprecated and will
    be soon removed. Please consider using uwsgi and consider following
    the migration path described here:
    https://docs.openstack.org/oslo.service/latest/migration/wsgi.html
    ",
    version="1.0"
)
if _options.backend == "eventlet":
    from oslo_service.eventlet import service
else
    raise ImportError("WSGI module not found in the threading backend...")

oslo_service
├── _i18n.py
├── __init__.py
├── locale
│   └── .. (voluntary ignored)
├── loopingcall.py
├── _options.py
├── periodic_task.py
├── service.py
├── systemd.py
├── tests
│   └── .. (voluntary ignored)
├── threadgroup.py
└── version.py

[DEFAULT]
oslo_service_backend = eventlet

choices=['eventlet', 'threading']

doc/source/backends/

doc/source/migration

[extras]
eventlet =
    eventlet>=0.36.1 # MIT
threading =
    futurist>=3.0.0 # Apache-2.0
    cotyledon>=1.7.3 # Apache-2.0

[app:healthcheck]
paste.app_factory = oslo_middleware:Healthcheck.app_factory
backends = enable_by_files (optional, default: empty)
# used by the 'enable_by_files' backend
enable_by_file_paths = /var/lib/glance/images,/var/lib/glance/cache (optional, default: empty)

# Use this composite for keystone auth with caching and cache management
[composite:glance-api-keystone+cachemanagement]
paste.composite_factory = glance.api:root_app_factory
/: api-keystone+cachemanagement
/healthcheck: healthcheck

              +--------------+
      +------>|   Consul     |<------------------+
      |       +--------------+                   |
      |                                     +-------------+
      |                                +--->|  RPC server |
      |                                |    +-------------+
+-------------+   Call/Cast RPC        |    +-------------+
| RPC client  +---------------------------> |  RPC server |
+-------------+                        |    +-------------+
      |                                |    +-------------+
      | Cast Fanout                    +--->|  RPC server |
      |                                |    +-------------+
      |       +--------------+         |
      +------>| Broadcaster  |---------+
              +--------------+
           Send Cast to all RPC servers

              +--------------+
      +------>|   Consul     |
      |       +--------------+
      |
      |             * Call RPC
+----------------+  (1) select_destinations    +----------------+
| nova-conductor +---------------------------> | nova-scheduler |
|                +------+                      +----------------+
+----------------+      | * Cast RPC
                        | (2) build_and_run_instance
                        |                      +----------------+
                        +--------------------->|  nova-compute  |
                                               +----------------+

Availability Zone-A                Availability Zone-B
+----------------+                 +----------------+
|                |   RPC Request   |                |
|   RPC server   |        +------->+   RPC server   |
|       |        |        |        |       |        |
|       |        |        |        |       |        |
|   RPC client   +--------+        |   RPC client   |
|       |        |                 |       |        |
|       |        |   Federation    |       |        |
| Consul Cluster +<--------------->+ Consul Cluster |
|                |                 |                |
+----------------+                 +----------------+

[oslo_messaging_http]
port_range=20000:20100

[consul]
port = 8500
host = <Consul hostname>
token = <Consul token>
check_timeout = 60s
check_deregister = 30m

[http_driver]
http_token = <Token to access OpenAPI server>
http_api_config_file = <OpenAPI definition>
enable_ssl = True
ssl_certfile = <Path for SSL Cert file>
ssl_keyfile =  <Path for SSL Key file>
listen_timeout = 60

[oslo_messaging_notifications]
sock_path=/run/<service>/notifications.sock

./tools/list_unreleased_changes.sh master $(.tox/venv/bin/list-deliverables --team oslo -r)
./tools/list_unreleased_changes.sh master $(.tox/venv/bin/list-deliverables --team oslo -r --series independent)

./tools/list_unreleased_changes.sh stable/train $(.tox/venv/bin/list-deliverables --team oslo -r --series train)

./tools/new_release.sh ussuri oslo.config feature --stable-branch

+--------------+        +--------------+     +-------------+
|              |        |              |     | any         |
|oslo.messaging+--------> oslo.metrics <-----> monitoring  |
|              |        |              |     | system      |
+--------------+        +--------------+     +-------------+
               unix socket

[oslo_messaging_notifications]
driver = messaging
topics = notifications,notifications_designate
transport_url = rabbit://username:password@rabbit001.com:5672

[oslo_messaging_notifications]
driver = messaging
topics = notifications,notifications_designate,any_other_notification
transport_url = rabbit://username:password@rabbit001.com:5672

[oslo_messaging_topic_notifications]
transport_url = rabbit://username:password@rabbit001.com:5672

[oslo_messaging_topic_notifications_designate]
transport_url = rabbit://username:password@rabbit002.com:5672

[oslo_messaging_notifications]
driver = messaging
topics = notifications
transport_url = rabbit://username:password@rabbit001.com:5672

[oslo_messaging_notifications]
driver = messaging
topics = notifications_designate
transport_url = rabbit://username:password@rabbit002.com:5672

[oslo_messaging_notifications]
driver = messaging
topics = any_other_notification
transport_url = rabbit://username:password@rabbit001.com:5672

fixed-address {
    prefix: /unicast
    fanout: single
    bias: closest
}

fixed-address {
    prefix: /exclusive
    fanout: single
    bias: closest
}

fixed-address {
    prefix: /broadcast
    fanout: multiple
}

--queue-patterns exclusive --queue-patterns unicast --topic-patterns broadcast

-- nova/policy/create.py

from oslo_policy import policy
from nova import policy as nova_policy

server_policies = [
    policy.PolicyOpt(rulename='os_compute_api:servers:create',
                     rule='rule:admin_or_owner',
                     description='Checked on POST /servers'),
    policy.PolicyOpt(rulename='os_compute_api:servers:create:forced_host',
                     rule='rule:admin_or_owner',
                     description='Controls whether the forced_host '
                     'scheduler hint is allowed.'),
    policy.PolicyOpt(rulename='os_compute_api:servers:create:attach_volume',
                     rule='rule:admin_or_owner',
                     description='Checks if a volume can be attached '
                     'during instance create.'),
    policy.PolicyOpt(rulename='os_compute_api:servers:create:attach_network',
                     rule='rule:admin_or_owner',
                     description='Checks if a network can be attached '
                     'during instance create.'),
]

policy_engine = nova_policy.get_policy()
# registration will error if a duplicate policy is defined
policy_engine.register_rules(server_policies)

-- nova/api/openstack/compute/servers.py

from nova import policy

policy_engine = policy.get_policy()

def create(self, context):
    ...
    policy_engine.authorize('os_compute_api:servers:create', target, creds)
    try:
        # This would error because the policy is not registered
        policy_engine.authorize(
            'os_compute_api:servers:create_not_registered', target, creds)
    except:
        pass
    if volume_to_attach:
        policy_engine.authorize(
            'os_compute_api:servers:create:attach_volume', target, creds)

 +-----------+       +-----------+
 |RPC Server1|       |RPC Caller1|
 +-----+-----+       +----+------+
       |                  |
       |                  |
   +---v----+         +---v----+
   |Router A+#########+Router B|
   +---+----+         +----+---+ <------+
       #    ##       ##    #            |
       #      ##   ##      #        +---+--+
       #        ##         #        |Broker|
       #      ##  ##       #        +------+
       #    ##       ##    #
   +---+----+         +-----+--+ <------+
   |Router C+#########+Router D|  +-----+-----+
   +---+----+         +-----+--+  |RPC Caller2|
       ^                    ^     +-----------+
       |                    |
       |                    |
+------+----+              ++----------+
|RPC Caller3|              |RPC Server2|
+-----------+              +-----------+

invalid_configuration_items['config_errors'] = [
    {'config_item': 'namespace', 'item_name': 'DEFULT',
     'message': 'Namespace DEFULT does not exist.'},
    {'config_item': 'option', 'item_name': 'auth_uri',
     'message': 'Option auth_uri has no value assigned.'},
]

invalid_configuration_items['config_warnings'] = [
    {'config_item': 'option', 'item_name': 'auth_strategy',
     'message': 'Option is configured with the default value, not required.'},
    {'config_item': 'option', 'item_name': 'some_advanced_option',
     'message': 'Option some_advanced_option is an advanced option and may'
                'effect performance.'},
]

docker run -t -p 127.0.0.1:8081:80 \
  -e "DB_SYNC=True" \
  -e "AUTH_STRATEGY=noauth2" \
  myservice

spec:
  containers:
    - name: myservice
      image: myservice
      env:
        - name: DB_SYNC
          value: "True"
        - name: AUTH_STRATEGY
          value: noauth2
      ports:
      - containerPort: 80

[placement]
database_connection = foo

[placement_database]
connection = bar

chown: CommandFilter, chown, root

# In (eg) neutron_privileged/foo.py
import os
from neutron_privileged import privsep

@privsep.entrypoint
def example_task_that_requires_privileges():
    return os.getuid()

from neutron_privileged import foo

def bar():
    uid = foo.example_task_that_requires_privileges()
    print "privsep is running as %s" % uid

# In neutron_privileged/__init__.py (once per project)
from oslo_privsep import capabilities as c
from oslo_privsep import priv_context

CFG_SECTION = 'privsep'  # important with multiple privsep daemons
DEFAULT_CAPS = [c.CAP_SYS_ADMIN, c.CAP_NET_ADMIN]  # eg
privsep = priv_context.PrivContext(
    __name__, cfg_section=CFG_SECTION,
    default_capabilities=DEFAULT_CAPS,
)

# Resulting pseudo code, after decorator is applied
def example_function(*args, **kwargs):
    if in_unprivileged_mode:
        privsep_channel.send((CALL, 'example_function', args, kwargs))
        result = privsep_channel.read()
        if result.raised_exception():
            raise result.exc_class(result.exc_args)
        return result.value
    else:
        # privileged_mode
        return _real_example_function(*args, **kwargs)

[privsep]
user = novapriv
group = novapriv
capabilities = CAP_SYS_ADMIN, CAP_NET_ADMIN

while not is_done():
    self._impl.ioloop.poll()
    self._impl.ioloop.process_timeouts()

{
    "context_is_admin":  "role:admin",
    "default": "role:admin",
    ...
    "get_images": "http://external_pdp_server:8080/{name}s",
    ...
}

POST /authz

POST /authz/

   +------------+          +----------+
   | RPC Caller |          | Notifier |
   +-----+------+          +----+-----+
         |                      |
         |                      |
         v                      v
+-------------------+  +-------------------+
|       RPC         |  |    Notification   |
| Messaging Backend |  | Messaging Backend |
|   (amqp:// or     |  |    (kafka://)     |
|    rabbit://)     |  |                   |
+--------+----------+  +--------+----------+
         |                      |
         |                      |
         v                      v
   +------------+        +------+-------+
   |    RPC     |        | Notification |
   |   Server   |        |    Server    |
   +------------+        +--------------+

export OS_TEST_DBAPI_ADMIN_CONNECTION=\
       /path/to/sqlite.db;\
       postgresql+psycopg2://scott:tiger@localhost/openstack

class SomeNovatest(DbTestCase):

    SCHEMA_SCOPE = "nova-cells"
    DRIVER = ('sqlite', 'postgresql', 'mysql')

    def generate_schema(self, engine):
        """Generate schema objects to be used within a test."""

        nova.create_all_tables(engine)

    def test_something(self):
        # do an actual test

instance_provision=${PYTHON:-python} -m oslo.db.sqlalchemy.provision echo $INSTANCE_COUNT
instance_execute=OSLO_SCHEMA_TOKEN=$INSTANCE_ID $COMMAND
instance_dispose=${PYTHON:-python} -m oslo.db.sqlalchemy.provision drop --conditional $INSTANCE_IDS

from concurrent import futures as _futures
from concurrent.futures import process as _process
from concurrent.futures import thread as _thread

ThreadPoolExecutor(_thread.ThreadPoolExecutor)
    """
    Executor that uses a thread pool to execute calls asynchronously.
    It gathers statistics about the submissions executed for
    post-analysis...

    See: https://docs.python.org/dev/library/concurrent.futures.html
    """
    - statistics (read-only property)
    - alive (read-only property)
    - submit (same as parent class)
    - shutdown (same as parent class)

ProcessPoolExecutor(_process.ProcessPoolExecutor)
    """
    Executor that uses a process pool to execute calls asynchronously.
    It gathers statistics about the submissions executed for
    post-analysis...

    See: https://docs.python.org/dev/library/concurrent.futures.html
    """
    - statistics (read-only property)
    - alive (read-only property)
    - submit (same as parent class)
    - shutdown (same as parent class)

SynchronousExecutor(_futures.Executor)
    """Executor that uses the caller to execute calls synchronously.
    This provides an interface to a caller that looks like an executor but
    will execute the calls inside the caller thread instead of executing it
    in a external process/thread for when this type of functionality is
    useful to provide... It gathers statistics about the submissions
    executed for post-analysis...
    """
    - statistics (read-only property)
    - alive (read-only property)
    - submit (same as parent class)
    - restart (Restarts this executor (*iff* previously shutoff/shutdown))
    - shutdown (same as parent class)

GreenFuture(Future)
    """Future that ensures internal condition is a green(ed) condition."""

GreenThreadPoolExecutor(_futures.Executor)
    """Executor that uses a green thread pool to execute calls
    asynchronously.

    See: https://docs.python.org/dev/library/concurrent.futures.html
    and http://eventlet.net/doc/modules/greenpool.html for information on
    how this works.

    It gathers statistics about the submissions executed for
    post-analysis...
    """
    - statistics (read-only property)
    - alive (read-only property)
    - submit (same as parent class)
    - shutdown (same as parent class)

ExecutorStatistics(object)
    """Holds *immutable* information about a executors executions."""
    - failures (read-only property)
    - executed (read-only property)
    - runtime (read-only property)
    - cancelled (read-only property)
    - average_runtime (read-only property)

data = {
    'class': cls_name,
    'module': mod_name,
    'message': six.text_type(exception),
    'tb': tb,
    'args': exception.args,
    'kwargs': kwargs
}

oslo_messaging.RemoteError(data.get('class'), data.get('message'),
                           data.get('tb'))

klass = <load module and class and verify class is an exception type>
exception = klass(*data.get('args', []), **data.get('kwargs', {}))

exc_type = type(exception)
str_override = lambda self: message
new_ex_type = type(ex_type.__name__ + _REMOTE_POSTFIX, (ex_type,),
                   {'__str__': str_override, '__unicode__': str_override})
new_ex_type.__module__ = '%s%s' % (module, _REMOTE_POSTFIX)
exception.__class__ = new_ex_type

>>> from taskflow.types import failure
>>> try:
...    raise IOError("I have broke")
... except Exception:
...    f = failure.Failure()
...
>>> print(json.dumps(f.to_dict(), indent=4, sort_keys=True))
{
    "causes": [],
    "exc_type_names": [
        "IOError",
        "EnvironmentError",
        "StandardError",
        "Exception"
    ],
    "exception_str": "I have broke",
    "traceback_str": "  File \"<stdin>\", line 2, in <module>\n",
    "version": 1
}

SCHEMA = {
    "$ref": "#/definitions/cause",
    "definitions": {
        "cause": {
            "type": "object",
            'properties': {
                'version': {
                    "type": "integer",
                    "minimum": 0,
                },
                'exception_str': {
                    "type": "string",
                },
                'traceback_str': {
                    "type": "string",
                },
                'exc_type_names': {
                    "type": "array",
                    "items": {
                        "type": "string",
                    },
                    "minItems": 1,
                },
                'causes': {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/cause",
                    },
                }
            },
            "required": [
                "exception_str",
                'traceback_str',
                'exc_type_names',
            ],
            "additionalProperties": True,
        },
    },
}

>>> from twisted.python import failure
>>> import pickle
>>> import traceback
>>> def blow_up():
...    raise ValueError("broken")
>>> try:
...    blow_up()
... except ValueError:
...    f = failure.Failure()
>>> print(f)
[Failure instance: Traceback: <type 'exceptions.ValueError'>: broken
--- <exception caught here> ---
<stdin>:2:<module>
<stdin>:2:blow_up
]
>>> f.raiseException()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in blow_up
ValueError: broken
>>> f_p = pickle.dumps(f)
>>> f_2 = pickle.loads(f_p)
>>> f_2.raiseException()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 2, in raiseException
ValueError: broken
>>> print(f_2.tb)
None
>>> traceback.print_tb(f_2.getTracebackObject())
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in blow_up

@classmethod
def validate(cls, data):
    """Validate input data matches expected failure format."""

def check(self, *exc_classes):
    """Check if any of ``exc_classes`` caused the failure.

    ...

    """

def reraise(self):
    """Re-raise captured exception."""

@property
def causes(self):
    """Tuple of all *inner* failure *causes* of this failure.

    ...

    """

def pformat(self, traceback=False):
    """Pretty formats the failure object into a string."""

@classmethod
def from_dict(cls, data):
    """Converts this from a dictionary to a object."""

def to_dict(self):
    """Converts this object to a dictionary."""

def copy(self):
    """Copies this object."""

[filter:healthcheck]
paste.filter_factory = oslo.middleware.healthcheck:Healthcheck
path = /healthcheck (default)
backends = database,disable_by_file (optional, default: empty)
# used by the 'disable_by_file' backend
disable_by_file_path = /var/run/nova/healthcheck_disable (optional, default: empty)

HealthcheckResult = namedtuple('HealthcheckResult', ['available', 'reason'], verbose=True)

class HealthcheckBaseExtension(object):
    def __init__(self, conf):
        self.conf = conf

    @abc.abstractmethod
    def healthcheck():
        """method called by the healthcheck middleware

        return: HealthcheckResult object
        """

class MyDBHealthcheck(HealthcheckBaseExtension):
    def healthcheck():
        ...
        return HealthcheckResult(available=False,
                                 reason="Fail to connect to the database")

[entry_points]
healthcheck =
    database = oslo.db:DBHealthcheck
    disable_by_file = oslo.middleware.healthcheck:DisableByFileHealthcheck

return HealthcheckResult(available=False, reason="DISABLED BY FILE")

return HealthcheckResult(available=True, reason="")

def open_source_from_opt_group(self, conf, group_name):
    """Return an open option source.

    Use group_name to find the configuration settings for the new
    source then open the source and return it.

    If a source cannot be open, raise an appropriate exception.

    :param conf: The active configuration option handler from which
                 to seek configuration values.
    :type conf: ConfigOpts
    :param group_name: The configuration option group name where the
                       options for the source are stored.
    :type group_name: str
    :return: instance of subclass of ConfigurationSource
    """

def get(self, group_name, option_name, opt):
    """Return the value of the option from the group.

    :param group_name: Name of the group.
    :type group_name: str
    :param option_name: Name of the option.
    :type option_name: str
    :param opt: The option definition.
    :type opt: Opt
    :return: Option value or NoValue.
    """

$ app --config-file /path/to/file.conf

[DEFAULT]
config_sources = secret

[secret]
driver = castellan
mapping_file = /path/to/mapping.ini

                            +--------------+
Old configuration  +-------->              |
 (N-1 release)              |     Oslo     |
                            |    Config    +-------> New configuration
      Namespaces   +-------->   Migrator   |            (N release)
                            |              |
                            +--------------+

                      Running on new environment

[keystone_authtoken]
auth_uri = http://192.168.122.250:5000
-->
[keystone_authtoken]
www_authenticate_uri = http://192.168.122.250:5000

[DEFAULT]
api_paste_config = api-paste.ini
-->
[wsgi]
api_paste_config = api-paste.ini

[DEFAULT]
notification_driver = messaging
-->
[oslo_messaging_notifications]
driver = messaging

cfg.StrOpt('choices_opt',
            choices=('a_new', 'b_new', 'c_new'),
            convert_on_upgrade=choice_opt_converter,
            help = 'a choice opt')

def choice_opt_converter(opt, value):
    return {
        'a': 'a_new',
        'b': 'b_new',
        'c': 'c_new',
    }.get(value)

[keystone_authtoken]
auth_protocol = http
auth_host = controller
auth_port = 35357
-->
[keystone_authtoken]
identity_uri = http://controller:35357

[DEFAULT]
rpc_backend = rabbit
#rpc_backend = kafka

[oslo_messaging_rabbit]
rabbit_host = controller
rabbit_userid = openstack
rabbit_password = RABBIT_PASS
rabbit_port = 5672

[oslo_messaging_kafka]
#kafka_default_host = controller
#kafka_default_port = 9092
-->

[DEFAULT]
transport_url = rabbit://openstack:RABBIT_PASS@controller:5672
#transport_url = kafka//openstack:9092

[DEFAULT]
enabled_backends = lvm

[lvm]
# ...
volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver
volume_group = cinder-volumes
iscsi_protocol = iscsi
iscsi_helper = tgtadm

[DEFAULT]
enabled_backends=ceph

[ceph]
# ...
volume_driver=cinder.volume.drivers.rbd.RBDDriver
rbd_pool=volumes
rbd_ceph_conf=/etc/ceph/ceph.conf
rbd_store_chunk_size = 4
rados_connect_timeout = -1
rbd_secret_uuid=457eb676-33da-42ec-9a8c-9293d545c337

[keystone_authtoken]
...
auth_uri = http://controller:5000
auth_url = http://controller:5000
memcached_servers = controller:11211
auth_type = password
project_domain_id = default
user_domain_id = default
project_name = service
username = cinder
password = cinder

bobMessenger = messenger.Client(cfg, 'Bob')
aliceMessenger = messenger.Client(cfg, 'Alice')

server = messenger.Server(cfg)

server.run()
bobMessenger.run()
aliceMessenger.run()

time.sleep(2) # wait for all participants discover each other

assertEqual(server.clientsList,
             bobMessenger.clientsList,
             aliceMessenger.clientsList)

bobMessenger.sendMessage('Alice', 'Hi, there!')

assertEqual(bobMessenger.history['Alice'],
             aliceMessenger.history['Bob'])

fibServer = fibonacci.Server(cfg)
fibClient = fibonacci.Client(cfg)

fibServer.run()

value = fibClient.getFibonacci(20)
assertEqual(value, 6765)

from oslo_policy import policy

...

policy.DocumentedRuleDefault(
    name=SERVERS % 'create',
    check_str=RULE_ADMIN_OR_OWNER,
    description='Create a server.',
    operations=[
        {'method': 'POST',
         'path': '/servers'}
    ]
)

...

policy.DocumentedRuleDefault(
    name=base.IDENTITY % 'create_user',
    check_str=base.RULE_ADMIN_REQUIRED,
    description='Create a user.',
    operations=[
        {'method': 'POST',
         'path': '/v3/users'}
    ]
)

from oslo_policy import policy

...

policy.DocumentedRuleDefault(
    name=SERVERS % 'create',
    scope_type=['project'],
    check_str=RULE_ADMIN_OR_OWNER,
    description='Create a server.',
    operations=[
        {'method': 'POST',
         'path': '/servers'}
    ]
)

...

policy.DocumentedRuleDefault(
    name=base.IDENTITY % 'create_user',
    scope_type=['system', 'project'],
    check_str=base.RULE_ADMIN_REQUIRED,
    description='Create a user.',
    operations=[
        {'method': 'POST',
         'path': '/v3/users'}
    ]
)

[composite:neutronapi_v2_0]
use = call:neutron.auth:pipeline_factory
noauth = cors http_proxy_to_wsgi request_id catch_errors extensions neutronapiapp_v2_0
keystone = cors http_proxy_to_wsgi request_id catch_errors authtoken keystonecontext extensions neutronapiapp_v2_0
#                                  ^                                 ^
# request_id generated here -------+                                 |
# context built here ------------------------------------------------+

# Use this pipeline for keystone auth
[pipeline:glance-api-keystone]
pipeline = cors healthcheck http_proxy_to_wsgi versionnegotiation osprofiler authtoken context  rootapp
#                                                                                      ^
# request_id & context built here -----------------------------------------------------+

[composite:openstack_volume_api_v3]
use = call:cinder.api.middleware.auth:pipeline_factory
noauth = cors http_proxy_to_wsgi request_id faultwrap sizelimit osprofiler noauth apiv3
keystone = cors http_proxy_to_wsgi request_id faultwrap sizelimit osprofiler authtoken keystonecontext apiv3
#                                  ^                                                   ^
# request_id generated here -------+                                                   |
# context built here ------------------------------------------------------------------+

[composite:openstack_compute_api_v21]
use = call:nova.api.auth:pipeline_factory_v21
noauth2 = cors http_proxy_to_wsgi compute_req_id faultwrap sizelimit osprofiler noauth2 osapi_compute_app_v21
keystone = cors http_proxy_to_wsgi compute_req_id faultwrap sizelimit osprofiler authtoken keystonecontext osapi_compute_app_v21
#                                  ^                                                       ^
# request_id generated here -------+                                                       |
# context built here ----------------------------------------------------------------------+

kwargs = {
   'owner_is_tenant': CONF.owner_is_tenant,
   'service_catalog': service_catalog,
   'policy_enforcer': self.policy_enforcer,
   'request_id': request_id,
}

ctxt = glance.context.RequestContext.from_environ(req.environ,
                                                  **kwargs)

def _get_available_networks(self, context, project_id,
                            net_ids=None, neutron=None,
                            auto_allocate=False):
    """Return a network list available for the tenant.
    The list contains networks owned by the tenant and public networks.
    If net_ids specified, it searches networks with requested IDs only.
    """
    if not neutron:
        neutron = get_client(context)

    if net_ids:
        # If user has specified to attach instance only to specific
        # networks then only add these to **search_opts. This search will
        # also include 'shared' networks.
        search_opts = {'id': net_ids}
        nets = neutron.list_networks(**search_opts).get('networks', [])
    else:
        # (1) Retrieve non-public network list owned by the tenant.
        search_opts = {'tenant_id': project_id, 'shared': False}
        if auto_allocate:
            # The auto-allocated-topology extension may create complex
            # network topologies and it does so in a non-transactional
            # fashion. Therefore API users may be exposed to resources that
            # are transient or partially built. A client should use
            # resources that are meant to be ready and this can be done by
            # checking their admin_state_up flag.
            search_opts['admin_state_up'] = True
        nets = neutron.list_networks(**search_opts).get('networks', [])
        # (2) Retrieve public network list.
        search_opts = {'shared': True}
        nets += neutron.list_networks(**search_opts).get('networks', [])

    _ensure_requested_network_ordering(
        lambda x: x['id'],
        nets,
        net_ids)

    return nets

   LOG = logging.getLogger(__name__)

causes the logger to be called ``nova.api.auth``.

LOG.debug("Neither X_USER_ID nor X_USER found in request")

LOG.exception('the exception log msg')

2017-04-24 15:15:54.823 1108 ERROR oslo.tester:24 [-] the exception log msg
2017-04-24 15:15:54.823 1108 ERROR oslo.tester Traceback (most recent call last):
2017-04-24 15:15:54.823 1108 ERROR oslo.tester   File "./tester.py", line 21, in <module>
2017-04-24 15:15:54.823 1108 ERROR oslo.tester     raise RuntimeError('the error text')
2017-04-24 15:15:54.823 1108 ERROR oslo.tester RuntimeError: the error text
2017-04-24 15:15:54.823 1108 ERROR oslo.tester

2017-04-24 15:15:54.823 1108 ERROR oslo.tester:24 [-] the exception log msg: RuntimeError: the error text
2017-04-24 15:15:54.823 1108 ERROR oslo.tester Traceback (most recent call last):
2017-04-24 15:15:54.823 1108 ERROR oslo.tester   File "./tester.py", line 21, in <module>
2017-04-24 15:15:54.823 1108 ERROR oslo.tester     raise RuntimeError('the error text')
2017-04-24 15:15:54.823 1108 ERROR oslo.tester RuntimeError: the error text
2017-04-24 15:15:54.823 1108 ERROR oslo.tester

%(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s:%(lineno)s [%(request_id)s %(user_identity)s] [%(error_summary)s] %(instance)s%(message)s

2017-04-24 15:15:54.823 1108 INFO oslo.tester:24 [-] [RuntimeError: the error text] a regular log message goes here

2017-04-24 15:15:54.823 1108 INFO oslo.tester:24 [-] [-] a regular log message goes here

generator_options:
    args: --config-file=etc/nova/nova-config-generator.conf
    output_file: etc/nova/nova.conf.yaml
    wrap_width: 80
    namespace:
        - nova.conf
        - oslo.log
        ...
    summarize: False
    # minimal intentionally omitted as I don't think it makes sense in
    # this context
    [more generator details can be added as desired]
options:
    DEFAULT:
        image_service:
            # The list of parameters is for example only.  The actual output
            # can include anything deployment tools would find useful.
            default: nova.image.glance.GlanceImageService
            documentation: Service used to search for and retrieve images.
            type: string
            required: True
            deprecated: False
            deprecated_reason: blabla
            deprecated_for_removal: False
            deprecated_since: XXX
            deprecated_name: old_parameter
            [all other parameters passed to the opt constructor]
        new_opt:
            deprecated_name: old_opt
            ...
        ...
    conductor:
        workers: (...)
        ...
    ...
deprecated_options:
    DEFAULT:
        old_opt:
            default: foo
            documentation: Example deprecated opt
            type: string
            replacement_name: new_opt
            replacement_group: DEFAULT
            ...

rootwrap-daemon /etc/myservice/rootwrap.conf

>>> from subprocess import *
>>> from multiprocessing.managers import BaseManager
>>> process = Popen(["rootwrap-daemon", "rootwrap.conf"], stdout=PIPE)
>>> address = process.stdout.readline()[:-1].decode('utf-8')
>>> authkey = process.stdout.read(32)
>>> class MyManager(BaseManager): pass
...
>>> MyManager.register("rootwrap")
>>> from oslo.rootwrap import client  # to set up 'jsonrpc' serializer only
>>> manager = MyManager(address, authkey, serializer='jsonrpc')
>>> manager.connect()
>>> proxy = manager.rootwrap()
>>> proxy.run_one_command(["cat"], stdin="Hello, world!")
[0, u'Hello, world!', u'']
>>> process.kill()

fred/
fred/v1
fred/v1/tests
fred/v2
fred/v2/tests

from fred import v1 as fred

fred.v1.extensionname

FiniteMachine
    - runner (read-only property)
    - default_start_state (read/write property)
    - current_state (read-only property)
    - terminated (read-only property)
    - add_state(state, terminal=False, on_enter=None, on_exit=None)
    - add_reaction(state, event, reaction, *args, **kwargs)
    - add_transition(start, end, event)
    - process_event(event) -- main function/method!!
    - initialize(start_state=None)
    - copy(shallow=False, unfreeze=False)
    - freeze()
    - frozen (read/write property)
    - states (read-only property)
    - events (read-only property)
    - pformat(sort=True, empty='.')

HierarchicalFiniteMachine(FiniteMachine)
    - runner (read-only property)
    - add_state(state, terminal=False,
                on_enter=None, on_exit=None, machine=None)

from openstack.common import fileutils

from oslo_utils import fileutils

fileutils.file_open()

open()

fileutils.read_cached_file()

oslo_policy

#!/bin/bash

# Depends on refactored graduation scripts found
# in https://review.openstack.org/#/c/151027/

set -ex

(cd nova && git checkout master && git pull)
new_repo=oslo.versionedobjects-$(date +%Y-%m-%d-%H%M)
git clone nova $new_repo
cd $new_repo

tooldir=~/repos/openstack/oslo-incubator/tools

FILES="
    nova/exception.py
    nova/objects/__init__.py
    nova/objects/base.py
    nova/objects/fields.py
    nova/test.py
    nova/tests/fixtures.py
    nova/tests/unit/objects/__init__.py
    nova/tests/unit/objects/test_fields.py
    nova/tests/unit/objects/test_objects.py
    nova/tests/unit/test_utils.py
    nova/safe_utils.py
    nova/utils.py
"

$tooldir/filter_git_history.sh $FILES

git mv nova oslo_versionedobjects
git mv oslo_versionedobjects/objects/* oslo_versionedobjects/
rmdir oslo_versionedobjects/objects
git mv oslo_versionedobjects/tests/unit/objects/* oslo_versionedobjects/tests/
rmdir oslo_versionedobjects/tests/unit/objects
git mv oslo_versionedobjects/tests/unit/test_utils.py oslo_versionedobjects/tests/
rmdir oslo_versionedobjects/tests/unit

$tooldir/apply_cookiecutter.sh versionedobjects

cat - >requirements.txt <<EOF
six>=1.7.0
Babel>=1.3
netaddr>=0.7.12
oslo.concurrency>=1.4.1         # Apache-2.0
oslo.context>=0.1.0                     # Apache-2.0
oslo.messaging>=1.4.0,!=1.5.0
oslo.serialization>=1.2.0               # Apache-2.0
oslo.utils>=1.2.0                       # Apache-2.0
iso8601>=0.1.9
EOF

cat - >test-requirements.txt <<EOF
hacking>=0.5.6,<0.8
oslotest>=1.2.0  # Apache-2.0
mock>=1.0
testtools>=0.9.36,!=1.2.0
# These are needed for docs generation
oslosphinx>=2.2.0  # Apache-2.0
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
EOF

echo
echo "Output in $(pwd)"

exit $?

# oslo-incubator modules:
# versionutils

# oslo_messaging/_drivers/impl_zmq.py

class ZmqSocket(object):

   def __init__(self, addr, zmq_type, bind=True, subscribe=None):
      self.ctxt = zmq.Context(CONF.rpc_zmq_contexts)
      self.sock = self.ctxt.socket(zmq_type)

# oslo_messaging/_drivers/impl_zmq.py

class ZmqDriver(base.BaseDriver):

    def __init__(self, conf, url, default_exchange=None,
                 allowed_remote_exmods=None):
    self.ctxt = zmq.Context(CONF.rpc_zmq_contexts)

# oslo_messaging/_drivers/impl_zmq.py

class ZmqSocket(object):
   ...
   def __init__(self, zmq_ctx, addr, zmq_type, bind=True, subscribe=None):
      self.ctxt = zmq_ctx
      self.sock = self.ctxt.socket(zmq_type)

from oslo_service import bar

from foo.openstack.common import bar

# Patterns devoted to 'moving' functions, methods, classes, arguments...

def moved_decorator(kind, new_attribute_name, message=None,
                    version=None, removal_version=None,
                    stacklevel=3)

 # Creates a decorator of the given kind for the given attribute name
 # with the provided message, version deprecated in, the version it will
 # be removed in and the given stacklevel (used to output the users code
 # location when this decorator is called).
 #
 # An example message:
 >>> kind = 'Property'
 >>> new_attribute_name = 'a'
 >>> what = "%s '%s' has moved to '%s" % (kind, 'b', new_attribute_name)
 >>> deprecation._generate_moved_message(what, message='sorry its going away', version='0.1', removal_version='0.2')
 "Property 'a' has moved to 'b' in version '0.1' and will be removed in version '0.2': sorry its going away"

 def moved_property(new_attribute_name, message=None,
                    version=None, removal_version=None, stacklevel=3):

 # Decorator specialization of moved_decorator that sets the kind to
 # a property instead of allowing it to be specified.

 def moved_class(new_class, old_class_name, old_module_name, message=None,
                 version=None, removal_version=None, stacklevel=3):

 # Same as moved_decorator but for classes, returns a class proxy that can
 # not be inherited from (useful for when the user of this is aware that no
 # inheritance is happening)

 def moved_class_inheritable(new_class, old_class_name, old_module_name, message=None,
                             version=None, removal_version=None, stacklevel=3):

 # Same as moved_class but for classes, returns a new-old class that can
 # be inherited from (useful for when the user of this is unaware if any
 # inheritance is happening)

 ...

# Patterns devoted to 'renaming' functions, methods, classes, arguments...

def renamed_kwarg(old_name, new_name, message=None,
                  version=None, removal_version=None, stacklevel=3):

# Creates a decorator that can be applied to a keyword argument accepting
# method, function, callable that will warn the user of that function
# when they are using the old, to be removed keyword argument; creates
# an appropriate message telling the user this (in a similar format
# as mentioned above).

...

# Generic *internal* library used utils...

def generate_message(prefix, postfix=None, message=None,
                     version=None, removal_version=None):

# Generates the messages for renames or moves in a common (share as much
# as possible manner) so that the messages look and feel like they are
# coming from a common library

...

from oslo_policy import policy

class Rules(dict):
    """A store for rules. Handles the default_rule setting directly."""

class Enforcer(object):
    """Responsible for loading and enforcing rules.

    :param policy_file: Custom policy file to use, if none is
                        specified, `CONF.policy_file` will be
                        used.
    :param rules: Default dictionary / Rules to use. It will be
                considered just in the first instantiation. If
                `load_rules(True)`, `clear()` or `set_rules(True)`
                is called this will be overwritten.
    :param default_rule: Default rule to use, CONF.default_rule will
                        be used if none is specified.
    :param use_conf: Whether to load rules from cache or config file.
    :param overwrite: Whether to overwrite existing rules when reload rules
                    from config file.
    """

def load_json(cls, data, default_rule=None):
    """Allow loading of JSON rule data."""

def set_rules(self, rules, overwrite=True, use_conf=False):
    """Create a new Rules object based on the provided dict of rules.

    :param rules: New rules to use. It should be an instance of dict.
    :param overwrite: Whether to overwrite current rules or update them
                      with the new rules.
    :param use_conf: Whether to reload rules from cache or config file.
    """

def clear(self):
    """Clears Enforcer rules, policy's cache and policy's path."""

def load_rules(self, force_reload=False):
    """Loads policy_path's rules.

    Policy file is cached and will be reloaded if modified.

    :param force_reload: Whether to reload rules from config file.
    """

def enforce(self, rule, target, creds, do_raise=False,
            exc=None, *args, **kwargs):
    """Checks authorization of a rule against the target and credentials.

    :param rule: A string or BaseCheck instance specifying the rule
                to evaluate.
    :param target: As much information about the object being operated
                on as possible, as a dictionary.
    :param creds: As much information about the user performing the
                action as possible, as a dictionary.
    :param do_raise: Whether to raise an exception or not if check
                    fails.
    :param exc: Class of the exception to raise if the check fails.
                Any remaining arguments passed to enforce() (both
                positional and keyword arguments) will be passed to
                the exception class. If not specified, PolicyNotAuthorized
                will be used.

    :return: Returns False if the policy does not allow the action and
            exc is not provided; otherwise, returns a value that
            evaluates to True.  Note: for rules using the "case"
            expression, this True value will be the specified string
            from the expression.
    """

class BaseCheck(object):
    """Abstract base class for Check classes."""

filter =  NotificationFilter(
    publisher_id='^compute.*',
    context={'tenant_id': '^5f643cfc-664b-4c69-8000-ce2ed7b08216$',
             'roles': 'private'},
    event_type='^compute\.instance\..*',
    metadata={'timestamp': 'Aug'}.
    payload={'state': '^active$'})

class NotificationEndpoint(object):
    filter = NotificationFilter(publisher_id='^compute.*')

def get_logging_values(self):
    """Return a dict containing values for logging using this context.
    """
    values = self.to_dict()
    values.update({
       'user_identity': self.user_identity,
       'resource_id': self.resource_id,
       'request_chain': ' '.join(self.request_ids),
    })
    return values

import oslo_context

def generate_request_id():
    "Return a unique request identifier."

class RequestContext(object):

    """Helper class to represent useful information about a request context.

    Stores information about the security context under which the user
    accesses the system, as well as additional request information.
    """

def get_admin_context(show_deleted=False):
    "Return a RequestContext configured as an admin user"

def get_context_from_function_and_args(function, args, kwargs):
    """Find an arg of type RequestContext and return it.

       This is useful in a couple of decorators where we don't
       know much about the function we're wrapping.
    """

def is_user_context(context):
    """Indicates if the request context is a normal user."""

def get_current():
    "Return this thread's current context"

from oslo.foo import bar

from oslo_foo import bar

_engine_facade = None

def _get_engine_facade():
    global _engine_facade

    if not _engine_facade:
        _engine_facade = db_session.EngineFacade.from_config(CONF)

    return _engine_facade

_FACADE = None

def _create_facade_lazily():
    global _FACADE
    if _FACADE is None:
        _FACADE = db_session.EngineFacade(
            CONF.database.connection,
            **dict(CONF.database.iteritems())
        )
    return _FACADE

_ENGINE_FACADE = None
_LOCK = threading.Lock()

def _create_facade_lazily():
    global _LOCK, _ENGINE_FACADE
    if _ENGINE_FACADE is None:
        with _LOCK:
            if _ENGINE_FACADE is None:
                _ENGINE_FACADE = db_session.EngineFacade.from_config(CONF)
    return _ENGINE_FACADE

def add_resource_association(self, context, service_type, provider_name,
                             resource_id):

    # ...

    with context.session.begin(subtransactions=True):
        assoc = ProviderResourceAssociation(provider_name=provider_name,
                                            resource_id=resource_id)
        context.session.add(assoc)

@sql.handle_conflicts(conflict_type='trust')
def list_trusts(self):
    session = sql.get_session()
    trusts = session.query(TrustModel).filter_by(deleted_at=None)
    return [trust_ref.to_dict() for trust_ref in trusts]

@require_admin_context
def cell_update(context, cell_name, values):
    session = get_session()
    with session.begin():
        cell_query = _cell_get_by_name_query(context, cell_name,
                                             session=session)
        if not cell_query.update(values):
            raise exception.CellNotFound(cell_name=cell_name)
        cell = cell_query.first()
    return cell

@require_context
def floating_ip_bulk_destroy(context, ips):
    session = get_session()
    with session.begin():
        project_id_to_quota_count = collections.defaultdict(int)
        for ip_block in _ip_range_splitter(ips):
            query = model_query(context, models.FloatingIp).\
                filter(models.FloatingIp.address.in_(ip_block)).\
                filter_by(auto_assigned=False)
            rows = query.all()
            for row in rows:
                project_id_to_quota_count[row['project_id']] -= 1
            model_query(context, models.FloatingIp).\
                filter(models.FloatingIp.address.in_(ip_block)).\
                soft_delete(synchronize_session='fetch')
        for project_id, count in project_id_to_quota_count.iteritems():
            try:
                reservations = quota.QUOTAS.reserve(context,
                                                    project_id=project_id,
                                                    floating_ips=count)
                quota.QUOTAS.commit(context,
                                    reservations,
                                    project_id=project_id)
            except Exception:
                with excutils.save_and_reraise_exception():
                    LOG.exception(_("Failed to update usages bulk "
                                    "deallocating floating IP"))

def commit(self, context, reservations, project_id=None, user_id=None):
    """Commit reservations."""
    if project_id is None:
        project_id = context.project_id
    # If user_id is None, then we use the user_id in context
    if user_id is None:
        user_id = context.user_id

    db.reservation_commit(context, reservations, project_id=project_id,
                          user_id=user_id)

@require_context
@_retry_on_deadlock
def reservation_commit(context, reservations, project_id=None, user_id=None):
    session = get_session()
    with session.begin():
        _project_usages, user_usages = _get_project_user_quota_usages(
                context, session, project_id, user_id)
        reservation_query = _quota_reservations_query(session, context,
                                                      reservations)
        for reservation in reservation_query.all():
            usage = user_usages[reservation.resource]
            if reservation.delta >= 0:
                usage.reserved -= reservation.delta
            usage.in_use += reservation.delta
        reservation_query.soft_delete(synchronize_session=False)

from oslo.db import enginefacade as sql

@sql.reader
def some_api_method(context):
    # work with context.session

@sql.writer
def some_other_api_method(context):
    # work with context.session

def some_api_method(context):
    with sql.using_reader(context) as session:
        # work with session

def some_other_api_method(context):
    with sql.using_writer(context) as session:
        # work with session

# at the top of the api module
GLOBAL_CONTEXT = threading.local()

def some_api_method():
    with sql.using_writer(GLOBAL_CONTEXT) as session:
        # work with session

@sql.writer_connection
def some_core_api_method(context):
    context.connection.execute(<statement>)

def some_core_api_method(context):
    with sql.using_writer_connection(context) as conn:
        conn.execute(<statement>)

from oslo.db import enginefacade as sql

sql.configure(sqlite_fk=True)

def some_api_method():
    with sql.reader() as session:
        # work with session

@sql.reader
def some_api_method(context):
    # work with context.session

@sql.writer
def some_other_api_method(context):
    # work with context.session

@sql.reader
def some_api_method(session):
    # work with session

@sql.writer
def some_other_api_method(session):
    # work with session

def some_api_method(context):
    with sql.using_reader(context) as session:
        # work with session

def some_other_api_method(context):
    with sql.using_writer(context) as session:
        # work with session

def some_api_method():
    with sql.using_reader() as session:
        # work with session

def some_other_api_method():
    with sql.using_writer() as session:
        # work with session

def some_api_method():
    with sql.using_reader(GLOBAL_CONTEXT) as session:
        # work with session

def some_other_api_method():
    with sql.using_writer(GLOBAL_CONTEXT) as session:
        # work with session

def some_api_method():
    with sql.writer() as session:
        # do something with session

    # transaction completes here

    for element in stuff:
        # new transaction per element
        some_other_api_method_with_db(element)

@require_context
def instance_create(context, values):

    # ...  about halfway through

    session = get_session()

    # session / connection / transaction #1
    with session.begin():
        # does some things with instnace_ref

    # session / connection / transaction #2
    ec2_instance_create(context, instance_ref['uuid'])

    # session / connection / transaction #3
    _instance_extra_create(context, {'instance_uuid': instance_ref['uuid']})

    return instance_ref

@sql.writer()
def some_api_method(context):
    # do something with context.session

    for element in stuff:
        # uses same session / transaction guaranteed
        some_other_api_method_with_db(context, element)

    # transaction completes here

# versionutils.py

def report_deprecated_feature(logger, msg, *args, **kwds):
    """Call this function when a deprecated feature is used.

     If the system is configured for fatal deprecations then the message
     is logged at the 'critical' level and :class:`DeprecatedConfig` will
     be raised.

     Otherwise, the message will be logged (once) at the 'warn' level.

     :param logger: The Python logger to use to generate the message.
     :type logger: logging.Logger
     :param msg: The message to emit.
     :type msg: unicode
     :raises: :class:`DeprecatedConfig` if the system is configured for
              fatal deprecations.

     """

oslo-incubator/tests/unit/test_deprecated.py
38:    def test_deprecated(self):
39:        LOG.deprecated('test')
54:        LOG.deprecated('only once!')
55:        LOG.deprecated('only once!')
56:        LOG.deprecated('only once!')
65:        LOG.deprecated(msg1)
66:        LOG.deprecated(msg2)
67:        LOG.deprecated(msg1)
68:        LOG.deprecated(msg1)
69:        LOG.deprecated(msg2)
70:        LOG.deprecated(msg2)
83:        LOG.deprecated('only once! %s', 'arg1')
84:        LOG.deprecated('only once! %s', 'arg1')
85:        LOG.deprecated('only once! %s', 'arg2')
86:        LOG.deprecated('only once! %s', 'arg2')
108:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)
109:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_2)  # logged: args different
110:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)  # no log: same msg+args
112:        LOG.deprecated(msg_fmt_2, msg_fmt_2_arg_1)
113:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # logged: args different
114:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # logged: args different
115:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # no log: same msg+args
116:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # no log: same msg+args

cinder/cinder/api/contrib/services.py
91:            LOG.deprecated(_("Query by service parameter is deprecated. "

cinder/cinder/quota.py
106:                LOG.deprecated(_("Default quota for resource: %(res)s is set "

cinder/cinder/scheduler/manager.py
66:            LOG.deprecated(_('ChanceScheduler and SimpleScheduler have been '

neutron/neutron/plugins/vmware/nsx_cluster.py
49:            LOG.deprecated(_("Attribute '%s' has been deprecated or moved "

neutron/neutron/agent/common/config.py
104:        LOG.deprecated(_('DEFAULT.root_helper is deprecated! Please move '

glance/glance/store/__init__.py
200:                LOG.deprecated(_("%s not found in `known_store`. "

$ ack --ignore-dir=.tox --ignore-dir=build --ignore-dir=.venv \
--ignore-dir=.update-venv --ignore-dir=openstack 'deprecated\('

python-keystoneclient/keystoneclient/tests/test_discovery.py
673:    def test_allow_deprecated(self):

python-keystoneclient/keystoneclient/tests/test_http.py
136:    def test_client_deprecated(self):

keystone/keystone/catalog/backends/templated.py
128:@versionutils.deprecated(

keystone/keystone/contrib/stats/core.py
130:    @versionutils.deprecated(

keystone/keystone/contrib/access/core.py
35:    @versionutils.deprecated(

keystone/keystone/middleware/s3_token.py
50:    @versionutils.deprecated(

keystone/keystone/middleware/core.py
148:    @versionutils.deprecated(

keystone/keystone/auth/plugins/external.py
102:    @versionutils.deprecated(
113:    @versionutils.deprecated(
130:    @versionutils.deprecated(
151:    @versionutils.deprecated(

keystone/keystone/token/core.py
263:    @versionutils.deprecated(versionutils.deprecated.ICEHOUSE, remove_in=+1)

keystone/keystone/common/controller.py
33:def v2_deprecated(f):
42:        v2_deprecated = versionutils.deprecated(

keystone/keystone/common/kvs/legacy.py
49:    @versionutils.deprecated(versionutils.deprecated.ICEHOUSE,

keystone/vendor/python-keystoneclient-master/keystoneclient/tests/test_http.py
136:    def test_client_deprecated(self):

oslo-incubator/tests/unit/test_versionutils.py
24:    def assert_deprecated(self, mock_log, **expected_details):
35:        @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE)
48:            @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE)
59:        @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE,
66:        self.assert_deprecated(mock_log,
75:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
82:        self.assert_deprecated(mock_log,
91:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY)
97:        self.assert_deprecated(mock_log,
105:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
113:        self.assert_deprecated(mock_log,
122:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
129:        self.assert_deprecated(mock_log,
137:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
144:        self.assert_deprecated(mock_log,

oslo-incubator/tests/unit/test_log.py
600:    def test_logfile_deprecated(self):
610:    def test_logdir_deprecated(self):

oslo-incubator/tests/unit/test_deprecated.py
38:    def test_deprecated(self):
39:        LOG.deprecated('test')
54:        LOG.deprecated('only once!')
55:        LOG.deprecated('only once!')
56:        LOG.deprecated('only once!')
65:        LOG.deprecated(msg1)
66:        LOG.deprecated(msg2)
67:        LOG.deprecated(msg1)
68:        LOG.deprecated(msg1)
69:        LOG.deprecated(msg2)
70:        LOG.deprecated(msg2)
83:        LOG.deprecated('only once! %s', 'arg1')
84:        LOG.deprecated('only once! %s', 'arg1')
85:        LOG.deprecated('only once! %s', 'arg2')
86:        LOG.deprecated('only once! %s', 'arg2')
108:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)
109:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_2)  # logged: args different
110:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)  # no log: same msg+args
112:        LOG.deprecated(msg_fmt_2, msg_fmt_2_arg_1)
113:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # logged: args different
114:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # logged: args different
115:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # no log: same msg+args
116:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # no log: same msg+args

cinder/cinder/api/contrib/services.py
91:            LOG.deprecated(_("Query by service parameter is deprecated. "

cinder/cinder/quota.py
106:                LOG.deprecated(_("Default quota for resource: %(res)s is set "

cinder/cinder/scheduler/manager.py
66:            LOG.deprecated(_('ChanceScheduler and SimpleScheduler have been '

oslo.config/tests/test_cfg.py
654:    def test_conf_file_str_value_override_use_deprecated(self):
1086:    def test_conf_file_dict_values_override_deprecated(self):
1106:    def test_conf_file_dict_deprecated(self):
1232:    def test_conf_file_multistr_values_append_deprecated(self):
1271:    def test_conf_file_multistr_deprecated(self):

neutron/neutron/plugins/vmware/nsx_cluster.py
49:            LOG.deprecated(_("Attribute '%s' has been deprecated or moved "

neutron/neutron/agent/common/config.py
104:        LOG.deprecated(_('DEFAULT.root_helper is deprecated! Please move '

heat/heat/tests/test_neutron_loadbalancer.py
429:    def test_create_deprecated(self):

heat/heat/tests/test_neutron_vpnservice.py
201:    def test_create_deprecated(self):

heat/heat/tests/test_parser.py
759:    def test_stack_resolve_runtime_data_deprecated(self):

heat/heat/tests/test_engine_service.py
1950:    def test_list_resource_types_deprecated(self):

heat/heat/tests/test_neutron.py
914:    def test_subnet_deprecated(self):
1387:    def test_router_interface_deprecated(self):
1801:    def test_floating_ip_deprecated(self):

heat/heat/tests/test_neutron_network_gateway.py
233:    def test_network_gateway_create_deprecated(self):

os-refresh-config/os_refresh_config/tests/test_os_refresh_config.py
27:    def test_default_base_dir_deprecated(self):

glance/glance/store/__init__.py
200:                LOG.deprecated(_("%s not found in `known_store`. "

os-apply-config/os_apply_config/tests/test_apply_config.py
293:    def test_default_templates_dir_deprecated(self):
298:    def test_default_templates_dir_old_deprecated(self):

$ for d in ceilometer cinder glance heat ironic keystone neutron nova sahara trove swift;
do echo $d; ack LOG.audit $d/$d | wc -l; done
ceilometer
0
cinder
4
glance
0
heat
0
ironic
0
keystone
0
neutron
0
nova
101
sahara
0
trove
0
swift
0

LOG.info('some message: %(named_arg)s', named_arg=val, context=context)

from oslo.log import log

from foo.openstack.common import log

* CatchErrors
* CorrelationId
* Debug
* RequestId
* RequestBodySizeLimiter

[filter:<middleware>]
paste.filter_factory = oslo.middleware:<ClassName>.factory

import foo

print(CONF.blaa)

CONF.import_opt('blaa', 'foo')
print(CONF.blaa)

CONF = ConfigFilter(cfg.CONF)
CONF.import_opt('blaa', 'foo')
print(CONF.blaa)

from __future__ import print_function

from oslo.config.cfg import *
from openstack.common.cfgfilter import *

class Widget(object):

    def __init__(self, conf):
        self.conf = conf
        self._private_conf = ConfigFilter(self.conf)
        self._private_conf.register_opt(StrOpt('foo'))

    @property
    def foo(self):
        return self._private_conf.foo

conf = ConfigOpts()
widget = Widget(conf)
print(widget.foo)
print(conf.foo)  # raises NoSuchOptError

$> oslo-config-generator --namespace oslo.messaging > oslo.messaging.conf

[entry_points]
oslo.config.opts =
    oslo.messaging = oslo.messaging.opts:list_opts

opts = [
    cfg.StrOpt('foo'),
    cfg.StrOpt('bar'),
]

cfg.CONF.register_opts(opts, group='blaa')

def list_opts():
    return [('blaa', opts)]

def list_opts():
    return [('blaa', copy.deepcopy(opts))]

[entry_points]
oslo.config.opts =
    nova.common = nova.config:list_common_opts
    nova.api = nova.config:list_api_opts
    nova.compute = nova.config:list_compute_opts

$> oslo-config-generator --namespace oslo.messaging \
                         --namespace nova.common \
                         --namespace nova.api > nova-api.conf
$> oslo-config-generator --namespace oslo.messaging \
                         --namespace nova.common \
                         --namespace nova.compute > nova-compute.conf

$> cat > config-generator/api.conf <<EOF
[DEFAULT]
output_file = etc/nova/nova-api.conf
namespace = oslo.messaging
namespace = nova.common
namespace = nova.api
EOF
$> cat > config-generator/compute.conf <<EOF
[DEFAULT]
output_file = etc/nova/nova-compute.conf
namespace = oslo.messaging
namespace = nova.compute
namespace = nova.compute
EOF
$> oslo-config-generator --config-file config-generator/api.conf
$> oslo-config-generator --config-file config-generator/compute.conf

cfg.StrOpt('base_dir'
           default=os.getcwd(),
           sample_default='/usr/lib/myapp')

@filters("mysql", sqla_exc.OperationalError, r"^.*\(1213, 'Deadlock.*")
@filters("postgresql", sqla_exc.OperationalError, r"^.*deadlock detected.*")
def _deadlock_error(operational_error, match, engine_name, is_disconnect):
    raise exception.DBDeadlock(operational_error)

sem-ver: feature, api-break

import pbr.version
...
version_info = pbr.version.Version('MYPACKAGENAME').version_info()

# no tags, one commit, no sem-ver:
last_tag = 0.0.0
tag_distance = 1
version = 0.0.1.dev1+gHASH
Debian version = 0.0.1~dev1+gHASH
RPM version = 0.0.0.dev1+gHASH

# tag of 0.0.1 on a commit - tag sets version.
last_tag = 0.0.1
tag_distance = 0
version = 0.0.1
Debian version = 0.0.1
RPM version = 0.0.1

# tag of 0.0.1.0a4 on a commit, 5 commits since the start
# tag sets X.Y.Z of next version, and a devN version is emitted.
no_rc = True
last_tag = 0.0.0
tag_distance = 5 # distance to origin
version = 0.0.1.dev5+gHASH
Debian version = 0.0.1~dev5+gHASH
RPM version = 0.0.0.dev5+gHASH

# tag of 0.12.2, 2 commits ago with a sem-ver: deprecation line present
# in one of them.
# However since this is a 0.x.y version, we right shift the increment.
last_tag = 0.12.2
version = 0.12.3.dev2+gHASH
Debian version = 0.12.3~dev2+gHASH
RPM version = 0.12.2.dev2+gHASH

# tag of 1.12.2, 2 commits ago with a sem-ver: deprecation line present
# in one of them.
pbr_deprecation = 1.12
version = 1.13.0.dev2+gHASH
Debian version = 0.13.0~dev2+gHASH
RPM version = 0.12.9999.dev2+gHASH

# versionutils.py

def deprecation_warning(msg, *args, **kwds):
    """Call this function when a deprecated feature is used.

     If the system is configured for fatal deprecations then the message
     is logged at the 'critical' level and :class:`DeprecatedConfig` will
     be raised.

     Otherwise, the message will be logged (once) at the 'warn' level.

     :raises: :class:`DeprecatedConfig` if the system is configured for
              fatal deprecations.

     """

oslo-incubator/tests/unit/test_deprecated.py
38:    def test_deprecated(self):
39:        LOG.deprecated('test')
54:        LOG.deprecated('only once!')
55:        LOG.deprecated('only once!')
56:        LOG.deprecated('only once!')
65:        LOG.deprecated(msg1)
66:        LOG.deprecated(msg2)
67:        LOG.deprecated(msg1)
68:        LOG.deprecated(msg1)
69:        LOG.deprecated(msg2)
70:        LOG.deprecated(msg2)
83:        LOG.deprecated('only once! %s', 'arg1')
84:        LOG.deprecated('only once! %s', 'arg1')
85:        LOG.deprecated('only once! %s', 'arg2')
86:        LOG.deprecated('only once! %s', 'arg2')
108:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)
109:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_2)  # logged: args different
110:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)  # no log: same msg+args
112:        LOG.deprecated(msg_fmt_2, msg_fmt_2_arg_1)
113:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # logged: args different
114:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # logged: args different
115:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # no log: same msg+args
116:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # no log: same msg+args

cinder/cinder/api/contrib/services.py
91:            LOG.deprecated(_("Query by service parameter is deprecated. "

cinder/cinder/quota.py
106:                LOG.deprecated(_("Default quota for resource: %(res)s is set "

cinder/cinder/scheduler/manager.py
66:            LOG.deprecated(_('ChanceScheduler and SimpleScheduler have been '

neutron/neutron/plugins/vmware/nsx_cluster.py
49:            LOG.deprecated(_("Attribute '%s' has been deprecated or moved "

neutron/neutron/agent/common/config.py
104:        LOG.deprecated(_('DEFAULT.root_helper is deprecated! Please move '

glance/glance/store/__init__.py
200:                LOG.deprecated(_("%s not found in `known_store`. "

$ ack --ignore-dir=.tox --ignore-dir=build --ignore-dir=.venv \
--ignore-dir=.update-venv --ignore-dir=openstack 'deprecated\('

python-keystoneclient/keystoneclient/tests/test_discovery.py
673:    def test_allow_deprecated(self):

python-keystoneclient/keystoneclient/tests/test_http.py
136:    def test_client_deprecated(self):

keystone/keystone/catalog/backends/templated.py
128:@versionutils.deprecated(

keystone/keystone/contrib/stats/core.py
130:    @versionutils.deprecated(

keystone/keystone/contrib/access/core.py
35:    @versionutils.deprecated(

keystone/keystone/middleware/s3_token.py
50:    @versionutils.deprecated(

keystone/keystone/middleware/core.py
148:    @versionutils.deprecated(

keystone/keystone/auth/plugins/external.py
102:    @versionutils.deprecated(
113:    @versionutils.deprecated(
130:    @versionutils.deprecated(
151:    @versionutils.deprecated(

keystone/keystone/token/core.py
263:    @versionutils.deprecated(versionutils.deprecated.ICEHOUSE, remove_in=+1)

keystone/keystone/common/controller.py
33:def v2_deprecated(f):
42:        v2_deprecated = versionutils.deprecated(

keystone/keystone/common/kvs/legacy.py
49:    @versionutils.deprecated(versionutils.deprecated.ICEHOUSE,

keystone/vendor/python-keystoneclient-master/keystoneclient/tests/test_http.py
136:    def test_client_deprecated(self):

oslo-incubator/tests/unit/test_versionutils.py
24:    def assert_deprecated(self, mock_log, **expected_details):
35:        @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE)
48:            @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE)
59:        @versionutils.deprecated(as_of=versionutils.deprecated.ICEHOUSE,
66:        self.assert_deprecated(mock_log,
75:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
82:        self.assert_deprecated(mock_log,
91:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY)
97:        self.assert_deprecated(mock_log,
105:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
113:        self.assert_deprecated(mock_log,
122:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
129:        self.assert_deprecated(mock_log,
137:        @versionutils.deprecated(as_of=versionutils.deprecated.GRIZZLY,
144:        self.assert_deprecated(mock_log,

oslo-incubator/tests/unit/test_log.py
600:    def test_logfile_deprecated(self):
610:    def test_logdir_deprecated(self):

oslo-incubator/tests/unit/test_deprecated.py
38:    def test_deprecated(self):
39:        LOG.deprecated('test')
54:        LOG.deprecated('only once!')
55:        LOG.deprecated('only once!')
56:        LOG.deprecated('only once!')
65:        LOG.deprecated(msg1)
66:        LOG.deprecated(msg2)
67:        LOG.deprecated(msg1)
68:        LOG.deprecated(msg1)
69:        LOG.deprecated(msg2)
70:        LOG.deprecated(msg2)
83:        LOG.deprecated('only once! %s', 'arg1')
84:        LOG.deprecated('only once! %s', 'arg1')
85:        LOG.deprecated('only once! %s', 'arg2')
86:        LOG.deprecated('only once! %s', 'arg2')
108:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)
109:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_2)  # logged: args different
110:        LOG.deprecated(msg_fmt_1, msg_fmt_1_arg_1)  # no log: same msg+args
112:        LOG.deprecated(msg_fmt_2, msg_fmt_2_arg_1)
113:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # logged: args different
114:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # logged: args different
115:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_3)  # no log: same msg+args
116:        LOG.deprecated(msg_fmt_2, *msg_fmt_2_arg_2)  # no log: same msg+args

cinder/cinder/api/contrib/services.py
91:            LOG.deprecated(_("Query by service parameter is deprecated. "

cinder/cinder/quota.py
106:                LOG.deprecated(_("Default quota for resource: %(res)s is set "

cinder/cinder/scheduler/manager.py
66:            LOG.deprecated(_('ChanceScheduler and SimpleScheduler have been '

oslo.config/tests/test_cfg.py
654:    def test_conf_file_str_value_override_use_deprecated(self):
1086:    def test_conf_file_dict_values_override_deprecated(self):
1106:    def test_conf_file_dict_deprecated(self):
1232:    def test_conf_file_multistr_values_append_deprecated(self):
1271:    def test_conf_file_multistr_deprecated(self):

neutron/neutron/plugins/vmware/nsx_cluster.py
49:            LOG.deprecated(_("Attribute '%s' has been deprecated or moved "

neutron/neutron/agent/common/config.py
104:        LOG.deprecated(_('DEFAULT.root_helper is deprecated! Please move '

heat/heat/tests/test_neutron_loadbalancer.py
429:    def test_create_deprecated(self):

heat/heat/tests/test_neutron_vpnservice.py
201:    def test_create_deprecated(self):

heat/heat/tests/test_parser.py
759:    def test_stack_resolve_runtime_data_deprecated(self):

heat/heat/tests/test_engine_service.py
1950:    def test_list_resource_types_deprecated(self):

heat/heat/tests/test_neutron.py
914:    def test_subnet_deprecated(self):
1387:    def test_router_interface_deprecated(self):
1801:    def test_floating_ip_deprecated(self):

heat/heat/tests/test_neutron_network_gateway.py
233:    def test_network_gateway_create_deprecated(self):

os-refresh-config/os_refresh_config/tests/test_os_refresh_config.py
27:    def test_default_base_dir_deprecated(self):

glance/glance/store/__init__.py
200:                LOG.deprecated(_("%s not found in `known_store`. "

os-apply-config/os_apply_config/tests/test_apply_config.py
293:    def test_default_templates_dir_deprecated(self):
298:    def test_default_templates_dir_old_deprecated(self):

Use	Format
RPC Fanout	openstack.org/om/rpc/multicast/$EXCHANGE/$TOPIC
RPC Server	openstack.org/om/rpc/unicast/$EXCHANGE/$TOPIC/$SERVER
RPC Shared	openstack.org/om/rpc/anycast/$EXCHANGE/$TOPIC
Notifications	openstack.org/om/notify/anycast/$EXCHANGE/$TOPIC.$PRIORITY

Release Name	Description
Kilo	Introduced
Rocky	Modified to better reflect current release landscape

Release Name	Description
Icehouse	Introduced
Kilo	Formalized during the move out of the `oslo` namespace package.

Value	Disposition
error	turn matching warnings into exceptions
ignore	never print matching warnings (the default in python 2.7+)
always	always print matching warnings
default	print the first occurrence of matching warnings for each location where the warning is issued
module	print the first occurrence of matching warnings for each module where the warning is issued
once	print only the first occurrence of matching warnings, regardless of location

oslo-specs

Remove Eventlet From oslo.service

Problem description

Constraints

Proposed change

Features triagging

How to proceed?

Alternatives

Impact on Existing APIs

The temporary backends

Removed sub-modules

Periodic task

Service

Loopingcall & threadgroup

Security impact

Performance Impact

Configuration Impact

Developer Impact

Testing Impact

Implementation

Assignee(s)

Milestones

Work Items

Documentation Impact

Dependencies

Periodic task

Service

References

Enable By Files Healthcheck Plugin

Problem description

Proposed change

Alternatives

Impact on Existing APIs

Security impact

Performance Impact

Configuration Impact

Developer Impact

Testing Impact

Implementation

Assignee(s)

Milestones

Work Items

Documentation Impact

Dependencies

References

http driver

Problem description

PUB/SUB advantage examples

REQ/RESP advantage examples

Proposed change

Main points to be improved by the architecture

RPC Client

RPC Server

Endpoint datastore

HTTP Broadcaster

Sample RPC communication flow for Nova

select_destinations() Call RPC

build_and_run_instance() Cast RPC

Sample RPC server information registered in Consul

Nova’s RPC server information

nova-condutor RPC server list

Health check status of one of nova-condutor RPC server

Multi-AZ support

Alternatives

Datastore for host/topic management

Cast Fanout support design

API framework

Advanced feature

Multi Availability zones support

Impact on Existing APIs

Security impact

Performance Impact

Configuration Impact

Detailed design for port_range

Developer Impact

Testing Impact

Implementation

Assignee(s)

Milestones

Work Items