Package: ocptv
ocp-diag-pythonTheOCP Test & Validation Initiativeis a collaboration between datacenter hyperscalers having the goal of standardizing aspects of the hardware validation/diagnosis space, along with providing necessary tooling to enable both diagnostic developers and executors to leverage these interfaces.Specifically, theocp-diag-pythonproject makes it easy for developers to use theOCP Test & Validation specificationartifacts by presenting a pure-python api that can be used to output spec compliant JSON messages.To start, please see below forinstallation instructionsandusage.This project is part ofocp-diag-coreand exists under the sameMIT License Agreement.InstallationStable releases of theocp-diag-pythoncodebase are published toPyPIunder the package nameocptv, and can be easily installed with python package managers.Minimum python version is currently py37.For general usage, the following steps should be sufficient to get the latest stable version:[option 1]: using thePackage Installer for Python[optional]if your project needs or already has a venv, activate it first, otherwise the installation will be system-wide.$python-mvenvenv
$sourceenv/bin/activateThen just install:$pipinstallocptv[option 2]usingPython Poetry[optional]for a completely new project, run eitherpoetry neworpoetry init(seepoetry docs). Then:$poetryaddocptvTo use the bleeding edge instead of the stable version, the git repository should be cloned.
This assumes that the clone is manually kept up to date by git pulling whenever there are new commits upstream. All of the installation methods below will automatically use the latest library code.First clone the upstream latest code:$gitclonehttps://github.com/opencomputeproject/ocp-diag-python.git
$cdocp-diag-python
$gitcheckoutdev# dev branch has the latest code[option 1]: usingpipeditable installSimilar to the stable version steps above, but with-e. Either system-wide or inside a venv.$pipinstall-epath/to/git_cloned/ocp-diag-python[option 2]: usingpoetryThe--editableflag is still in1.2betaas of this writing, so add the dependency to yourpyproject.tomlwithdevelop = true:[tool.poetry.dependencies]ocptv={path="path/to/git_cloned/ocp-diag-python",develop=true}Then install everything:$poetryinstallThe instructions above assume a Linux-type system. However, the steps should be identical on Windows and MacOS platforms.Seedocs.python.orgfor more details on how to use python venvs.UsageThe specification does not impose any particular level of usage. To be compliant, a diagnostic package just needs output the correct artifact messages in the correct format. However, any particular such diagnostic is free to choose what aspects it needs to use/output; eg. a simple validation test may not output any measurements, opting to just have a final Diagnosis outcome.Full API reference is availablehere.A very simple starter example, which just outputs a diagnosis:importocptv.outputastvdefmain():run=tv.TestRun(name="simple_diagnosis",version="1.0")dut=tv.Dut(id="server0",name="server0.domain.net")withrun.scope(dut=dut):step=run.add_step("check_fanspeed")withstep.scope():ifget_fan_speed()>1600:# assuming external get_fan_speed() implstep.add_diagnosis(DiagnosisType.PASS,verdict="fan_ok")else:step.add_diagnosis(DiagnosisType.FAIL,verdict="fan_low")Expected output (slightly reformatted for readability):{"schemaVersion":{"major":2,"minor":0},"sequenceNumber":0,"timestamp":"2023-04-19T20:54:05.652514+01:00"}{"testRunArtifact":{"testRunStart":{"name":"simple_diagnosis","version":"1.0","commandLine":"","parameters":{},"dutInfo":{"dutInfoId":"server0","name":"server0.domain.net","platformInfos":[],"softwareInfos":[],"hardwareInfos":[]}}},"sequenceNumber":1,"timestamp":"2023-04-19T20:54:05.652646+01:00"}{"testStepArtifact":{"testStepId":"0","testStepStart":{"name":"check_fanspeed"}},"sequenceNumber":2,"timestamp":"2023-04-19T20:54:05.652771+01:00"}{"testStepArtifact":{"testStepId":"0","diagnosis":{"verdict":"fan_ok","type":"PASS","sourceLocation":{"file":"/home/user/ocp-diag-python/test.py","line":16}}},"sequenceNumber":3,"timestamp":"2023-04-19T20:54:05.653037+01:00"}{"testStepArtifact":{"testStepId":"0","testStepEnd":{"status":"COMPLETE"}},"sequenceNumber":4,"timestamp":"2023-04-19T20:54:05.653167+01:00"}{"testRunArtifact":{"testRunEnd":{"status":"COMPLETE","result":"PASS"}},"sequenceNumber":5,"timestamp":"2023-04-19T20:54:05.653219+01:00"}For more examples of usage, there are a number available in theexamples folder, along with expected outputs.ConfigurationThere are a couple of knobs that can be used to configure the behavior of theocptvlibrary:enable_runtime_checks: when this is true, the lib code will try to validate the actual types of the data being fed to it against what the specification requires. This may be disable if performance is critical or if it shows any false positives. Default isTrue.timezone: adatetime.tzinfoimplementation overriding the default local timezone. Default isNone, which means local timezone.writer: aocptv.output.Writerimplementation that is used for the lowlevel writing of serialized JSON strings. Default isocptv.output.StdoutWriterwhich just writes everything to standard output.To setup any of these aspects:importocptv.outputastvfromocptv.outputimportStdoutWriter# signature:# config(#     writer: ty.Optional[Writer] = None,#     enable_runtime_checks: ty.Optional[bool] = None,#     timezone: ty.Union[tzinfo, None] = _NOT_SET,# )# disable the runtime type checkstv.config(enable_runtime_checks=False)# change writer and timezonetv.config(timezone=pytz.UTC,writer=StdoutWriter())When using the configuration endpoint, at the moment of starting a test run, the configuration is considered committed. The settings can still be technically modified, but it might result in unexpected behavior, eg. changing thewriterwill result in a partial output, which is not compliant.There's also some more advanced configuration inconfig.pyandadvanced.pyin theexamples folder.ExamplesThe examples inexamples folderare setup to run as a module.# run all demos available$python-mexamples# list demo names$python-mexampleslist# run a specific example$python-mexamplesdemo_diagnosisThesample output fileshows a run of all demos. This is meant as documentation.Developer notesIf you would like to contribute, please head over todeveloper notesfor instructions regarding setting up a development environment and more on submitting code.ContactFeel free to start a newdiscussion, or otherwise post anissue/request.An email contact is also available at:ocp-test-validation@OCP-All.groups.io