pypage 2.0.9__py3-none-any.whl → 2.2.0__py3-none-any.whl

{pypage-2.0.9.dist-info → pypage-2.2.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: pypage
-Version: 2.0.9
-Summary: Light-weight Python Templating Engine
+Version: 2.2.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.9.tar.gz
+Download-URL: https://github.com/arjun-menon/pypage/archive/v2.2.0.tar.gz
 Author: Arjun G. Menon
 Author-email: contact@arjungmenon.com
 License: Apache-2.0
@@ -24,6 +24,16 @@ Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python :: 2
 Classifier: Programming Language :: Python :: 3
 License-File: LICENSE.txt
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: summary
 
 PyPage |pypi| |docs| |test|
 ===========================
@@ -62,6 +72,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**
 
 

pypage-2.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pypage.py,sha256=s6OuUUo_nZjpS9aZFaXMBXlUvBUDSiF_3DzIoaE2uW4,30890
+pypage-2.2.0.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pypage-2.2.0.dist-info/METADATA,sha256=GDhXXdpQcCAnSziU-5_Z9P1QujNlnSFUAY9sXggefWU,18347
+pypage-2.2.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
+pypage-2.2.0.dist-info/entry_points.txt,sha256=iHPN6EfIUdv-njh8GV04yDTzkcCLGNcXvdbA43s_8mo,39
+pypage-2.2.0.dist-info/top_level.txt,sha256=8AAB15dVQEt9xcwH_eLcVUZEbFlc__81RA5mOrYtJiQ,7
+pypage-2.2.0.dist-info/RECORD,,

{pypage-2.0.9.dist-info → pypage-2.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: setuptools (78.1.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pypage.py

@@ -18,7 +18,7 @@
 from __future__ import print_function
 import string, sys, time, os, json
 
-pypage_version = '2.0.9'
+pypage_version = '2.2.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()
@@ -303,6 +303,51 @@ class WhileBlock(BlockTag):
 
         return output
 
+class DefBlock(BlockTag):
+    """
+    The function tag. {% def foo a b c %}
+    """
+    tag_startswith = 'def '
+
+    @staticmethod
+    def identify(src):
+        return src.strip().startswith(DefBlock.tag_startswith)
+
+    def __init__(self, node):
+        super(DefBlock, self).__init__(node.loc)
+        self.src = node.src.strip()
+
+        name_and_args = self.src[len(self.tag_startswith):].strip().split()
+        for name  in name_and_args:
+            if not isidentifier(name):
+                raise InvalidDefBlockFunctionOrArgName(name)
+
+        self.funcname = name_and_args[0]
+        self.argnames = name_and_args[1:]
+
+    def run(self, pe):
+        def invoke(args):
+            if len(args) != len(self.argnames):
+                raise InvalidDefBlockMismatchingArgCount(self.argnames, args)
+
+            conflicting = set(pe.env.keys()) & set(self.argnames)
+            backup = { x : pe.env[x] for x in conflicting }
+
+            local_vars = dict(zip(self.argnames, args))
+            pe.env.update(local_vars)
+
+            output = exec_tree(self, pe)
+
+            for argname in self.argnames:
+                if argname in pe.env:
+                    del pe.env[argname]
+
+            pe.env.update(backup)
+            return output
+
+        pe.env[self.funcname] = lambda *args: invoke(args)
+        return ""
+
 class CaptureBlock(BlockTag):
     """
     Capture all content within this tag, and bind it to a variable.
@@ -383,7 +428,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):
@@ -443,6 +494,15 @@ class InvalidCaptureBlockVariableName(PypageSyntaxError):
     def __init__(self, varname):
         self.description = "Incorrect CaptureBlock: '%s' is not a valid Python variable name." % varname
 
+class InvalidDefBlockFunctionOrArgName(PypageSyntaxError):
+    def __init__(self, varname):
+        self.description = "Incorrect DefBlock: '%s' is not a valid function or argument name." % varname
+
+class InvalidDefBlockMismatchingArgCount(PypageSyntaxError):
+    def __init__(self, argnames, args):
+        self.description = "Incorrect DefBlock function call: expected %d arguments (%s) but received %d arguments (%s) instead." % (
+            len(argnames), ', '.join(argnames), len(args), ', '.join(map(repr, args)))
+
 class UnknownTag(PypageSyntaxError):
     def __init__(self, node):
         self.description = "Unknown tag '%s%s%s' at line %d, column %d." % (
@@ -832,10 +892,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.9.dist-info/RECORD

@@ -1,7 +0,0 @@
-pypage.py,sha256=qZnkMH_GC-05W-XlavDrT3B4xbkCm2i1T4nIJSMYMJU,28803
-pypage-2.0.9.dist-info/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pypage-2.0.9.dist-info/METADATA,sha256=jdL5K1PuLp14Qt4jAyiVTsnx6SePwSS6t5SyeP4mNSA,14640
-pypage-2.0.9.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-pypage-2.0.9.dist-info/entry_points.txt,sha256=iHPN6EfIUdv-njh8GV04yDTzkcCLGNcXvdbA43s_8mo,39
-pypage-2.0.9.dist-info/top_level.txt,sha256=8AAB15dVQEt9xcwH_eLcVUZEbFlc__81RA5mOrYtJiQ,7
-pypage-2.0.9.dist-info/RECORD,,