Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Command/__init__.py

@@ -0,0 +1,332 @@
+"""
+Pyjoyment.Command - Command base class
+======================================
+::
+
+    # Lowercase command name, in the module Pyjoyment.Command.mycommand
+    from Pyjoyment.Command import Command
+
+    from Pyjo.Util import extract_usage
+
+
+    class Pyjoyment_Command_mycommand(Command):
+        # Short description
+        description = 'My first Pyjoyment command'
+
+        # Usage message from the synopsis of the docstring of the module
+        usage = extract_usage()
+
+        def run(self, *args):
+            # Magic here! :)
+            ...
+
+
+    object = Pyjoyment_Command_mycommand
+
+    # Or import the module, as in Google Python Style Guide
+
+    # Lowercase command name, in the module Pyjoyment.Command.mycommand
+    import Pyjoyment.Command
+
+    from Pyjo.Util import extract_usage
+
+
+    class Pyjoyment_Command_mycommand(Pyjoyment.Command.object):
+        # Short description
+        description = 'My first Pyjoyment command'
+
+        # Usage message from the synopsis of the docstring of the module
+        usage = extract_usage()
+
+        def run(self, *args):
+            # Magic here! :)
+            ...
+
+
+    object = Pyjoyment_Command_mycommand
+
+    # The synopsis in the docstring of the module
+    \"\"\"
+    Pyjoyment.Command.mycommand - My command
+    ========================================
+    ::
+
+        Usage: APPLICATION mycommand [OPTIONS]
+
+        Options:
+          -s, --something   Does something
+    \"\"\"
+
+:mod:`Pyjoyment.Command` is an abstract base class for :mod:`Pyjoyment`
+commands.
+
+See :mod:`Pyjoyment.Commands` for a list of commands that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Command <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command.pm>`_
+of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Base
+import Pyjo.File
+import Pyjo.Loader
+import Pyjo.Server
+import Pyjo.Template
+import Pyjo.Util
+
+import os
+import sys
+import weakref
+
+from pkgutil import extend_path
+from typing import TYPE_CHECKING, Any, Self
+
+
+if TYPE_CHECKING:
+    import Pyjoyment
+
+
+class Pyjoyment_Command(Pyjo.Base.object):
+    """
+    :mod:`Pyjoyment.Command` inherits all methods from :mod:`Pyjo.Base` and
+    implements the following new ones.
+    """
+
+    description: str = 'No description'
+    """::
+
+        description = command.description
+        command.description = 'Foo'
+
+    Short description of command, used for the command list.
+    """
+
+    quiet: bool | None = None
+    """::
+
+        boolean = command.quiet
+        command.quiet = boolean
+
+    Limited command output.
+    """
+
+    usage: str = 'Usage: APPLICATION\n'
+    """::
+
+        usage = command.usage
+        command.usage = 'Foo'
+
+    Usage information for command, used for the help screen.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._app: weakref.ref[Pyjoyment.object] | None = None
+        self._app_ref: Pyjoyment.object | None = None
+        self.template: dict[str, Any] = {'vars': True}
+        """::
+
+            template = command.template
+            command.template = {'vars': True}
+
+        Attribute values passed to :mod:`Pyjo.Template` objects used to
+        render templates with :meth:`render_data`, defaults to activating
+        ``vars``.
+        """
+        for name, value in kwargs.items():
+            setattr(self, name, value)
+
+    @property
+    def app(self) -> 'Pyjoyment.object':
+        """::
+
+            app = command.app
+            command.app = Pyjoyment.new()
+
+        Application for command, defaults to a :mod:`Pyjoyment.HelloWorld`
+        object. Note that this attribute is weakened. ::
+
+            # Introspect
+            for path in command.app.renderer.paths:
+                print(f'Template path: {path}')
+        """
+        if self._app is not None:
+            if (app := self._app()) is None:
+                raise ReferenceError('weakly-referenced object no longer exists')
+            return app
+        if self._app_ref is None:
+            self._app_ref = Pyjo.Server.new().build_app('Pyjoyment.HelloWorld')  # pyright: ignore[reportAttributeAccessIssue]
+        return self._app_ref  # pyright: ignore[reportReturnType]
+
+    @app.setter
+    def app(self, value: 'Pyjoyment.object') -> None:
+        self._app = weakref.ref(value)
+
+    def chmod_file(self, path: str | os.PathLike[str], mode: int) -> Self:
+        """::
+
+            command = command.chmod_file('/home/sri/foo.txt', 0o644)
+
+        Change mode of a file.
+        """
+        Pyjo.File.path(path).chmod(mode)
+        return self._loud(f'  [chmod] {path} {mode:o}')
+
+    def chmod_rel_file(self, path: str, mode: int) -> Self:
+        """::
+
+            command = command.chmod_rel_file('foo/foo.txt', 0o644)
+
+        Portably change mode of a file relative to the current working
+        directory.
+        """
+        return self.chmod_file(self.rel_file(path), mode)
+
+    def create_dir(self, path: str | os.PathLike[str]) -> Self:
+        """::
+
+            command = command.create_dir('/home/sri/foo/bar')
+
+        Create a directory if it does not exist already.
+        """
+        if os.path.isdir(path):
+            return self._loud(f'  [exist] {path}')
+        Pyjo.File.path(path).make_path()
+        return self._loud(f'  [mkdir] {path}')
+
+    def create_rel_dir(self, path: str) -> Self:
+        """::
+
+            command = command.create_rel_dir('foo/bar/baz')
+
+        Portably create a directory relative to the current working directory
+        if it does not exist already.
+        """
+        return self.create_dir(self.rel_file(path))
+
+    def extract_usage(self) -> str:
+        """::
+
+            usage = command.extract_usage()
+
+        Extract usage message from the synopsis of the docstring of the file
+        this method was called from with :func:`Pyjo.Util.extract_usage`.
+        """
+        return Pyjo.Util.extract_usage(sys._getframe(1).f_code.co_filename)  # pyright: ignore[reportPrivateUsage]
+
+    def help(self, *args: str) -> None:
+        """::
+
+            command.help()
+
+        Print usage information for command.
+        """
+        print(self.usage, end='')
+
+    def rel_file(self, path: str) -> Pyjo.File.object:
+        """::
+
+            path = command.rel_file('foo/bar.txt')
+
+        Return a :mod:`Pyjo.File` object relative to the current working
+        directory.
+        """
+        return Pyjo.File.path().child(*path.split('/'))
+
+    def render_data(self, name: str, *args: Any) -> str:
+        """::
+
+            data = command.render_data('foo_bar')
+            data = command.render_data('foo_bar', *args)
+            data = command.render_data('foo_bar', {'foo': 'bar'})
+
+        Render a template from the ``DATA`` section of the module of the
+        command with :mod:`Pyjo.Loader` and :mod:`Pyjo.Template`. The template
+        can be configured with :attr:`template`.
+        """
+        template = Pyjo.Template.new(**self.template)
+        template.name = f'template {name} from DATA section'
+        output = template.render(str(Pyjo.Loader.data_section(type(self), name)), *args)
+        if isinstance(output, Exception):
+            raise output
+        return str(output)
+
+    def render_to_file(self, data: str, path: str | os.PathLike[str], *args: Any) -> Self:
+        """::
+
+            command = command.render_to_file('foo_bar', '/home/sri/foo.txt')
+            command = command.render_to_file('foo_bar', '/home/sri/foo.txt', *args)
+            command = command.render_to_file('foo_bar', '/home/sri/foo.txt', {'foo': 'bar'})
+
+        Render a template with :meth:`render_data` to a file if it does not
+        exist already, and create the directory if necessary.
+        """
+        return self.write_file(path, self.render_data(data, *args))
+
+    def render_to_rel_file(self, data: str, path: str, *args: Any) -> Self:
+        """::
+
+            command = command.render_to_rel_file('foo_bar', 'foo/bar.txt')
+            command = command.render_to_rel_file('foo_bar', 'foo/bar.txt', *args)
+            command = command.render_to_rel_file('foo_bar', 'foo/bar.txt', {'foo': 'bar'})
+
+        Portably render a template with :meth:`render_data` to a file relative
+        to the current working directory if it does not exist already, and
+        create the directory if necessary.
+        """
+        return self.render_to_file(data, self.rel_file(path), *args)
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            command.run()
+            command.run(*sys.argv[1:])
+
+        Run command. Meant to be overloaded in a subclass.
+        """
+        raise NotImplementedError('Method "run" not implemented by subclass')
+
+    def write_file(self, path: str | os.PathLike[str], data: str | bytes) -> Self:
+        """::
+
+            command = command.write_file('/home/sri/foo.txt', 'Hello World!')
+
+        Write text to a file if it does not exist already, and create the
+        directory if necessary.
+        """
+        if os.path.isfile(path):
+            return self._loud(f'  [exist] {path}')
+        self.create_dir(Pyjo.File.path(path).dirname())
+        Pyjo.File.path(path).spew(data)
+        return self._loud(f'  [write] {path}')
+
+    def write_rel_file(self, path: str, data: str | bytes) -> Self:
+        """::
+
+            command = command.write_rel_file('foo/bar.txt', 'Hello World!')
+
+        Portably write text to a file relative to the current working
+        directory if it does not exist already, and create the directory if
+        necessary.
+        """
+        return self.write_file(self.rel_file(path), data)
+
+    def _loud(self, msg: str) -> Self:
+        if not self.quiet:
+            print(msg)
+        return self
+
+
+# Not in Mojolicious: a namespace that other distributions can add commands to
+__path__ = extend_path(__path__, __name__)
+
+new = Pyjoyment_Command.new
+object = Pyjoyment_Command
+Command = Pyjoyment_Command

Pyjoyment/Command/asgi.py

@@ -0,0 +1,92 @@
+"""
+Pyjoyment.Command.asgi - ASGI command
+=====================================
+::
+
+    Usage: APPLICATION asgi [OPTIONS]
+
+      application = app.start('asgi')
+      PYJO_ASGI=1 uvicorn myapp:application
+
+    Options:
+      -h, --help                Show this summary of available options
+          --home <path>         Path to home directory of your application,
+                                defaults to the value of PYJO_HOME or
+                                auto-detection
+          --log-format <name>   Format of log messages, "text" or "json",
+                                defaults to the value of PYJO_LOG_FORMAT or
+                                "text"
+      -m, --mode <name>         Operating mode for your application, defaults to
+                                the value of PYJO_MODE or "development"
+
+:mod:`Pyjoyment.Command.asgi` starts applications with the
+:mod:`Pyjo.Server.ASGI` backend: it returns the ASGI application, which a
+script keeps for the ASGI server that imports it. The script of an application
+that ends with ``application = app.start()`` runs this command when the
+``PYJO_ASGI`` environment variable is set, and the command of its arguments
+otherwise.
+
+This is a core command, that means it is always enabled and its code a good
+example for learning to build new commands, you're welcome to fork it.
+
+See :mod:`Pyjoyment.Commands` for a list of commands that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Inspired by `Mojolicious::Command::psgi
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/psgi.pm>`_ of Mojolicious 9.49, for ASGI.
+
+Classes
+-------
+"""
+
+# Not in Mojolicious: the command of ASGI, as Pyjoyment.Command.wsgi of WSGI
+
+import Pyjo.Server.ASGI
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage
+
+from typing import Any
+
+
+class Pyjoyment_Command_asgi(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.asgi` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Start application with ASGI'
+    """::
+
+        description = asgi.description
+        asgi.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = asgi.usage
+        asgi.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            application = asgi.run()
+
+        Run this command.
+        """
+        return Pyjo.Server.ASGI.new(app=self.app).to_asgi_app()
+
+
+new = Pyjoyment_Command_asgi.new
+object = Pyjoyment_Command_asgi

Pyjoyment/Command/cgi.py

@@ -0,0 +1,90 @@
+"""
+Pyjoyment.Command.cgi - CGI command
+===================================
+::
+
+    Usage: APPLICATION cgi [OPTIONS]
+
+      ./myapp.py cgi
+
+    Options:
+      -h, --help                Show this summary of available options
+          --home <path>         Path to home directory of your application,
+                                defaults to the value of PYJO_HOME or
+                                auto-detection
+          --log-format <name>   Format of log messages, "text" or "json",
+                                defaults to the value of PYJO_LOG_FORMAT or
+                                "text"
+      -m, --mode <name>         Operating mode for your application, defaults to
+                                the value of PYJO_MODE or "development"
+          --nph                 Enable non-parsed-header mode
+
+:mod:`Pyjoyment.Command.cgi` starts applications with the
+:mod:`Pyjo.Server.CGI` backend.
+
+This is a core command, that means it is always enabled and its code a good
+example for learning to build new commands, you're welcome to fork it.
+
+See :mod:`Pyjoyment.Commands` for a list of commands that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Command::cgi
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/cgi.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjo.Server.CGI
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage, getopt
+
+from typing import Any
+
+
+class Pyjoyment_Command_cgi(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.cgi` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Start application with CGI'
+    """::
+
+        description = cgi.description
+        cgi.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = cgi.usage
+        cgi.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            cgi.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        arguments = list(args)
+        if not (opts := getopt(arguments, {'nph': None})):
+            raise Pyjo.Exception.new(self.usage)
+        return Pyjo.Server.CGI.new(app=self.app, nph=bool(opts.nph)).run()
+
+
+new = Pyjoyment_Command_cgi.new
+object = Pyjoyment_Command_cgi

Pyjoyment/Command/daemon.py

@@ -0,0 +1,160 @@
+"""
+Pyjoyment.Command.daemon - Daemon command
+=========================================
+::
+
+    Usage: APPLICATION daemon [OPTIONS]
+
+      ./myapp.py daemon
+      ./myapp.py daemon -m production -p -l http://*:8080
+      ./myapp.py daemon -l http://127.0.0.1:8080 -l https://[::]:8081
+      ./myapp.py daemon -l 'https://*:443?cert=./server.crt&key=./server.key'
+      ./myapp.py daemon -l http+unix://%2Ftmp%2Fmyapp.sock
+      ./myapp.py daemon -l fcgi://127.0.0.1:9000
+      ./myapp.py daemon -l http://127.0.0.1:8080 -p 127.0.0.0/8 -p fc00::/7
+
+    Options:
+      -b, --backlog <size>                 Listen backlog size, defaults to
+                                           SOMAXCONN
+      -c, --clients <number>               Maximum number of concurrent
+                                           connections, defaults to 1000
+      -h, --help                           Show this summary of available options
+          --home <path>                    Path to home directory of your
+                                           application, defaults to the value of
+                                           PYJO_HOME or auto-detection
+      -i, --inactivity-timeout <seconds>   Inactivity timeout, defaults to the
+                                           value of PYJO_INACTIVITY_TIMEOUT or 30
+      -k, --keep-alive-timeout <seconds>   Keep-alive timeout, defaults to the
+                                           value of PYJO_KEEP_ALIVE_TIMEOUT or 5
+      -l, --listen <location>              One or more locations you want to
+                                           listen on, defaults to the value of
+                                           PYJO_LISTEN, the port of PORT or
+                                           "http://*:3000"
+          --log-format <name>              Format of log messages, "text" or
+                                           "json", defaults to the value of
+                                           PYJO_LOG_FORMAT or "text"
+      -m, --mode <name>                    Operating mode for your application,
+                                           defaults to the value of PYJO_MODE or
+                                           "development"
+      -p, --proxy [<network>]              Activate reverse proxy support,
+                                           defaults to the value of
+                                           PYJO_REVERSE_PROXY, optionally takes
+                                           one or more trusted proxy addresses or
+                                           networks
+      -r, --requests <number>              Maximum number of requests per
+                                           keep-alive connection, defaults to 100
+      -S, --shutdown-delay <seconds>       Time to keep serving after INT or TERM
+                                           before shutting down gracefully,
+                                           defaults to 0
+
+:mod:`Pyjoyment.Command.daemon` starts applications with the
+:mod:`Pyjo.Server.Daemon` backend.
+
+An option that is not given has the value of the environment variable of
+``PYJO_`` and its name, as ``PYJO_CLIENTS`` for ``--clients``, with the
+values of ``--listen`` and ``--proxy`` separated by commas, see
+:mod:`Pyjo.GetOpt`, so that the environment of a container or a platform
+can tune the server. ::
+
+    PYJO_CLIENTS=100 ./myapp.py daemon
+
+This is a core command, that means it is always enabled and its code a good
+example for learning to build new commands, you're welcome to fork it.
+
+See :mod:`Pyjoyment.Commands` for a list of commands that are available by
+default.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Command::daemon
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/daemon.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjo.Server.Daemon
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage, getopt
+
+from typing import Any
+
+
+class Pyjoyment_Command_daemon(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.daemon` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Start application with HTTP and WebSocket server'
+    """::
+
+        description = daemon.description
+        daemon.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = daemon.usage
+        daemon.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def build_server(self, *args: str) -> Pyjo.Server.Daemon.object:
+        """::
+
+            server = daemon.build_server(*sys.argv[1:])
+
+        Build :mod:`Pyjo.Server.Daemon` instance from command line arguments.
+        """
+        arguments = list(args)
+        daemon = Pyjo.Server.Daemon.new(app=self.app)
+        listen: list[str] = []
+        proxy: list[str] = []
+        # Not in Mojolicious: the options from the environment variables of their names
+        if not getopt(
+            arguments,
+            {
+                'b|backlog=i': lambda name, value: setattr(daemon, 'backlog', value),
+                'c|clients=i': lambda name, value: setattr(daemon, 'max_clients', value),
+                'i|inactivity-timeout=i': lambda name, value: setattr(daemon, 'inactivity_timeout', value),
+                'k|keep-alive-timeout=i': lambda name, value: setattr(daemon, 'keep_alive_timeout', value),
+                'l|listen=s': listen,
+                'p|proxy:s': proxy,
+                'r|requests=i': lambda name, value: setattr(daemon, 'max_requests', value),
+                # Not in Mojolicious: the delay of the graceful shutdown, while the readiness fails
+                'S|shutdown-delay=i': lambda name, value: setattr(daemon, 'shutdown_delay', value),
+            },
+            env_prefix='PYJO_',
+        ):
+            raise Pyjo.Exception.new(self.usage)
+
+        if listen:
+            daemon.listen = listen
+        if proxy:
+            daemon.reverse_proxy = True
+        if trusted := [p for p in proxy if p]:
+            daemon.trusted_proxies = trusted
+        return daemon
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            daemon.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        return self.build_server(*args).run()
+
+
+new = Pyjoyment_Command_daemon.new
+object = Pyjoyment_Command_daemon