flasklet 0.1.0__py3-none-any.whl

flasklet/__init__.py

@@ -0,0 +1,10 @@
+from flasklet.blueprints import register_blueprints
+from flasklet.flashing import FlashMessage, parse_flashed_messages
+from flasklet.imports import import_routes
+
+__all__ = [
+	"FlashMessage",
+	"import_routes",
+	"parse_flashed_messages",
+	"register_blueprints",
+]

flasklet/blueprints.py

@@ -0,0 +1,74 @@
+import time
+from importlib import import_module
+from pathlib import Path
+from pkgutil import iter_modules
+from types import ModuleType
+from typing import Any
+
+from flask import Blueprint, Flask
+
+BlueprintTree = tuple[Blueprint, list[Any]]
+
+
+def _find_blueprints(module: ModuleType) -> list[BlueprintTree]:
+	"""
+	Recursively find blueprints in the given module and its sub-modules.
+	"""
+	if module.__file__ is None:  #  path of the __init__.py file
+		msg = f"Module {module.__name__} does not have an __init__.py file"
+		raise ValueError(msg)
+
+	found_blueprints: list[BlueprintTree] = []
+	for _, sub_package_name, is_package in iter_modules([Path(module.__file__).parent]):
+		if not is_package:
+			continue
+
+		sub_module = import_module(f"{module.__name__}.{sub_package_name}")
+		sub_blueprint = getattr(sub_module, "bp", None)
+
+		if not isinstance(sub_blueprint, Blueprint):
+			continue
+
+		found_blueprints += [(sub_blueprint, _find_blueprints(sub_module))]
+
+	return found_blueprints
+
+
+def _register_blueprints(blueprint: Blueprint, blueprint_trees: list[BlueprintTree]) -> None:
+	"""
+	Recursively register blueprints on the given root (app or blueprint), using a
+	depth-first traversal.
+	"""
+
+	# Avoid registering the same blueprint multiple times
+	if blueprint._got_registered_once:  # noqa: SLF001
+		return
+
+	for sub_bp, sub_trees in blueprint_trees:
+		_register_blueprints(sub_bp, sub_trees)  # Depth first
+
+		blueprint.register_blueprint(sub_bp)
+		print(f"📘 {sub_bp.name} registered on {blueprint.name}")
+
+
+def register_blueprints(app: Flask) -> None:
+	"""
+	Find and register all blueprints starting from the root module.
+
+	Recursively walks the sub-packages of `app`'s import module. Any sub-package
+	exposing a module-level `bp: Blueprint` attribute is registered on its parent
+	package's blueprint (or on `app` itself for top-level packages), depth-first.
+	Sub-packages without a `bp` attribute are skipped, along with their children.
+	"""
+	t0 = time.time()
+
+	print("📘 Registering Blueprints ...")
+
+	finded_blueprints = _find_blueprints(import_module(app.name))
+	for blueprint, sub_trees in finded_blueprints:
+		_register_blueprints(blueprint, sub_trees)  # Depth first
+
+		app.register_blueprint(blueprint)
+		print(f"📘 {blueprint.name} registered on {app.name}")
+
+	print(f"📘 done in {time.time() - t0:.3f}s")

flasklet/flashing.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+
+from flask import get_flashed_messages
+
+
+@dataclass(frozen=True, slots=True)
+class FlashMessage:
+	message: str
+	category: str
+	type: str
+
+
+def parse_flashed_messages() -> list[FlashMessage]:
+	"""
+	From Flask's "get_flashed_messages", parse the messages into a
+	list of FlashMessage objects.
+
+	The message type is derived from the flash category: a category containing
+	"toast", "modal", or "oob_swap" sets `type` accordingly (and that keyword is
+	removed from `category`); otherwise `type` defaults to "message".
+	"""
+
+	messages = [x for x in get_flashed_messages(with_categories=True) if isinstance(x, tuple)]
+
+	res = []
+	for category, message in messages:
+		message_type = "message"
+		if "toast" in category:
+			message_type = "toast"
+		elif "modal" in category:
+			message_type = "modal"
+		elif "oob_swap" in category:
+			message_type = "oob_swap"
+
+		category_no_type = " ".join(c for c in category.split(" ") if c != message_type)
+		res.append(FlashMessage(message, category_no_type, message_type))
+	return res

flasklet/imports.py

