Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Command/Author/generate/app.py

@@ -0,0 +1,299 @@
+"""
+Pyjoyment.Command.Author.generate.app - App generator command
+=============================================================
+::
+
+    Usage: APPLICATION generate app [OPTIONS] [NAME]
+
+      pyjo generate app
+      pyjo generate app TestApp
+      pyjo generate app My.TestApp
+
+    Options:
+      -h, --help   Show this summary of available options
+
+:mod:`Pyjoyment.Command.Author.generate.app` generates application directory
+structures for fully functional :mod:`Pyjoyment` applications: the package of
+the application in the directory of the project, which is its home, with
+``pyproject.toml`` for its dependencies, so that
+``uv run python -m MyApp daemon`` starts it and
+``uv run python -m Pyjo.Prove -l -r t`` tests it, as does ``uv run pytest``,
+with pytest of the dependency group ``dev``, and ``AGENTS.md``, which
+``CLAUDE.md`` imports, tells a coding agent how the application is made, run
+and tested, and where the skills of Pyjoyment are.
+
+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::Author::generate::app
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/Author/generate/app.pm>`_ of
+Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjoyment.Command
+import Pyjoyment.Command.Author.generate.pyproject
+
+from Pyjo.Util import class_to_file, class_to_path, decamelize, extract_usage
+from Pyjoyment.Command.Author.generate.pyproject import _requirement  # pyright: ignore[reportPrivateUsage]
+
+
+class Pyjoyment_Command_Author_generate_app(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.Author.generate.app` inherits all attributes and
+    methods from :mod:`Pyjoyment.Command` and implements the following new
+    ones.
+    """
+
+    description = 'Generate Pyjoyment application directory structure'
+    """::
+
+        description = app.description
+        app.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = app.usage
+        app.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, class_: str | None = None, *args: str) -> None:
+        """::
+
+            app.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        class_ = class_ or 'MyApp'
+
+        # Script
+        # Renamed from Mojolicious: the __main__ module of the package, for python -m, where Mojo has script/my_app
+        name = class_to_file(class_)
+        package = class_.replace('.', '/')
+        self.render_to_rel_file('main', f'{name}/{package}/__main__.py', {'class_': class_})
+
+        # Application class
+        # Unlike Mojolicious: a package in the directory of the project, as the current directory is on sys.path, where
+        # Mojo has the lib directory
+        self.render_to_rel_file(
+            'appclass', f'{name}/{package}/__init__.py', {'class_': _identifier(class_), 'alias': _alias(class_)}
+        )
+
+        # Config file (using the default moniker)
+        self.render_to_rel_file('config', f'{name}/{decamelize(class_.replace(".", "::"))}.yml')
+
+        # Controller
+        controller = f'{class_}.Controller.Example'
+        path = class_to_path(controller)
+        self.render_to_rel_file(
+            'controller', f'{name}/{path}', {'class_': _identifier(controller), 'alias': _alias(controller)}
+        )
+
+        # Test
+        # Renamed from Mojolicious: t/basic.py, where Mojo has t/basic.t
+        self.render_to_rel_file('test', f'{name}/t/basic.py', {'class_': class_})
+
+        # Not in Mojolicious: pyproject.toml, with the dependencies, as Mojo leaves Makefile.PL to generate makefile
+        pyproject = Pyjoyment.Command.Author.generate.pyproject.new(app=self.app, quiet=self.quiet)
+        pyproject.render_to_rel_file(
+            'pyproject', f'{name}/pyproject.toml', {'name': name, 'requirement': _requirement(), 'tests': True}
+        )
+
+        # Static file
+        self.render_to_rel_file('static', f'{name}/public/index.html')
+        self.create_rel_dir(f'{name}/public/assets')
+
+        # Templates
+        self.render_to_rel_file('layout', f'{name}/templates/layouts/default.html.ep')
+        self.render_to_rel_file('welcome', f'{name}/templates/example/welcome.html.ep')
+
+        # Not in Mojolicious: the guide of the coding agents, AGENTS.md, which CLAUDE.md imports for Claude Code
+        config = f'{decamelize(class_.replace(".", "::"))}.yml'
+        self.render_to_rel_file('agents', f'{name}/AGENTS.md', {'class_': class_, 'config': config, 'package': package})
+        self.render_to_rel_file('claude', f'{name}/CLAUDE.md')
+
+
+# Not in Mojolicious: the name of the class in its module, with underscores, as Pyjo_URL is of Pyjo.URL
+def _identifier(class_: str) -> str:
+    return class_.replace('.', '_')
+
+
+# Not in Mojolicious: the name of the class for the constructor of Python, the last part of its module, as Path is of
+# Pyjo.Path
+def _alias(class_: str) -> str:
+    return class_.rsplit('.', 1)[-1]
+
+
+new = Pyjoyment_Command_Author_generate_app.new
+object = Pyjoyment_Command_Author_generate_app
+
+__DATA__ = r"""
+@@ main
+import Pyjoyment.Commands
+
+
+# Start command line interface for application
+Pyjoyment.Commands.start_app('<%= class_ %>')
+
+@@ appclass
+import Pyjoyment
+
+
+class <%= class_ %>(Pyjoyment.object):
+    # This method will run once at server start
+    def startup(self):
+        # Load configuration from config file
+        config = self.plugin('YAMLConfig')
+
+        # Configure the application
+        self.secrets = config.get('secrets')
+
+%# Not in Mojolicious: the plugin Health, whose endpoints the probes of containers and orchestrators request
+        # Liveness and readiness for containers and orchestrators
+        self.plugin('Health')
+
+        # Router
+        r = self.routes
+
+        # Normal route to controller
+        r.get('/').to('Example#welcome')
+
+
+new = <%= class_ %>.new
+object = <%= class_ %>
+% if alias != class_:
+<%= alias %> = <%= class_ %>
+% end
+
+@@ controller
+import Pyjoyment.Controller
+
+
+class <%= class_ %>(Pyjoyment.Controller.object):
+    # This action will render a template
+    def welcome(self):
+        # Render template "example/welcome.html.ep" with message
+        self.render(msg='Welcome to the Pyjoyment real-time web framework!')
+
+
+object = <%= class_ %>
+<%= alias %> = <%= class_ %>
+
+@@ static
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Welcome to the Pyjoyment real-time web framework!</title>
+  </head>
+  <body>
+    <h2>Welcome to the Pyjoyment real-time web framework!</h2>
+    This is the static document "public/index.html",
+    <a href="/">click here</a> to get back to the start.
+  </body>
+</html>
+
+@@ test
+from Pyjo.Test import *
+
+import Pyjo.Test.Pyjo
+
+
+t = Pyjo.Test.Pyjo.new('<%= class_ %>')
+t.get_ok('/').status_is(200).content_like(r'(?i)Pyjoyment')
+
+done_testing()
+
+@@ layout
+<!DOCTYPE html>
+<html>
+  <head><title><%%= c.title() %></title></head>
+  <body><%%= content() %></body>
+</html>
+
+@@ welcome
+%% c.layout('default')
+%% c.title('Welcome')
+<h2><%%= msg %></h2>
+<p>
+  This page was generated from the template "templates/example/welcome.html.ep"
+  and the layout "templates/layouts/default.html.ep",
+  <%%= link_to('click here', url_for()) %> to reload the page or
+  <%%= link_to('here', '/index.html') %> to move forward to a static page.
+</p>
+
+@@ config
+% from Pyjo.Util import generate_secret
+---
+secrets:
+  - <%= generate_secret() %>
+
+@@ agents
+# <%= class_ %>
+
+An application of [Pyjoyment](https://pyjoyment.readthedocs.io/), the port of
+Mojolicious to Python, made with `pyjo generate app`. This file says how it is
+made and run, for whoever changes it, a coding agent too.
+
+## Layout
+
+- `<%= package %>/__init__.py`: the application, whose `startup` loads the
+  configuration and sets up the routes, as `r.get('/').to('Example#welcome')`.
+- `<%= package %>/Controller/`: the controllers, a class for each, whose
+  methods are the actions.
+- `templates/`: the `ep` templates of the actions, as
+  `templates/example/welcome.html.ep`, and the layouts.
+- `public/`: the static files.
+- `<%= config %>`: the configuration, with the secrets of the sessions.
+- `t/`: the test scripts of `Pyjo.Test` and `Pyjo.Test.Pyjo`.
+
+## Commands
+
+```sh
+% for command, comment in ((f'python -m {class_} daemon', 'http://127.0.0.1:3000'), (f'python -m {class_} routes', 'the routes and their names'), (f'python -m {class_} get /', 'a request without a server'), ('python -m Pyjo.Prove -l -r t', 'the tests'), ('pytest', 'the tests with pytest')):
+<%= f'uv run {command}'.ljust(max(41, len(class_) + 36)) %># <%= comment %>
+% end
+```
+
+## Conventions
+
+- An action renders its response with `self.render(...)`, as
+  `self.render(json={...})`; what it returns is not the response.
+- One event loop serves every connection: an action that waits is an
+  `async def` that awaits promises, as `await self.ua().get_p(url)`, and
+  nothing blocks it, as `time.sleep` or `requests`.
+- A helper is called, `self.ua()`, not `self.ua`.
+- A change comes with a test in `t/`, where `Pyjo.Test.Pyjo` requests the
+  application without a server.
+
+## Skills
+
+The plugin of Claude Code for Pyjoyment has skills of its idioms, of the
+migration from Flask, FastAPI and Django, of the tests, the templates, the
+APIs and the deployment:
+
+```sh
+claude plugin install pyjoyment --marketplace dex4er/Pyjoyment
+```
+
+Other agents read their files, the `SKILL.md` of each skill, in
+https://github.com/dex4er/Pyjoyment/tree/main/plugins/pyjoyment/skills.
+
+@@ claude
+@AGENTS.md
+"""

