Package: testflows.texts
TestFlows-TextsUsetestflows.textsPython module to help you write auto verified software documentation
by combining your text with the verification procedure of the described functionality
in the same source file while leveraging the power and flexibility ofTestFlows.com Open-Source Test Framework.Source files for auto verified documentation by convention have.tfdextension
and are written using Markdown. Therefore, all.tfdfiles are valid
Markdown files. However,.tfdfiles are only the source files for your documentation
that must be executed usingtfs document runcommand to produce final
Markdown documentation files.$tfsdocumentrun--inputmy_document.tfd--outputmy_document.mdRequirementsInstallationWriting Auto Verified DocsTutorialPassing ArgumentsControlling Output FormatDebugging ErrorsUsingtfs document runRequirementsPython3 >= 3.8InstallationYou can installtestflows.textsusingpip3command:pip3install--upgradetestflows.textsAfter installingtestflows.textsyou will also havetfscommand available in your environment.Writing Auto Verified DocsFollow the example Markdown document to get to know how you can write auto verified docs yourself.## This is a heading

    This file is written using Markdown where you can have any number
    of`python:testflows`code blocks that contain executable Python code.
    
    ```python:testflows
    # This is Python code that will be executed when .tfd document is run.
    
    msg = "Hello TestFlows Texts"```The scope is shared between all the code blocks in the same document.```python:testflows# so `msg` variable defined above can also be accessed in this# `python:testflows` code blocknew_msg = msg + " Thanks for making verifying docs so easy!"```The output of executing`.tfd`document using`tfs document run`is the final`.md`file with all the`python:testflows`code blocks
    removed and replaced with the text added to the document using
    the`text()`function.

    ```python:testflows
    # Let's use`text()`function to add some text to our document
    # dynamically in our Python code
 
    text("add this line to the final Markdown document")```Any text outside the `python:testflows` code blocks are treated as Pythonf-strings. This allows you to specify expressions for substitutions.See [Python formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals)for more details.Here is an example where we will substitute the value of `msg` variable next {msg}.But with Python f-strings you can specify even complex expressions. For example, we canconvert our string in `msg` to title case as follows {msg.title()}.You can double your curly brackets to escape them when substitution expression is not neededusing `{{` or `}}`.By the way, your document can't contain any triple quotes. If you need them then you have toadd them using `{triple_quotes}` expression. For example,```markdownThis text has {triple_quotes} triple quotes.```Well, this is pretty much it. With`testflows.texts`you have full power of full featured
    test framework and Python language at your disposal to make sure your documentation always
    stays upto date.Now if you want to give it a try then save the above Markdown intotest.tfdfile but make sure to remove the indentation.
Then you can run it as$tfsdocumentrun-itest.tfd-o-and you should get the output of the final Markdown document printed to the stdout.$tfsdocumentrun-itest.tfd-o-## This is a headingThisfileiswrittenusingMarkdownwhereyoucanhaveanynumber
of`python:testflows`codeblocksthatcontainexecutablePythoncode.
...TutorialHere a simple tutorial to introduce you to usingtestflows.texts.# TestFlows Texts Tutorial

    Let's see`testflows.texts`in action by writing auto verified
    documentation for the`-a`option of the`ls`command.

    The man page for the`ls`utility says the following:```NAMEls - list directory contentsSYNOPSISls [OPTION]... [FILE]...DESCRIPTIONList  information  about  the FILEs (the current directory by default).Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci‐fied.Mandatory  arguments  to  long  options are mandatory for short optionstoo.-a, --alldo not ignore entries starting with .```Let's see how`-a`option works.

    First, create a file that starts with`.`using the`touch`command
    ```python:testflows
    from subprocess import run

    command = "touch .hidden_file"``````bash{command}``````python:testflows
    run(command, shell=True, check=True)
    # add clean up at the end of our document generation
    cleanup(run, "rm -rf .hidden_file", shell=True, check=True)```Let's now run```python:testflowsls_a_command = "ls -a | grep .hidden_file"cmd = run(ls_a_command, shell=True, capture_output=True, text=True)assert cmd.returncode == 0, "returncode {cmd.returncode} is not 0"assert ".hidden_file" in cmd.stdout, "hidden file '.hidden_file' in not in the outout"``````bash{ls_a_command}```and you should see our`.hidden_file`listed```bash{cmd.stdout.strip()}```Voilà,`ls -a`does indeed show hidden files!Now save this source file astutorial.tfdand execute it to produce the final Markdown
filetutorial.mdthat we can use on our documentation site.tfs document run -i tutorial.tfd -o tutorial.mdWe know that the instructions in this article are correct astestflows.textshas executed them during
writing oftutorial.mdjust like a technical writer would execute the commands
as part of the process of writing a technical article.Moreover, we can rerun our documentation any time a new version oflsutility is ready
to be shipped to make sure our documentation is still valid and the software still behaves as described.By the way, here is the final Markdown we get# TestFlows Texts Tutorial

    Let's see`testflows.texts`in action by writing auto verified
    documentation for the`-a`option of the`ls`command.

    The man page for the`ls`utility says the following:```NAMEls - list directory contentsSYNOPSISls [OPTION]... [FILE]...DESCRIPTIONList  information  about  the FILEs (the current directory by default).Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci‐fied.Mandatory  arguments  to  long  options are mandatory for short optionstoo.-a, --alldo not ignore entries starting with .```Let's see how`-a`option works.

    First, create a file that starts with`.`using the`touch`command```bashtouch.hidden_file```Let's now run```bashls-a|grep.hidden_file```and you should see our`.hidden_file`listed```bash.hidden_file```Voilà,`ls -a`does indeed show hidden files!Passing ArgumentsExecution of any.tfdfile usingtfs document runcommand results in execution of a document writer program.
