pypage 2.0.8__tar.gz → 2.1.0__tar.gz

{pypage-2.0.8 → pypage-2.1.0}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.1
 Name: pypage
-Version: 2.0.8
+Version: 2.1.0
 Summary:  Light-weight Python Templating Engine
 Home-page: https://github.com/arjun-menon/pypage
-Download-URL: https://github.com/arjun-menon/pypage/archive/v2.0.8.tar.gz
+Download-URL: https://github.com/arjun-menon/pypage/archive/v2.1.0.tar.gz
 Author: Arjun G. Menon
 Author-email: contact@arjungmenon.com
-License: Apache
-Keywords: templating enigne text processing static generator
+License: Apache-2.0
+Keywords: templating engine text processing static generator,templating engine,text processing,template,templates
 Classifier: Topic :: Text Processing
+Classifier: Intended Audience :: Developers
 Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -20,26 +22,22 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python :: 2
-Classifier: Programming Language :: Python :: 2.7
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.2
-Classifier: Programming Language :: Python :: 3.3
-Classifier: Programming Language :: Python :: 3.4
-Classifier: Programming Language :: Python :: 3.5
 License-File: LICENSE.txt
 
-pypage |pypi| |docs|
-====================
+PyPage |pypi| |docs| |test|
+===========================
 
-pypage is a document template engine for Python programmers with a
+PyPage is a document template engine for Python programmers with a
 short learning curve.
 
-**Why use pypage?**
+**Why use PyPage?**
 
 -  Easy to pick up. Syntax similar to Python's.
 -  You need an eval-based template engine.
 
-pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
+PyPage supports Python 3.x and 2.7, and has been tested
+(using `test_cmd <https://github.com/arjun-menon/test_cmd>`_) on CPython and PyPy.
 
 **What does it look like?**
 
@@ -56,7 +54,7 @@ pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
 
 **Installation**
 
-You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `pip <https://pip.pypa.io/en/stable/>`_:
+You can `install <https://docs.python.org/3/installing/>`_ PyPage easily with `pip <https://pip.pypa.io/en/stable/>`_:
 
 .. code::
 
