{ "info": { "author": "Solly Ross", "author_email": "sross@redhat.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: ISC License (ISCL)", "License :: OSI Approved :: Python Software Foundation License", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Topic :: Documentation", "Topic :: Software Development" ], "description": "Yet Another Literate Python Tool\n================================\n\n[![PyPI version](https://badge.fury.io/py/yalpt.svg)](https://badge.fury.io/py/yalpt)\n[![GitHub version](https://badge.fury.io/gh/directxman12%2Fyalpt.svg)](https://badge.fury.io/gh/directxman12%2Fyalpt)\n\nYALPT is a tool to assist in literate programming. Specifically, it is\ndesigned for using literate programing to write interactive tutorials.\n\n\nWhat Is Literate Programming?\n-----------------------------\n\nThe term literate programing was coined by Donald Knuth (see [Wikipedia][1])\nto describe a style of programming whereby documentation and information\nabout the code was written using normal language, generally in some markup\nlanguage, and then interspersed with actual code. The resulting files\nwere then supposed to be compilable into normal programs. In the case\nof Python, this means that there should be a way to run them like normal\nPython programs.\n\n\nWhat is YALPT?\n--------------\n\nYALPT is a tool for running properly formatted literate Python files. A\nYALPT-compatible file consists of normal text interspersed with interactive\nPython sessions. These sessions should be detectable by doctest (in fact, you\ncan run YALPT files through doctest if you want). Other than that, the\nformatting is up to you. YALPT comes with a formatter that takes\nMarkdown-formatted text and displays it using ANSI escape codes to make bold\ntext show up as bold, etc. However, this is optional.\n\nSince YALPT is based on the `doctest` and `code` modules from the Python\nstandard library, it behaves very similarly to the tools you already know.\nIn fact, YALPT will check the results of each chunk of code and warn you\nif it differs from what you have written in your file.\n\n\nWhy YALPT?\n----------\n\nAt this point, you may be asking yourself why you should use YALPT instead\nof some other literate Python tool, like\n[IPython notebooks](http://ipython.org/notebook.html) or\n[python-literate](https://github.com/stdbrouw/python-literate).\n\nYALPT differs from tools like python-literate because it's designed to run\nthe code right in an interactive session, instead of running the code and\nthe generating the output later.\n\nYALPT differs from IPython notebooks in that it has a very loose format.\nIPython notebooks are stored in a JSON-based format that's not particularly\neasy for a human to read or write quickly. One of the goals of YALPT is to\nhave files that are stand-alone, and are perfectly useful without YALPT.\nThis means that they should be readable and writable by humans. Additionally\nit is easy to write YALPT files that are also valid files in your markup\nlanguage of choice. For instance, Markdown-flavored YALPT files can be passed\nto a Markdown parser, so you can generate static pages as well without having\nto rely on YALPT knowning how to read and output your markup and output formats\nof choice.\n\n\nHow do I run YALPT?\n-------------------\n\nThe basic invocation of YALPT is as such:\n\n $ run-lit.py my-file.txt\n\nIf your file is in Markdown, you can use the Markdown formatter:\n\n $ run-lit.py -f markdown my-file.md\n\nBy default, YALPT will drop into an interactive session after each code\nblock, so that you can experiment around with the results of that block before\ncontinuing on. To continue, simply enter two blank lines at the interactive\nsession (press enter twice). If you wish to disable this, and only show an\ninteractive session at the end, you may pass the `--no-interactive` flag:\n\n $ run-lit.py my-file.txt --no-interactive\n\nThis will simply pause after each code block. You can press enter to continue.\nIf you do not even want the pause, you can run YALPT with the `--no-pause`\nflag:\n\n $ run-lit.py my-file.txt --no-pause\n\nBy default, YALPT will enable readline support for completion and history.\nCompletion is triggered with `Control-space`, and history is stored in your\nhome directory in the file `.literate-python-history`. You can disable this\nfunctionality with the `--no-readline` flag:\n\n $ run-lit.py my-file.txt --no-readline\n\nFinally, by default YALPT will use ANSI escape codes to color the code a\ndifferent color and format error messages. You can disable this using the\n`--no-ansi` flag:\n\n $ run-lit.py my-file.txt --no-ansi\n\nThat's all there is to it!\n\n\nI didn't read that description above, so how do I write YALPT files?\n--------------------------------------------------------------------\n\nAny file that looks like doctest-compatible interactive python sessions\ninterspersed between chunks of other text-based \"stuff\" is a YALPT-compatible\nfiles. As long as `doctest` can find the code chunks, so can YALPT, since\nYALPT makes use of `doctest`. You are otherwise free to use your markup\nlanguage of choice for the text parts, or even no markup at all.\n\nHowever, as mentioned above, YALPT does know how to format some Markdown, but\nusing Markdown is by no means necessary. If you want to write a formatter for\nsome other language, you can use the formatter for Markdown as a guideline, and\nsubmit a pull request on [GitHub](https://github.com/directxman12/yalpt).\n\n\nCan I use this on files that don't have doctest code blocks?\n------------------------------------------------------------\n\nYALPT now technically has support for running any code in Markdown code blocks.\nAny indented code blocks, as well as both untyped fenced code blocks and fenced\ncode blocks marked as Python, will be interpreted as Python code blocks and\nexecuted.\n\nHowever, this functionality has not been tested as extensively as the the\ndoctest parser, and is not as \"self-documenting\", since it does not include the\noutput of each line like the doctest format does.\n\nIf you wish to use a different parser, you can call YALPT with the `-p` flag:\n\n $ run-lit.py -p markdown my-file.md\n\n\nMy YALPT file needs a lot a setup that distracts from the main contents!\n------------------------------------------------------------------------\n\nWhile it's generally preferable to provide basic setup as part of the literate\nPython file, it can be cumbersome and distracting when too much boilerplate\nis required. In this case, and \"environment driver\" may be specified.\nEnvironment drivers perform some setup and teardown, and may also provide\nobjects that the literate Python files can use.\n\nTo run YALPT with an environment driver, use the `-e` flag:\n\n $ run-lit.py -e gssapi basic-tutorial.md\n\nOne example of a package which provides an environment driver is\n[GSSAPI Console](https://pypi.python.org/pypi/gssapi_console). This\nenvironment driver sets up a self-contained MIT Krb5 environment for use\nwhen writing literate Python files that involve GSSAPI.\n\n\nReusing/Extending YALPT\n-----------------------\n\nThe core functionality of YALPT exists in the class\n`yalpt.core.LiterateInterpreter`. This class may be subclassed to modify\nfunctionality.\n\nIt functions much like the standard library's `code.InteractiveConsole`,\nfrom which it inherits.\n\nCustom formatters should implement a format method which takes a string and\nreturns a formatted string.\n\nAdditionally, YALPT now has several setuptools entry points for extension:\n\n* `yalpt.formatters` can be used to introduce custom formatters for\n pretty-printing the non-code portions of the files. See `yalpt.formatters`\n for more information.\n\n* `yalpt.parsers` can be used to introduce custom parsers to separate code\n from non-code. See `yalpt.parsers` for more information.\n\n* `yalpt.env_drivers` can be used to introduce environment drivers to provide\n boilerplate setup for literate Python files. Environment driver classes\n should implement a `setup()` method (which returns a `dict` of locals to\n include in the environment), a `teardown()` method, and have\n `DRIVER_NAME` and `banner` properties/field.\n\n\n[1]: http://en.wikipedia.org/wiki/Literate_programming", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/directxman12/yalpt", "keywords": "literate documentation tutorial", "license": "ISC and PSF", "maintainer": null, "maintainer_email": null, "name": "yalpt", "package_url": "https://pypi.org/project/yalpt/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/yalpt/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/directxman12/yalpt" }, "release_url": "https://pypi.org/project/yalpt/1.0.0/", "requires_dist": null, "requires_python": null, "summary": "Yet Another Literate Python Tool", "version": "1.0.0" }, "last_serial": 2002096, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "459483304e0c4cb4140d84fa3c9123eb", "sha256": "1fdfb21d8221a071bb9ba12cd5252125e5868d418e71de0a2e88a7123cae47bc" }, "downloads": -1, "filename": "yalpt-1.0.0.tar.gz", "has_sig": false, "md5_digest": "459483304e0c4cb4140d84fa3c9123eb", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18728, "upload_time": "2016-03-11T21:13:53", "url": "https://files.pythonhosted.org/packages/7a/b1/4de373db7655ddbe3052ae95f8fac76cbad3e9f03b862b33ff33dd40bacf/yalpt-1.0.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "459483304e0c4cb4140d84fa3c9123eb", "sha256": "1fdfb21d8221a071bb9ba12cd5252125e5868d418e71de0a2e88a7123cae47bc" }, "downloads": -1, "filename": "yalpt-1.0.0.tar.gz", "has_sig": false, "md5_digest": "459483304e0c4cb4140d84fa3c9123eb", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18728, "upload_time": "2016-03-11T21:13:53", "url": "https://files.pythonhosted.org/packages/7a/b1/4de373db7655ddbe3052ae95f8fac76cbad3e9f03b862b33ff33dd40bacf/yalpt-1.0.0.tar.gz" } ] }