@@ -0,0 +1,29 @@
+import importlib
+from pathlib import Path
+
+
+def import_routes(file: str, module_name: str) -> None:
+	"""
+	Call with: `import_routes(__file__, __name__)`
+
+	Imports all python files in:
+	- All .py files in the `./routes` directory relative to the calling file
+	- All .py files in the current directory relative to the calling file
+	"""
+
+	# Import all routes in the ./routes directory
+
+	if (routes_dir := Path(file).parent / "routes").is_dir():
+		for path in routes_dir.iterdir():
+			if not path.is_file() or path.suffix != ".py" or path.stem == "__init__":
+				continue
+
+			importlib.import_module(f"{module_name}.routes.{path.stem}")
+
+	# Import all routes in the current directory
+
+	for path in Path(file).parent.iterdir():
+		if not path.is_file() or path.suffix != ".py" or path.stem == "__init__":
+			continue
+
+		importlib.import_module(f"{module_name}.{path.stem}")

flasklet/render/__init__.py

@@ -0,0 +1,22 @@
+from flasklet.render.block import render_block
+from flasklet.render.jinja import (
+	HighlightBlockExtension,
+	IncludeRawExtension,
+	JinjaTemplateMetadata,
+	get_template_metadata,
+	load_jinja_env,
+)
+from flasklet.render.macro import render_macro, render_macro_unsafe
+from flasklet.render.partial import render_partial
+
+__all__ = [
+	"HighlightBlockExtension",
+	"IncludeRawExtension",
+	"JinjaTemplateMetadata",
+	"get_template_metadata",
+	"load_jinja_env",
+	"render_block",
+	"render_macro",
+	"render_macro_unsafe",
+	"render_partial",
+]

flasklet/render/block.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+from markupsafe import Markup
+
+from flasklet.render.jinja import get_template_metadata
+
+
+def render_block(
+	template_name: str,
+	block_name: str,
+	**context: dict[str, Any],
+) -> str:
+	"""
+	Render a specific block from a given template.
+
+	This function extracts and renders a named block from a Jinja2 template,
+	similar to how template inheritance works, but without requiring extension.
+
+	Raises:
+		ValueError: If the specified block is not found in the template
+
+	Example:
+		Template file "components/card.html":
+		```
+		{% block header %}
+			<h2>{{ title }}</h2>
+		{% endblock %}
+
+		{% block content %}
+			<p>{{ description }}</p>
+		{% endblock %}
+		```
+
+		Usage in Python:
+		```python
+		rendered = render_block(
+			"components/card.html",
+			"header",
+			title="Welcome"
+		)
+		# Returns: <h2>Welcome</h2>
+		```
+
+		Usage in Jinja template:
+		```
+		{{ render_block("components/card.html", "content", description="Hello World") }}
+		```
+	"""
+
+	template = get_template_metadata(template_name).template
+	rendered_blocks = template.blocks.get(block_name)
+
+	if not rendered_blocks:
+		msg = f"Block {block_name} not found in template {template_name}"
+		raise ValueError(msg)
+
+	# Render the block
+	rendered_content = "".join(rendered_blocks(template.new_context(context)))
+
+	return Markup(rendered_content)  # noqa: S704

