Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Plugin/YAMLConfig.py

@@ -0,0 +1,178 @@
+"""
+Pyjoyment.Plugin.YAMLConfig - YAML configuration plugin
+=======================================================
+::
+
+    # myapp.yml (it's just YAML with embedded Python)
+    ---
+    foo: bar
+    baz:
+      - ♥
+    music_dir: <%= app.home.child('music') %>
+
+    # Pyjoyment
+    config = app.plugin('YAMLConfig')
+    print(config['foo'])
+
+    # Pyjoyment.Lite
+    config = plugin('YAMLConfig')
+    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('YAMLConfig', file='/etc/myapp.conf')
+
+:mod:`Pyjoyment.Plugin.YAMLConfig` is a YAML configuration plugin that
+preprocesses its input with :mod:`Pyjo.Template`. By default it uses
+:mod:`Pyjo.YAML` for parsing, which is not the best YAML module available, but
+good enough for most config files. If you need something more correct you can
+use a different module like PyYAML with the ``module`` option.
+
+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.yml``). You can extend
+the normal configuration file ``$moniker.yml`` with ``mode`` specific ones
+like ``$moniker.$mode.yml``, which will be detected automatically.
+
+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.YAMLConfig` inherits all options from
+:mod:`Pyjoyment.Plugin.JSONConfig` and supports the following new ones.
+
+module ::
+
+    # Pyjoyment.Lite
+    plugin('YAMLConfig', module='yaml')
+    plugin('YAMLConfig', module=yaml.safe_load)
+
+Alternative YAML module to use for parsing, whose function ``safe_load``, or
+``load``, takes a string, or such a function.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Plugin::NotYAMLConfig
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugin/NotYAMLConfig.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+# Renamed from Mojolicious: YAMLConfig, where Mojo has NotYAMLConfig, as the file is YAML once its template is rendered,
+# as the files of JSONConfig and TOMLConfig are JSON and TOML
+
+import Pyjo.Exception
+import Pyjo.YAML
+import Pyjoyment.Plugin.JSONConfig
+
+import importlib
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, cast
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+
+
+class Pyjoyment_Plugin_YAMLConfig(Pyjoyment.Plugin.JSONConfig.object):
+    """
+    :mod:`Pyjoyment.Plugin.YAMLConfig` inherits all methods from
+    :mod:`Pyjoyment.Plugin.JSONConfig` and implements the following new ones.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._yaml: Callable[[str], Any] = Pyjo.YAML.load
+
+    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:`Pyjo.YAML`. ::
+
+            def parse(self, content, file, conf, app):
+                ...
+                content = self.render(content, file, conf, app)
+                ...
+                return config
+        """
+        try:
+            config = self._yaml(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
+        if not isinstance(config, dict):
+            raise Pyjo.Exception.new(f'Configuration file "{file}" did not return a YAML mapping')
+        return cast(dict[str, Any], config)
+
+    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.
+        """
+        conf = {'ext': 'yml', **(conf or {})}
+
+        self._yaml = Pyjo.YAML.load
+        if module := conf.get('module'):
+            if (load := _load(module)) is None:
+                raise Pyjo.Exception.new(f'YAML module {module} has no Load function')
+            self._yaml = load
+
+        return super().register(app, conf)
+
+
+# Not in Mojolicious: a function of a module, safe_load or load, as the YAML modules of Python name it, or the function
+# itself, where Mojo takes the function Load of a module
+def _load(module: Any) -> Callable[[str], Any] | None:
+    if callable(module):
+        return cast(Callable[[str], Any], module)
+    try:
+        mod = importlib.import_module(str(module))
+    except ImportError:
+        return None
+    load = getattr(mod, 'safe_load', None) or getattr(mod, 'load', None)
+    return cast(Callable[[str], Any], load) if callable(load) else None
+
+
+new = Pyjoyment_Plugin_YAMLConfig.new
+object = Pyjoyment_Plugin_YAMLConfig
+YAMLConfig = Pyjoyment_Plugin_YAMLConfig

Pyjoyment/Plugin/__init__.py