@@ -64,6 +62,29 @@ You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `p
 
 Try running ``pypage -h`` to see the command-line options available.
 
+
+**Why another templating language?**
+
+PyPage is lets you embed Python code easily and flexibly in textual documents (such as Markdown_, HTML, reStructuredText_, plain text, etc). It lets you construct powerful  programmatically-generated documents by embedding Python code in an elegant and flexible manner. Its syntax is similar to and partially inspired by the templating languages Jinja_ and Liquid_.
+
+While there are many templating engines out there, the primarily advantage of PyPage is the fact that its syntax is very close to Python's, and therefore the learning curve is very short for Python programmers.
+
+Rather than create a new mini domain-specific language for constructs such as ``for`` and ``if``, PyPage does a teeny tiny bit of obvious string manipulation, and passes your logical directives unaltered to the Python interpreter. As such, PyPage inherits Python's syntax for the most part. For example, ``for`` loops in PyPage get converted into Python's generator expressions. The ``for`` loop in a Python generator expression (or list comprehension) is far more powerful than its regular ``for`` loop. This means that PyPage ``for`` loops are richer and more expressive than you'd otherwise expect, while the learning curve is nearly non-existent.
+
+The primary disadvantage of using PyPage instead of a templating engine like Liquid is that PyPage does not operate on a restricted non-Turing-complete subset of programming languages, as Liquid for instance does. Liquid allows untrusted users to write and upload their own templates, because the expressiveness of Liquid is limited such that there is an implicit guarantee that the template will be processed in a reasonable (probably linear) amount of time using a reasonable amount of system resources. As such, Liquid's templating language is rather limited -- it offers a limited number of pre-defined functions/filters, and the overall flexibility of the language has been constrained in order to guarantee termination in a reasonable amount of time.
+
+PyPage, on the other hand gives the template writer full unfettered access to the Python interpreter. As such, PyPage is meant only for use in trusted contexts (or containers), and in some ways it's similar to PHP in that a you're mixing a full-blown programming language (Python) and text that could be HTML.
+
+This brings us to another topic: mixing code and UI. It is generally frowned upon to mix logic/code and the UI (or "view"). So it is good practise to not do any intelligent processing within your PyPage template. Instead, you can do it in a separate program, and pass an *environment* containing the results, to PyPage. An environment is a dictionary of variables that is passed to Python's ``exec``, and is therefore accessible from all of the code in the PyPage template. From within your template you can focus solely on how to transform these input variables into the HTML/rST/other page you're building.
+
+A pleasant aspect of PyPage, in comparison to other templating languages is that you don't have to learn much new syntax. It's probably the easiest to learn and most *flexible* templating language out there. It is highly flexible because of the plethora of easy-to-use powerful constructs that PyPage offers.
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _Liquid: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers
+.. _Jinja: https://github.com/pallets/jinja
+
+
 .. contents:: **Table of Contents**
 
 
@@ -85,7 +106,7 @@ example of an inline code tag:
 
     There are {{ 5 + 2 }} days in a week.
 
-The above, when processed by pypage, yields:
+The above, when processed by PyPage, yields:
 
 ::
 
@@ -127,7 +148,7 @@ for all code tags in the same file.
 
 As such, a variable instantiated in a code tag at the
 beginning of the document, will be available to all other code tags in
-the document. When pypage is invoked as library, an initial seed
+the document. When PyPage is invoked as library, an initial seed
 environment consisting of a Python dictionary mapping variable names to
 values, can be provided.
 
@@ -198,7 +219,7 @@ It's best to explain this with an example:
     {% %}
 
 When the above template is run, the resulting page will contain a
-randomly chosen greeting. As is evident, pypage syntax for if/elif/else
+randomly chosen greeting. As is evident, PyPage syntax for if/elif/else
 conditions closely mirrors Python's. The terminal ``{% %}`` can be
 replaced with an ``{% endif %}`` with no change in meaning (as with any
 block tag).
@@ -214,7 +235,7 @@ Let's start with a simple example:
 
 This will print out the vowels with a space after every character.
 
-Now that's an ordinary for loop. pypage permits for loops that are more
+Now that's an ordinary for loop. PyPage permits for loops that are more
 expressive than traditional Python for loops, by leveraging Python's
 *generator expressions*.
 
@@ -241,7 +262,7 @@ The above loop would result in:
     3 ~ b
     3 ~ c
 
-*Internally*, pypage morphs the expression
+*Internally*, PyPage morphs the expression
 ``for x in [1,2,3] for y in ['a','b','c']`` into the generator
 expression ``(x, y) for x in [1,2,3] for y in ['a','b','c']``. It
 exposes the the loop variables ``x`` and ``y`` by injecting them into
@@ -249,7 +270,7 @@ your namespace.
 
 *Note:* Injected loop variables replace variables with the same name for
 the duration of the loop. After the loop, the old variables with the
-identical names are restored (pypage backs them up).
+identical names are restored (PyPage backs them up).
 
 While Loops
 ^^^^^^^^^^^
@@ -289,13 +310,13 @@ evaluated.
 Long Loops
 ''''''''''
 
-If a loop runs *for more than 2 seconds*, pypage stops executing it, and
+If a loop runs *for more than 2 seconds*, PyPage stops executing it, and
 writes an error message to ``stdout`` saying that the loop had been
-terminated. As pypage is mostly intended to be used as a templatig
+terminated. As PyPage is mostly intended to be used as a templating
 language, loops generally shouldn't be running for longer than two
 seconds, and this timeout was added to make it easier to catch accidental
 infinite loops. If you actually need a loop to run for longer than 2
-seoncds, you can add the keyword ``slow`` right after the condition expression
+seconds, you can add the keyword ``slow`` right after the condition expression
 (``{{% while condition slow %}}``), and that would suppress this 2-second timeout.
 
 Capture Blocks
@@ -320,10 +341,10 @@ Finer Details
 Inheritance (with inject and exists)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The approach taken by pypage toward template inheritance is quite distinct from that of other
+The approach taken by PyPage toward template inheritance is quite distinct from that of other
 templating engines (`like Jinja's <http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance>`_).
