{"id":32599705,"url":"https://github.com/testflows/testflows-texts","last_synced_at":"2025-10-30T06:51:36.409Z","repository":{"id":57474456,"uuid":"433261077","full_name":"testflows/TestFlows-Texts","owner":"testflows","description":"TestFlows.com Open-Source Software Testing Framework Texts For Writing Auto Verified Documentation in Markdown.","archived":false,"fork":false,"pushed_at":"2023-03-13T22:14:27.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-30T15:21:57.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testflows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-30T02:05:17.000Z","updated_at":"2024-03-25T14:06:37.000Z","dependencies_parsed_at":"2022-09-10T04:03:11.045Z","dependency_job_id":null,"html_url":"https://github.com/testflows/TestFlows-Texts","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/testflows/TestFlows-Texts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testflows%2FTestFlows-Texts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testflows%2FTestFlows-Texts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testflows%2FTestFlows-Texts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testflows%2FTestFlows-Texts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testflows","download_url":"https://codeload.github.com/testflows/TestFlows-Texts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testflows%2FTestFlows-Texts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281761858,"owners_count":26557114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-30T06:51:12.636Z","updated_at":"2025-10-30T06:51:36.399Z","avatar_url":"https://github.com/testflows.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![TestFlows.com Open-Source Software Testing Framework](https://raw.githubusercontent.com/testflows/TestFlows-ArtWork/master/images/logo.png)\n\n# TestFlows-Texts\n\nUse `testflows.texts` Python module to help you write auto verified software documentation\nby combining your text with the verification procedure of the described functionality\nin the same source file while leveraging the power and flexibility of [TestFlows.com Open-Source Test Framework](https://testflows.com).\n\nSource files for auto verified documentation by convention have `.tfd` extension\nand are written using Markdown. Therefore, all `.tfd` files are valid\nMarkdown files. However, `.tfd` files are only the source files for your documentation\nthat must be executed using `tfs document run` command to produce final \nMarkdown documentation files.\n\n```bash\n$ tfs document run --input my_document.tfd --output my_document.md\n```\n\n* [Requirements](#requirements)\n* [Installation](#installation)\n* [Writing Auto Verified Docs](#writing-auto-verified-docs)\n* [Tutorial](#tutorial)\n* [Passing Arguments](#passing-arguments)\n* [Controlling Output Format](#controlling-output-format)\n* [Debugging Errors](#debugging-errors)\n* [Using `tfs document run`](#using-tfs-document-run)\n\n## Requirements\n\n* Python3 \u003e= 3.8\n\n## Installation\n\nYou can install `testflows.texts` using `pip3` command:\n\n```bash\npip3 install --upgrade testflows.texts\n```\n\nAfter installing `testflows.texts` you will also have `tfs` command available in your environment.\n\n## Writing Auto Verified Docs\n\nFollow the example Markdown document to get to know how you can write auto verified docs yourself.\n\n```markdown\n    ## This is a heading\n\n    This file is written using Markdown where you can have any number\n    of `python:testflows` code blocks that contain executable Python code.\n    \n    ```python:testflows\n    # This is Python code that will be executed when .tfd document is run.\n    \n    msg = \"Hello TestFlows Texts\"\n    ```\n \n    The scope is shared between all the code blocks in the same document.\n    \n    ```python:testflows\n    # so `msg` variable defined above can also be accessed in this\n    # `python:testflows` code block\n\n    new_msg = msg + \" Thanks for making verifying docs so easy!\"\n    ```\n    \n    The output of executing `.tfd` document using `tfs document run`\n    is the final `.md` file with all the `python:testflows` code blocks\n    removed and replaced with the text added to the document using\n    the `text()` function.\n\n    ```python:testflows\n    # Let's use `text()` function to add some text to our document\n    # dynamically in our Python code\n \n    text(\"add this line to the final Markdown document\")\n    ```\n    \n    Any text outside the `python:testflows` code blocks are treated as Python\n    f-strings. This allows you to specify expressions for substitutions.\n    See [Python formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals)\n    for more details.\n    \n    Here is an example where we will substitute the value of `msg` variable next {msg}.\n    But with Python f-strings you can specify even complex expressions. For example, we can \n    convert our string in `msg` to title case as follows {msg.title()}.\n    \n    You can double your curly brackets to escape them when substitution expression is not needed\n    using `{{` or `}}`.\n    \n    By the way, your document can't contain any triple quotes. If you need them then you have to\n    add them using `{triple_quotes}` expression. For example,\n    \n    ```markdown\n    This text has {triple_quotes} triple quotes.\n    ```\n    \n    Well, this is pretty much it. With `testflows.texts` you have full power of full featured\n    test framework and Python language at your disposal to make sure your documentation always\n    stays upto date.\n```\n\nNow if you want to give it a try then save the above Markdown into `test.tfd` file but make sure to remove the indentation.\nThen you can run it as\n\n```bash\n$ tfs document run -i test.tfd -o -\n```\n\nand you should get the output of the final Markdown document printed to the stdout.\n\n```bash\n$ tfs document run -i test.tfd -o -\n## This is a heading\n\nThis file is written using Markdown where you can have any number\nof `python:testflows` code blocks that contain executable Python code.\n...\n```\n\n## Tutorial\n\nHere a simple tutorial to introduce you to using `testflows.texts`.\n\n```markdown\n    # TestFlows Texts Tutorial\n\n    Let's see `testflows.texts` in action by writing auto verified\n    documentation for the `-a` option of the `ls` command.\n\n    The man page for the `ls` utility says the following:\n\n    ```\n    NAME\n           ls - list directory contents\n\n    SYNOPSIS\n           ls [OPTION]... [FILE]...\n\n    DESCRIPTION\n           List  information  about  the FILEs (the current directory by default).\n           Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci‐\n           fied.\n\n           Mandatory  arguments  to  long  options are mandatory for short options\n           too.\n\n           -a, --all\n                  do not ignore entries starting with .\n    ```\n\n    Let's see how `-a` option works.\n\n    First, create a file that starts with `.` using the `touch` command\n    ```python:testflows\n    from subprocess import run\n\n    command = \"touch .hidden_file\"\n    ```\n\n    ```bash\n    {command}\n    ```\n    ```python:testflows\n    run(command, shell=True, check=True)\n    # add clean up at the end of our document generation\n    cleanup(run, \"rm -rf .hidden_file\", shell=True, check=True)\n    ```\n\n    Let's now run\n    ```python:testflows\n\n    ls_a_command = \"ls -a | grep .hidden_file\"\n\n    cmd = run(ls_a_command, shell=True, capture_output=True, text=True)\n\n    assert cmd.returncode == 0, \"returncode {cmd.returncode} is not 0\"\n    assert \".hidden_file\" in cmd.stdout, \"hidden file '.hidden_file' in not in the outout\"\n    ```\n\n    ```bash\n    {ls_a_command}\n    ```\n\n    and you should see our `.hidden_file` listed\n\n    ```bash\n    {cmd.stdout.strip()}\n    ```\n\n    Voilà, `ls -a` does indeed show hidden files!\n```\n\nNow save this source file as `tutorial.tfd` and execute it to produce the final Markdown\nfile `tutorial.md` that we can use on our documentation site.\n\n```\ntfs document run -i tutorial.tfd -o tutorial.md\n```\n\nWe know that the instructions in this article are correct as `testflows.texts` has executed them during\nwriting of `tutorial.md` just like a technical writer would execute the commands\nas part of the process of writing a technical article.\n\nMoreover, we can rerun our documentation any time a new version of `ls` utility is ready\nto be shipped to make sure our documentation is still valid and the software still behaves as described. \n\nBy the way, here is the final Markdown we get\n\n```markdown\n    # TestFlows Texts Tutorial\n\n    Let's see `testflows.texts` in action by writing auto verified\n    documentation for the `-a` option of the `ls` command.\n\n    The man page for the `ls` utility says the following:\n\n    ```\n    NAME\n           ls - list directory contents\n\n    SYNOPSIS\n           ls [OPTION]... [FILE]...\n\n    DESCRIPTION\n           List  information  about  the FILEs (the current directory by default).\n           Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci‐\n           fied.\n\n           Mandatory  arguments  to  long  options are mandatory for short options\n           too.\n\n           -a, --all\n                  do not ignore entries starting with .\n    ```\n\n    Let's see how `-a` option works.\n\n    First, create a file that starts with `.` using the `touch` command\n\n    ```bash\n    touch .hidden_file\n    ```\n\n    Let's now run\n\n    ```bash\n    ls -a | grep .hidden_file\n    ```\n\n    and you should see our `.hidden_file` listed\n\n    ```bash\n    .hidden_file\n    ```\n\n    Voilà, `ls -a` does indeed show hidden files!\n```\n\n## Passing Arguments\n\nExecution of any `.tfd` file using `tfs document run` command results in execution of a document writer program.\nThis is similar to the test programs you write with [TestFlows.com Open-Source Testing Framework](https://testflows.com).\n\nYou can control different aspects of writer program execution by passing arguments as follows.\n\n```bash\ntfs document run -t test.tfd -o test.md -- \u003cwriter program arguments\u003e\n```\n\nFor example, to see all the arguments your document writer program can take pass `-h/--help` argument\n\n```bash\ntfs document run -- --help\n```\n\n## Controlling Output Format\n\nYou can control output format by passing `-o/--output` argument to your writer program.\n\nFor example,\n\n```bash\ntfs document run -i test.tfd -o test.md -- --output classic\n```\n\nSee `-h/--help` for other formats.\n\n## Debugging Errors\n\nHere are some common errors that you might run into while writing your `.tfd` source files.\n\nAll exceptions will point to the line number where the error has occured.\n\n### Unescaped Curly Brackets\n\nIf you forget to double your curly brackets when you are not using f-string expression\nthen you will see an error.\n\nFor example,\n\n```markdown\nHello there\n\nOops I forgot to double {quote} my curly brackets.\n```\n\nwhen executed will result in the `NameError`.\n\n```bash\n                10ms   ⟥⟤ Error test.tfd, /test.tfd, NameError\n                         Traceback (most recent call last):\n                           File \"/tmp/tmp_ckk4f3m.py\", line 1, in \u003cmodule\u003e\n                             text(fr\"\"\"Oops I forgot to double {quote} my curly brackets.\n                         NameError: name 'quote' is not defined\n\n                         Error occured in the following text:\n\n                           3|\u003e Oops I forgot to double {quote} my curly brackets.\n```\n\n### Syntax Errors\n\nIf you have a syntax error in the `python:testflows` block you will get an error.\n\nFor example,\n\n```markdown\n    Hello there\n\n    ```python:testflows\n    x = 1\n    y = 2 boo \n    ```\n```\n\nwhen executed will result in the SyntaxError.\n\n```bash\n                11ms   ⟥⟤ Error test.tfd, /test.tfd, SyntaxError\n                         Traceback (most recent call last):\n                           File \"/home/user/.local/lib/python3.8/site-packages/testflows/texts/executable.py\", line 87, in execute\n                             exec(compile(source_code, source_name, 'exec'),\n                         SyntaxError: invalid syntax (tmp7e6op1y_.py, line 2)\n\n                         Syntax Error occured in the following text:\n\n                           3|  ```python:testflows\n                           4|  x = 1\n                           5|\u003e y = 2 boo \n                           6|  ```\n```\n\n### Triple Quotes\n\nIf your text have triple quotes like `\"\"\"` it will result in an error.\n\nFor example,\n\n```markdown\nHello There\n\nThis text has \"\"\" triple quotes.\n```\n\nwhen executed will result in `SyntaxError`.\n\n```bash\n                 9ms   ⟥⟤ Error test.tfd, /test.tfd, SyntaxError\n                         Traceback (most recent call last):\n                           File \"/home/user/.local/lib/python3.8/site-packages/testflows/texts/executable.py\", line 87, in execute\n                             exec(compile(source_code, source_name, 'exec'),\n                         SyntaxError: invalid syntax (tmph44nbvgo.py, line 1)\n\n                         Syntax Error occured in the following text:\n\n                           3|\u003e This test has \"\"\" triple quotes.\n```\n\nThe workaround is to use `{triple_quotes}` expression to output `\"\"\"`.\n\nFor example,\n\n```markdown\n    Hello There\n\n    This text has {triple_quotes} triple quotes.\n```\n\nwhere `triple_quotes` is provided by default by `testflows.texts` module. This is equivalent to the following.\n\n```markdown\n    ```python:testflows\n    triple_quotes = '\"\"\"'\n    ```\n    Hello There\n\n    This text has {triple_quotes} triple quotes.\n```\n\n## Using `tfs document run`\n\n```bash\n$ tfs document run -h\nusage: tfs document run [-h] [-i path [path ...]] [-o [path]] [-f]\n\n  ---- o o o ----\n |   o       o   |\n | 1 o 10010 o 0 |\n |   o       o   |    TestFlows.com Open-Source Software Testing Framework v1.7.211208.1222904\n  ---  o o oxx --\n /           xx   \\\n/  ^^^        xx   \\\n ------------------\n\nRun executable document.\n\nExecutable documents are Markdown documents that\ncontain `python:testflows` code blocks which may contain\nany Python code that will be run during document execution.  \n\nAll text within executable document except for the\n`python:testflows` code blocks are treated as Python f-strings.\nTherefore, you must escape any `{`, `}` characters by doubling\nthem, for example: `{{` or `}}`, otherwise they will be treated\nas f-string expressions.\n\nText must not contain triple quotes `\"\"\"`. If you need them\nthen you must use either `text()` function within `python:testflows` code block\nto explicitly add them to the the text or use `{triple_quotes}` expression. \n\nFor example:\n    ```python:testflows\n    text('adding triple quotes \"\"\" to text')\n    ``` \n    or\n\n    {triple_quotes}\n    \n\nSpecify '--' at the end of the command line options to pass\noptions to the executable document writer program itself.\n\nFor example:\n   tfs document run -i \u003cpath\u003e--o \u003cpath\u003e -- --help\n\nYou must set PYTHONPATH when modules needed by the executable\ndocument are not in the default path.\n\nFor example:\n   PYTHONPATH=\u003cpath/to/module\u003e tfs document run -i \u003cpath\u003e -o \u003cpath\u003e\n\nThe `--input` can take multiple files and in such case if `--output`\nis specified it is treated as directory name.\n\nFor example,\n   tfs document run -i `find $(pwd) -name \"*.tfd\"` -o . -f \nor\n   tfs document run -i `find $(pwd) -name \"*.tfd\"` -o /path/to/output/dir -f \n\nIf input is '-' (stdin) and output is '.' then output file is 'document.md'\nwhich is created in the current working directory.\n\noptional arguments:\n  -h, --help                                   show this help message and exit\n  -i path [path ...], --input path [path ...]  input file, use '-' for stdin, default: stdin\n  -o [path], --output [path]                   output file or directory if multiple input files are\n                                               passed, default: '.' or if input is stdin then '-'.\n                                               The '.' means to create output file in the same\n                                               directory as the input file having .md extension and\n                                               the '-' means output to stdout.\n  -f, --force                                  force to override existing output file if it already\n                                               exists\n\nTestFlows.com Open-Source Software Testing Framework. Copyright 2021 Katteli Inc.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestflows%2Ftestflows-texts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestflows%2Ftestflows-texts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestflows%2Ftestflows-texts/lists"}