Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Command/prefork.py

@@ -0,0 +1,181 @@
+"""
+Pyjoyment.Command.prefork - Pre-fork command
+============================================
+::
+
+    Usage: APPLICATION prefork [OPTIONS]
+
+      ./myapp.py prefork
+      ./myapp.py prefork -m production -p -l http://*:8080
+      ./myapp.py prefork -l http://127.0.0.1:8080 -l https://[::]:8081
+      ./myapp.py prefork -l 'https://*:443?cert=./server.crt&key=./server.key'
+      ./myapp.py prefork -l http+unix://%2Ftmp%2Fmyapp.sock -w 12
+      ./myapp.py prefork -l fcgi://127.0.0.1:9000
+      ./myapp.py prefork -l http://127.0.0.1:8080 -p 127.0.0.0/8 -p fc00::/7
+
+    Options:
+      -a, --accepts <number>               Number of connections for workers to
+                                           accept, defaults to 10000
+      -b, --backlog <size>                 Listen backlog size, defaults to
+                                           SOMAXCONN
+      -c, --clients <number>               Maximum number of concurrent
+                                           connections, defaults to 1000
+      -G, --graceful-timeout <seconds>     Graceful timeout, defaults to 25.
+      -I, --heartbeat-interval <seconds>   Heartbeat interval, defaults to 5
+      -H, --heartbeat-timeout <seconds>    Heartbeat timeout, defaults to 50
+      -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, --pid-file <path>                Path to process id file, defaults to
+                                           "prefork.pid" in a temporary directory
+      -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
+      -s, --spare <number>                 Temporarily spawn up to this number of
+                                           additional workers, defaults to 2
+      -w, --workers <number>               Number of workers, defaults to 4
+
+:mod:`Pyjoyment.Command.prefork` starts applications with the
+:mod:`Pyjo.Server.Prefork` backend.
+
+An option that is not given has the value of the environment variable of
+``PYJO_`` and its name, as ``PYJO_WORKERS`` for ``--workers``, 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_GRACEFUL_TIMEOUT=8 PYJO_WORKERS=2 ./myapp.py prefork
+
+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::prefork
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/prefork.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjo.Server.Prefork
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage, getopt
+
+from typing import Any
+
+
+class Pyjoyment_Command_prefork(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.prefork` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Start application with pre-forking HTTP and WebSocket server'
+    """::
+
+        description = prefork.description
+        prefork.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = prefork.usage
+        prefork.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    # Not in Mojolicious: the class of the server, which Pyjoyment.Command.prethread replaces
+    _server: type[Pyjo.Server.Prefork.object] = Pyjo.Server.Prefork.object
+
+    def build_server(self, *args: str) -> Pyjo.Server.Prefork.object:
+        """::
+
+            server = prefork.build_server(*sys.argv[1:])
+
+        Build :mod:`Pyjo.Server.Prefork` instance from command line arguments.
+        """
+        arguments = list(args)
+        prefork = self._server.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,
+            {
+                'a|accepts=i': lambda name, value: setattr(prefork, 'accepts', value),
+                'b|backlog=i': lambda name, value: setattr(prefork, 'backlog', value),
+                'c|clients=i': lambda name, value: setattr(prefork, 'max_clients', value),
+                # Unlike Mojolicious: the graceful timeout defaults to 25 seconds, as Pyjo.Server.Prefork has it
+                'G|graceful-timeout=i': lambda name, value: setattr(prefork, 'graceful_timeout', value),
+                'I|heartbeat-interval=i': lambda name, value: setattr(prefork, 'heartbeat_interval', value),
+                'H|heartbeat-timeout=i': lambda name, value: setattr(prefork, 'heartbeat_timeout', value),
+                'i|inactivity-timeout=i': lambda name, value: setattr(prefork, 'inactivity_timeout', value),
+                'k|keep-alive-timeout=i': lambda name, value: setattr(prefork, 'keep_alive_timeout', value),
+                'l|listen=s': listen,
+                'P|pid-file=s': lambda name, value: setattr(prefork, 'pid_file', value),
+                'p|proxy:s': proxy,
+                'r|requests=i': lambda name, value: setattr(prefork, 'max_requests', value),
+                # Not in Mojolicious: the delay of the graceful shutdown, while the readiness fails
+                'S|shutdown-delay=i': lambda name, value: setattr(prefork, 'shutdown_delay', value),
+                's|spare=i': lambda name, value: setattr(prefork, 'spare', value),
+                'w|workers=i': lambda name, value: setattr(prefork, 'workers', value),
+            },
+            env_prefix='PYJO_',
+        ):
+            raise Pyjo.Exception.new(self.usage)
+
+        if listen:
+            prefork.listen = listen
+        if proxy:
+            prefork.reverse_proxy = True
+        if trusted := [p for p in proxy if p]:
+            prefork.trusted_proxies = trusted
+        return prefork
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            prefork.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        return self.build_server(*args).run()
+
+
+new = Pyjoyment_Command_prefork.new
+object = Pyjoyment_Command_prefork