flasklet/render/jinja.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from flask import current_app
+from jinja2 import BaseLoader, Environment, Template, nodes
+from jinja2.ext import Extension
+from markupsafe import Markup
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+
+if TYPE_CHECKING:
+	from collections.abc import Callable
+
+	from jinja2.parser import Parser
+
+MSG_JINJA_ENV_MUST_HAVE_LOADER = "Jinja environment must have a loader"
+
+
+########################################################################################
+#### MARK: Environment and templates
+
+
+@dataclass(frozen=True, slots=True)
+class JinjaTemplateMetadata:
+	template: Template
+	name: str
+	source: str
+	ast: nodes.Template
+
+
+def load_jinja_env() -> tuple[Environment, BaseLoader]:
+	env = current_app.jinja_env
+	if env.loader is None:
+		raise ValueError(MSG_JINJA_ENV_MUST_HAVE_LOADER)
+	return env, env.loader
+
+
+def get_template_metadata(template_name_or_list: str) -> JinjaTemplateMetadata:
+	env, env_loader = load_jinja_env()
+
+	template = env.get_or_select_template(template_name_or_list)
+
+	if template.name is None:
+		msg = "Template name not found"
+		raise ValueError(msg)
+
+	template_source, _, _ = env_loader.get_source(env, template.name)
+	ast = env.parse(template_source)
+
+	return JinjaTemplateMetadata(
+		template=template,
+		name=template.name,
+		source=template_source,
+		ast=ast,
+	)
+
+
+########################################################################################
+#### MARK: Include raw file without Jinja processing extension
+
+
+class IncludeRawExtension(Extension):
+	tags = {"include_raw"}  # noqa: RUF012
+
+	@override
+	def parse(self, parser: Parser) -> nodes.Output:
+		lineno = parser.stream.expect("name:include_raw").lineno
+		template = parser.parse_expression()
+		result = self.call_method("_render", [template], lineno=lineno)
+		return nodes.Output([result], lineno=lineno)
+
+	def _render(self, filename: str) -> Markup:
+		if not self.environment.loader:
+			raise ValueError(MSG_JINJA_ENV_MUST_HAVE_LOADER)
+
+		template_source, _, _ = self.environment.loader.get_source(self.environment, filename)
+		return Markup(template_source)  # noqa: S704
+
+
+########################################################################################
+#### MARK: Highlight code blocks extension
+
+
+class HighlightBlockExtension(Extension):
+	tags = {"highlight"}  # noqa: RUF012
+
+	@override
+	def parse(self, parser: Parser) -> nodes.Node:
+		# Parse the block
+		lineno = next(parser.stream).lineno
+		args = [parser.parse_expression()]  # Language argument
+		body = parser.parse_statements(("name:endhighlight",), drop_needle=True)
+		call_block = nodes.CallBlock(self.call_method("_render", args), [], [], body)
+		return call_block.set_lineno(lineno)
+
+	def _render(self, language: str, caller: Callable[[], str]) -> Markup:
+		def unindent(code: str) -> str:
+			lines = code.splitlines()
+
+			while all(x.startswith(" ") for x in lines if x != "") or all(
+				x.startswith("\t") for x in lines if x != ""
+			):
+				lines = [x[1:] if x.startswith((" ", "\t")) else x for x in lines]
+
+			return "\n".join(lines)
+
+		# Get the block content
+
+		code = unindent(caller())
+
+		# Apply Pygments highlighting
+
+		lexer = get_lexer_by_name(language)
+		formatter = HtmlFormatter(style="monokai")
+		highlighted_code = highlight(code, lexer, formatter)
+
+		# Adjust CSS
+
+		css = formatter.get_style_defs(".highlight")
+		css += """
+			pre {
+				background-color: unset; /* Remove host stylesheet's background color */
+				color: unset; /* Remove host stylesheet's text color */
+				margin: 0;
+			}
+			.highlight {
+				border-radius: 10px;
+				padding: 14px;
+				margin: 14px 0;
+			}
+		"""
+
+		return Markup(f"<style>{css}</style>{highlighted_code}")  # noqa: S704

