{"id":15009975,"url":"https://github.com/josef-friedrich/tmep","last_synced_at":"2026-02-21T20:04:12.052Z","repository":{"id":37969303,"uuid":"66592197","full_name":"Josef-Friedrich/tmep","owner":"Josef-Friedrich","description":"Template and Macros Expansion for Path names.","archived":false,"fork":false,"pushed_at":"2025-03-06T03:34:13.000Z","size":511,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T09:11:14.362Z","etag":null,"topics":["macros","python","python-3","template","template-engine"],"latest_commit_sha":null,"homepage":"https://pypi.python.org/pypi/tmep","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Josef-Friedrich.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-25T20:48:53.000Z","updated_at":"2025-01-07T19:18:43.000Z","dependencies_parsed_at":"2024-04-12T13:55:14.269Z","dependency_job_id":"b0210aee-f19d-4604-bec0-7049092f9ca0","html_url":"https://github.com/Josef-Friedrich/tmep","commit_stats":{"total_commits":159,"total_committers":2,"mean_commits":79.5,"dds":"0.0062893081761006275","last_synced_commit":"a5403013cdd1c3939254ee70571addccedbb2456"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josef-Friedrich%2Ftmep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josef-Friedrich%2Ftmep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josef-Friedrich%2Ftmep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josef-Friedrich%2Ftmep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Josef-Friedrich","download_url":"https://codeload.github.com/Josef-Friedrich/tmep/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248961186,"owners_count":21189991,"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","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":["macros","python","python-3","template","template-engine"],"created_at":"2024-09-24T19:29:20.007Z","updated_at":"2026-02-21T20:04:12.045Z","avatar_url":"https://github.com/Josef-Friedrich.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: http://img.shields.io/pypi/v/tmep.svg\n    :target: https://pypi.org/project/tmep\n    :alt: This package on the Python Package Index\n\n.. image:: https://github.com/Josef-Friedrich/tmep/actions/workflows/tests.yml/badge.svg\n    :target: https://github.com/Josef-Friedrich/tmep/actions/workflows/tests.yml\n    :alt: Tests\n\n.. image:: https://readthedocs.org/projects/tmep/badge/?version=latest\n    :target: https://tmep.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n\n====\nTMEP\n====\n\nTMEP (Template Macro Expansion for Paths) is a small template engine that\nhas been specially developed for file paths.\n\nThe engine can replace or expand symbols (or variables) like ``$title`` and\napply functions (or macros) like ``%upper{}`` in path templates.\n\nThe code originates from the `Beets project \u003chttps://beets.io/\u003e`_ and was “extracted”\nfrom the code base together with the tests.\n\nInstallation\n============\n\nFrom PyPI\n---------\n\n.. code:: Shell\n\n    pip install tmep\n\nUsage\n=====\n\n.. code:: Python\n\n    \u003e\u003e\u003e import tmep\n    \u003e\u003e\u003e template = \"%upper{$prename $lastname}\"\n    \u003e\u003e\u003e values = {\"prename\": \"Franz\", \"lastname\": \"Schubert\"}\n    \u003e\u003e\u003e result = tmep.parse(template, values)\n    \u003e\u003e\u003e print(result)\n    FRANZ SCHUBERT\n\nThis module implements a string formatter based on the standard\n`PEP 292 \u003chttps://peps.python.org/pep-0292\u003e`_\n`string.Template \u003chttps://docs.python.org/3/library/string.html#template-strings\u003e`_\nclass extended with function calls. Variables, as with\n`string.Template \u003chttps://docs.python.org/3/library/string.html#template-strings\u003e`_,\nare indicated with ``$`` and functions are delimited\nwith ``%``.\n\nThis module assumes that everything is Unicode: the template and the\nsubstitution values. Bytestrings are not supported. Also, the templates\nalways behave like the ``safe_substitute`` method in the standard\nlibrary: unknown symbols are left intact.\n\nThis is sort of like a tiny, horrible degeneration of a real templating\nengine like Jinja2 or Mustache.\n\nTMEP provides public Python functions and a small command line tool that outputs\ndocumentation in various formats that can be used by projects based on TMEP.\n\nIntroduction\n============\n\n``tmep-doc --introduction-rst``\n\nTemplate Symbols (or Variables)\n  In path templates, symbols or varialbes such as ``$title``\n  (any name with the prefix ``$``) are replaced by the corresponding value.\n\n  Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit\n  a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent\n  to ``$title``; you can use this if you need to separate a field name from the\n  text that follows it.\n\n.. _Python template strings: https://docs.python.org/library/string.html#template-strings\n\nTemplate Functions (or Macros)\n  Path templates also support *function calls*, which can be used to transform\n  text and perform logical manipulations. The syntax for function calls is like\n  this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument\n  upper-case, so ``%upper{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.\n  You can, of course, nest function calls and place variable references in\n  function arguments, so ``%upper{$title}`` becomes the upper-case version of the\n  title.\n\nSyntax Details\n  The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are “special” in the path\n  template syntax. This means that, for example, if you want a ``%`` character to\n  appear in your paths, you’ll need to be careful that you don’t accidentally\n  write a function call. To escape any of these characters (except ``{``, and\n  ``,`` outside a function argument), prefix it with a ``$``.  For example,\n  ``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:\n\n  * ``${``, which is ambiguous with the variable reference syntax (like\n    ``${title}``). To insert a ``{`` alone, it's always sufficient to just type\n    ``{``.\n  * commas are used as argument separators in function calls. Inside of a\n    function’s argument, use ``$,`` to get a literal ``,`` character. Outside of\n    any function argument, escaping is not necessary: ``,`` by itself will\n    produce ``,`` in the output.\n\n  If a value or function is undefined, the syntax is simply left unreplaced. For\n  example, if you write ``$foo`` in a path template, this will yield ``$foo`` in\n  the resulting paths because \"foo\" is not a valid field name. The same is true of\n  syntax errors like unclosed ``{}`` pairs; if you ever see template syntax\n  constructs leaking into your paths, check your template for errors.\n\n  If an error occurs in the Python code that implements a function, the function\n  call will be expanded to a string that describes the exception so you can debug\n  your template. For example, the second parameter to ``%left`` must be an\n  integer; if you write ``%left{foo,bar}``, this will be expanded to something\n  like ``\u003cValueError: invalid literal for int()\u003e``.\n\nFunctions\n=========\n\nreStructuredText format (``tmep-doc --functions-rst``):\n\n:: \n\n    alpha\n      ``%alpha{text}``:  This function first ASCIIfies the given text, then all\n      non alphabet characters are replaced with whitespaces.\n\n      **Example:** ``%alpha{a1b23c}`` → ``a b c``\n\n    alphanum\n      ``%alphanum{text}``:  This function first ASCIIfies the given text, then all\n      non alpanumeric characters are replaced with whitespaces.\n\n      **Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``\n\n    asciify\n      ``%asciify{text}``:  Translate non-ASCII characters to their ASCII\n      equivalents. For example, “café” becomes “cafe”. Uses the mapping provided\n      by the unidecode module.\n\n      **Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``\n\n    delchars\n      ``%delchars{text,chars}``:  Delete every single character of “chars“ in\n      “text”.\n\n      **Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``\n\n    deldupchars\n      ``%deldupchars{text,chars}``:  Search for duplicate characters and replace\n      with only one occurrance of this characters.\n\n      **Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a\n      ---b___c, -}`` → ``a-b___c``\n\n    first\n      ``%first{text}`` or ``%first{text,count,skip}`` or\n      ``%first{text,count,skip,sep,join}``:  Returns the first item, separated by\n      ``;``. You can use ``%first{text,count,skip}``, where count is the number of\n      items (default 1) and skip is number to skip (default 0). You can also use\n      ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like\n      ``;`` or ``/`` and join is the text to concatenate the items.\n\n      **Example:** ``%first{Alice / Bob / Eve,2,0, / , \u0026 }`` → ``Alice \u0026 Bob``\n\n    if\n      ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``:  If\n      condition is nonempty (or nonzero, if it’s a number), then returns the\n      second argument. Otherwise, returns the third argument if specified (or\n      nothing if ``falseval`` is left off).\n\n      **Example:** ``x%if{false,foo}`` → ``x``\n\n    ifdef\n      ``%ifdef{field}``, ``%ifdef{field,trueval}`` or\n      ``%ifdef{field,trueval,falseval}``:  If field exists, then return\n      ``trueval`` or field (default). Otherwise, returns ``falseval``. The field\n      should be entered without ``$``.\n\n      **Example:** ``%ifdef{compilation,Compilation}``\n\n    ifdefempty\n      ``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``:  If\n      field exists and is empty, then return ``truetext``. Otherwise, returns\n      ``falsetext``. The field should be entered without ``$``.\n\n      **Example:** ``%ifdefempty{compilation,Album,Compilation}``\n\n    ifdefnotempty\n      ``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:\n      If field is not empty, then return ``truetext``. Otherwise, returns\n      ``falsetext``. The field should be entered without ``$``.\n\n      **Example:** ``%ifdefnotempty{compilation,Compilation,Album}``\n\n    initial\n      ``%initial{text}``:  Get the first character of a text in lowercase. The\n      text is converted to ASCII. All non word characters are erased.\n\n      **Example:** ``%initial{Schubert}`` → ``s``\n\n    left\n      ``%left{text,n}``:  Return the first “n” characters of “text”.\n\n      **Example:** ``%left{Schubert, 3}`` → ``Sch``\n\n    lower\n      ``%lower{text}``:  Convert “text” to lowercase.\n\n      **Example:** ``%lower{SCHUBERT}`` → ``schubert``\n\n    nowhitespace\n      ``%nowhitespace{text,replace}``:  Replace all whitespace characters with\n      ``replace``. By default: a dash (``-``)\n\n      **Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →\n      ``a_b``\n\n    num\n      ``%num{number,count}``:  Pad decimal number with leading zeros.\n\n      **Example:** ``%num{7,3}`` → ``007``\n\n    replchars\n      ``%replchars{text,chars,replace}``:  Replace the characters “chars” in\n      “text” with “replace”.\n\n      **Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``\n\n    right\n      ``%right{text,n}``:  Return the last “n” characters of “text”.\n\n      **Example:** ``%right{Schubert,3}`` → ``ert``\n\n    sanitize\n      ``%sanitize{text}``:  Delete characters that are not allowed in most file\n      systems.\n\n      **Example:** ``%sanitize{x:*?\u003c\u003e|/~\u0026x}`` → ``xx``\n\n    shorten\n      ``%shorten{text}`` or ``%shorten{text,max_size}``:  Shorten “text” on word\n      boundarys.\n\n      **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``\n\n    time\n      ``%time{date_time,format,curformat}``:  Return the date and time in any\n      format accepted by ``strftime``. For example, to get the year, use\n      ``%time{$added,%Y}``.\n\n      **Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``\n\n    title\n      ``%title{text}``:  Convert “text” to Title Case.\n\n      **Example:** ``%title{franz schubert}`` → ``Franz Schubert``\n\n    upper\n      ``%upper{text}``:  Convert “text” to UPPERCASE.\n\n      **Example:** ``%upper{foo}`` → ``FOO``\n\nPlain text format (``tmep-doc --functions-txt``):\n\n:: \n\n    alpha\n        -----\n\n        ``%alpha{text}``\n            This function first ASCIIfies the given text, then all non alphabet\n            characters are replaced with whitespaces.\n            ``%alpha{a1b23c}`` → ``a b c``\n\n        alphanum\n        --------\n\n        ``%alphanum{text}``\n            This function first ASCIIfies the given text, then all non alpanumeric\n            characters are replaced with whitespaces.\n            ``%alphanum{après-évêque1}`` → ``apres eveque1``\n\n        asciify\n        -------\n\n        ``%asciify{text}``\n            Translate non-ASCII characters to their ASCII equivalents. For\n            example, “café” becomes “cafe”. Uses the mapping provided by the\n            unidecode module.\n            ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``\n\n        delchars\n        --------\n\n        ``%delchars{text,chars}``\n            Delete every single character of “chars“ in “text”.\n            ``%delchars{Schubert, ue}`` → ``Schbrt``\n\n        deldupchars\n        -----------\n\n        ``%deldupchars{text,chars}``\n            Search for duplicate characters and replace with only one occurrance\n            of this characters.\n            ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a---\n            b___c, -}`` → ``a-b___c``\n\n        first\n        -----\n\n        ``%first{text}`` or ``%first{text,count,skip}`` or\n        ``%first{text,count,skip,sep,join}``\n            Returns the first item, separated by ``;``. You can use\n            ``%first{text,count,skip}``, where count is the number of items\n            (default 1) and skip is number to skip (default 0). You can also use\n            ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator,\n            like ``;`` or ``/`` and join is the text to concatenate the items.\n            ``%first{Alice / Bob / Eve,2,0, / , \u0026 }`` → ``Alice \u0026 Bob``\n\n        if\n        --\n\n        ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``\n            If condition is nonempty (or nonzero, if it’s a number), then returns\n            the second argument. Otherwise, returns the third argument if\n            specified (or nothing if ``falseval`` is left off).\n            ``x%if{false,foo}`` → ``x``\n\n        ifdef\n        -----\n\n        ``%ifdef{field}``, ``%ifdef{field,trueval}`` or\n        ``%ifdef{field,trueval,falseval}``\n            If field exists, then return ``trueval`` or field (default).\n            Otherwise, returns ``falseval``. The field should be entered without\n            ``$``.\n            ``%ifdef{compilation,Compilation}``\n\n        ifdefempty\n        ----------\n\n        ``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``\n            If field exists and is empty, then return ``truetext``. Otherwise,\n            returns ``falsetext``. The field should be entered without ``$``.\n            ``%ifdefempty{compilation,Album,Compilation}``\n\n        ifdefnotempty\n        -------------\n\n        ``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``\n            If field is not empty, then return ``truetext``. Otherwise, returns\n            ``falsetext``. The field should be entered without ``$``.\n            ``%ifdefnotempty{compilation,Compilation,Album}``\n\n        initial\n        -------\n\n        ``%initial{text}``\n            Get the first character of a text in lowercase. The text is converted\n            to ASCII. All non word characters are erased.\n            ``%initial{Schubert}`` → ``s``\n\n        left\n        ----\n\n        ``%left{text,n}``\n            Return the first “n” characters of “text”.\n            ``%left{Schubert, 3}`` → ``Sch``\n\n        lower\n        -----\n\n        ``%lower{text}``\n            Convert “text” to lowercase.\n            ``%lower{SCHUBERT}`` → ``schubert``\n\n        nowhitespace\n        ------------\n\n        ``%nowhitespace{text,replace}``\n            Replace all whitespace characters with ``replace``. By default: a dash\n            (``-``)\n            ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` → ``a_b``\n\n        num\n        ---\n\n        ``%num{number,count}``\n            Pad decimal number with leading zeros.\n            ``%num{7,3}`` → ``007``\n\n        replchars\n        ---------\n\n        ``%replchars{text,chars,replace}``\n            Replace the characters “chars” in “text” with “replace”.\n            ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``\n\n        right\n        -----\n\n        ``%right{text,n}``\n            Return the last “n” characters of “text”.\n            ``%right{Schubert,3}`` → ``ert``\n\n        sanitize\n        --------\n\n        ``%sanitize{text}``\n            Delete characters that are not allowed in most file systems.\n            ``%sanitize{x:*?\u003c\u003e|/~\u0026x}`` → ``xx``\n\n        shorten\n        -------\n\n        ``%shorten{text}`` or ``%shorten{text,max_size}``\n            Shorten “text” on word boundarys.\n            ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``\n\n        time\n        ----\n\n        ``%time{date_time,format,curformat}``\n            Return the date and time in any format accepted by ``strftime``. For\n            example, to get the year, use ``%time{$added,%Y}``.\n            ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``\n\n        title\n        -----\n\n        ``%title{text}``\n            Convert “text” to Title Case.\n            ``%title{franz schubert}`` → ``Franz Schubert``\n\n        upper\n        -----\n\n        ``%upper{text}``\n            Convert “text” to UPPERCASE.\n            ``%upper{foo}`` → ``FOO``\n\nPackage documentation\n=====================\n\nThe package documentation is hosted on\n`readthedocs \u003chttp://tmep.readthedocs.io\u003e`_.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosef-friedrich%2Ftmep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosef-friedrich%2Ftmep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosef-friedrich%2Ftmep/lists"}