fastlifeweb 0.17.0__tar.gz → 0.18.0__tar.gz

fastlifeweb-0.18.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: fastlifeweb
+Version: 0.18.0
+Summary: High-level web framework
+Home-page: https://github.com/mardiros/fastlife
+License: BSD-derived
+Author: Guillaume Gauvrit
+Author-email: guillaume@gauvr.it
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: doc
+Provides-Extra: testing
+Requires-Dist: babel (>=2.16.0,<3.0.0)
+Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0) ; extra == "testing"
+Requires-Dist: fastapi[standard] (>=0.115.0,<0.116.0)
+Requires-Dist: itsdangerous (>=2.1.2,<3.0.0)
+Requires-Dist: jinjax (>=0.44,<0.45)
+Requires-Dist: markupsafe (>=2.1.3,<3.0.0)
+Requires-Dist: multidict (>=6.0.5,<7.0.0)
+Requires-Dist: pydantic (>=2.5.3,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
+Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
+Requires-Dist: sphinx (>=7.0.1,<8.0.0) ; extra == "doc"
+Requires-Dist: venusian (>=3.0.0,<4.0.0)
+Project-URL: Repository, https://github.com/mardiros/fastlife
+Description-Content-Type: text/markdown
+
+# Fastlife
+
+[![Documentation](https://github.com/mardiros/fastlife/actions/workflows/gh-pages.yml/badge.svg)](https://mardiros.github.io/fastlife/)
+[![Continuous Integration](https://github.com/mardiros/fastlife/actions/workflows/main.yml/badge.svg)](https://github.com/mardiros/fastlife/actions/workflows/main.yml)
+[![Coverage Report](https://codecov.io/gh/mardiros/fastlife/graph/badge.svg?token=DTpi73d7mf)](https://codecov.io/gh/mardiros/fastlife)
+[![Maintainability](https://api.codeclimate.com/v1/badges/94d107797b15b5e8843e/maintainability)](https://codeclimate.com/github/mardiros/fastlife/maintainability)
+
+> ⚠️ **Under Heavy Development**
+> Please note that this project is still in active development. Features and APIs may change frequently.
+> Even the name is not definitive.
+
+An opinionated Python web framework (based on {term}`FastAPI`).
+
+## Purpose
+
+Fastlife helps at building Web Application with session, security, html test client,
+and html form generated from pydantic schema using customizable widget.
+
+Templates are made using {term}`JinjaX` and an extensible [set of
+component](https://mardiros.github.io/fastlife/components/index.html) is available
+in order to build pages.
+
+Those components are currently stylized by {term}`Tailwind CSS`,
+using [pytailwindcss](https://github.com/timonweb/pytailwindcss).
+
+Moreover, you can also write API, in an opinionated way to enforce documentation
+consistency.
+
+
+## First class configuration.
+
+Fastlife is adding a "Configurator", like {term}`Pyramid` to get a better scallable codebase.
+
+The configurator in fastlife organizes configuration settings hierarchically,
+enabling easy management and overriding at different levels.
+This promotes modularity and clarity in application configuration, making it simpler
+to maintain and scale your project.
+
+
+## Tests
+
+Fastlife come with [a test client](https://mardiros.github.io/fastlife/develop/fastlife/fastlife.testing.testclient.html) that can interact with html inside unit tests.
+
+
+## Try it
+
+The package is available on pypi with the name fastlifeweb.
+
+```bash
+pip install fastlifeweb
+```
+

fastlifeweb-0.18.0/pyproject.toml

@@ -0,0 +1,118 @@
+[tool.poetry]
+authors = ["Guillaume Gauvrit <guillaume@gauvr.it>"]
+description = "High-level web framework"
+name = "fastlifeweb"
+license = "BSD-derived"
+packages = [{ include = "fastlife", from = "src" }]
+homepage = "https://github.com/mardiros/fastlife"
+repository = "https://github.com/mardiros/fastlife"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+version = "0.18.0"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+babel = "^2.16.0"
+beautifulsoup4 = { version = "^4.12.2", optional = true }
+fastapi = { version = "^0.115.0", extras = ["standard"] }
+itsdangerous = "^2.1.2"
+jinjax = "^0.44"
+markupsafe = "^2.1.3"
+multidict = "^6.0.5"
+pydantic = "^2.5.3"
+pydantic-settings = "^2.0.3"
+python-multipart = "^0.0.9"
+sphinx = { version = "^7.0.1", optional = true }
+venusian = "^3.0.0"
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.extras]
+testing = ["beautifulsoup4"]
+doc = ["sphinx"]
+
+[tool.poetry.group.dev.dependencies]
+beautifulsoup4 = "^4.12.2"
+behave = "^1.2.6"
+heroicons = "^2.7.0"
+httpx = "^0.25.0"
+mypy = "^1.4.0"
+pytest = "^8.2.0"
+pytest-asyncio = "^0.21.0"
+pytest-cov = "^4.1.0"
+sphinx = "^7.0.1"
+types-beautifulsoup4 = "^4.12.0.6"
+isort = "^5.12.0"
+email-validator = "^2.0.0.post2"
+hypercorn = "^0.14.4"
+pytest-playwright = "^0.4.3"
+pytailwindcss = "^0.2.0"
+
+[tool.poetry.group.doc]
+optional = true
+
+[tool.poetry.group.doc.dependencies]
+furo = "^2024.5.6"
+myst-parser = "^4.0.0"
+sphinx = "^7.0.1"
+sphinx-autodoc-typehints = "^1.12.0"
+sphinx-autodoc2 = "^0.5.0"
+tomlkit = "^0.12.5"
+linkify-it-py = "^2.0.3"
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+
+[[tool.mypy.overrides]]
+module = "fastlife.*"
+disallow_any_generics = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["behave", "venusian", "docutils"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "B",   # bug bear security warning
+    "I",   # isort import order
+    "F",   # pyflakes
+    "UP",  # alter when better syntax is available
+    "RUF", #  the ruff devleoper's own rules
+]
+
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",                                                                           # setuptools
+    'ignore:.*pkg_resources is deprecated as an API.*:DeprecationWarning',
+    'ignore:.*Deprecated call to `pkg_resources.declare_namespace:DeprecationWarning', # venusian
+    'ignore:.*find_module\(\) is deprecated.*:DeprecationWarning',
+    'ignore:.*FileFinder.find_loader\(\) is deprecated.*:DeprecationWarning',
+    'ignore:.*Pydantic serializer warnings.*:UserWarning',
+]
+testpaths = ["tests"]
+
+[tool.coverage.report]
+exclude_lines = ["# coverage: ignore", "\\s+\\.\\.\\.$"]
+
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core"]

fastlifeweb-0.18.0/src/fastlife/adapters/jinjax/__init__.py

@@ -0,0 +1,7 @@
+"""Main template renderer based on JinjaX."""
+
+from .renderer import JinjaxEngine
+
+__all__ = [
+    "JinjaxEngine",
+]

fastlifeweb-0.18.0/src/fastlife/adapters/jinjax/jinjax_ext/__init__.py

@@ -0,0 +1 @@
+"""JinjaX extention to support introspection."""

fastlifeweb-0.18.0/src/fastlife/adapters/jinjax/jinjax_ext/docstring.py

@@ -0,0 +1,77 @@
+"""
+Template rending based on JinjaX.
+"""
+
+import ast
+import textwrap
+from typing import Any
+
+
+def generate_docstring(
+    func_def: ast.FunctionDef, component_name: str, add_content: bool
+) -> str:
+    """Generate a docstring for a JinjaX component."""
+    # Extract function name and docstring
+    docstring = (ast.get_docstring(func_def, clean=True) or "").strip()
+    if docstring:
+        docstring = textwrap.dedent(docstring)
+        docstring_lines = [line for line in docstring.split("\n")]
+        # Add a newline for separation after the function docstring
+        docstring_lines.append("")
+    else:
+        docstring_lines = []
+
+    component_params: list[str] = []
+
+    # Function for processing an argument and adding its docstring lines
+    def process_arg(arg: ast.arg, default_value: Any = None) -> None:
+        arg_name = arg.arg
+        param_desc = ""
+        # Extract the type annotation (if any)
+        if (
+            isinstance(arg.annotation, ast.Subscript)
+            and isinstance(arg.annotation.value, ast.Name)
+            and arg.annotation.value.id == "Annotated"
+        ):
+            # For Annotated types, we expect the first argument to be the type and
+            # the second to be the description
+            type_annotation = arg.annotation.slice.elts[0]  # type: ignore
+            param_type = ast.unparse(type_annotation)  # type: ignore
+
+            if len(arg.annotation.slice.elts) > 1 and isinstance(  # type: ignore
+                arg.annotation.slice.elts[1],  # type: ignore
+                ast.Constant,  # type: ignore
+            ):
+                param_desc = arg.annotation.slice.elts[1].value  # type: ignore
+        else:
+            # Otherwise, just use the type if available
+            param_type = ast.unparse(arg.annotation) if arg.annotation else "Any"
+
+        # Build the parameter docstring line
+        docstring_lines.append(f":param {arg_name.rstrip('_')}: {param_desc}".strip())
+
+        # Build the string representation of the parameter
+        param_str = f"{arg_name}: {param_type}"
+        if default_value is not None:
+            param_str += f" = {ast.unparse(default_value)}"  # type: ignore
+
+        component_params.append(param_str)
+
+    # Process keyword-only arguments
+    kwonlyargs = func_def.args.kwonlyargs
+    kw_defaults = func_def.args.kw_defaults
+
+    for arg, default in zip(kwonlyargs, kw_defaults, strict=False):
+        process_arg(arg, default)
+
+    if add_content:
+        component_params.append("content: Any")
+        docstring_lines.append(":param content: child node.")
+
+    return (
+        f"{component_name}({', '.join(component_params)})"
+        + "\n"
+        + "\n    "
+        + ("\n    ".join(docstring_lines).strip()).replace("\n    \n", "\n\n")
+        + "\n"
+    )

fastlifeweb-0.18.0/src/fastlife/adapters/jinjax/jinjax_ext/inspectable_catalog.py

@@ -0,0 +1,85 @@
+"""
+Template rending based on JinjaX.
+"""
+
+import logging
+import re
+from collections.abc import Iterator, Sequence
+
+from jinja2.exceptions import TemplateSyntaxError
+from jinjax import DuplicateDefDeclaration, InvalidArgument
+from jinjax.catalog import Catalog
+
+from .inspectable_component import InspectableComponent
+
+log = logging.getLogger(__name__)
+
+
+def to_include(
+    name: str,
+    ignores: Sequence[re.Pattern[str]] | None = None,
+    includes: Sequence[re.Pattern[str]] | None = None,
+) -> bool:
+    if includes and not any(include.match(name) for include in includes):
+        return False
+
+    if ignores and any(ignore.match(name) for ignore in ignores):
+        return False
+
+    return True
+
+
+class InspectableCatalog(Catalog):
+    """
+    JinjaX Catalog with introspection support.
+
+    Override the catalog in order to iterate over components to build the doc.
+    """
+
+    def iter_components(
+        self,
+        ignores: Sequence[re.Pattern[str]] | None = None,
+        includes: Sequence[re.Pattern[str]] | None = None,
+    ) -> Iterator[InspectableComponent]:
+        """
+        Walk into every templates from the settings, iterate over components.
+
+        :params ignores: filter components using an block list.
+        :params includes: filter components using an allowed list.
+        """
+        for prefix, loader in self.prefixes.items():
+            for t in loader.list_templates():
+                name, file_ext = t.split(".", maxsplit=1)
+                name = name.replace("/", ".")
+                path, tmpl_name = self._get_component_path(
+                    prefix, name, file_ext=file_ext
+                )
+                is_included = to_include(name, ignores, includes)
+                if is_included:
+                    try:
+                        component = InspectableComponent(
+                            name=name, prefix=prefix, path=path, source=path.read_text()
+                        )
+                    except InvalidArgument as exc:
+                        log.error(f"Definition Syntax Error in <{name}/>: {exc}")
+                        log.error(path.read_text())
+                        continue
+                    except DuplicateDefDeclaration as exc:
+                        log.error(f"Duplicate Definition in <{name}/>: {exc}")
+                        log.error(path.read_text())
+                        continue
+
+                    self.jinja_env.loader = loader
+
+                    try:
+                        component.tmpl = self.jinja_env.get_template(
+                            tmpl_name, globals=self._tmpl_globals
+                        )
+                    except TemplateSyntaxError as exc:
+                        log.error(
+                            f"Template Syntax Error in <{name}/>: {exc} on "
+                            "{exc.lineno} :"
+                        )
+                        log.error(path.read_text())
+                        continue
+                    yield component

fastlifeweb-0.18.0/src/fastlife/adapters/jinjax/jinjax_ext/inspectable_component.py

@@ -0,0 +1,112 @@
+"""
+Template rending based on JinjaX.
+"""
+
+import ast
+import logging
+import re
+from pathlib import Path
+from typing import cast
+
+from jinja2 import Template
+from jinjax.component import RX_ARGS_START, RX_META_HEADER, Component
+
+from .docstring import generate_docstring
+
+log = logging.getLogger(__name__)
+
+RX_DOC_START = re.compile(r"{#-?\s*doc\s+")
+RX_CONTENT = re.compile(r"\{\{-?\s*content\s*-?\}\}", re.DOTALL)
+RX_COMMENT_REPLACE = re.compile(r"{#[^#]+#}")
+
+
+SIGNATURE = """
+def component({args}):
+    '''
+    {docstring}
+    '''
+    ...
+"""
+
+
+def has_content(source: str) -> bool:
+    nocomment = RX_COMMENT_REPLACE.sub("", source)
+    return len(RX_CONTENT.findall(nocomment)) > 0
+
+
+class InspectableComponent(Component):
+    """
+    JinjaX Components override that support intropspection.
+
+    The Component class of JinjaX does not support documentation by default.
+    """
+
+    __slots__ = (
+        "name",
+        "prefix",
+        "url_prefix",
+        "required",
+        "optional",
+        "css",
+        "js",
+        "path",
+        "mtime",
+        "tmpl",
+        "source",
+    )
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        prefix: str = "",
+        url_prefix: str = "",
+        source: str = "",
+        mtime: float = 0,
+        tmpl: "Template | None" = None,
+        path: "Path | None" = None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            prefix=prefix,
+            url_prefix=url_prefix,
+            source=source,
+            mtime=mtime,
+            tmpl=tmpl,
+            path=path,
+        )
+        self.source = source
+
+    def as_def(self) -> ast.FunctionDef:
+        """Return the component definition as a python function definition."""
+        signature = "def component(): pass"
+        match = RX_META_HEADER.match(self.source)
+        if match:
+            headers = match.group(0)
+            header = headers.split("#}")[:-1]
+            docstring = ""
+
+            expr = None
+            while header:
+                item = header.pop(0).strip(" -\n")
+
+                expr = self.read_metadata_item(item, RX_ARGS_START)  # type: ignore
+                doc = self.read_metadata_item(item, RX_DOC_START)  # type: ignore
+                if doc:
+                    docstring += f"    {doc.strip()}\n"
+                    continue
+
+            sigargs = f"*, {expr}" if expr else ""
+            signature = SIGNATURE.format(args=sigargs, docstring=docstring or "")
+
+        astree = ast.parse(signature)
+        return cast(ast.FunctionDef, astree.body[0])
+
+    def build_docstring(self) -> str:
+        """Build a rst docstring for the jinjax component."""
+        func_def = self.as_def()
+        prefix = f"{self.prefix}." if self.prefix else ""
+        ret = ".. jinjax:component:: " + generate_docstring(
+            func_def, f"{prefix}{self.name}", has_content(self.source)
+        )
+        return ret