{
"info": {
"author": "David Bau",
"author_email": "david.bau@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Topic :: Software Development :: Libraries",
"Topic :: Text Processing :: General"
],
"description": "# Python Templating with @templet\n\nHere is an elegant lightweight python templating module that supports inline python, speedy compilation, subtemplates, and subclassing, all in a simple decorator module implemented in about 125 lines of python.\n\n## What's New\n\nTemplet was created by David Bau, and modifications for version 4 are by Kriszti\u00e1n Fekete. Version 4 adds:\n\n * Python 3 support.\n * Proper unit tests, verifying python2, python3, and pypy support.\n * Support only unicode strings (no bytestrings).\n * Removed special case for empty-first-newline.\n * Cleaned up code for readability.\n\n## Usage\n\nTo use templet, just annotate a python function with @templet, and then put the template text where the docstring would normally be. Leave the function body empty, and efficient code to concatenate the contents will be created.\n\n```\n from templet import templet\n \n @templet\n def myTemplate(animal, body):\n \"the $animal jumped over the $body.\"\n \n print(myTemplate('cow', 'moon'))\n```\n\nThis is turned into something like this:\n\n```\n def myTemplate(animal, body):\n out = []\n out.append(\"the \")\n out.append(str(animal))\n out.append(\" jumped over the \")\n out.append(str(body))\n out.append(\".\")\n return ''.join(out)\n```\n\nThere are just six constructs that are supported, all starting with $:\n\n| syntax | meaning |\n|--------|---------|\n| `$myvar` | inserts the value of the variable `myvar` |\n| `${...}` | evaluates the expression and inserts the result |\n| `${[...]}` | runs a list comprehension and concatenates the results |\n| `${{...}}` | executes enclosed code; use `out.append(text)` to insert text |\n| `$$` | an escape for a single `$` |\n| `$` | (at the end of the line) is a line continuation |\n\nAll ordinary uses of `$` in the template need to be escaped by doubling the `$$` - with the exception of (as mentioned above) `$.`, `$(`, `$/`, `$'`, and `$\"`.\n\nIn the actual generated code, line numbers are aligned exactly so that both syntax errors and runtime errors in exception traces are reported on the correct line of the template file in which the code appears.\n\n## Philosophy\n\nThe philosophy behind templet is to introduce only the concepts necessary to simplify the construction of long strings in python; and then to encourage all other logic to be expressed using ordinary python.\n\nA @templet function can do everything that you can do with any function that returns a string: it can be called recursively; it can have variable or keyword arguments; it can be a member of a package or a method of a class; and it can access global imports or invoke other packages. As a result, although the construct is extremely simple, it brings all the power of python to templates, and the @templet idea scales very well.\n\nBeyond simple interpolation, templet does not invent any new syntax for data formatting. If you want to format a floating-point number, you can write `${\"%2.3f\" % num}`; if you want to escape HTML sequences, just write `${cgi.escape(message)}`. Not as brief as a specialized syntax, but easy to remember, brief enough, and readable to any python programmer.\n\nSimilarly, templet does not invent any new control flow or looping structures. To loop a template, you need to use a python loop or list comprension and call the subtemplate as a function:\n\n```\n @templet\n def doc_template(table):\n \"\"\"\\\n \n ${ table.name }
\n \n ${{\n for item in table:\n out.append(self.row_template(item))\n }}\n
\n \n \"\"\"\n```\n\nIf you prefer list comprehensions, it is slightly more brief:\n\n```\n @templet\n def doc_template(table):\n \"\"\"\\\n \n ${ table.name }
\n \n ${[self.row_template(item) for item in table]}\n
\n \n \"\"\"\n```\n\nThe design encourages simple templates that read in straight-line fashion, an excellent practice in the long run. Although when invoking subtemplates you need to pass state, of course you can use @templet to make methods and pass state on \"self\", or use object parameters.\n\n## Details and Style\n\nSome tips/guidelines for using these annotations.\n\nWhitespace can be important inside HTML, but for python readability you often want to indent things, so @templet gives you a few tools:\n\n * It identifies the number of leading spaces that are uniformly used to the left of the template and strips them.\n * It allows you to use a `$` at the end of a line for a line continuation.\n\nSo my recommended style for multiline templates is:\n\n * indent template text in the function as if it were python code.\n * use a python triple-quote and put the opening quote on its own line.\n * never indent HTML tags - they just get too deep, so put them all at column 0.\n * when nesting gets confusing, for readability, just put one tag on each line.\n * liberally use `$` continuations if layout demands no-whitespace.\n * indent code inside `${{` and then put `}}` on its own line (a newline right after a closing `}}` is eaten).\n\nRelative indenting for python code inside `${{...}}` is preserved using the same leading-space-stripping trick as is used for the templates themselves, so you can indent embedded python as normal, and you can start the indenting at whichever column feels natural. I usually indent embedded python by one more level.\n\nIn the unusual case where it is necessary to emit text that has leading spaces on every line, you can begin the template with a continuation line with the `$` in the column that you want to treat as column zero, as follows:\n\n```\n@templet\ndef indented(x):\n \"\"\"\\\n $\n var val\n x $x\n \"\"\"\n```\n\nOne question is whether the opening `\"\"\"` should be on the same line as the def or its own line. For clarity I usually put the opening quote on its own line, but to get columns to line up correctly, I eat the newline with a python line continuation immediately `\"\"\"\\`.\n\nFor example, if you want to achieve all on one line the following:\n\n\n```\n| .... | ... |
\n```\n\nThen you could use:\n\n```\n@templet\ndef table_row(row_data):\n \"\"\"\\\n $\n | $\n $\n ${cgi.escape(link_text})}$\n $\n | $\n $\n ${{\n if (enrolled): out.append('enrolled')\n }}\n ${cgi.escape(label_text)}$\n | $\n
\n \"\"\"\n```",
"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/python-templet/templet",
"keywords": "simple string template decorator",
"license": "BSD",
"maintainer": null,
"maintainer_email": null,
"name": "python-templet",
"package_url": "https://pypi.org/project/python-templet/",
"platform": "UNKNOWN",
"project_url": "https://pypi.org/project/python-templet/",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "https://github.com/python-templet/templet"
},
"release_url": "https://pypi.org/project/python-templet/4.0.0/",
"requires_dist": null,
"requires_python": null,
"summary": "Lightweight string templating via function decorator.",
"version": "4.0.0"
},
"last_serial": 1895046,
"releases": {
"4.0": [],
"4.0.0": [
{
"comment_text": "",
"digests": {
"md5": "ac6acb34cd43a686156db592dfecc6f0",
"sha256": "cf6992c53a5b8829e743f11a1437400344a9ae4521975e10ea5d3f93f7d8c23f"
},
"downloads": -1,
"filename": "python_templet-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ac6acb34cd43a686156db592dfecc6f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8606,
"upload_time": "2016-01-08T15:15:36",
"url": "https://files.pythonhosted.org/packages/17/02/11033aa13800ec6551064a507b8c44dde24eaa47f5f37193b8559260c423/python_templet-4.0.0.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "ac6acb34cd43a686156db592dfecc6f0",
"sha256": "cf6992c53a5b8829e743f11a1437400344a9ae4521975e10ea5d3f93f7d8c23f"
},
"downloads": -1,
"filename": "python_templet-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ac6acb34cd43a686156db592dfecc6f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8606,
"upload_time": "2016-01-08T15:15:36",
"url": "https://files.pythonhosted.org/packages/17/02/11033aa13800ec6551064a507b8c44dde24eaa47f5f37193b8559260c423/python_templet-4.0.0.tar.gz"
}
]
}