A module to measure metrics on Ansible scripts
Project description
ansible-metrics
A python module that provides metrics for Ansible scripts.
This repository contains 50 metrics currently implemented in Python 3.6. Although, there are 5 more implicit metrics that can be derived by combining the implemented ones. See the documentation for further details.
How to install and import modules locally
First, install the necessary dependencies with the command:
pip3 install -r requirements.txt
You can install the package locally from the project root folder with the command:
pip3 install .
Once the installation succeed you can import the module in your python application with:
import ansiblemetrics
For example, if you want to call the metric LOC, execute the following instructions:
from ansiblemetrics.general.loc import LOC
from io import StringIO
metric = LOC(StringIO('key:value'))
print(metric.count())
The general pattern is
from ansiblemetrics.<general|playbook|tasks>.<Metric> import <Metric>
metric = <Metric>('StringIO object representing a playbook')
print(metric.count())
How to use
Once installed, typing ansible-metrics
will return information on usage:
usage: ansible-metrics [-h] [-v] file
Extract metrics from Ansible scripts. If no optional parameter is passed, the
tool computes only the general metrics which are suitable for both playbooks
and task files.
positional arguments:
file input file path (playbook or tasks file)
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
How to contribute
First, clone the repository as following:
git clone https://github.com/radon-h2020/radon-ansible-metrics.git
Then, move to the folder location and run
pip3 install requirements.txt
to install dependencies.
Execute pytest tests
to run the test suite.
Step 1: Create a new branch to work on the metric
Create a branch on purpose to work on the metric implementation and testing.
Move to project folder and run the following commands:
git checkout master
to move to branchmaster
git pull
to be sure to be updated with the latest versiongit checkout -b <metric_name>
to create and move to the new working branch. The name is up to you, but it would be usefull to call it with the metric's name or acronym
Step 2: Document metric
In docs/README.md insert the name of the metrics and link it to its documentation in the folder docs/playbook.
Name the documentation file as the extended metric name, in uppercase with underscores (_) in places of blank spaces. For example, if the metric is "Number of loops" then create the file docs/playbook/NUMBER_OF_LOOPS.md.
The documentation should contain at least the following elements:
- a unique name;
- an acronym (3/4 letters) to be used to identify it and to name the script implementing it;
- a description that explains its purpose;
- the input parameters;
- the output type;
- an example of a playbook for the problem at hand and the expected result of the metric wrt that playbook. The playbook of the example must be included in the test case testing the metric, along with further examples, if needed.
- an example on how to call the method that implement the metric.
Step 3: Create Test Case
- Create a test case in the tests folder and name it with tests_<metric_acronym>_<method_to_test>.py. For example, to test the method
count()
of metric "Number of loops (NLP)", the script path would results like tests/playbook/test_nlp_count.py.
<TODO: To insert example of test case>
Step 4: Implement metric
Create a script in folder ansiblemetrics/playbook/ and name it as <metric_acronym>.py.
Define the method to test with an empty body.
Run pytest
to make sure test cases implemented at Step 3 fail.
Implement the body of the function.
Run pytest
again to make sure test cases implemented at Step 3 pass.
Step 4: Commit your work
Move to project folder and run the following commands:
git add <modified_file>
for each modified files,git add .
to add all modified files (be carefull that the right files are added whn using this option)git status
is helpful to check what files have been changed/added/deleted.- Once ready, run
git commit -m "A message describing the work done"
- Finally,
git push origin/<branch_name>
and open a pull request if you desire to integrate your changes to the master branch.
For further information about the implemented classes, please refer to the wiki.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.