This is similar to the test programs you write withTestFlows.com Open-Source Testing Framework.You can control different aspects of writer program execution by passing arguments as follows.tfsdocumentrun-ttest.tfd-otest.md--<writerprogramarguments>For example, to see all the arguments your document writer program can take pass-h/--helpargumenttfsdocumentrun----helpControlling Output FormatYou can control output format by passing-o/--outputargument to your writer program.For example,tfsdocumentrun-itest.tfd-otest.md----outputclassicSee-h/--helpfor other formats.Debugging ErrorsHere are some common errors that you might run into while writing your.tfdsource files.All exceptions will point to the line number where the error has occured.Unescaped Curly BracketsIf you forget to double your curly brackets when you are not using f-string expression
then you will see an error.For example,Hello there

Oops I forgot to double {quote} my curly brackets.when executed will result in theNameError.10ms⟥⟤Errortest.tfd,/test.tfd,NameErrorTraceback(mostrecentcalllast):File"/tmp/tmp_ckk4f3m.py",line1,in<module>text(fr"""Oops I forgot to double {quote} my curly brackets.NameError: name 'quote' is not definedError occured in the following text:3|> Oops I forgot to double {quote} my curly brackets.Syntax ErrorsIf you have a syntax error in thepython:testflowsblock you will get an error.For example,Hello there

    ```python:testflows
    x = 1
    y = 2 boo 
    ```when executed will result in the SyntaxError.11ms⟥⟤Errortest.tfd,/test.tfd,SyntaxErrorTraceback(mostrecentcalllast):File"/home/user/.local/lib/python3.8/site-packages/testflows/texts/executable.py",line87,inexecuteexec(compile(source_code,source_name,'exec'),SyntaxError:invalidsyntax(tmp7e6op1y_.py,line2)SyntaxErroroccuredinthefollowingtext:3|```python:testflows4|x=15|>y=2boo6|```Triple QuotesIf your text have triple quotes like"""it will result in an error.For example,Hello There

This text has """ triple quotes.when executed will result inSyntaxError.9ms⟥⟤Errortest.tfd,/test.tfd,SyntaxErrorTraceback(mostrecentcalllast):File"/home/user/.local/lib/python3.8/site-packages/testflows/texts/executable.py",line87,inexecuteexec(compile(source_code,source_name,'exec'),SyntaxError:invalidsyntax(tmph44nbvgo.py,line1)SyntaxErroroccuredinthefollowingtext:3|>Thistesthas""" triple quotes.The workaround is to use{triple_quotes}expression to output""".For example,Hello There

    This text has {triple_quotes} triple quotes.wheretriple_quotesis provided by default bytestflows.textsmodule. This is equivalent to the following.```python:testflows
    triple_quotes = '"""'
    ```
    Hello There

    This text has {triple_quotes} triple quotes.Usingtfs document run$tfsdocumentrun-h
usage:tfsdocumentrun[-h][-ipath[path...]][-o[path]][-f]----ooo----|oo||1o10010o0||oo|TestFlows.comOpen-SourceSoftwareTestingFrameworkv1.7.211208.1222904---oooxx--/xx\/^^^xx\------------------

Runexecutabledocument.

ExecutabledocumentsareMarkdowndocumentsthat
contain`python:testflows`codeblockswhichmaycontain
anyPythoncodethatwillberunduringdocumentexecution.Alltextwithinexecutabledocumentexceptforthe`python:testflows`codeblocksaretreatedasPythonf-strings.
Therefore,youmustescapeany`{`,`}`charactersbydoubling
them,forexample:`{{`or`}}`,otherwisetheywillbetreated
asf-stringexpressions.

Textmustnotcontaintriplequotes`"""`. If you need themthen you must use either `text()` function within `python:testflows` code blockto explicitly add them to the the text or use `{triple_quotes}` expression.For example:```python:testflowstext('adding triple quotes """totext')```or{triple_quotes}Specify '--' at the end of the command line options to passoptions to the executable document writer program itself.For example:tfs document run -i <path>--o <path> -- --helpYou must set PYTHONPATH when modules needed by the executabledocument are not in the default path.For example:PYTHONPATH=<path/to/module> tfs document run -i <path> -o <path>The `--input` can take multiple files and in such case if `--output`is specified it is treated as directory name.For example,tfs document run -i `find $(pwd) -name "*.tfd"` -o . -fortfs document run -i `find $(pwd) -name "*.tfd"` -o /path/to/output/dir -fIf input is '-' (stdin) and output is '.' then output file is 'document.md'which is created in the current working directory.optional arguments:-h, --help                                   show this help message and exit-i path [path ...], --input path [path ...]  input file, use '-' for stdin, default: stdin-o [path], --output [path]                   output file or directory if multiple input files arepassed, default: '.' or if input is stdin then '-'.The '.' means to create output file in the samedirectory as the input file having .md extension andthe '-'meansoutputtostdout.-f,--forceforcetooverrideexistingoutputfileifitalreadyexists

TestFlows.comOpen-SourceSoftwareTestingFramework.Copyright2021KatteliInc.