Welcome to pytraceability’s documentation!

Warning

This project is still a work in flux. Although the core functionality is largely there, the API is not stable and some parts will definitely change in the future.

Caveat utilitor!

pytraceability is a Python library that helps you link code to requirements.

Problem Statement

There is often a tension between working in an agile environment and the need to track the link between requirements and implementation, especially in a heavily regulated industry.

Part of this problem can be solved using a requirements management tool, but these tools generally work better for the requirements side of the equation than the implementation side and don’t integrate well with the codebase.

Solution

pytraceability is designed to help bridge this gap by providing a way to annotate code with traceability information in a way that is lightweight and easy to integrate into existing workflows.

The core design is to provide a decorator with key that can be used to annotate functions, classes, and methods with traceability information stored in a metadata dictionary.

It provides a command line interface (CLI) and a Python API for extracting all the tagged traceability information from the codebase and generating a report in a variety of formats.

History Tracking

Most importantly, it can search through git history to track changes to the code that is marked as implementing a specific requirement (based on a specific decorator). Because this tracking is based on the decorator key, it can do this in a much more comprehensive way that is possible with git line or function history alone. This is particularly useful in a heavily regulated environment where you need to be able to demonstrate that a requirement has been implemented and that - although the file containing the code might have changed with eg dependency upgrades, the core implementation of the functionality has not changed.

Have a look at the Sample Report for an example.

Note

This report is generated from some decorators in the pytraceability codebase itself. This is not how you would use the library in practice, but it provides a good example of the sort of information that can be extracted.

Note also, that this report is a simplified example and will be improved in future releases.

For further information, check out the Quickstart guide or more detailed docs below.

Contents: