{"id":8010,"library":"cheetah3","title":"Cheetah3 Template Engine","description":"Cheetah is a powerful, open-source template engine and code generation tool for Python. It allows developers to generate dynamic web content, source code, and other text-based output from templates using a Python-like syntax. The current stable version is 3.2.6.post1. It maintains a moderate release cadence, focusing on stability and Python 3 compatibility.","status":"active","version":"3.2.6.post1","language":"en","source_language":"en","source_url":"https://github.com/CheetahTemplate3/cheetah3","tags":["templating","code-generation","template-engine","web"],"install":[{"cmd":"pip install cheetah3","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The package namespace is capitalized as `Cheetah`, not `cheetah`.","wrong":"from cheetah import Template","symbol":"Template","correct":"from Cheetah.Template import Template"},{"symbol":"DummyTransaction","correct":"from Cheetah.DummyTransaction import DummyTransaction"}],"quickstart":{"code":"from Cheetah.Template import Template\nimport os\n\n# Example template content\ntemplate_content = \"\"\"\n#def say_hello($name=\"Guest\")\nHello $name! Welcome to #filter upper $project_name#end filter .\n#end def\n\n$say_hello(\"World\")\nToday's date is $date.\n#if $enable_feature\n  Feature XYZ is enabled.\n#else\n  Feature XYZ is disabled.\n#end if\n\"\"\"\n\n# Data to pass to the template\nproject_data = {\n    'project_name': os.environ.get('CHEETAH_PROJECT_NAME', 'MyCheetahProject'),\n    'date': '2024-04-16',\n    'enable_feature': True\n}\n\n# Create a Template instance and pass data via searchList\nt = Template(template_content, searchList=[project_data])\n\n# Render the template\nrendered_output = str(t)\nprint(rendered_output)\n\n# Example of assigning variables directly\ntwo = Template(\"The value is $value.\")\ntwo.value = 123\nprint(str(two))\n","lang":"python","description":"This quickstart demonstrates how to create a simple Cheetah template, pass variables using a search list, define and call a macro (`#def`), use filters (`#filter`), and render the output. It also shows direct variable assignment."},"warnings":[{"fix":"Ensure your development and deployment environments use Python 3.4 or higher for `cheetah3`. If you need Python 2.7, install the legacy `cheetah` package using `pip install 'cheetah<3'`.","message":"The `cheetah3` package requires Python 3.4+. Despite PyPI's `requires_python` metadata potentially suggesting Python 2.7 compatibility, this is incorrect for the `cheetah3` fork. For Python 2.7 support, you must use the older `cheetah` (2.x) package.","severity":"breaking","affected_versions":"All cheetah3 versions"},{"fix":"Always use the capitalized module name: `from Cheetah.ModuleName import ...`","message":"The top-level import for Cheetah's modules uses a capitalized 'Cheetah' (e.g., `from Cheetah.Template import Template`). Using `cheetah` (lowercase) will result in an `ImportError` because Python's module resolution is case-sensitive.","severity":"gotcha","affected_versions":"All cheetah3 versions"},{"fix":"Ensure all variables accessed in the template are either assigned directly to the `Template` instance (e.g., `t.myVar = 'value'`) or provided via the `searchList` argument during initialization (e.g., `Template(..., searchList=[{'myVar': 'value'}])`).","message":"Cheetah templates resolve variables through a 'searchList', which is a list of objects (dictionaries, objects, modules) scanned for attributes. If a variable is not found in any item of the `searchList` or assigned directly, it will raise a `NameMapper.NotFound` error.","severity":"gotcha","affected_versions":"All cheetah3 versions"},{"fix":"Use `##` only for full-line comments. For multi-line comments, use `#* ... *#`. For inline comments or to remove text, consider using more advanced directives or custom filters if strict stripping is required.","message":"Cheetah's line comments (`##`) must start at the beginning of a line to be treated as comments. If `##` appears after non-whitespace characters on a line, it will be treated as literal output or cause a template parsing error.","severity":"gotcha","affected_versions":"All cheetah3 versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `cheetah3` is installed (`pip install cheetah3`) and use the capitalized import path: `from Cheetah.Template import Template`.","cause":"Attempting to import the `cheetah` package with a lowercase namespace, or `cheetah3` is not installed.","error":"ImportError: No module named 'cheetah'"},{"fix":"Pass the variable via the `searchList` argument during `Template` initialization (e.g., `Template(template_str, searchList=[{'my_variable': 'value'}])`) or assign it directly to the template instance (`t.my_variable = 'value'`).","cause":"A variable used in the template (`$my_variable`) was not found in the data provided to the template instance's search path.","error":"NameMapper.NotFound: Can't find 'my_variable' in the searchList"},{"fix":"Ensure the template content passed to `Template()` is a string. If you want to load from a file, use the `file` keyword argument: `Template(file='my_template.tmpl')`.","cause":"The first argument to `Template()` must be a string containing the template content. A non-string variable (e.g., a file handle, None) was passed directly.","error":"SyntaxError: Non-string object used as a template"},{"fix":"Cheetah directives are part of the template language and are used within the template string itself, not directly in Python code. Ensure directives follow Cheetah's specific template syntax (e.g., `#def myfunc($arg)...#end def`).","cause":"Attempting to instantiate or call a Cheetah directive (like `#def`, `#for`, `#if`) as if it were a Python class or function outside of the template context.","error":"TypeError: 'Class' object is not callable"}]}