Pyjoyment/Command/Author/generate/dockerfile.py

@@ -0,0 +1,281 @@
+"""
+Pyjoyment.Command.Author.generate.dockerfile - Dockerfile generator command
+===========================================================================
+::
+
+    Usage: APPLICATION generate dockerfile [OPTIONS]
+
+      ./myapp.py generate dockerfile
+      python -m MyApp generate dockerfile
+      python -m MyApp generate dockerfile --user app
+      python -m MyApp generate dockerfile --port 8080
+      python -m MyApp generate dockerfile --graceful-timeout 8
+      python -m MyApp generate dockerfile --healthcheck /
+      python -m MyApp generate dockerfile --target lambda
+
+    Options:
+      -G, --graceful-timeout <seconds>   Graceful timeout of the workers of the
+                                         server, defaults to the one of the
+                                         server
+      -H, --healthcheck <path>           Path that the HEALTHCHECK of the image
+                                         requests, defaults to the liveness of
+                                         the plugin Health, if the application
+                                         has it
+      -h, --help                         Show this summary of available options
+      -p, --port <port>                  Port that the server listens on and the
+                                         image exposes, defaults to 3000
+      -t, --target <name>                Target of the image, "lambda" for an
+                                         event function of AWS Lambda, defaults
+                                         to a server
+      -u, --user <name>                  Create a system user and run the
+                                         application as it, defaults to the user
+                                         of the image
+
+:mod:`Pyjoyment.Command.Author.generate.dockerfile` generates ``Dockerfile``
+and ``.dockerignore`` for applications.
+
+The image is built in two stages. The first one installs the dependencies
+with uv into ``.venv``: the ones of ``pyproject.toml``, which
+:mod:`Pyjoyment.Command.Author.generate.pyproject` generates, locked with
+``uv.lock`` if there is one, or the ones of the inline metadata of PEP 723 of
+a :mod:`Pyjoyment.Lite` script that has it and no ``pyproject.toml``, locked
+with its ``.lock`` file if there is one. The second one has Python, ``.venv``
+and the application only, and its command runs the pre-forking server without
+uv, so that the signals of ``docker stop`` go straight to the server, which
+stops gracefully on ``TERM``. The images of Python and of uv are those of the
+versions that run the generator.
+
+Docker and Cloud Run give a container 10 seconds to stop, less than the 25
+seconds that :attr:`Pyjo.Server.Prefork.Pyjo_Server_Prefork.graceful_timeout`
+gives a worker, so ``--graceful-timeout 8`` sets ``PYJO_GRACEFUL_TIMEOUT`` in
+the image, which the command ``prefork`` takes for its option, and which the
+environment of the container can change again. With Docker,
+``docker stop -t 30``, or ``stop_grace_period: 30s`` of Docker Compose, lets
+the workers finish their requests too.
+
+The server listens on the port of the ``PORT`` environment variable, which
+the image sets to the port of ``--port``, ``3000`` by default, and exposes,
+and which ``docker build --build-arg PORT=8080`` changes too. A platform as
+Knative, Cloud Run, Render, Koyeb or Heroku sets ``PORT`` for the container,
+and the server listens on its port, as Knative ignores ``EXPOSE`` and sets
+``PORT`` to the ``containerPort`` of the service, ``8080`` by default.
+
+An application with :mod:`Pyjoyment.Plugin.Health` gets a ``HEALTHCHECK``
+that requests its liveness, ``/livez`` by default, or the path of
+``--healthcheck``, and an empty path leaves it out. Python makes the request
+with :mod:`http.client`, as the image has no ``curl``, and Docker shows the
+health of the container in ``docker ps``, and Docker Compose waits for it with
+``depends_on`` and ``condition: service_healthy``. Kubernetes and Cloud Run
+ignore it and have probes of their own.
+
+With ``--target lambda``, the image is the one of an event function of AWS
+Lambda: its command runs the script of the application, or its package, which
+is the runtime of the function itself, as :mod:`Pyjoyment.Command.lambda`
+detects, with the runtime client of :mod:`Pyjo.Server.Lambda`, and it has no
+port, no ``HEALTHCHECK`` and no graceful timeout of a server, whose options
+are not for it. A function whose Function URL streams its responses has
+``PYJO_LAMBDA_INVOKE_MODE=RESPONSE_STREAM`` in its environment, as
+:attr:`Pyjo.Server.Lambda.Pyjo_Server_Lambda.invoke_mode` says.
+
+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::Author::generate::dockerfile
+<https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojolicious/Command/Author/generate/dockerfile.pm>`_ of
+Mojolicious 9.49.
+
+Classes
+-------
+"""
+
+import Pyjo.Exception
+import Pyjo.File
+import Pyjoyment.Command
+
+from Pyjo.Util import extract_usage, getopt
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+from typing import Any
+
+
+class Pyjoyment_Command_Author_generate_dockerfile(Pyjoyment.Command.object):
+    """
+    :mod:`Pyjoyment.Command.Author.generate.dockerfile` inherits all
+    attributes and methods from :mod:`Pyjoyment.Command` and implements the
+    following new ones.
+    """
+
+    description = 'Generate "Dockerfile"'
+    """::
+
+        description = dockerfile.description
+        dockerfile.description = 'Foo'
+
+    Short description of this command, used for the command list.
+    """
+
+    usage = extract_usage()
+    """::
+
+        usage = dockerfile.usage
+        dockerfile.usage = 'Foo'
+
+    Usage information for this command, used for the help screen.
+    """
+
+    def run(self, *args: str) -> None:
+        """::
+
+            dockerfile.run(*sys.argv[1:])
+
+        Run this command.
+        """
+        # Not in Mojolicious: the options
+        arguments = list(args)
+        if not (
+            opts := getopt(
+                arguments,
+                {
+                    'G|graceful-timeout=i': None,
+                    'H|healthcheck=s': None,
+                    'p|port=i': None,
+                    't|target=s': None,
+                    'u|user=s': None,
+                },
+            )
+        ):
+            raise Pyjo.Exception.new(self.usage)
+
+        # Not in Mojolicious: the target of the image, an event function of AWS Lambda, which has no options of a server
+        target: str | None = opts.target
+        if target not in (None, 'lambda'):
+            raise Pyjo.Exception.new(f'Unknown target: {target}')
+        if target == 'lambda':
+            for option in ('graceful_timeout', 'healthcheck', 'port'):
+                if getattr(opts, option) is not None:
+                    raise Pyjo.Exception.new(f'Option --{option.replace("_", "-")} is not for the target lambda')
+
+        name = self.app.moniker
+
+        # Not in Mojolicious: the HEALTHCHECK of the liveness of Pyjoyment.Plugin.Health, with http.client, as the image
+        # has no curl
+        # Helpers of a plugin are found at run time, so the application is Any
+        app: Any = self.app
+        path: str | None = opts.healthcheck
+        if path is None and target is None and app.renderer.get_helper('health.path') is not None:
+            path = app.health.path('livez')
+        port = "int(os.environ['PORT'])"
+        code = f"c = http.client.HTTPConnection('127.0.0.1', {port}, timeout=2); c.request('GET', {path!r})"
+        healthcheck = (
+            json.dumps(
+                ['python', '-c', f'import http.client, os, sys; {code}; sys.exit(c.getresponse().status != 200)']
+            )
+            if path
+            else None
+        )
+
+        # Unlike Mojolicious: the script of Pyjoyment.Lite or the package of the application, which python runs, where
+        # Mojo runs the script, and the dependencies of the inline metadata of PEP 723 of the script, if it has them and
+        # there is no pyproject.toml
+        exe = os.environ.get('PYJO_EXE')
+        script = Pyjo.File.path(exe).to_rel(self.app.home).to_str() if exe else None
+        cmd = ['python', script] if script else ['python', '-m', type(self.app).__module__]
+        project = os.path.isfile(self.rel_file('pyproject.toml')) or not exe or not _metadata(Pyjo.File.path(exe))
+        lock = 'uv.lock' if project else f'{script}.lock'
+        values = {
+            'cmd': json.dumps(cmd if target == 'lambda' else [*cmd, 'prefork']),
+            'graceful_timeout': opts.graceful_timeout,
+            'healthcheck': healthcheck,
+            'lock': lock if os.path.isfile(self.rel_file(lock)) else None,
+            'name': name,
+            'port': opts.port or 3000,
+            'python': f'{sys.version_info.major}.{sys.version_info.minor}',
+            'script': None if project else script,
+            'target': target,
+            'user': opts.user,
+            'uv': _uv(),
+        }
+        self.render_to_rel_file('dockerfile', 'Dockerfile', values)
+
+        # Not in Mojolicious: .dockerignore, as the .venv of the host is not the one of the image
+        self.render_to_rel_file('dockerignore', '.dockerignore')
+
+
+# Not in Mojolicious: whether the script has the inline metadata of PEP 723
+def _metadata(path: Pyjo.File.object) -> bool:
+    try:
+        return re.search(r'(?m)^# /// script\r?$', str(path.slurp('UTF-8') or '')) is not None
+    except OSError:
+        return False
+
+
+# Not in Mojolicious: the version of uv, for its image
+def _uv() -> str:
+    if (uv := shutil.which('uv')) is None:
+        return 'latest'
+    try:
+        output = subprocess.run([uv, '--version'], capture_output=True, text=True, check=True).stdout
+    except (OSError, subprocess.CalledProcessError):
+        return 'latest'
+    return m[1] if (m := re.match(r'uv (\d+\.\d+\.\d+)', output)) else 'latest'
+
+
+new = Pyjoyment_Command_Author_generate_dockerfile.new
+object = Pyjoyment_Command_Author_generate_dockerfile
+
+__DATA__ = r"""
+@@ dockerfile
+FROM python:<%= python %>-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:<%= uv %> /uv /bin/
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_NO_DEV=1 UV_PYTHON_DOWNLOADS=0
+WORKDIR /opt/<%= name %>
+% if script:
+ENV VIRTUAL_ENV=/opt/<%= name %>/.venv
+COPY <%= ' '.join([script, *([lock] if lock else [])]) %> ./
+RUN uv venv && uv sync --script <%= script %> --active<%= ' --locked' if lock else '' %>
+% else:
+COPY <%= ' '.join(['pyproject.toml', *([lock] if lock else [])]) %> ./
+RUN uv sync --no-install-project<%= ' --locked' if lock else '' %>
+% end
+
+FROM python:<%= python %>-slim
+WORKDIR /opt/<%= name %>
+COPY --from=builder /opt/<%= name %>/.venv .venv
+COPY . .
+ENV PATH="/opt/<%= name %>/.venv/bin:$PATH"
+% if user:
+RUN useradd --system <%= user %>
+USER <%= user %>
+% end
+% if target != 'lambda':
+ARG PORT=<%= port %>
+ENV PORT=${PORT}
+% if graceful_timeout is not None:
+ENV PYJO_GRACEFUL_TIMEOUT=<%= graceful_timeout %>
+% end
+EXPOSE ${PORT}
+% if healthcheck:
+HEALTHCHECK --timeout=3s --start-period=30s --start-interval=1s CMD <%= healthcheck %>
+% end
+% end
+CMD <%= cmd %>
+
+@@ dockerignore
+.git
+.venv
+__pycache__
+"""