Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Plugin/Mount.py

@@ -0,0 +1,223 @@
+"""
+Pyjoyment.Plugin.Mount - Application mount plugin
+=================================================
+::
+
+    # Pyjoyment
+    route = app.plugin('Mount', {'/prefix': '/home/sri/foo/script/foo'})
+
+    # Pyjoyment.Lite
+    route = plugin('Mount', {'/prefix': '/home/sri/myapp.py'})
+
+    # Adjust the generated route and mounted application
+    example = plugin('Mount', {'/example': '/home/sri/example.py'})
+    example.to(message='It works great!')
+    embedded = example.pattern.defaults['app']
+    embedded.config(foo='bar')
+    embedded.log = app.log
+
+    # Mount application with host
+    plugin('Mount', {'example.com': '/home/sri/myapp.py'})
+
+    # Host and path
+    plugin('Mount', {'example.com/myapp': '/home/sri/myapp.py'})
+
+    # Or even hosts with wildcard subdomains
+    plugin('Mount', {'*.example.com/myapp': '/home/sri/myapp.py'})
+
+    # Application object
+    plugin('Mount', {'/prefix': MyApp.new()})
+
+    # WSGI application, as an object or as the name of its module and its
+    # attribute
+    plugin('Mount', {'/flask': flask_app})
+    plugin('Mount', {'/flask': 'myflask:app'})
+
+    # ASGI application, as an object or as the name of its module and its
+    # attribute
+    plugin('Mount', {'/starlette': starlette_app})
+    plugin('Mount', {'/starlette': 'mystarlette:app'})
+
+    # FastCGI application, as PHP on php-fpm, by its location, with the
+    # directory of its scripts and the one entry of every other path
+    plugin('Mount', {'/php': 'fcgi://127.0.0.1:9000'})
+    plugin('Mount', {'/php': 'fcgi+unix://%2Frun%2Fphp%2Ffpm.sock'})
+    plugin('Mount', {'/blog': 'fcgi://127.0.0.1:9000?document_root=%2Fvar%2Fwww&script=index.php'})
+
+    # CGI application, as an object, as a string is the path of a script
+    plugin('Mount', {'/cgi-bin': Pyjo.App.CGI.new(document_root='/usr/lib/cgi-bin')})
+
+    # Event function of AWS Lambda, as an object, in a process of its own
+    plugin('Mount', {'/function': Pyjo.App.Lambda.new(function='myfunction.handler')})
+
+    # A regular expression of the whole path, whose group path is the rest of
+    # the path for the application, and whose other named groups are captures
+    plugin('Mount', {re.compile(r'/php(?P<path>/.*)?'): flask_app})
+    plugin('Mount', {re.compile(r'/(?P<user>\\w+)/blog(?P<path>/.*)?'): flask_app})
+
+:mod:`Pyjoyment.Plugin.Mount` is a plugin that allows you to mount whole
+:mod:`Pyjoyment` applications, other applications of :mod:`Pyjo`, ``WSGI``
+applications, which :mod:`Pyjo.App.WSGI` runs, and ``ASGI`` applications,
+whose ``__call__`` is a coroutine function, which :mod:`Pyjo.App.ASGI` runs,
+as an application of :mod:`Pyjo` from a script, an object, or the name of a
+module and its attribute, and ``FastCGI`` applications, which
+:mod:`Pyjo.App.FastCGI` connects to, by their location ``fcgi://`` or
+``fcgi+unix://``, ``CGI`` programs, which :mod:`Pyjo.App.CGI` runs, and
+event functions of AWS Lambda, which :mod:`Pyjo.App.Lambda` runs, as an
+object of them. An application that is not one of :mod:`Pyjoyment` gets the
+server that runs it with :meth:`~Pyjo.App.Pyjo_App.server` before the server
+starts, as the application that mounts it does.
+
+The path is a pattern of a route that matches the beginning of the path of a
+request, as in Mojolicious, so that ``/php`` matches ``/php.css`` too, which
+an application of another framework does not get, as its ``SCRIPT_NAME`` or
+``root_path`` ends at a slash. A regular expression matches the whole path, as
+the ones of PromQL do, with the rest of it for the application in its group
+``path``.
+
+The code of this plugin is a good example for learning to build new plugins,
+you're welcome to fork it.
+
+See :mod:`Pyjoyment.Plugins` for a list of plugins that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Plugin::Mount
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugin/Mount.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.App
+import Pyjo.App.ASGI
+import Pyjo.App.FastCGI
+import Pyjo.App.WSGI
+import Pyjo.Exception
+import Pyjo.Server
+import Pyjoyment.Plugin
+import Pyjoyment.Routes.Pattern
+
+import importlib
+import inspect
+import os
+import re
+
+from typing import TYPE_CHECKING, Any, cast
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+    import Pyjoyment.Routes.Route
+
+
+class Pyjoyment_Plugin_Mount(Pyjoyment.Plugin.object):
+    """
+    :mod:`Pyjoyment.Plugin.Mount` inherits all methods from
+    :mod:`Pyjoyment.Plugin` and implements the following new ones.
+    """
+
+    def register(self, app: 'Pyjoyment.object', conf: dict[Any, Any]) -> 'Pyjoyment.Routes.Route.object':
+        """::
+
+            route = plugin.register(Pyjoyment.new(), {'/foo': '/some/app.py'})
+            route = plugin.register(Pyjoyment.new(), {'/foo': 'some_app:app'})
+
+        Mount application and return the generated route, which is usually a
+        :mod:`Pyjoyment.Routes.Route` object.
+        """
+        import Pyjoyment
+
+        key: str | re.Pattern[str] = next(iter(conf))
+        embed: Any = _load(conf[key])
+        if isinstance(embed, Pyjoyment.object):
+            embed.secrets = app.secrets
+
+        # Not in Mojolicious: another application of Pyjo, as one of Pyjo.App.WSGI, gets the server that runs it before it
+        # starts and after it stops, as the application that mounts it gets it
+        else:
+
+            def before_server_start(server: Pyjo.Server.object, app: Any) -> None:
+                embed.server(server)
+
+            def after_server_stop(server: Pyjo.Server.object, app: Any) -> Any:
+                return embed.server_stopped(server)
+
+            app.hook('before_server_start', before_server_start)
+            app.hook('after_server_stop', after_server_stop)
+        embed.log = app.log
+
+        # Not in Mojolicious: a regular expression that matches the whole path, as the ones of PromQL do, whose group
+        # path is the rest of the path for the application, as partial routes have it, and whose other named groups are
+        # captures
+        if isinstance(key, re.Pattern):
+            route = app.routes.any()
+            route.pattern = _Whole(key)
+            route.partial = True
+            return route.to(app=embed)
+
+        # Extract host
+        path: str | None = key
+        host = None
+        if m := re.match(r'^(\*\.)?([^/]+)(/.*)?$', path):
+            host = re.compile(rf'^(?:.*\.)?{re.escape(m[2])}$' if m[1] else rf'^{re.escape(m[2])}$', re.I)
+            path = m[3]
+
+        route = app.routes.any(path)
+        route.partial = True
+        route.to(app=embed)
+        return route.requires(host=host) if host else route
+
+
+# Not in Mojolicious: an application as an object, or as the name of a module and its attribute, as ASGI servers take
+# it, an ASGI or a WSGI application, which Pyjo.App.ASGI or Pyjo.App.WSGI runs, and the location of a FastCGI
+# application, which Pyjo.App.FastCGI connects to, where Mojolicious loads a script
+def _load(value: Any) -> Pyjo.Server.Application:
+    if isinstance(value, str) and re.match(r'fcgi(\+unix)?://', value):
+        return Pyjo.App.FastCGI.new(url=value)
+    if isinstance(value, str) and re.fullmatch(r'[\w.]+:[\w.]+', value) and not os.path.exists(value):
+        module, _, name = value.partition(':')
+        try:
+            value = importlib.import_module(module)
+            for attr in name.split('.'):
+                value = getattr(value, attr)
+        except Exception as e:
+            raise Pyjo.Exception.new(f'Can\'t load application "{module}:{name}": {e}') from e
+    elif isinstance(value, str | os.PathLike):
+        return Pyjo.Server.new().load_app(cast(str, value))
+
+    if isinstance(value, Pyjo.App.object):
+        return value
+    if inspect.iscoroutinefunction(value) or inspect.iscoroutinefunction(type(value).__call__):
+        return Pyjo.App.ASGI.new(app=value)
+    if not callable(value):
+        raise Pyjo.Exception.new(f'"{value!r}" is not an application')
+    return Pyjo.App.WSGI.new(app=value)
+
+
+# Not in Mojolicious: the pattern of a regular expression that matches the whole path, whose named groups are captures,
+# and whose group path, from its start to the end of the path, is the rest of the path
+class _Whole(Pyjoyment.Routes.Pattern.object):
+    def __init__(self, whole: re.Pattern[str]) -> None:
+        super().__init__()
+        self.whole = whole
+        # The regular expression and its source, as the pages of exceptions and of not found and the command routes show
+        # them
+        self.regex = whole
+        self.unparsed = whole.pattern
+
+    def match_partial(self, path: str, detect: bool = False) -> tuple[dict[str, Any], str] | None:
+        if (m := self.whole.fullmatch(path)) is None:
+            return None
+        captures = {**self.defaults, **{name: value for name, value in m.groupdict().items() if value is not None}}
+        rest = path[m.start('path') :] if captures.pop('path', None) is not None else ''
+        return captures, rest
+
+
+new = Pyjoyment_Plugin_Mount.new
+object = Pyjoyment_Plugin_Mount
+Mount = Pyjoyment_Plugin_Mount

Pyjoyment/Plugin/PyRenderer.py

@@ -0,0 +1,209 @@
+"""
+Pyjoyment.Plugin.PyRenderer - Template string renderer plugin
+=============================================================
+::
+
+    # Pyjoyment
+    app.plugin('PyRenderer')
+
+    # A template of a function
+    @app.template('index.html')
+    def index(c, name):
+        return t'<p>Hello {name}!</p>'
+
+    c.render('index', name='Joe')
+
+    # An inline t-string of Python 3.14
+    c.render(inline=t'<p>Hello {name}!</p>')
+
+    # The same on any Python
+    c.render(inline=t('<p>Hello {name}!</p>', name=name))
+
+:mod:`Pyjoyment.Plugin.PyRenderer` is a renderer for ``py`` templates, which
+are template strings, t-strings of
+`PEP 750 <https://peps.python.org/pep-0750/>`_ or of
+:func:`Pyjo.String.Template.t`, rendered by :mod:`Pyjo.String.Template`, which
+escapes the values that they interpolate, unless they are markup, as the
+helpers of :mod:`Pyjoyment.Plugin.TagHelpers` return. ::
+
+    from Pyjo.String.Template import t
+
+    # "<p>Hello &lt;script&gt;!</p>"
+    name = '<script>'
+    c.render(inline=t('<p>Hello {name}!</p>', name=name))
+
+    # "<p><a href="/">Home</a></p>"
+    c.render(inline=t('<p>{link}</p>', link=c.link_to('Home', '/')))
+
+A template string is code, which cannot be read from a file of data as a
+template of :mod:`Pyjoyment.Plugin.EPRenderer` is, so a template is a function
+that returns one, registered with :meth:`Pyjoyment.Pyjoyment_App.template`,
+or the function ``template`` of :mod:`Pyjoyment.Lite`, by its name with the
+format, as ``index.html``. The function gets the controller and the values
+of the stash that it names as its parameters, as the variables of an ``ep``
+template, or all of them with ``**``, and it can set the values of the stash
+that the renderer reads, as a layout. ::
+
+    # A template with a layout
+    @app.template('hello.html')
+    def hello(c, name):
+        c.layout('default')
+        c.title('Hello')
+        return t'<p>Hello {name}!</p>'
+
+    # The layout, which gets the content and the title
+    @app.template('layouts/default.html')
+    def default(c, **stash):
+        return t'<title>{c.title()}</title><body>{c.content()}</body>'
+
+A template can also be a file in
+:attr:`Pyjoyment.Renderer.Pyjoyment_Renderer.paths` with the extension ``py``,
+as ``templates/index.html.py``, a module of Python whose function ``render``
+is the function of the template. The file is
+compiled once and kept in the cache of the renderer, without the bytecode
+that an import writes next to it, and an exception in it shows the lines of
+the file. ::
+
+    # templates/hello.html.py
+    def render(c, name):
+        return t'<p>Hello {name}!</p>'
+
+An inline template that is a template string is rendered by it, unless
+another handler is given. Its values are evaluated where it is written, so it
+gets the values of the stash as the code around it does, ``c.stash('name')``,
+and a layout does not apply to it, as to any inline template.
+
+This is a core plugin, that means it is always enabled and its code a good
+example for learning to build new plugins, you're welcome to fork it.
+
+See :mod:`Pyjoyment.Plugins` for a list of plugins that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Inspired by `Mojolicious::Plugin::EPLRenderer
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugin/EPLRenderer.pm>`_ of Mojolicious 9.49.
+"""
+
+import Pyjo.Exception
+import Pyjo.File
+import Pyjo.String.Template
+import Pyjoyment.Plugin
+
+from Pyjo.Util import decode, encode, md5_sum
+
+import inspect
+import io
+import types
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+    import Pyjoyment.Controller
+    import Pyjoyment.Renderer
+
+
+class Pyjoyment_Plugin_PyRenderer(Pyjoyment.Plugin.object):
+    """
+    :mod:`Pyjoyment.Plugin.PyRenderer` inherits all methods from
+    :mod:`Pyjoyment.Plugin` and implements the following new ones.
+    """
+
+    def register(self, app: 'Pyjoyment.object', conf: dict[str, Any] | None = None) -> None:
+        """::
+
+            plugin.register(Pyjoyment.new())
+
+        Register renderer in :mod:`Pyjoyment` application.
+        """
+        app.renderer.add_handler('py', _handler)
+
+
+def _handler(
+    renderer: 'Pyjoyment.Renderer.object',
+    c: 'Pyjoyment.Controller.object',
+    output: io.StringIO,
+    options: dict[str, Any],
+) -> None:
+    log = c.helpers.log()
+
+    # Inline
+    inline = options.get('inline')
+    if inline is not None:
+        if not Pyjo.String.Template.is_template(inline):
+            return
+        template = Pyjo.String.Template.t(inline)
+        name = md5_sum(encode('UTF-8', '{}'.join(template.strings)))
+        log.trace(f'Rendering inline template "{name}"')
+        output.write(template.render())
+        return
+
+    if (name := renderer.template_name(options)) is None:
+        return
+
+    # Function
+    if (cb := renderer.templates.get(name.removesuffix('.py'))) is not None:
+        log.trace(f'Rendering template "{name}" of a function')
+
+    # File
+    elif (path := renderer.template_path(options)) is not None:
+        key = md5_sum(encode('UTF-8', f'py:{path}'))
+        if (cb := renderer.cache.get(key)) is not None:
+            log.trace(f'Rendering cached template "{name}"')
+        else:
+            log.trace(f'Rendering template "{name}"')
+            renderer.cache.set(key, cb := _load(path, key, renderer.encoding))
+
+    # No template
+    else:
+        log.debug(f'Template "{name}" not found')
+        return
+
+    output.write(Pyjo.String.Template.escape(_call(cb, c, c.stash())))
+
+
+# The function "render" of a file, which is compiled from its source, as importlib would write its bytecode next to it,
+# with the path of the file, from which a traceback reads the lines of the template
+def _load(path: str, key: str, encoding: str | None) -> Callable[..., Any]:
+    data = Pyjo.File.path(path).slurp()
+    assert isinstance(data, bytes)
+    if encoding is None:
+        source = data.decode('latin-1')
+    elif (source := decode(encoding, data)) is None:
+        raise Pyjo.Exception.new(f'Template "{path}" has invalid encoding')
+    try:
+        code = compile(source, path, 'exec', dont_inherit=True)
+    except SyntaxError as e:
+        raise Pyjo.Exception.new(f'{e.msg} at {path} line {e.lineno}.\n') from None
+
+    module = types.ModuleType(f'{__name__}.{key}')
+    module.__file__ = path
+
+    # No spec, as a spec without a loader makes linecache warn, which then reads the lines from the file
+    del module.__spec__
+    exec(code, module.__dict__)
+    if not callable(cb := module.__dict__.get('render')):
+        raise Pyjo.Exception.new(f'Template "{path}" has no function "render"')
+    return cb
+
+
+# The controller and the values of the stash that the function names, or all of them for **
+def _call(cb: Callable[..., Any], c: 'Pyjoyment.Controller.object', stash: dict[str, Any]) -> Any:
+    parameters = list(inspect.signature(cb).parameters.values())
+    rest = parameters[1:]
+    if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in rest):
+        values = {k: v for k, v in stash.items() if k.isidentifier() and k != parameters[0].name}
+    else:
+        values = {p.name: stash[p.name] for p in rest if p.name in stash}
+    return cb(c, **values)
+
+
+new = Pyjoyment_Plugin_PyRenderer.new
+object = Pyjoyment_Plugin_PyRenderer
+PyRenderer = Pyjoyment_Plugin_PyRenderer

Pyjoyment/Plugin/TOMLConfig.py

@@ -0,0 +1,141 @@
+"""
+Pyjoyment.Plugin.TOMLConfig - TOML configuration plugin
+=======================================================
+::
+
+    # myapp.toml (it's just TOML with embedded Python)
+    %# Just a value
+    foo = "bar"
+
+    %# Nested data structures are fine too
+    baz = ["♥"]
+
+    %# You have full access to the application
+    music_dir = '<%= app.home.child('music') %>'
+
+    [db]
+    host = "localhost"
+
+    # Pyjoyment
+    config = app.plugin('TOMLConfig')
+    print(config['foo'])
+
+    # Pyjoyment.Lite
+    config = plugin('TOMLConfig')
+    print(config['foo'])
+
+    # foo.html.ep
+    %= config()['foo']
+
+    # The configuration is available application-wide
+    config = app.config()
+    print(config['foo'])
+
+    # Everything can be customized with options
+    config = plugin('TOMLConfig', file='/etc/myapp.conf')
+
+:mod:`Pyjoyment.Plugin.TOMLConfig` is a TOML configuration plugin that
+preprocesses its input with :mod:`Pyjo.Template` and parses it with
+:mod:`tomllib` of the standard library.
+
+The application object can be accessed via ``app``. A default configuration
+filename in the application home directory will be generated from the value
+of :attr:`Pyjoyment.Pyjoyment_App.moniker` (``$moniker.toml``). You can extend
+the normal configuration file ``$moniker.toml`` with ``mode`` specific ones
+like ``$moniker.$mode.toml``, which will be detected automatically.
+
+A path goes into a literal string of TOML, in single quotes, which keeps
+the backslashes of a path of Windows, where a basic string in double quotes
+takes them for escapes.
+
+These configuration values are currently reserved:
+
+``config_override``
+    If this configuration value has been set in
+    :meth:`Pyjoyment.Pyjoyment_App.config` when this plugin is loaded, it will
+    not do anything besides loading deployment specific plugins.
+
+``plugins`` ::
+
+    plugins = [{ SetUserGroup = { user = "sri", group = "staff" } }]
+
+    One or more deployment specific plugins that should be loaded right after
+    this plugin has been loaded.
+
+The code of this plugin is a good example for learning to build new plugins,
+you're welcome to fork it.
+
+See :mod:`Pyjoyment.Plugins` for a list of plugins that are available by
+default.
+
+Options
+-------
+
+:mod:`Pyjoyment.Plugin.TOMLConfig` inherits all options from
+:mod:`Pyjoyment.Plugin.JSONConfig`.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Inspired by `Mojolicious::Plugin::NotYAMLConfig
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugin/NotYAMLConfig.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjoyment.Plugin.JSONConfig
+
+import tomllib
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+
+
+class Pyjoyment_Plugin_TOMLConfig(Pyjoyment.Plugin.JSONConfig.object):
+    """
+    :mod:`Pyjoyment.Plugin.TOMLConfig` inherits all methods from
+    :mod:`Pyjoyment.Plugin.JSONConfig` and implements the following new ones.
+    """
+
+    def parse(self, content: str, file: str, conf: dict[str, Any], app: 'Pyjoyment.object') -> dict[str, Any]:
+        """::
+
+            plugin.parse(content, file, conf, app)
+
+        Process content with
+        :meth:`~Pyjoyment.Plugin.JSONConfig.Pyjoyment_Plugin_JSONConfig.render`
+        and parse it with :mod:`tomllib`. ::
+
+            def parse(self, content, file, conf, app):
+                ...
+                content = self.render(content, file, conf, app)
+                ...
+                return config
+        """
+        try:
+            return tomllib.loads(self.render(content, file, conf, app))
+        except Exception as e:
+            raise Pyjo.Exception.new(f'Can\'t load configuration from file "{file}": {e}') from e
+
+    def register(self, app: 'Pyjoyment.object', conf: dict[str, Any] | None = None) -> dict[str, Any]:
+        """::
+
+            config = plugin.register(Pyjoyment.new())
+            config = plugin.register(Pyjoyment.new(), {'file': '/etc/foo.conf'})
+
+        Register plugin in :mod:`Pyjoyment` application and merge
+        configuration.
+        """
+        return super().register(app, {'ext': 'toml', **(conf or {})})
+
+
+new = Pyjoyment_Plugin_TOMLConfig.new
+object = Pyjoyment_Plugin_TOMLConfig
+TOMLConfig = Pyjoyment_Plugin_TOMLConfig