c5079cbc7a
This moves the example implementation from __main__.py to the docs tree so it isn't confused for production code. A unit test is also added to ensure that the example is kept up to date with any changes in the API. Change-Id: I92aa685f410ae0e56d5d55a15812edaae83c8ff1
58 lines
2.1 KiB
ReStructuredText
58 lines
2.1 KiB
ReStructuredText
=======
|
|
Usage
|
|
=======
|
|
|
|
See the module ``oslo_upgradecheck.__main__`` for an example of how to use this
|
|
project.
|
|
|
|
Each consuming project should create a class that inherits from
|
|
:class:`oslo_upgradecheck.upgradecheck.UpgradeCommands` and implement check
|
|
methods on it. Those check methods should then be added to the
|
|
``_upgrade_checks`` tuple so they will be run when the
|
|
:meth:`oslo_upgradecheck.upgradecheck.UpgradeCommands.check` method is
|
|
called. For example::
|
|
|
|
from oslo_upgradecheck import upgradecheck
|
|
|
|
class ProjectSpecificUpgradeCommands(upgradecheck.UpgradeCommands):
|
|
def an_upgrade_check(self):
|
|
if everything_is_awesome():
|
|
return upgradecheck.Result(
|
|
upgradecheck.Code.SUCCESS, 'Success details')
|
|
else:
|
|
return upgradecheck.Result(
|
|
upgradecheck.Code.FAILURE, 'Failure details')
|
|
|
|
_upgrade_checks = (('Awesome upgrade check', an_upgrade_check))
|
|
|
|
oslo.upgradecheck also includes a basic implementation of command line argument
|
|
handling that can be used to provide the minimum processing needed to implement
|
|
a ``$SERVICE-status upgrade check`` command. To make use of it, write a method
|
|
that creates an instance of the class created above, then pass that class's
|
|
``check`` function into :func:`oslo_upgradecheck.upgradecheck.main`. The
|
|
project's ConfigOpts instance must also be passed. In most projects this will
|
|
just be cfg.CONF. For example::
|
|
|
|
from oslo_config import cfg
|
|
|
|
def main():
|
|
return upgradecheck.main(
|
|
conf=cfg.CONF,
|
|
project='myprojectname',
|
|
upgrade_command=ProjectSpecificUpgradeCommands(),
|
|
)
|
|
|
|
The entry point for the ``$SERVICE-status`` command should then point at this
|
|
function.
|
|
|
|
Alternatively, if a project has its own CLI code that it would prefer to reuse,
|
|
it simply needs to ensure that the ``inst.check`` method is called when the
|
|
``upgrade check`` parameters are passed to the ``$SERVICE-status`` command.
|
|
|
|
Example
|
|
-------
|
|
|
|
The following is a fully functional example of implementing a check command:
|
|
|
|
.. literalinclude:: main.py
|