<commit_before>=======
 Usage
=======

To use oslo.policy in a project, import the relevant module. For
example::

    from oslo_policy import policy

Migrating to oslo.policy
========================

Applications using the incubated version of the policy code from Oslo aside
from changing the way the library is imported, may need to make some extra
changes.

Incorporating oslo.policy tooling
---------------------------------

The ``oslo.policy`` library offers a generator that projects can use to render
sample policy files, check for redundant rules or policies, among other things.
This is a useful tool not only for operators managing policies, but also
developers looking to automate documentation describing the projects default
policies.

This part of the document describes how you can incorporate these features into
your project. Let's assume we're working on an OpenStack-like project called
``foo``. Policies for this service are registered in code in a common module of
the project.

First, you'll need to expose a couple of entry points in the project's
``setup.cfg``::

    [entry_points]
    oslo.policy.policies =
        foo = foo.common.policies:list_rules

    oslo.policy.enforcer =
        foo = foo.common.policy:get_enforcer

The ``oslo.policy`` library uses the project namespace to call ``list_rules``,
which should return a list of ``oslo.policy`` objects, either instances of
``RuleDefault`` or ``DocumentedRuleDefault``.

The second entry point allows ``oslo.policy`` to generate complete policy from
overrides supplied by an existing policy file on disk. This is useful for
operators looking to supply a policy file to Horizon or for security compliance
complete with overrides important to that deployment. The ``get_enforcer``
method should return an instance of ``oslo.policy.policy:Enforcer``. The
information passed into the constructor of ``Enforcer`` should resolve any
overrides on disk. An example for project ``foo`` might look like the
following::

    from oslo_config import cfg
    from oslo_policy import policy

    from foo.common import policies

    CONF = cfg.CONF
    _ENFORCER = None

    def get_enforcer():
        CONF([], project='foo')
        global _ENFORCER
        if not _ENFORCER:
            _ENFORCER = policy.Enforcer(CONF)
            _ENFORCER.register_defaults(policies.list_rules())
        return _ENFORCER

Please note that if you're incorporating this into a project that already uses
``oslo.policy`` in some form or fashion, this might need to be changed to fit
that project's structure accordingly.

Next, you can create a configuration file for generating policies specifically
for project ``foo``. This file could be called ``foo-policy-generator.conf``
and it can be kept under version control within the project::

    [DEFAULT]
    output_file = etc/foo/policy.yaml.sample
    namespace = foo

If project ``foo`` uses tox, this makes it easier to create a specific tox
environment for generating sample configuration files in ``tox.ini``::

    [testenv:genpolicy]
    commands = oslopolicy-sample-generator --config-file etc/foo/policy.yaml.sample

Changes to Enforcer Initialization
----------------------------------

The ``oslo.policy`` library no longer assumes a global configuration object is
available. Instead the :py:class:`oslo_policy.policy.Enforcer` class has been
changed to expect the consuming application to pass in an ``oslo.config``
configuration object.

When using policy from oslo-incubator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    enforcer = policy.Enforcer(policy_file=_POLICY_PATH)

When using oslo.policy<commit_msg>Corrects tox.ini snippet to point to config file<commit_after>=======
 Usage
=======

To use oslo.policy in a project, import the relevant module. For
example::

    from oslo_policy import policy

Migrating to oslo.policy
========================

Applications using the incubated version of the policy code from Oslo aside
from changing the way the library is imported, may need to make some extra
changes.

Incorporating oslo.policy tooling
---------------------------------

The ``oslo.policy`` library offers a generator that projects can use to render
sample policy files, check for redundant rules or policies, among other things.
This is a useful tool not only for operators managing policies, but also
developers looking to automate documentation describing the projects default
policies.

This part of the document describes how you can incorporate these features into
your project. Let's assume we're working on an OpenStack-like project called
``foo``. Policies for this service are registered in code in a common module of
the project.

First, you'll need to expose a couple of entry points in the project's
``setup.cfg``::

    [entry_points]
    oslo.policy.policies =
        foo = foo.common.policies:list_rules

    oslo.policy.enforcer =
        foo = foo.common.policy:get_enforcer

The ``oslo.policy`` library uses the project namespace to call ``list_rules``,
which should return a list of ``oslo.policy`` objects, either instances of
``RuleDefault`` or ``DocumentedRuleDefault``.

The second entry point allows ``oslo.policy`` to generate complete policy from
overrides supplied by an existing policy file on disk. This is useful for
operators looking to supply a policy file to Horizon or for security compliance
complete with overrides important to that deployment. The ``get_enforcer``
method should return an instance of ``oslo.policy.policy:Enforcer``. The
information passed into the constructor of ``Enforcer`` should resolve any
overrides on disk. An example for project ``foo`` might look like the
following::

    from oslo_config import cfg
    from oslo_policy import policy

    from foo.common import policies

    CONF = cfg.CONF
    _ENFORCER = None

    def get_enforcer():
        CONF([], project='foo')
        global _ENFORCER
        if not _ENFORCER:
            _ENFORCER = policy.Enforcer(CONF)
            _ENFORCER.register_defaults(policies.list_rules())
        return _ENFORCER

Please note that if you're incorporating this into a project that already uses
``oslo.policy`` in some form or fashion, this might need to be changed to fit
that project's structure accordingly.

Next, you can create a configuration file for generating policies specifically
for project ``foo``. This file could be called ``foo-policy-generator.conf``
and it can be kept under version control within the project::

    [DEFAULT]
    output_file = etc/foo/policy.yaml.sample
    namespace = foo

If project ``foo`` uses tox, this makes it easier to create a specific tox
environment for generating sample configuration files in ``tox.ini``::

    [testenv:genpolicy]
    commands = oslopolicy-sample-generator --config-file etc/foo/foo-policy-generator.conf

Changes to Enforcer Initialization
----------------------------------

The ``oslo.policy`` library no longer assumes a global configuration object is
available. Instead the :py:class:`oslo_policy.policy.Enforcer` class has been
changed to expect the consuming application to pass in an ``oslo.config``
configuration object.

When using policy from oslo-incubator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    enforcer = policy.Enforcer(policy_file=_POLICY_PATH)

When using oslo.policy
{'fraction_non_alphanumeric': 0.1013938234490298, 'fraction_numerical': 0.0, 'mean_word_length': 3.905495978552279, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6506940', 'n_tokens_mistral': 1912, 'n_tokens_neox': 1848, 'n_words': 864}