| Name | tmep JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | https://github.com/Josef-Friedrich/tmep |
| Summary | Template engine for file paths. Expand variables like ``$title`` and apply functions like ``%upper{}``. |
| upload_time | 2024-02-10 19:07:04 |
| maintainer | |
| docs_url | None |
| author | Josef Friedrich |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: http://img.shields.io/pypi/v/tmep.svg
:target: https://pypi.org/project/tmep
:alt: This package on the Python Package Index
.. image:: https://github.com/Josef-Friedrich/tmep/actions/workflows/tests.yml/badge.svg
:target: https://github.com/Josef-Friedrich/tmep/actions/workflows/tests.yml
:alt: Tests
.. image:: https://readthedocs.org/projects/tmep/badge/?version=latest
:target: https://tmep.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
====
TMEP
====
TMEP (Template Macro Expansion for Paths) is a small template engine that
has been specially developed for file paths.
The engine can replace or expand symbols (or variables) like ``$title`` and
apply functions (or macros) like ``%upper{}`` in path templates.
The code originates from the `Beets project <https://beets.io/>`_ and was “extracted”
from the code base together with the tests.
Installation
============
From PyPI
---------
.. code:: Shell
pip install tmep
Usage
=====
.. code:: Python
>>> import tmep
>>> template = "%upper{$prename $lastname}"
>>> values = {"prename": "Franz", "lastname": "Schubert"}
>>> result = tmep.parse(template, values)
>>> print(result)
FRANZ SCHUBERT
This module implements a string formatter based on the standard
`PEP 292 <https://peps.python.org/pep-0292>`_
`string.Template <https://docs.python.org/3/library/string.html#template-strings>`_
class extended with function calls. Variables, as with
`string.Template <https://docs.python.org/3/library/string.html#template-strings>`_,
are indicated with ``$`` and functions are delimited
with ``%``.
This module assumes that everything is Unicode: the template and the
substitution values. Bytestrings are not supported. Also, the templates
always behave like the ``safe_substitute`` method in the standard
library: unknown symbols are left intact.
This is sort of like a tiny, horrible degeneration of a real templating
engine like Jinja2 or Mustache.
TMEP provides public Python functions and a small command line tool that outputs
documentation in various formats that can be used by projects based on TMEP.
Introduction
============
``tmep-doc --introduction-rst``
Template Symbols (or Variables)
In path templates, symbols or varialbes such as ``$title``
(any name with the prefix ``$``) are replaced by the corresponding value.
Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit
a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent
to ``$title``; you can use this if you need to separate a field name from the
text that follows it.
.. _Python template strings: https://docs.python.org/library/string.html#template-strings
Template Functions (or Macros)
Path templates also support *function calls*, which can be used to transform
text and perform logical manipulations. The syntax for function calls is like
this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument
upper-case, so ``%upper{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.
You can, of course, nest function calls and place variable references in
function arguments, so ``%upper{$title}`` becomes the upper-case version of the
title.
Syntax Details
The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are “special” in the path
template syntax. This means that, for example, if you want a ``%`` character to
appear in your paths, you’ll need to be careful that you don’t accidentally
write a function call. To escape any of these characters (except ``{``, and
``,`` outside a function argument), prefix it with a ``$``. For example,
``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:
* ``${``, which is ambiguous with the variable reference syntax (like
``${title}``). To insert a ``{`` alone, it's always sufficient to just type
``{``.
* commas are used as argument separators in function calls. Inside of a
function’s argument, use ``$,`` to get a literal ``,`` character. Outside of
any function argument, escaping is not necessary: ``,`` by itself will
produce ``,`` in the output.
If a value or function is undefined, the syntax is simply left unreplaced. For
example, if you write ``$foo`` in a path template, this will yield ``$foo`` in
the resulting paths because "foo" is not a valid field name. The same is true of
syntax errors like unclosed ``{}`` pairs; if you ever see template syntax
constructs leaking into your paths, check your template for errors.
If an error occurs in the Python code that implements a function, the function
call will be expanded to a string that describes the exception so you can debug
your template. For example, the second parameter to ``%left`` must be an
integer; if you write ``%left{foo,bar}``, this will be expanded to something
like ``<ValueError: invalid literal for int()>``.
Functions
=========
reStructuredText format (``tmep-doc --functions-rst``):
alpha
``%alpha{text}``: This function first ASCIIfies the given text, then all
non alphabet characters are replaced with whitespaces.
**Example:** ``%alpha{a1b23c}`` → ``a b c``
alphanum
``%alphanum{text}``: This function first ASCIIfies the given text, then all
non alpanumeric characters are replaced with whitespaces.
**Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``
asciify
``%asciify{text}``: Translate non-ASCII characters to their ASCII
equivalents. For example, “café” becomes “cafe”. Uses the mapping provided
by the unidecode module.
**Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
delchars
``%delchars{text,chars}``: Delete every single character of “chars“ in
“text”.
**Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``
deldupchars
``%deldupchars{text,chars}``: Search for duplicate characters and replace
with only one occurrance of this characters.
**Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a
---b___c, -}`` → ``a-b___c``
first
``%first{text}`` or ``%first{text,count,skip}`` or
``%first{text,count,skip,sep,join}``: Returns the first item, separated by
``;``. You can use ``%first{text,count,skip}``, where count is the number of
items (default 1) and skip is number to skip (default 0). You can also use
``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like
``;`` or ``/`` and join is the text to concatenate the items.
**Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
if
``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If
condition is nonempty (or nonzero, if it’s a number), then returns the
second argument. Otherwise, returns the third argument if specified (or
nothing if ``falseval`` is left off).
**Example:** ``x%if{false,foo}`` → ``x``
ifdef
``%ifdef{field}``, ``%ifdef{field,trueval}`` or
``%ifdef{field,trueval,falseval}``: If field exists, then return
``trueval`` or field (default). Otherwise, returns ``falseval``. The field
should be entered without ``$``.
**Example:** ``%ifdef{compilation,Compilation}``
ifdefempty
``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``: If
field exists and is empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefempty{compilation,Album,Compilation}``
ifdefnotempty
``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:
If field is not empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefnotempty{compilation,Compilation,Album}``
initial
``%initial{text}``: Get the first character of a text in lowercase. The
text is converted to ASCII. All non word characters are erased.
**Example:** ``%initial{Schubert}`` → ``s``
left
``%left{text,n}``: Return the first “n” characters of “text”.
**Example:** ``%left{Schubert, 3}`` → ``Sch``
lower
``%lower{text}``: Convert “text” to lowercase.
**Example:** ``%lower{SCHUBERT}`` → ``schubert``
nowhitespace
``%nowhitespace{text,replace}``: Replace all whitespace characters with
``replace``. By default: a dash (``-``)
**Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →
``a_b``
num
``%num{number,count}``: Pad decimal number with leading zeros.
**Example:** ``%num{7,3}`` → ``007``
replchars
``%replchars{text,chars,replace}``: Replace the characters “chars” in
“text” with “replace”.
**Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
right
``%right{text,n}``: Return the last “n” characters of “text”.
**Example:** ``%right{Schubert,3}`` → ``ert``
sanitize
``%sanitize{text}``: Delete characters that are not allowed in most file
systems.
**Example:** ``%sanitize{x:*?<>|/~&x}`` → ``xx``
shorten
``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten “text” on word
boundarys.
**Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
time
``%time{date_time,format,curformat}``: Return the date and time in any
format accepted by ``strftime``. For example, to get the year, use
``%time{$added,%Y}``.
**Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
title
``%title{text}``: Convert “text” to Title Case.
**Example:** ``%title{franz schubert}`` → ``Franz Schubert``
upper
``%upper{text}``: Convert “text” to UPPERCASE.
**Example:** ``%upper{foo}`` → ``FOO``
::
alpha
``%alpha{text}``: This function first ASCIIfies the given text, then all
non alphabet characters are replaced with whitespaces.
**Example:** ``%alpha{a1b23c}`` → ``a b c``
alphanum
``%alphanum{text}``: This function first ASCIIfies the given text, then all
non alpanumeric characters are replaced with whitespaces.
**Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``
asciify
``%asciify{text}``: Translate non-ASCII characters to their ASCII
equivalents. For example, “café” becomes “cafe”. Uses the mapping provided
by the unidecode module.
**Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
delchars
``%delchars{text,chars}``: Delete every single character of “chars“ in
“text”.
**Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``
deldupchars
``%deldupchars{text,chars}``: Search for duplicate characters and replace
with only one occurrance of this characters.
**Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a
---b___c, -}`` → ``a-b___c``
first
``%first{text}`` or ``%first{text,count,skip}`` or
``%first{text,count,skip,sep,join}``: Returns the first item, separated by
``;``. You can use ``%first{text,count,skip}``, where count is the number of
items (default 1) and skip is number to skip (default 0). You can also use
``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like
``;`` or ``/`` and join is the text to concatenate the items.
**Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
if
``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If
condition is nonempty (or nonzero, if it’s a number), then returns the
second argument. Otherwise, returns the third argument if specified (or
nothing if ``falseval`` is left off).
**Example:** ``x%if{false,foo}`` → ``x``
ifdef
``%ifdef{field}``, ``%ifdef{field,trueval}`` or
``%ifdef{field,trueval,falseval}``: If field exists, then return
``trueval`` or field (default). Otherwise, returns ``falseval``. The field
should be entered without ``$``.
**Example:** ``%ifdef{compilation,Compilation}``
ifdefempty
``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``: If
field exists and is empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefempty{compilation,Album,Compilation}``
ifdefnotempty
``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:
If field is not empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefnotempty{compilation,Compilation,Album}``
initial
``%initial{text}``: Get the first character of a text in lowercase. The
text is converted to ASCII. All non word characters are erased.
**Example:** ``%initial{Schubert}`` → ``s``
left
``%left{text,n}``: Return the first “n” characters of “text”.
**Example:** ``%left{Schubert, 3}`` → ``Sch``
lower
``%lower{text}``: Convert “text” to lowercase.
**Example:** ``%lower{SCHUBERT}`` → ``schubert``
nowhitespace
``%nowhitespace{text,replace}``: Replace all whitespace characters with
``replace``. By default: a dash (``-``)
**Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →
``a_b``
num
``%num{number,count}``: Pad decimal number with leading zeros.
**Example:** ``%num{7,3}`` → ``007``
replchars
``%replchars{text,chars,replace}``: Replace the characters “chars” in
“text” with “replace”.
**Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
right
``%right{text,n}``: Return the last “n” characters of “text”.
**Example:** ``%right{Schubert,3}`` → ``ert``
sanitize
``%sanitize{text}``: Delete characters that are not allowed in most file
systems.
**Example:** ``%sanitize{x:*?<>|/~&x}`` → ``xx``
shorten
``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten “text” on word
boundarys.
**Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
time
``%time{date_time,format,curformat}``: Return the date and time in any
format accepted by ``strftime``. For example, to get the year, use
``%time{$added,%Y}``.
**Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
title
``%title{text}``: Convert “text” to Title Case.
**Example:** ``%title{franz schubert}`` → ``Franz Schubert``
upper
``%upper{text}``: Convert “text” to UPPERCASE.
**Example:** ``%upper{foo}`` → ``FOO``
Plain text format (``tmep-doc --functions-txt``):
::
alpha
-----
``%alpha{text}``
This function first ASCIIfies the given text, then all non alphabet
characters are replaced with whitespaces.
``%alpha{a1b23c}`` → ``a b c``
alphanum
--------
``%alphanum{text}``
This function first ASCIIfies the given text, then all non alpanumeric
characters are replaced with whitespaces.
``%alphanum{après-évêque1}`` → ``apres eveque1``
asciify
-------
``%asciify{text}``
Translate non-ASCII characters to their ASCII equivalents. For
example, “café” becomes “cafe”. Uses the mapping provided by the
unidecode module.
``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
delchars
--------
``%delchars{text,chars}``
Delete every single character of “chars“ in “text”.
``%delchars{Schubert, ue}`` → ``Schbrt``
deldupchars
-----------
``%deldupchars{text,chars}``
Search for duplicate characters and replace with only one occurrance
of this characters.
``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a---
b___c, -}`` → ``a-b___c``
first
-----
``%first{text}`` or ``%first{text,count,skip}`` or
``%first{text,count,skip,sep,join}``
Returns the first item, separated by ``;``. You can use
``%first{text,count,skip}``, where count is the number of items
(default 1) and skip is number to skip (default 0). You can also use
``%first{text,count,skip,sep,join}`` where ``sep`` is the separator,
like ``;`` or ``/`` and join is the text to concatenate the items.
``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
if
--
``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``
If condition is nonempty (or nonzero, if it’s a number), then returns
the second argument. Otherwise, returns the third argument if
specified (or nothing if ``falseval`` is left off).
``x%if{false,foo}`` → ``x``
ifdef
-----
``%ifdef{field}``, ``%ifdef{field,trueval}`` or
``%ifdef{field,trueval,falseval}``
If field exists, then return ``trueval`` or field (default).
Otherwise, returns ``falseval``. The field should be entered without
``$``.
``%ifdef{compilation,Compilation}``
ifdefempty
----------
``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``
If field exists and is empty, then return ``truetext``. Otherwise,
returns ``falsetext``. The field should be entered without ``$``.
``%ifdefempty{compilation,Album,Compilation}``
ifdefnotempty
-------------
``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``
If field is not empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
``%ifdefnotempty{compilation,Compilation,Album}``
initial
-------
``%initial{text}``
Get the first character of a text in lowercase. The text is converted
to ASCII. All non word characters are erased.
``%initial{Schubert}`` → ``s``
left
----
``%left{text,n}``
Return the first “n” characters of “text”.
``%left{Schubert, 3}`` → ``Sch``
lower
-----
``%lower{text}``
Convert “text” to lowercase.
``%lower{SCHUBERT}`` → ``schubert``
nowhitespace
------------
``%nowhitespace{text,replace}``
Replace all whitespace characters with ``replace``. By default: a dash
(``-``)
``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` → ``a_b``
num
---
``%num{number,count}``
Pad decimal number with leading zeros.
``%num{7,3}`` → ``007``
replchars
---------
``%replchars{text,chars,replace}``
Replace the characters “chars” in “text” with “replace”.
``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
right
-----
``%right{text,n}``
Return the last “n” characters of “text”.
``%right{Schubert,3}`` → ``ert``
sanitize
--------
``%sanitize{text}``
Delete characters that are not allowed in most file systems.
``%sanitize{x:*?<>|/~&x}`` → ``xx``
shorten
-------
``%shorten{text}`` or ``%shorten{text,max_size}``
Shorten “text” on word boundarys.
``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
time
----
``%time{date_time,format,curformat}``
Return the date and time in any format accepted by ``strftime``. For
example, to get the year, use ``%time{$added,%Y}``.
``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
title
-----
``%title{text}``
Convert “text” to Title Case.
``%title{franz schubert}`` → ``Franz Schubert``
upper
-----
``%upper{text}``
Convert “text” to UPPERCASE.
``%upper{foo}`` → ``FOO``
Development
===========
Test
----
::
poetry run tox
Publish a new version
---------------------
::
git tag 1.1.1
git push --tags
poetry build
poetry publish
Package documentation
---------------------
The package documentation is hosted on
`readthedocs <http://tmep.readthedocs.io>`_.
Generate the package documentation:
::
python setup.py build_sphinx
Raw data
{
"_id": null,
"home_page": "https://github.com/Josef-Friedrich/tmep",
"name": "tmep",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Josef Friedrich",
"author_email": "josef@friedrich.rocks",
"download_url": "https://files.pythonhosted.org/packages/35/7a/b8a6a8ded97727a13fb26be93a129fc081b8d452217a8249630c802be7c5/tmep-3.0.0.tar.gz",
"platform": null,
"description": ".. 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 <https://beets.io/>`_ and was \u201cextracted\u201d\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 >>> import tmep\n >>> template = \"%upper{$prename $lastname}\"\n >>> values = {\"prename\": \"Franz\", \"lastname\": \"Schubert\"}\n >>> result = tmep.parse(template, values)\n >>> print(result)\n FRANZ SCHUBERT\n\nThis module implements a string formatter based on the standard\n`PEP 292 <https://peps.python.org/pep-0292>`_\n`string.Template <https://docs.python.org/3/library/string.html#template-strings>`_\nclass extended with function calls. Variables, as with\n`string.Template <https://docs.python.org/3/library/string.html#template-strings>`_,\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 \u201cspecial\u201d in the path\n template syntax. This means that, for example, if you want a ``%`` character to\n appear in your paths, you\u2019ll need to be careful that you don\u2019t 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\u2019s 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 ``<ValueError: invalid literal for int()>``.\n\nFunctions\n=========\n\nreStructuredText format (``tmep-doc --functions-rst``):\n\nalpha\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}`` \u2192 ``a b c``\n\nalphanum\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\u00e8s-\u00e9v\u00eaque1}`` \u2192 ``apres eveque1``\n\nasciify\n ``%asciify{text}``: Translate non-ASCII characters to their ASCII\n equivalents. For example, \u201ccaf\u00e9\u201d becomes \u201ccafe\u201d. Uses the mapping provided\n by the unidecode module.\n\n **Example:** ``%asciify{\u00e4\u00c4\u00f6\u00d6\u00fc\u00dc}`` \u2192 ``aeAeoeOeueUe``\n\ndelchars\n ``%delchars{text,chars}``: Delete every single character of \u201cchars\u201c in\n \u201ctext\u201d.\n\n **Example:** ``%delchars{Schubert, ue}`` \u2192 ``Schbrt``\n\ndeldupchars\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}`` \u2192 ``a-b_c.d``; ``%deldupchars{a\n ---b___c, -}`` \u2192 ``a-b___c``\n\nfirst\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, / , & }`` \u2192 ``Alice & Bob``\n\nif\n ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If\n condition is nonempty (or nonzero, if it\u2019s 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}`` \u2192 ``x``\n\nifdef\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\nifdefempty\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\nifdefnotempty\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\ninitial\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}`` \u2192 ``s``\n\nleft\n ``%left{text,n}``: Return the first \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%left{Schubert, 3}`` \u2192 ``Sch``\n\nlower\n ``%lower{text}``: Convert \u201ctext\u201d to lowercase.\n\n **Example:** ``%lower{SCHUBERT}`` \u2192 ``schubert``\n\nnowhitespace\n ``%nowhitespace{text,replace}``: Replace all whitespace characters with\n ``replace``. By default: a dash (``-``)\n\n **Example:** ``%nowhitespace{a b}`` \u2192 ``a-b``; ``%nowhitespace{a b, _}`` \u2192\n ``a_b``\n\nnum\n ``%num{number,count}``: Pad decimal number with leading zeros.\n\n **Example:** ``%num{7,3}`` \u2192 ``007``\n\nreplchars\n ``%replchars{text,chars,replace}``: Replace the characters \u201cchars\u201d in\n \u201ctext\u201d with \u201creplace\u201d.\n\n **Example:** ``%replchars{Schubert,-,ue}`` \u2192 ``Sch-b-rt``\n\nright\n ``%right{text,n}``: Return the last \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%right{Schubert,3}`` \u2192 ``ert``\n\nsanitize\n ``%sanitize{text}``: Delete characters that are not allowed in most file\n systems.\n\n **Example:** ``%sanitize{x:*?<>|/~&x}`` \u2192 ``xx``\n\nshorten\n ``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten \u201ctext\u201d on word\n boundarys.\n\n **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` \u2192 ``Lorem``\n\ntime\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}`` \u2192 ``2024``\n\ntitle\n ``%title{text}``: Convert \u201ctext\u201d to Title Case.\n\n **Example:** ``%title{franz schubert}`` \u2192 ``Franz Schubert``\n\nupper\n ``%upper{text}``: Convert \u201ctext\u201d to UPPERCASE.\n\n **Example:** ``%upper{foo}`` \u2192 ``FOO``\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}`` \u2192 ``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\u00e8s-\u00e9v\u00eaque1}`` \u2192 ``apres eveque1``\n\n asciify\n ``%asciify{text}``: Translate non-ASCII characters to their ASCII\n equivalents. For example, \u201ccaf\u00e9\u201d becomes \u201ccafe\u201d. Uses the mapping provided\n by the unidecode module.\n\n **Example:** ``%asciify{\u00e4\u00c4\u00f6\u00d6\u00fc\u00dc}`` \u2192 ``aeAeoeOeueUe``\n\n delchars\n ``%delchars{text,chars}``: Delete every single character of \u201cchars\u201c in\n \u201ctext\u201d.\n\n **Example:** ``%delchars{Schubert, ue}`` \u2192 ``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}`` \u2192 ``a-b_c.d``; ``%deldupchars{a\n ---b___c, -}`` \u2192 ``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, / , & }`` \u2192 ``Alice & Bob``\n\n if\n ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If\n condition is nonempty (or nonzero, if it\u2019s 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}`` \u2192 ``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}`` \u2192 ``s``\n\n left\n ``%left{text,n}``: Return the first \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%left{Schubert, 3}`` \u2192 ``Sch``\n\n lower\n ``%lower{text}``: Convert \u201ctext\u201d to lowercase.\n\n **Example:** ``%lower{SCHUBERT}`` \u2192 ``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}`` \u2192 ``a-b``; ``%nowhitespace{a b, _}`` \u2192\n ``a_b``\n\n num\n ``%num{number,count}``: Pad decimal number with leading zeros.\n\n **Example:** ``%num{7,3}`` \u2192 ``007``\n\n replchars\n ``%replchars{text,chars,replace}``: Replace the characters \u201cchars\u201d in\n \u201ctext\u201d with \u201creplace\u201d.\n\n **Example:** ``%replchars{Schubert,-,ue}`` \u2192 ``Sch-b-rt``\n\n right\n ``%right{text,n}``: Return the last \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%right{Schubert,3}`` \u2192 ``ert``\n\n sanitize\n ``%sanitize{text}``: Delete characters that are not allowed in most file\n systems.\n\n **Example:** ``%sanitize{x:*?<>|/~&x}`` \u2192 ``xx``\n\n shorten\n ``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten \u201ctext\u201d on word\n boundarys.\n\n **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` \u2192 ``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}`` \u2192 ``2024``\n\n title\n ``%title{text}``: Convert \u201ctext\u201d to Title Case.\n\n **Example:** ``%title{franz schubert}`` \u2192 ``Franz Schubert``\n\n upper\n ``%upper{text}``: Convert \u201ctext\u201d to UPPERCASE.\n\n **Example:** ``%upper{foo}`` \u2192 ``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}`` \u2192 ``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\u00e8s-\u00e9v\u00eaque1}`` \u2192 ``apres eveque1``\n\n asciify\n -------\n\n ``%asciify{text}``\n Translate non-ASCII characters to their ASCII equivalents. For\n example, \u201ccaf\u00e9\u201d becomes \u201ccafe\u201d. Uses the mapping provided by the\n unidecode module.\n ``%asciify{\u00e4\u00c4\u00f6\u00d6\u00fc\u00dc}`` \u2192 ``aeAeoeOeueUe``\n\n delchars\n --------\n\n ``%delchars{text,chars}``\n Delete every single character of \u201cchars\u201c in \u201ctext\u201d.\n ``%delchars{Schubert, ue}`` \u2192 ``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}`` \u2192 ``a-b_c.d``; ``%deldupchars{a---\n b___c, -}`` \u2192 ``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, / , & }`` \u2192 ``Alice & Bob``\n\n if\n --\n\n ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``\n If condition is nonempty (or nonzero, if it\u2019s 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}`` \u2192 ``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}`` \u2192 ``s``\n\n left\n ----\n\n ``%left{text,n}``\n Return the first \u201cn\u201d characters of \u201ctext\u201d.\n ``%left{Schubert, 3}`` \u2192 ``Sch``\n\n lower\n -----\n\n ``%lower{text}``\n Convert \u201ctext\u201d to lowercase.\n ``%lower{SCHUBERT}`` \u2192 ``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}`` \u2192 ``a-b``; ``%nowhitespace{a b, _}`` \u2192 ``a_b``\n\n num\n ---\n\n ``%num{number,count}``\n Pad decimal number with leading zeros.\n ``%num{7,3}`` \u2192 ``007``\n\n replchars\n ---------\n\n ``%replchars{text,chars,replace}``\n Replace the characters \u201cchars\u201d in \u201ctext\u201d with \u201creplace\u201d.\n ``%replchars{Schubert,-,ue}`` \u2192 ``Sch-b-rt``\n\n right\n -----\n\n ``%right{text,n}``\n Return the last \u201cn\u201d characters of \u201ctext\u201d.\n ``%right{Schubert,3}`` \u2192 ``ert``\n\n sanitize\n --------\n\n ``%sanitize{text}``\n Delete characters that are not allowed in most file systems.\n ``%sanitize{x:*?<>|/~&x}`` \u2192 ``xx``\n\n shorten\n -------\n\n ``%shorten{text}`` or ``%shorten{text,max_size}``\n Shorten \u201ctext\u201d on word boundarys.\n ``%shorten{Lorem ipsum dolor sit, 10}`` \u2192 ``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}`` \u2192 ``2024``\n\n title\n -----\n\n ``%title{text}``\n Convert \u201ctext\u201d to Title Case.\n ``%title{franz schubert}`` \u2192 ``Franz Schubert``\n\n upper\n -----\n\n ``%upper{text}``\n Convert \u201ctext\u201d to UPPERCASE.\n ``%upper{foo}`` \u2192 ``FOO``\n\nDevelopment\n===========\n\nTest\n----\n\n::\n\n poetry run tox\n\nPublish a new version\n---------------------\n\n::\n\n git tag 1.1.1\n git push --tags\n poetry build\n poetry publish\n\nPackage documentation\n---------------------\n\nThe package documentation is hosted on\n`readthedocs <http://tmep.readthedocs.io>`_.\n\nGenerate the package documentation:\n\n::\n\n python setup.py build_sphinx\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Template engine for file paths. Expand variables like ``$title`` and apply functions like ``%upper{}``.",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/Josef-Friedrich/tmep",
"Repository": "https://github.com/Josef-Friedrich/tmep"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c154e0491e6ceaba31fd53127bfae71d9a228b15d0811130444f59dc55ed08b1",
"md5": "986bb11cde96017c8bddb71c7aebc5b7",
"sha256": "4084f49612cbfdc3e688c67c5c4dd8f7cbb467db852d4c248806eb096b56b600"
},
"downloads": -1,
"filename": "tmep-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "986bb11cde96017c8bddb71c7aebc5b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 22133,
"upload_time": "2024-02-10T19:07:01",
"upload_time_iso_8601": "2024-02-10T19:07:01.891470Z",
"url": "https://files.pythonhosted.org/packages/c1/54/e0491e6ceaba31fd53127bfae71d9a228b15d0811130444f59dc55ed08b1/tmep-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "357ab8a6a8ded97727a13fb26be93a129fc081b8d452217a8249630c802be7c5",
"md5": "796613cf680825704b3595aee337b9a8",
"sha256": "0c970c857d9bc35590215d3065ff3b29a0d36ca0e1ba9522a2ee0ab8a7b2854f"
},
"downloads": -1,
"filename": "tmep-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "796613cf680825704b3595aee337b9a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 23047,
"upload_time": "2024-02-10T19:07:04",
"upload_time_iso_8601": "2024-02-10T19:07:04.145246Z",
"url": "https://files.pythonhosted.org/packages/35/7a/b8a6a8ded97727a13fb26be93a129fc081b8d452217a8249630c802be7c5/tmep-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-10 19:07:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Josef-Friedrich",
"github_project": "tmep",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "tmep"
}