Pyjoyment/Command/prethread.py

@@ -0,0 +1,126 @@
+"""
+Pyjoyment.Command.prethread - Pre-thread command
+================================================
+::
+
+    Usage: APPLICATION prethread [OPTIONS]
+
+      ./myapp.py prethread
+      ./myapp.py prethread -m production -p -l http://*:8080
+      ./myapp.py prethread -l http://127.0.0.1:8080 -l https://[::]:8081
+      ./myapp.py prethread -l 'https://*:443?cert=./server.crt&key=./server.key'
+      ./myapp.py prethread -l http+unix://%2Ftmp%2Fmyapp.sock -w 12
+      ./myapp.py prethread -l fcgi://127.0.0.1:9000
+      ./myapp.py prethread -l http://127.0.0.1:8080 -p 127.0.0.0/8 -p fc00::/7
+
+    Options:
+      -a, --accepts <number>               Number of connections for workers to
+                                           accept, defaults to 10000
+      -b, --backlog <size>                 Listen backlog size, defaults to
+                                           SOMAXCONN
+      -c, --clients <number>               Maximum number of concurrent
+                                           connections, defaults to 1000
+      -G, --graceful-timeout <seconds>     Graceful timeout, defaults to 25.
+      -I, --heartbeat-interval <seconds>   Heartbeat interval, defaults to 5
+      -H, --heartbeat-timeout <seconds>    Heartbeat timeout, defaults to 50
+      -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, --pid-file <path>                Path to process id file, defaults to
+                                           "prethread.pid" in a temporary
+                                           directory
+      -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
+      -s, --spare <number>                 Temporarily spawn up to this number of
+                                           additional workers, defaults to 2
+      -w, --workers <number>               Number of workers, defaults to 4
+
+:mod:`Pyjoyment.Command.prethread` starts applications with the
+:mod:`Pyjo.Server.Prethread` backend, with the options of
+:mod:`Pyjoyment.Command.prefork`.
+
+An option that is not given has the value of the environment variable of
+``PYJO_`` and its name, as ``PYJO_WORKERS`` for ``--workers``, 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_GRACEFUL_TIMEOUT=8 PYJO_WORKERS=2 ./myapp.py prethread
+
+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:`Pyjo.Server.Prethread`, :mod:`Pyjoyment`, https://mojolicious.org.
+
+It has no counterpart in Mojolicious; it is inspired by
+:mod:`Pyjoyment.Command.prefork`, the counterpart of `Mojolicious::Command::prefork
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/prefork.pm>`_.
+
+Classes
+-------
+"""
+
+import Pyjo.Server.Prethread
+import Pyjoyment.Command.prefork
+
+from Pyjo.Util import extract_usage
+
+
+class Pyjoyment_Command_prethread(Pyjoyment.Command.prefork.object):
+    """
+    :mod:`Pyjoyment.Command.prethread` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command.prefork` and implements the following new ones.
+    """
+
+    description = 'Start application with pre-threading HTTP and WebSocket server'
+    """::
+
+        description = prethread.description
+        prethread.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = prethread.usage
+        prethread.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    _server = Pyjo.Server.Prethread.object
+
+
+new = Pyjoyment_Command_prethread.new
+object = Pyjoyment_Command_prethread

Pyjoyment/Command/routes.py

@@ -0,0 +1,133 @@
+"""
+Pyjoyment.Command.routes - Routes command
+=========================================
+::
+
+    Usage: APPLICATION routes [OPTIONS]
+
+      ./myapp.py routes
+      ./myapp.py routes -v
+
+    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"
+      -v, --verbose             Print additional details about routes, flags
+                                indicate C=Conditions, P=Partial, U=Under and
+                                W=WebSocket
+
+:mod:`Pyjoyment.Command.routes` lists all your application routes.
+
+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::routes
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/routes.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjoyment.Command
+import Pyjoyment.Routes.Route
+
+from Pyjo.Util import extract_usage, getopt, tablify
+
+from typing import Any
+
+
+class Pyjoyment_Command_routes(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.routes` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Show available routes'
+    """::
+
+        description = routes.description
+        routes.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = routes.usage
+        routes.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> None:
+        """::
+
+            routes.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        arguments = list(args)
+        if not (opts := getopt(arguments, {'v|verbose': None})):
+            raise Pyjo.Exception.new(self.usage)
+
+        rows: list[list[str]] = []
+        for route in self.app.routes.children:
+            _walk(route, 0, rows, bool(opts.verbose))
+        print(tablify(rows), end='')
+
+
+def _walk(route: Pyjoyment.Routes.Route.object, depth: int, rows: list[list[str]], verbose: bool) -> None:
+    # Pattern
+    prefix = ''
+    if i := depth * 2:
+        prefix += ' ' * i + '+'
+    row = [prefix + (route.pattern.unparsed or '/')]
+    rows.append(row)
+
+    # Flags
+    flags: list[str] = []
+    flags.append('C' if route.requires() else '.')
+    flags.append('P' if (partial := route.partial) else '.')
+    flags.append('U' if route.inline else '.')
+    flags.append('W' if route.is_websocket else '.')
+    if verbose:
+        row.append(''.join(flags))
+
+    # Methods
+    methods: Any = route.methods()
+    row.append(','.join(methods).upper() if methods else '*')
+
+    # Name
+    name = route.name or ''
+    row.append(f'"{name}"' if route.has_custom_name else name)
+
+    # Regex (verbose)
+    pattern = route.pattern
+    pattern.match('/', route.is_endpoint and not partial)
+    if verbose:
+        row.append(pattern.regex.pattern if pattern.regex is not None else '')
+
+    depth += 1
+    for child in route.children:
+        _walk(child, depth, rows, verbose)
+    depth -= 1
+
+
+new = Pyjoyment_Command_routes.new
+object = Pyjoyment_Command_routes

Pyjoyment/Command/stdio.py

@@ -0,0 +1,92 @@
+"""
+Pyjoyment.Command.stdio - Standard input and output command
+===========================================================
+::
+
+    Usage: APPLICATION stdio [OPTIONS]
+
+      ./myapp.py stdio
+      ./myapp.py stdio -m production
+
+    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.stdio` starts applications with the
+:mod:`Pyjo.Server.Stdio` backend, which serves the protocol that the
+application or a plugin gives with a subscriber of its event ``stream`` on
+the standard input and output. It is not detected, as a pipe on the standard
+input is too common to mean it.
+
+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.
+
+It has no counterpart in Mojolicious.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjo.Server.Stdio
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage, getopt
+
+from typing import Any
+
+
+class Pyjoyment_Command_stdio(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.stdio` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Start application on standard input and output'
+    """::
+
+        description = stdio.description
+        stdio.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = stdio.usage
+        stdio.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> Any:
+        """::
+
+            stdio.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        arguments = list(args)
+        if not getopt(arguments, {}) or len(arguments):
+            raise Pyjo.Exception.new(self.usage)
+        return Pyjo.Server.Stdio.new(app=self.app).run()
+
+
+new = Pyjoyment_Command_stdio.new
+object = Pyjoyment_Command_stdio

Pyjoyment/Command/version.py

@@ -0,0 +1,141 @@
+"""
+Pyjoyment.Command.version - Version command
+===========================================
+::
+
+    Usage: APPLICATION version [OPTIONS]
+
+      pyjo version
+
+    Options:
+      -h, --help   Show this summary of available options
+
+:mod:`Pyjoyment.Command.version` shows version information for
+available core and optional modules.
+
+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::version
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/version.pm>`_ of Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.IOLoop.Client
+import Pyjo.IOLoop.TLS
+import Pyjo.Reactor
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage
+
+import importlib.metadata
+import platform
+import re
+import ssl
+import sys
+import tomllib
+
+from pathlib import Path
+from typing import Any
+
+
+class Pyjoyment_Command_version(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.version` inherits all attributes and methods from
+    :mod:`Pyjoyment.Command` and implements the following new ones.
+    """
+
+    description = 'Show versions of available modules'
+    """::
+
+        description = version.description
+        version.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = version.usage
+        version.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> None:
+        """::
+
+            version.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        # Unlike Mojolicious: the counterparts of the optional modules of Perl that Mojo shows, which Python has in its
+        # standard library, and which Pyjoyment can turn off
+        reactor = Pyjo.Reactor.detect()
+        nnr = 'getaddrinfo in a thread' if Pyjo.IOLoop.Client.object.can_nnr() else 'n/a'
+        socks = 'Pyjo.IOLoop.Client' if Pyjo.IOLoop.Client.object.can_socks() else 'n/a'
+        tls = ssl.OPENSSL_VERSION if Pyjo.IOLoop.TLS.object.can_tls() else 'n/a'
+        current = _version()
+
+        print(f"""CORE
+  Python     ({platform.python_version()}, {sys.platform})
+  Pyjoyment  ({current})
+
+OPTIONAL
+  Reactor    ({reactor})
+  NNR        ({nnr})
+  SOCKS5     ({socks})
+  TLS        ({tls})
+""")
+
+        # Check latest version on PyPI
+        # Unlike Mojolicious: the JSON API of PyPI, where Mojo asks MetaCPAN
+        try:
+            ua = self.app.ua
+            ua.max_redirects = 10
+            ua.proxy.detect()
+            latest = str(ua.get('https://pypi.org/pypi/Pyjoyment/json').result.json()['info']['version'])
+        except Exception:
+            return
+
+        msg = 'This version is up to date, have fun!'
+        if _numbers(latest) < _numbers(current):
+            msg = 'Thanks for testing a development release, you are awesome!'
+        if _numbers(latest) > _numbers(current):
+            msg = f'You might want to update your Pyjoyment to {latest}!'
+        print(msg)
+
+
+# The numbers of a version, which compare as the versions do
+def _numbers(version: str) -> tuple[int, ...]:
+    return tuple(int(number) for number in re.findall(r'\d+', version))
+
+
+# Not in Mojolicious: the version of the distribution, from its metadata, or from the pyproject.toml of a checkout of
+# its source, as Python has no $VERSION of a module
+def _version() -> str:
+    try:
+        return importlib.metadata.version('Pyjoyment')
+    except importlib.metadata.PackageNotFoundError:
+        pass
+    pyproject = Path(__file__).resolve().parents[2] / 'pyproject.toml'
+    try:
+        project: Any = tomllib.loads(pyproject.read_text(encoding='utf-8')).get('project', {})
+    except (OSError, tomllib.TOMLDecodeError):
+        return 'n/a'
+    return str(project['version']) if project.get('name') == 'Pyjoyment' and 'version' in project else 'n/a'
+
+
+new = Pyjoyment_Command_version.new
+object = Pyjoyment_Command_version