-It's a lot simpler. You call a pypage-provided function ``inject`` with the path of a *pypage template* you want
-to inject (i.e. "*extend*" in Jinja parlance), and pypage will process that template under the current scope (with all
+It's a lot simpler. You call a PyPage-provided function ``inject`` with the path of a *PyPage template* you want
+to inject (i.e. "*extend*" in Jinja parlance), and PyPage will process that template under the current scope (with all
 previously defined variables being available to the injected template), and the ``inject`` function will return its output.
 
 A base template could look like this:
@@ -367,7 +388,7 @@ and is not present. The output of the "dervied" template is clear and obvious, w
 The include function
 ''''''''''''''''''''
 
-If you want to include (as in, substitute) a file directly without processing it with pypage, you can use the
+If you want to include (as in, substitute) a file directly without processing it with PyPage, you can use the
 ``include`` function. It functions like the ``inject`` function, taking the path to a file as argument, and
 returning the contents of the file unprocessed.
 
@@ -424,7 +445,7 @@ whitespace in the generated document.
 Automatic Indentation
 '''''''''''''''''''''
 
-pypage smartly handles indentation for you. In a multi-line code tag, if
+PyPage smartly handles indentation for you. In a multi-line code tag, if
 you consistently indent your Python code with a specific amount of
 whitespace, that indentation will be stripped off before executing the
 code block (as Python is indentation-sensitive), and the resulting
@@ -467,7 +488,7 @@ would produce the following output:
 Note that the ``Hello!`` was indented with same whitespace that the code
 in the code block was.
 
-pypage automatically intends the output of a multi-line tag to match the
+PyPage automatically intends the output of a multi-line tag to match the
 indentation level of the code tag. The number of whitespace characters
 at the beginning of the second line of the code block determines the
 indentation level for the whole block. All lines of code following the
@@ -484,3 +505,5 @@ License
    :target: https://pypi.python.org/pypi/pypage
 .. |docs| image:: https://readthedocs.org/projects/pypage/badge/?version=latest&style=flat
    :target: https://pypage.readthedocs.io/en/latest/
+.. |test| image:: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/

{pypage-2.0.8 → pypage-2.1.0}/README.rst

@@ -1,15 +1,16 @@
-pypage |pypi| |docs|
-====================
+PyPage |pypi| |docs| |test|
+===========================
 
-pypage is a document template engine for Python programmers with a
+PyPage is a document template engine for Python programmers with a
 short learning curve.
 
-**Why use pypage?**
+**Why use PyPage?**
 
 -  Easy to pick up. Syntax similar to Python's.
 -  You need an eval-based template engine.
 
-pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
+PyPage supports Python 3.x and 2.7, and has been tested
+(using `test_cmd <https://github.com/arjun-menon/test_cmd>`_) on CPython and PyPy.
 
 **What does it look like?**
 
@@ -26,7 +27,7 @@ pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
 
 **Installation**
 
-You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `pip <https://pip.pypa.io/en/stable/>`_:
+You can `install <https://docs.python.org/3/installing/>`_ PyPage easily with `pip <https://pip.pypa.io/en/stable/>`_:
 
 .. code::
 
@@ -34,6 +35,29 @@ You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `p
 
 Try running ``pypage -h`` to see the command-line options available.
 
+
+**Why another templating language?**
+
+PyPage is lets you embed Python code easily and flexibly in textual documents (such as Markdown_, HTML, reStructuredText_, plain text, etc). It lets you construct powerful  programmatically-generated documents by embedding Python code in an elegant and flexible manner. Its syntax is similar to and partially inspired by the templating languages Jinja_ and Liquid_.
+
+While there are many templating engines out there, the primarily advantage of PyPage is the fact that its syntax is very close to Python's, and therefore the learning curve is very short for Python programmers.
+
+Rather than create a new mini domain-specific language for constructs such as ``for`` and ``if``, PyPage does a teeny tiny bit of obvious string manipulation, and passes your logical directives unaltered to the Python interpreter. As such, PyPage inherits Python's syntax for the most part. For example, ``for`` loops in PyPage get converted into Python's generator expressions. The ``for`` loop in a Python generator expression (or list comprehension) is far more powerful than its regular ``for`` loop. This means that PyPage ``for`` loops are richer and more expressive than you'd otherwise expect, while the learning curve is nearly non-existent.
+
+The primary disadvantage of using PyPage instead of a templating engine like Liquid is that PyPage does not operate on a restricted non-Turing-complete subset of programming languages, as Liquid for instance does. Liquid allows untrusted users to write and upload their own templates, because the expressiveness of Liquid is limited such that there is an implicit guarantee that the template will be processed in a reasonable (probably linear) amount of time using a reasonable amount of system resources. As such, Liquid's templating language is rather limited -- it offers a limited number of pre-defined functions/filters, and the overall flexibility of the language has been constrained in order to guarantee termination in a reasonable amount of time.
+
+PyPage, on the other hand gives the template writer full unfettered access to the Python interpreter. As such, PyPage is meant only for use in trusted contexts (or containers), and in some ways it's similar to PHP in that a you're mixing a full-blown programming language (Python) and text that could be HTML.
+
+This brings us to another topic: mixing code and UI. It is generally frowned upon to mix logic/code and the UI (or "view"). So it is good practise to not do any intelligent processing within your PyPage template. Instead, you can do it in a separate program, and pass an *environment* containing the results, to PyPage. An environment is a dictionary of variables that is passed to Python's ``exec``, and is therefore accessible from all of the code in the PyPage template. From within your template you can focus solely on how to transform these input variables into the HTML/rST/other page you're building.
+
+A pleasant aspect of PyPage, in comparison to other templating languages is that you don't have to learn much new syntax. It's probably the easiest to learn and most *flexible* templating language out there. It is highly flexible because of the plethora of easy-to-use powerful constructs that PyPage offers.
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _Liquid: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers
+.. _Jinja: https://github.com/pallets/jinja
+
+
 .. contents:: **Table of Contents**
 
 
@@ -55,7 +79,7 @@ example of an inline code tag:
 
     There are {{ 5 + 2 }} days in a week.
 
-The above, when processed by pypage, yields:
+The above, when processed by PyPage, yields:
 
 ::
 
@@ -97,7 +121,7 @@ for all code tags in the same file.
 
 As such, a variable instantiated in a code tag at the
 beginning of the document, will be available to all other code tags in
-the document. When pypage is invoked as library, an initial seed
+the document. When PyPage is invoked as library, an initial seed
 environment consisting of a Python dictionary mapping variable names to
 values, can be provided.
 
@@ -168,7 +192,7 @@ It's best to explain this with an example:
     {% %}
 
 When the above template is run, the resulting page will contain a
-randomly chosen greeting. As is evident, pypage syntax for if/elif/else
+randomly chosen greeting. As is evident, PyPage syntax for if/elif/else
 conditions closely mirrors Python's. The terminal ``{% %}`` can be
 replaced with an ``{% endif %}`` with no change in meaning (as with any
 block tag).
@@ -184,7 +208,7 @@ Let's start with a simple example:
 
 This will print out the vowels with a space after every character.
 
-Now that's an ordinary for loop. pypage permits for loops that are more
+Now that's an ordinary for loop. PyPage permits for loops that are more
 expressive than traditional Python for loops, by leveraging Python's
 *generator expressions*.
 
@@ -211,7 +235,7 @@ The above loop would result in:
     3 ~ b
     3 ~ c
 
-*Internally*, pypage morphs the expression
+*Internally*, PyPage morphs the expression
 ``for x in [1,2,3] for y in ['a','b','c']`` into the generator
 expression ``(x, y) for x in [1,2,3] for y in ['a','b','c']``. It
 exposes the the loop variables ``x`` and ``y`` by injecting them into
@@ -219,7 +243,7 @@ your namespace.
 
 *Note:* Injected loop variables replace variables with the same name for
 the duration of the loop. After the loop, the old variables with the
-identical names are restored (pypage backs them up).
+identical names are restored (PyPage backs them up).
 
 While Loops
 ^^^^^^^^^^^
@@ -259,13 +283,13 @@ evaluated.
 Long Loops
 ''''''''''
 
-If a loop runs *for more than 2 seconds*, pypage stops executing it, and
+If a loop runs *for more than 2 seconds*, PyPage stops executing it, and
 writes an error message to ``stdout`` saying that the loop had been
-terminated. As pypage is mostly intended to be used as a templatig
+terminated. As PyPage is mostly intended to be used as a templating
 language, loops generally shouldn't be running for longer than two
 seconds, and this timeout was added to make it easier to catch accidental
 infinite loops. If you actually need a loop to run for longer than 2
-seoncds, you can add the keyword ``slow`` right after the condition expression
+seconds, you can add the keyword ``slow`` right after the condition expression
 (``{{% while condition slow %}}``), and that would suppress this 2-second timeout.
 
 Capture Blocks
@@ -290,10 +314,10 @@ Finer Details
 Inheritance (with inject and exists)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The approach taken by pypage toward template inheritance is quite distinct from that of other
+The approach taken by PyPage toward template inheritance is quite distinct from that of other
 templating engines (`like Jinja's <http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance>`_).
-It's a lot simpler. You call a pypage-provided function ``inject`` with the path of a *pypage template* you want
-to inject (i.e. "*extend*" in Jinja parlance), and pypage will process that template under the current scope (with all
+It's a lot simpler. You call a PyPage-provided function ``inject`` with the path of a *PyPage template* you want
+to inject (i.e. "*extend*" in Jinja parlance), and PyPage will process that template under the current scope (with all
 previously defined variables being available to the injected template), and the ``inject`` function will return its output.
 
 A base template could look like this:
@@ -337,7 +361,7 @@ and is not present. The output of the "dervied" template is clear and obvious, w
 The include function
 ''''''''''''''''''''
 
-If you want to include (as in, substitute) a file directly without processing it with pypage, you can use the
+If you want to include (as in, substitute) a file directly without processing it with PyPage, you can use the
 ``include`` function. It functions like the ``inject`` function, taking the path to a file as argument, and
 returning the contents of the file unprocessed.
 
@@ -394,7 +418,7 @@ whitespace in the generated document.
 Automatic Indentation
 '''''''''''''''''''''
 
-pypage smartly handles indentation for you. In a multi-line code tag, if
+PyPage smartly handles indentation for you. In a multi-line code tag, if
 you consistently indent your Python code with a specific amount of
 whitespace, that indentation will be stripped off before executing the
 code block (as Python is indentation-sensitive), and the resulting
@@ -437,7 +461,7 @@ would produce the following output:
 Note that the ``Hello!`` was indented with same whitespace that the code
 in the code block was.
 
-pypage automatically intends the output of a multi-line tag to match the
+PyPage automatically intends the output of a multi-line tag to match the
 indentation level of the code tag. The number of whitespace characters
 at the beginning of the second line of the code block determines the
 indentation level for the whole block. All lines of code following the
@@ -454,3 +478,5 @@ License
    :target: https://pypi.python.org/pypi/pypage
 .. |docs| image:: https://readthedocs.org/projects/pypage/badge/?version=latest&style=flat
    :target: https://pypage.readthedocs.io/en/latest/
+.. |test| image:: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/

{pypage-2.0.8 → pypage-2.1.0}/pypage.egg-info/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.1
 Name: pypage
-Version: 2.0.8
+Version: 2.1.0
 Summary:  Light-weight Python Templating Engine
 Home-page: https://github.com/arjun-menon/pypage
-Download-URL: https://github.com/arjun-menon/pypage/archive/v2.0.8.tar.gz
+Download-URL: https://github.com/arjun-menon/pypage/archive/v2.1.0.tar.gz
 Author: Arjun G. Menon
 Author-email: contact@arjungmenon.com
-License: Apache
-Keywords: templating enigne text processing static generator
+License: Apache-2.0
+Keywords: templating engine text processing static generator,templating engine,text processing,template,templates
 Classifier: Topic :: Text Processing
+Classifier: Intended Audience :: Developers
 Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -20,26 +22,22 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python :: 2
-Classifier: Programming Language :: Python :: 2.7
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.2
-Classifier: Programming Language :: Python :: 3.3
-Classifier: Programming Language :: Python :: 3.4
-Classifier: Programming Language :: Python :: 3.5
 License-File: LICENSE.txt
 
-pypage |pypi| |docs|
-====================
+PyPage |pypi| |docs| |test|
+===========================
 
-pypage is a document template engine for Python programmers with a
+PyPage is a document template engine for Python programmers with a
 short learning curve.
 
-**Why use pypage?**
+**Why use PyPage?**
 
 -  Easy to pick up. Syntax similar to Python's.
 -  You need an eval-based template engine.
 
-pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
+PyPage supports Python 3.x and 2.7, and has been tested
+(using `test_cmd <https://github.com/arjun-menon/test_cmd>`_) on CPython and PyPy.
 
 **What does it look like?**
 
@@ -56,7 +54,7 @@ pypage supports Python 3.x and 2.7, and has been on CPython and PyPy.
 
 **Installation**
 
-You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `pip <https://pip.pypa.io/en/stable/>`_:
+You can `install <https://docs.python.org/3/installing/>`_ PyPage easily with `pip <https://pip.pypa.io/en/stable/>`_:
 
 .. code::
 
@@ -64,6 +62,29 @@ You can `install <https://docs.python.org/3/installing/>`_ pypage easily with `p
 
 Try running ``pypage -h`` to see the command-line options available.
 
+
+**Why another templating language?**
+
+PyPage is lets you embed Python code easily and flexibly in textual documents (such as Markdown_, HTML, reStructuredText_, plain text, etc). It lets you construct powerful  programmatically-generated documents by embedding Python code in an elegant and flexible manner. Its syntax is similar to and partially inspired by the templating languages Jinja_ and Liquid_.
+
+While there are many templating engines out there, the primarily advantage of PyPage is the fact that its syntax is very close to Python's, and therefore the learning curve is very short for Python programmers.
+
+Rather than create a new mini domain-specific language for constructs such as ``for`` and ``if``, PyPage does a teeny tiny bit of obvious string manipulation, and passes your logical directives unaltered to the Python interpreter. As such, PyPage inherits Python's syntax for the most part. For example, ``for`` loops in PyPage get converted into Python's generator expressions. The ``for`` loop in a Python generator expression (or list comprehension) is far more powerful than its regular ``for`` loop. This means that PyPage ``for`` loops are richer and more expressive than you'd otherwise expect, while the learning curve is nearly non-existent.
+
+The primary disadvantage of using PyPage instead of a templating engine like Liquid is that PyPage does not operate on a restricted non-Turing-complete subset of programming languages, as Liquid for instance does. Liquid allows untrusted users to write and upload their own templates, because the expressiveness of Liquid is limited such that there is an implicit guarantee that the template will be processed in a reasonable (probably linear) amount of time using a reasonable amount of system resources. As such, Liquid's templating language is rather limited -- it offers a limited number of pre-defined functions/filters, and the overall flexibility of the language has been constrained in order to guarantee termination in a reasonable amount of time.
+
+PyPage, on the other hand gives the template writer full unfettered access to the Python interpreter. As such, PyPage is meant only for use in trusted contexts (or containers), and in some ways it's similar to PHP in that a you're mixing a full-blown programming language (Python) and text that could be HTML.
+
+This brings us to another topic: mixing code and UI. It is generally frowned upon to mix logic/code and the UI (or "view"). So it is good practise to not do any intelligent processing within your PyPage template. Instead, you can do it in a separate program, and pass an *environment* containing the results, to PyPage. An environment is a dictionary of variables that is passed to Python's ``exec``, and is therefore accessible from all of the code in the PyPage template. From within your template you can focus solely on how to transform these input variables into the HTML/rST/other page you're building.
+
+A pleasant aspect of PyPage, in comparison to other templating languages is that you don't have to learn much new syntax. It's probably the easiest to learn and most *flexible* templating language out there. It is highly flexible because of the plethora of easy-to-use powerful constructs that PyPage offers.
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _Liquid: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers
+.. _Jinja: https://github.com/pallets/jinja
+
+
 .. contents:: **Table of Contents**
 
 
@@ -85,7 +106,7 @@ example of an inline code tag:
 
     There are {{ 5 + 2 }} days in a week.
 
-The above, when processed by pypage, yields:
+The above, when processed by PyPage, yields:
 
 ::
 
@@ -127,7 +148,7 @@ for all code tags in the same file.
 
 As such, a variable instantiated in a code tag at the
 beginning of the document, will be available to all other code tags in
-the document. When pypage is invoked as library, an initial seed
+the document. When PyPage is invoked as library, an initial seed
 environment consisting of a Python dictionary mapping variable names to
 values, can be provided.
 
@@ -198,7 +219,7 @@ It's best to explain this with an example:
     {% %}
 
 When the above template is run, the resulting page will contain a
-randomly chosen greeting. As is evident, pypage syntax for if/elif/else
+randomly chosen greeting. As is evident, PyPage syntax for if/elif/else
 conditions closely mirrors Python's. The terminal ``{% %}`` can be
 replaced with an ``{% endif %}`` with no change in meaning (as with any
 block tag).
@@ -214,7 +235,7 @@ Let's start with a simple example:
 
 This will print out the vowels with a space after every character.
 
-Now that's an ordinary for loop. pypage permits for loops that are more
+Now that's an ordinary for loop. PyPage permits for loops that are more
 expressive than traditional Python for loops, by leveraging Python's
 *generator expressions*.
 
@@ -241,7 +262,7 @@ The above loop would result in:
     3 ~ b
     3 ~ c
 
-*Internally*, pypage morphs the expression
+*Internally*, PyPage morphs the expression
 ``for x in [1,2,3] for y in ['a','b','c']`` into the generator
 expression ``(x, y) for x in [1,2,3] for y in ['a','b','c']``. It
 exposes the the loop variables ``x`` and ``y`` by injecting them into
@@ -249,7 +270,7 @@ your namespace.
 
 *Note:* Injected loop variables replace variables with the same name for
 the duration of the loop. After the loop, the old variables with the
-identical names are restored (pypage backs them up).
+identical names are restored (PyPage backs them up).
 
 While Loops
 ^^^^^^^^^^^
@@ -289,13 +310,13 @@ evaluated.
 Long Loops
 ''''''''''
 
-If a loop runs *for more than 2 seconds*, pypage stops executing it, and
+If a loop runs *for more than 2 seconds*, PyPage stops executing it, and
 writes an error message to ``stdout`` saying that the loop had been
-terminated. As pypage is mostly intended to be used as a templatig
+terminated. As PyPage is mostly intended to be used as a templating
 language, loops generally shouldn't be running for longer than two
 seconds, and this timeout was added to make it easier to catch accidental
 infinite loops. If you actually need a loop to run for longer than 2
-seoncds, you can add the keyword ``slow`` right after the condition expression
+seconds, you can add the keyword ``slow`` right after the condition expression
 (``{{% while condition slow %}}``), and that would suppress this 2-second timeout.
 
 Capture Blocks
@@ -320,10 +341,10 @@ Finer Details
 Inheritance (with inject and exists)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The approach taken by pypage toward template inheritance is quite distinct from that of other
+The approach taken by PyPage toward template inheritance is quite distinct from that of other
 templating engines (`like Jinja's <http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance>`_).
-It's a lot simpler. You call a pypage-provided function ``inject`` with the path of a *pypage template* you want
-to inject (i.e. "*extend*" in Jinja parlance), and pypage will process that template under the current scope (with all
+It's a lot simpler. You call a PyPage-provided function ``inject`` with the path of a *PyPage template* you want
+to inject (i.e. "*extend*" in Jinja parlance), and PyPage will process that template under the current scope (with all
 previously defined variables being available to the injected template), and the ``inject`` function will return its output.
 
 A base template could look like this:
@@ -367,7 +388,7 @@ and is not present. The output of the "dervied" template is clear and obvious, w
 The include function
 ''''''''''''''''''''
 
-If you want to include (as in, substitute) a file directly without processing it with pypage, you can use the
+If you want to include (as in, substitute) a file directly without processing it with PyPage, you can use the
 ``include`` function. It functions like the ``inject`` function, taking the path to a file as argument, and
 returning the contents of the file unprocessed.
 
@@ -424,7 +445,7 @@ whitespace in the generated document.
 Automatic Indentation
 '''''''''''''''''''''
 
-pypage smartly handles indentation for you. In a multi-line code tag, if
+PyPage smartly handles indentation for you. In a multi-line code tag, if
 you consistently indent your Python code with a specific amount of
 whitespace, that indentation will be stripped off before executing the
 code block (as Python is indentation-sensitive), and the resulting
@@ -467,7 +488,7 @@ would produce the following output:
 Note that the ``Hello!`` was indented with same whitespace that the code
 in the code block was.
 
-pypage automatically intends the output of a multi-line tag to match the
+PyPage automatically intends the output of a multi-line tag to match the
 indentation level of the code tag. The number of whitespace characters
 at the beginning of the second line of the code block determines the
 indentation level for the whole block. All lines of code following the
@@ -484,3 +505,5 @@ License
    :target: https://pypi.python.org/pypi/pypage
 .. |docs| image:: https://readthedocs.org/projects/pypage/badge/?version=latest&style=flat
    :target: https://pypage.readthedocs.io/en/latest/
+.. |test| image:: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/arjun-menon/pypage/actions/workflows/test.yml/

{pypage-2.0.8 → pypage-2.1.0}/pypage.py

@@ -18,7 +18,7 @@
 from __future__ import print_function
 import string, sys, time, os, json
 
-pypage_version = '2.0.8'
+pypage_version = '2.1.0'
 
 class RootNode(object):
     """
@@ -62,7 +62,7 @@ class TagNode(object):
         open_delim:  string containig the opening delimiter
         close_delim: string containig the closing delimiter
     """
-    escape_delims = {'\{':'{', '\}':'}'}
+    escape_delims = {('\\' + '{'):'{', ('\\' + '}'):'}'}
 
     def __init__(self, loc):
         self.src = str()
@@ -383,7 +383,13 @@ class EndBlockTag(BlockTag):
     def __repr__(self):
         return 'EndBlockTag.\n'
 
-class PypageSyntaxError(Exception):
+class PypageError(Exception):
+    def __init__(self, description='undefined'):
+        self.description = description
+    def __str__(self):
+        return "Error: " + self.description
+
+class PypageSyntaxError(PypageError):
     def __init__(self, description='undefined'):
         self.description = description
     def __str__(self):
@@ -832,10 +838,9 @@ def read_file(filepath):
         with open(filepath, 'r') as source_file:
             return source_file.read()
     else:
-        print("File %s does not exist." % repr(filepath), file=sys.stderr)
-        sys.exit(1)
+        raise PypageError("File %s does not exist. CWD: %s" % (repr(filepath), os.getcwd()))
 
-__all__ = ['pypage', 'pypage_version']
+__all__ = ['pypage', 'pypage_version', PypageError, PypageSyntaxError]
 
 def main():
     import argparse

{pypage-2.0.8 → pypage-2.1.0}/setup.py

@@ -3,9 +3,11 @@
 from setuptools import setup
 
 from pypage import pypage_version as version
+
 repo_url = 'https://github.com/arjun-menon/pypage'
 download_url = '%s/archive/v%s.tar.gz' % (repo_url, version)
 
+
 def get_long_desc():
     doc_file_name = 'README.rst'
     exclude_lines_with_words = ['toctree', 'maxdepth']
@@ -14,6 +16,7 @@ def get_long_desc():
         lines = f.readlines()
         return ''.join(line for line in lines if not any(word in line for word in exclude_lines_with_words))
 
+
 setup(name='pypage',
       version=version,
       description=' Light-weight Python Templating Engine',
@@ -22,15 +25,23 @@ setup(name='pypage',
       download_url=download_url,
       author='Arjun G. Menon',
       author_email='contact@arjungmenon.com',
-      keywords='templating enigne text processing static generator',
-      license='Apache',
+      keywords=[
+          'templating engine text processing static generator',
+          'templating engine',
+          'text processing',
+          'template',
+          'templates'
+      ],
+      license='Apache-2.0',
       py_modules=['pypage'],
       entry_points={
           'console_scripts': ['pypage=pypage:main'],
       },
       classifiers=[
           'Topic :: Text Processing',
+          'Intended Audience :: Developers',
           'Topic :: Internet :: WWW/HTTP',
+          'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
           'Topic :: Text Processing :: Markup :: HTML',
           'License :: OSI Approved :: Apache Software License',
           'Topic :: Software Development :: Libraries :: Python Modules',
@@ -41,10 +52,5 @@ setup(name='pypage',
           'Programming Language :: Python :: Implementation :: CPython',
           'Programming Language :: Python :: Implementation :: PyPy',
           'Programming Language :: Python :: 2',
-          'Programming Language :: Python :: 2.7',
           'Programming Language :: Python :: 3',
-          'Programming Language :: Python :: 3.2',
-          'Programming Language :: Python :: 3.3',
-          'Programming Language :: Python :: 3.4',
-          'Programming Language :: Python :: 3.5',
       ])