flasklet/render/macro.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+from jinja2 import Template
+from jinja2.nodes import Macro, Name, Output, TemplateData
+from markupsafe import Markup
+
+if TYPE_CHECKING:
+	from jinja2.nodes import Expr
+
+from flasklet.render.jinja import load_jinja_env
+
+
+def _extract_macro_source(template_source: str, macro_name: str) -> str:
+	"""
+	Extracts the source code of a macro from the template source code.
+	"""
+
+	# Pattern to match the macro definition, including parameters and content
+	macro_pattern = re.compile(
+		r"{%\s*macro\s+"
+		+ re.escape(macro_name)
+		+ r"\s*\((.*?)\)\s*%}(.*?)"
+		+ r"{%\s*endmacro\s*%}",
+		re.DOTALL,
+	)
+
+	if not (match := macro_pattern.search(template_source)):
+		msg = f"Macro '{macro_name}' not found in template."
+		raise ValueError(msg)
+
+	# Return macro source code, including the {% macro %} and {% endmacro %} lines
+	return match.group(0)
+
+
+def _flatten_macro_source_nodes(nodes: list[Expr]) -> str:
+	"""Flattens the nodes of a macro's body into a single string of source code."""
+	res = ""
+	for node in nodes:
+		if isinstance(node, TemplateData):
+			res += node.data
+		elif isinstance(node, Name):
+			res += r"{{ " + node.name + r" }}"
+		else:
+			msg = f"Unsupported node type: {type(node)}"
+			raise TypeError(msg)
+	return res
+
+
+def render_macro_unsafe(template_name: str, macro_name: str, **kwargs: dict[str, Any]) -> str:
+	"""
+	Render a specific macro from a given template.
+	It returns unescaped HTML, meaning that it is not safe to use with user input.
+	"""
+	env, env_loader = load_jinja_env()
+
+	template_source, _, _ = env_loader.get_source(env, template_name)
+	parsed_template = env.parse(template_source)
+	macros = parsed_template.find_all(Macro)
+
+	if not (macro := next((m for m in macros if m.name == macro_name), None)):
+		msg = f"Macro {macro_name} not found in template {template_name}"
+		raise ValueError(msg)
+
+	macro_source = _flatten_macro_source_nodes(cast("Output", macro.body[0]).nodes)
+
+	return Template(macro_source).render(**kwargs, g=env.globals)
+
+
+def render_macro(template_name: str, macro_name: str, **kwargs: dict[str, Any]) -> str:
+	"""
+	Render a specific macro from a given template.
+	"""
+	env, env_loader = load_jinja_env()
+
+	# Load the template source code
+	template_source, _, _ = env_loader.get_source(env, template_name)
+
+	# Extract the macro source code
+	macro_source = _extract_macro_source(template_source, macro_name)
+
+	# Create a new template that includes the macro and calls it
+	macro_call_template_source = macro_source + "\n{{ " + macro_name + "()" + " }}"
+
+	# Compile the new template
+	macro_template = env.from_string(macro_call_template_source)
+
+	# Render the template with the provided arguments
+	rendered = macro_template.render(**kwargs)
+
+	# Return the rendered macro content
+	return Markup(rendered)  # noqa: S704

flasklet/render/partial.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+from flask import render_template
+from markupsafe import Markup
+
+
+def render_partial(template_name: str, **context: dict[str, Any]) -> str:
+	"""
+	Render a template to be used as a partial within another template.
+
+	Example usage:
+	In a Jinja template, you can use:
+		{{ render_partial("my_template.html", var1=value1, var2=value2) }}
+	"""
+
+	return Markup(render_template(template_name, **context))  # noqa: S704

flasklet-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: flasklet
+Version: 0.1.0
+Summary: A few nice things for Flask
+Author: Marcel Kröker
+Requires-Dist: flask>=3.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markupsafe>=2.1
+Requires-Dist: pygments>=2.18
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# flasklet
+

flasklet-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+flasklet/__init__.py,sha256=Iuk8Qs4kyaihC8WPDSG3wePKdjwW70qeKTNFnzXpPLk,263
+flasklet/blueprints.py,sha256=CCOYii8QfoT5-1nRKA9DUSRwf191weaLXHNr397612Y,2329
+flasklet/flashing.py,sha256=DA9Fjaw0ILRiYFQYyIcrhaxrzIBOSFDUUoViaAPaDZk,1050
+flasklet/imports.py,sha256=9PGOFAIgDQXItq6RCB4ZG5pBUGIJ5789M5FfqXXAy1Q,868
+flasklet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flasklet/render/__init__.py,sha256=trVaqTVg5xFiuw4-V_vpA5ORARwOHcCCwwKJyr3ckxo,532
+flasklet/render/block.py,sha256=uLfMxH6TEKEzWgN5OecdwNiRQxYX3NvwwmPDR1NlI0o,1341
+flasklet/render/jinja.py,sha256=pjPhE2CUTnH6fu-Q3JB0ShQ_xlW8dEaZjxC_rWUdqy4,3840
+flasklet/render/macro.py,sha256=idWxt5WWE1TPbnCQrJ3F47LG0TgoUNyzRnodAurPqs0,2852
+flasklet/render/partial.py,sha256=swJ7nzmnBPaZjSgKV0jXjK3fkqMRSVJrBz6oEp7f2ho,436
+flasklet-0.1.0.dist-info/WHEEL,sha256=l3MmIxu8qaet7ng2J9fFoJnYGj8IREj7jXTbgsuzmy4,81
+flasklet-0.1.0.dist-info/METADATA,sha256=fmjeouAHNyb0uT6q5l_YBeC0aygmPC4ZS58CB3LOVbA,303
+flasklet-0.1.0.dist-info/RECORD,,

flasklet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.32
+Root-Is-Purelib: true
+Tag: py3-none-any