User guide¶
Installation and usage¶
The assumptions package can be installed from PyPI:
pip install assumptions
Run the command line tool to generate help documentation:
assumptions -h
usage: assumptions [-h] [-l LOG_TYPE] [-o OUTFILE] [-p PATH] [-e EXTENSION]
[-t TEMPLATE] [-d]
Generate an assumptions and caveats log from code comments.
optional arguments:
-h, --help show this help message and exit
-l LOG_TYPE, --log-type LOG_TYPE
type of log to produce. Default is the assumptions and
caveats log.
-o OUTFILE, --outfile OUTFILE
output Markdown (`.md`) file path. Default is
'LOG_TYPE.md'.
-p PATH, --path PATH relative path to directory to seach for assumptions
and caveats under. Default is current directory.
-e EXTENSION, --extension EXTENSION
file extension to search for. Searches all file
extensions by default.
-t TEMPLATE, --template TEMPLATE
path to custom log template. Overrides template from
log argument.
-d, --dry-run when flag is passed, no output log is generated.
Your assumptions and caveats documented.
We recommend including assumptions in pre-commit configurations:
repos:
- repo: https://github.com/foster999/assumptions
rev: 1.1.0
hooks:
- id: assumptions
This ensures that up-to-date logs are included in your project’s version control.
Alternatively, the command line tool can be called as part of continuous integration workflows.
Assumptions and caveats¶
By default, assumptions will recursively search the current directory for assumptions and caveats, before writing the log to the same directory.
Assumptions and caveats should be written in you code as hashed comments:
# Assumption: Title of assumption
# Quality: RED
# Impact: AMBER
# Detailed description
# on next line or many.
# Caveat: Oh oh
# Something isn't quite what it seems
Or using the R {roxygen} @section tag:
#' Square a number
#'
#' @param x the input to be squared
#' @section Assumption: Numbers are used
#' No strings please.
square <- function(x){
return(x^2)
}
#' Square a number
#'
#' @param x the input to be squared
#' @section Caveat: Only tested with real numbers
square <- function(x){
return(x^2)
}
By default, the assumptions command line tool recursively searches the current directory for assumptions and caveats. These are summarised in an assumptions and caveats log, which is written to the current directory.
assumptions
Searching for log items under: /home/docs/checkouts/readthedocs.org/user_builds/assumptions/checkouts/stable/docs/source
Assumptions and caveats documented.
If the output log already exists, assumptions checks for any changes. If your documented assumptions and caveats haven’t changed, assumptions doesn’t overwrite the log to preserve the “last updated” date. Instead, it gives you a friendly nudge, just in case you’ve forgotten to update them.