@@ -0,0 +1,80 @@
+"""
+Pyjoyment.Plugin - Plugin base class
+====================================
+::
+
+    # CamelCase plugin name
+    from Pyjoyment.Plugin import Plugin
+
+    class Pyjoyment_Plugin_MyPlugin(Plugin):
+        def register(self, app, conf):
+            # Magic here! :)
+            ...
+
+    object = Pyjoyment_Plugin_MyPlugin
+
+    # Or import the module, as in Google Python Style Guide
+
+    # CamelCase plugin name
+    import Pyjoyment.Plugin
+
+    class Pyjoyment_Plugin_MyPlugin(Pyjoyment.Plugin.object):
+        def register(self, app, conf):
+            # Magic here! :)
+            ...
+
+    object = Pyjoyment_Plugin_MyPlugin
+
+:mod:`Pyjoyment.Plugin` is an abstract base class for :mod:`Pyjoyment`
+plugins.
+
+See :mod:`Pyjoyment.Plugins` for a list of plugins that are available by
+default.
+
+A plugin of another distribution is a module in the namespace
+``Pyjoyment.Plugin``, which :func:`pkgutil.extend_path` keeps open, and the
+class that the module names ``object``.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Plugin <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugin.pm>`_
+of Mojolicious 9.49.
+"""
+
+import Pyjo.Base
+
+from pkgutil import extend_path
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+
+
+class Pyjoyment_Plugin(Pyjo.Base.object):
+    """
+    :mod:`Pyjoyment.Plugin` inherits all methods from :mod:`Pyjo.Base` and
+    implements the following new ones.
+    """
+
+    def register(self, app: 'Pyjoyment.object', conf: dict[str, Any]) -> Any:
+        """::
+
+            plugin.register(Pyjoyment.new(), {})
+            plugin.register(Pyjoyment.new(), {'foo': 'bar'})
+
+        This method will be called by :mod:`Pyjoyment.Plugins` at startup time.
+        Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "register" not implemented by subclass')
+
+
+# Not in Mojolicious: a namespace that other distributions can add plugins to
+__path__ = extend_path(__path__, __name__)
+
+new = Pyjoyment_Plugin.new
+object = Pyjoyment_Plugin
+Plugin = Pyjoyment_Plugin

Pyjoyment/Plugins.py

@@ -0,0 +1,215 @@
+"""
+Pyjoyment.Plugins - Plugin manager
+==================================
+::
+
+    from Pyjoyment.Plugins import Plugins
+
+    plugins = Plugins()
+    plugins.namespaces.append('MyApp.Plugin')
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjoyment.Plugins
+
+    plugins = Pyjoyment.Plugins.new()
+    plugins.namespaces.append('MyApp.Plugin')
+
+:mod:`Pyjoyment.Plugins` is the plugin manager of :mod:`Pyjoyment`.
+
+Plugins
+-------
+
+The following plugins are included in the :mod:`Pyjoyment` distribution as
+examples.
+
+:mod:`Pyjoyment.Plugin.AllowedHosts`
+    Validation of ``Host`` and ``Origin`` against DNS rebinding.
+
+:mod:`Pyjoyment.Plugin.Config`
+    Python-ish configuration files.
+
+:mod:`Pyjoyment.Plugin.DefaultHelpers`
+    General purpose helper collection, loaded automatically.
+
+:mod:`Pyjoyment.Plugin.EPLRenderer`
+    Renderer for plain embedded Python templates, loaded automatically.
+
+:mod:`Pyjoyment.Plugin.EPRenderer`
+    Renderer for more sophisticated embedded Python templates, loaded
+    automatically.
+
+:mod:`Pyjoyment.Plugin.Health`
+    Liveness and readiness of containers and orchestrators.
+
+:mod:`Pyjoyment.Plugin.HeaderCondition`
+    Route condition for all kinds of headers, loaded automatically.
+
+:mod:`Pyjoyment.Plugin.JSONConfig`
+    JSON configuration files.
+
+:mod:`Pyjoyment.Plugin.Mount`
+    Mount whole :mod:`Pyjoyment` applications.
+
+:mod:`Pyjoyment.Plugin.PyRenderer`
+    Renderer for template strings, loaded automatically.
+
+:mod:`Pyjoyment.Plugin.TagHelpers`
+    Template specific helper collection, loaded automatically.
+
+:mod:`Pyjoyment.Plugin.TOMLConfig`
+    TOML configuration files.
+
+:mod:`Pyjoyment.Plugin.YAMLConfig`
+    YAML configuration files.
+
+Events
+------
+
+:mod:`Pyjoyment.Plugins` inherits all events from :mod:`Pyjo.EventEmitter`.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Plugins <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Plugins.pm>`_
+of Mojolicious 9.49.
+"""
+
+import Pyjo.EventEmitter
+import Pyjo.Exception
+import Pyjo.Loader
+import Pyjoyment.Plugin
+
+from Pyjo.Util import camelize
+
+import re
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Self
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+
+
+class Pyjoyment_Plugins(Pyjo.EventEmitter.object):
+    """
+    :mod:`Pyjoyment.Plugins` inherits all methods from
+    :mod:`Pyjo.EventEmitter` and implements the following new ones.
+    """
+
+    def __init__(self) -> None:
+        """::
+
+            plugins = Pyjoyment.Plugins.new()
+
+        Construct a new :mod:`Pyjoyment.Plugins` object.
+        """
+        super().__init__()
+
+        self.namespaces = ['Pyjoyment.Plugin']
+        """::
+
+            namespaces = plugins.namespaces
+            plugins.namespaces = ['Pyjoyment.Plugin']
+
+        Namespaces to load plugins from, defaults to :mod:`Pyjoyment.Plugin`. ::
+
+            # Add another namespace to load plugins from
+            plugins.namespaces.append('MyApp.Plugin')
+        """
+
+    def emit_chain(self, name: str, *args: Any) -> Any:
+        """::
+
+            plugins.emit_chain('foo')
+            plugins.emit_chain('foo', 123)
+
+        Emit events as chained hooks.
+        """
+        wrapper: Callable[[], Any] | None = None
+        for cb in reversed(self.subscribers(name)):
+            wrapper = _wrap(cb, wrapper, args)
+
+        return wrapper() if wrapper is not None else None
+
+    def emit_hook(self, name: str, *args: Any) -> Self:
+        """::
+
+            plugins = plugins.emit_hook('foo')
+            plugins = plugins.emit_hook('foo', 123)
+
+        Emit events as hooks.
+        """
+        for cb in self.subscribers(name):
+            cb(*args)
+        return self
+
+    def emit_hook_reverse(self, name: str, *args: Any) -> Self:
+        """::
+
+            plugins = plugins.emit_hook_reverse('foo')
+            plugins = plugins.emit_hook_reverse('foo', 123)
+
+        Emit events as hooks in reverse order.
+        """
+        for cb in reversed(self.subscribers(name)):
+            cb(*args)
+        return self
+
+    def load_plugin(self, name: str) -> Pyjoyment.Plugin.object:
+        """::
+
+            plugin = plugins.load_plugin('some_thing')
+            plugin = plugins.load_plugin('SomeThing')
+            plugin = plugins.load_plugin('MyApp.Plugin.SomeThing')
+
+        Load a plugin from the configured namespaces or by full module name.
+        """
+        # Try all namespaces and full module name
+        suffix = camelize(name).replace('::', '.') if re.match(r'^[a-z]', name) else name
+        classes = [f'{namespace}.{suffix}' for namespace in self.namespaces]
+        for cls in [*classes, name]:
+            if (plugin := _load(cls)) is not None:
+                return plugin.new()
+
+        # Not found
+        raise Pyjo.Exception.new(f'Plugin "{name}" missing, maybe you need to install it?\n')
+
+    def register_plugin(
+        self, name: str, app: 'Pyjoyment.object', conf: dict[str, Any] | None = None, /, **values: Any
+    ) -> Any:
+        """::
+
+            plugins.register_plugin('some_thing', Pyjoyment.new())
+            plugins.register_plugin('some_thing', Pyjoyment.new(), foo=23)
+            plugins.register_plugin('some_thing', Pyjoyment.new(), {'foo': 23})
+            plugins.register_plugin('SomeThing', Pyjoyment.new())
+            plugins.register_plugin('SomeThing', Pyjoyment.new(), foo=23)
+            plugins.register_plugin('SomeThing', Pyjoyment.new(), {'foo': 23})
+            plugins.register_plugin('MyApp.Plugin.SomeThing', Pyjoyment.new())
+            plugins.register_plugin('MyApp.Plugin.SomeThing', Pyjoyment.new(), foo=23)
+            plugins.register_plugin('MyApp.Plugin.SomeThing', Pyjoyment.new(), {'foo': 23})
+
+        Load a plugin from the configured namespaces or by full module name and
+        run ``register``, optional arguments are passed through.
+        """
+        return self.load_plugin(name).register(app, {**(conf or {}), **values})
+
+
+def _load(name: str) -> type[Pyjoyment.Plugin.object] | None:
+    if isinstance(e := Pyjo.Loader.load_class(name), Exception):
+        raise e
+    cls = Pyjo.Loader._class(name)  # pyright: ignore[reportPrivateUsage]
+    return cls if cls is not None and issubclass(cls, Pyjoyment.Plugin.object) else None
+
+
+def _wrap(cb: Callable[..., Any], next: Callable[[], Any] | None, args: tuple[Any, ...]) -> Callable[[], Any]:
+    return lambda: cb(next, *args)
+
+
+new = Pyjoyment_Plugins.new
+object = Pyjoyment_Plugins
+Plugins = Pyjoyment_Plugins