flexdown 0.1.0__tar.gz

flexdown-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.1
+Name: flexdown
+Version: 0.1.0
+Summary: Write interactive documentation with Markdown and Python.
+Author: Nikhil Rao
+Author-email: nikhil@reflex.dev
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: mistletoe (>=1.2.1,<2.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: reflex (>=0.2.6,<0.3.0)
+Description-Content-Type: text/markdown
+
+

flexdown-0.1.0/flexdown/__init__.py

@@ -0,0 +1,76 @@
+import reflex as rx
+
+from . import templates
+from .flexdown import Flexdown
+from .document import Document
+
+
+# The default Flexdown instance.
+flexdown = Flexdown()
+
+
+def parse(source) -> Document:
+    """Parse a Flexdown document.
+
+    Args:
+        source: The source code of the Flexdown document.
+
+    Returns:
+        The parsed Flexdown document.
+    """
+    return Document.from_source(source)
+
+
+def parse_file(path: str) -> Document:
+    """Parse a Flexdown file.
+
+    Args:
+        path: The path to the Flexdown file.
+
+    Returns:
+        The parsed Flexdown document.
+    """
+    return Document.from_file(path)
+
+
+def render(source: str, **kwargs) -> rx.Component:
+    """Render Flexdown source code into a Reflex component.
+
+    Args:
+        source: The source code of the Flexdown file.
+        **kwargs: The keyword arguments to pass to the Flexdown constructor.
+
+    Returns:
+        The Reflex component representing the Flexdown file.
+    """
+    return Flexdown(**kwargs).render(source)
+
+
+def render_file(path: str, **kwargs) -> rx.Component:
+    """Render a Flexdown file into a Reflex component.
+
+    Args:
+        path: The path to the Flexdown file.
+        **kwargs: The keyword arguments to pass to the Flexdown constructor.
+
+    Returns:
+        The Reflex component representing the Flexdown file.
+    """
+    return Flexdown(**kwargs).render_file(path)
+
+
+def app(path: str, **kwargs) -> rx.App:
+    """Create a Reflex app from a directory of Flexdown files.
+
+    Args:
+        path: The path to the directory of Flexdown files.
+        **kwargs: The keyword arguments to pass to the Flexdown constructor.
+
+    Returns:
+        The Reflex app representing the directory of Flexdown files.
+    """
+
+    class State(rx.State):
+        pass
+
+    return Flexdown(**kwargs).create_app(path)

flexdown-0.1.0/flexdown/blocks/__init__.py

@@ -0,0 +1,5 @@
+from .block import Block
+from .code_block import CodeBlock
+from .eval_block import EvalBlock
+from .exec_block import ExecBlock
+from .markdown_block import MarkdownBlock

flexdown-0.1.0/flexdown/blocks/block.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Callable, ClassVar
+
+import reflex as rx
+
+from flexdown import types
+
+
+class Block(rx.Base):
+    """Base class for all Flexdown blocks."""
+
+    # The type of the block (defined by the subclass).
+    type: ClassVar[str]
+
+    # The string denoting the start of the block.
+    starting_indicator: ClassVar[str | None] = None
+
+    # The string denoting the end of the block.
+    ending_indicator: ClassVar[str] = ""
+
+    # Whether to include the indicators in the content.
+    include_indicators: ClassVar[bool] = False
+
+    # List of transformations to apply to each line.
+    line_transforms: ClassVar[list[Callable[[str], str]]] = []
+
+    # The lines of text in the block.
+    lines: list[str] = []
+
+    # The starting line number of the block.
+    start_line_number: int = 0
+
+    @classmethod
+    def from_line(cls, line: str, line_number: int = 0) -> Block | None:
+        """Try to create a block from a line of text.
+
+        This method checks if the line of text is the start of a block.
+
+        Args:
+            line: The line of text to check.
+            line_number: The line number of the line of text.
+
+        Returns:
+            The block if the line is the start of a block, otherwise `None`.
+        """
+        # If there is no starting indicator, or the line starts with the
+        # starting indicator, then create a block.
+        if cls.starting_indicator is None or line.startswith(cls.starting_indicator):
+            return cls(start_line_number=line_number).append(line)
+
+        # Otherwise, return `None`.
+        return None
+
+    def _apply_transforms(self, line: str, env: types.Env) -> str:
+        """Apply transformations to a line of text.
+
+        Args:
+            line: The line of text to transform.
+            env: The environment variables to use for line transformations.
+
+        Returns:
+            The transformed line of text.
+        """
+        for transform in self.line_transforms:
+            line = transform(line, env)
+        return line
+
+    def get_content(self, env: types.Env) -> str:
+        """The content of the block.
+
+        Args:
+            env: The environment variables to use for line transformations.
+
+        Returns:
+            The content of the block.
+        """
+        start_index = (
+            0 if self.include_indicators or self.starting_indicator is None else 1
+        )
+        end_index = None if self.include_indicators else -1
+        lines = [
+            self._apply_transforms(line, env)
+            for line in self.lines[start_index:end_index]
+        ]
+        return "\n".join(lines)
+
+    def append(self, line: str) -> Block:
+        """Append a line of text to the block.
+
+        Args:
+            line: The line of text to append.
+
+        Returns:
+            The block with the line of text appended.
+        """
+        self.lines.append(line)
+        return self
+
+    def is_finished(self) -> bool:
+        """Whether the block is finished."""
+        return len(self.lines) > 0 and self.lines[-1] == self.ending_indicator
+
+    def render(
+        self,
+        env: types.Env | None = None,
+        component_map: types.ComponentMap | None = None,
+    ) -> rx.Component:
+        """Render a block to a Reflex component.
+
+        Args:
+            env: The environment to use for rendering.
+            component_map: The component map to use.
+
+        Returns:
+            The rendered Reflex component.
+        """
+        pass
+
+
+# Functions that process blocks before rendering.
+BlockProcessor = Callable[[list[Block], types.Env], list[Block]]

flexdown-0.1.0/flexdown/blocks/code_block.py

@@ -0,0 +1,13 @@
+import reflex as rx
+
+from flexdown import types
+from flexdown.blocks.markdown_block import MarkdownBlock
+
+
+class CodeBlock(MarkdownBlock):
+    """A block of code."""
+
+    type = "code"
+    starting_indicator = "```"
+    ending_indicator = "```"
+    include_indicators = True

flexdown-0.1.0/flexdown/blocks/eval_block.py

@@ -0,0 +1,15 @@
+import reflex as rx
+
+from flexdown import types
+from flexdown.blocks.block import Block
+
+
+class EvalBlock(Block):
+    """A block that evaluates a Reflex component to display."""
+
+    type = "eval"
+    starting_indicator = "```python eval"
+    ending_indicator = "```"
+
+    def render(self, env: types.Env, **_) -> rx.Component:
+        return eval(self.get_content(env), env, env)

flexdown-0.1.0/flexdown/blocks/exec_block.py

@@ -0,0 +1,57 @@
+import importlib
+import os
+import sys
+
+import reflex as rx
+
+from flexdown import types
+from flexdown.blocks.block import Block
+
+
+MODULES = "modules"
+
+
+class ExecBlock(Block):
+    """A block of executable Python code."""
+
+    type = "exec"
+    starting_indicator = "```python exec"
+    ending_indicator = "```"
+
+    def render(self, **_) -> rx.Component:
+        # Return an empty component.
+        return rx.fragment()
+
+    @classmethod
+    def process_blocks(cls, blocks: list[Block], env: types.Env):
+        """Execute all the exec blocks.
+
+        Args:
+            blocks: The blocks to process.
+            env: The environment to use for processing.
+        """
+        # Get all the exec blocks.
+        exec_blocks = [block for block in blocks if block.type == cls.type]
+
+        # Concat the content of all the exec blocks.
+        content = "\n".join([block.get_content(env) for block in exec_blocks])
+
+        # Get the path to the directory where the module should be saved.
+        flexdown_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        module_dir = os.path.join(flexdown_dir, MODULES)
+
+        # Write the content to a file in the module directory.
+        os.makedirs(module_dir, exist_ok=True)
+        module_name = rx.vars.get_unique_variable_name()
+        module_path = os.path.join(module_dir, f"{module_name}.py")
+        with open(module_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        # Import the module to execute the code.
+        module_name = f"flexdown.{MODULES}.{module_name}"
+        if module_name in sys.modules:
+            module = importlib.reload(sys.modules[module_name])
+        else:
+            module = importlib.import_module(module_name)
+
+        env.update(vars(module))

flexdown-0.1.0/flexdown/blocks/markdown_block.py

@@ -0,0 +1,16 @@
+import reflex as rx
+
+from flexdown import types, utils
+from flexdown.blocks.block import Block
+
+
+class MarkdownBlock(Block):
+    """A block of Markdown."""
+
+    type = "markdown"
+    line_transforms = [
+        utils.evaluate_templates,
+    ]
+
+    def render(self, env: types.Env, component_map: types.ComponentMap) -> rx.Component:
+        return rx.markdown(self.get_content(env), component_map=component_map)

flexdown-0.1.0/flexdown/cli.py

@@ -0,0 +1,29 @@
+"""The Flexdown CLI.""" ""
+import os
+
+from reflex.reflex import typer
+from reflex.utils.processes import new_process
+
+from flexdown import constants
+
+
+# The command line app.
+app = typer.Typer()
+
+
+@app.command()
+def run(path: str):
+    # Create a .flexdown directory in the current directory.
+    os.makedirs(constants.FLEXDOWN_DIR, exist_ok=True)
+
+    # Create a reflex project.
+    new_process(
+        ["reflex", "init"], cwd=constants.FLEXDOWN_DIR, show_logs=True, run=True
+    )
+
+    # Replace the app file with a template.
+    with open(constants.FLEXDOWN_FILE, "w") as f:
+        f.write(constants.APP_TEMPLATE.format(path=f"../../{path}"))
+
+    # Run the reflex project.
+    new_process(["reflex", "run"], cwd=constants.FLEXDOWN_DIR, show_logs=True, run=True)

flexdown-0.1.0/flexdown/constants.py

@@ -0,0 +1,27 @@
+"""Constants used in flexdown."""
+
+# The extension for Flexdown files.
+FLEXDOWN_EXTENSION = ".md"
+
+# The Flexdown app directory.
+FLEXDOWN_DIR = ".flexdown/flexd"
+FLEXDOWN_FILE = f"{FLEXDOWN_DIR}/flexd/flexd.py"
+FLEXDOWN_MODULES_DIR = "modules"
+
+# Regex for front matter.
+FRONT_MATTER_REGEX = r"^---\s*\n(.+?)\n---\s*\n(.*)$"
+# Regex for template placeholders.
+TEMPLATE_REGEX = r"(?<!\\)(?<!\\\\){(?!\\)(.*?)(?<!\\)}"
+
+# The default app template.
+APP_TEMPLATE = """import flexdown
+import reflex as rx
+component_map = {{
+    "a": lambda value, **props: rx.link(value, color="blue", **props),
+}}
+app = flexdown.app(
+    '{path}',
+    page_template=flexdown.templates.base_template,
+    component_map=component_map
+)
+"""

flexdown-0.1.0/flexdown/document.py

@@ -0,0 +1,61 @@
+"""Flexdown documents."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+import reflex as rx
+
+from flexdown import constants, types
+
+
+class Document(rx.Base):
+    """A Flexdown document."""
+
+    # Document metadata in the flexdown frontmatter.
+    metadata: dict[str, Any] = {}
+
+    # The content of the document.
+    content: str
+
+    @staticmethod
+    def parse_front_matter(source: str) -> tuple[types.FrontMatter, str]:
+        # Extract the front matter and content using the pattern
+        match = re.match(constants.FRONT_MATTER_REGEX, source, re.DOTALL)
+
+        # If there is no front matter, return an empty dictionary
+        if not match:
+            return {}, source
+
+        # Get the front matter and content
+        front_matter = yaml.safe_load(match.group(1))
+        content = match.group(2)
+        return front_matter, content
+
+    @classmethod
+    def from_source(cls, source: str) -> Document:
+        """Create a document from a source string.
+
+        Args:
+            source: The source string of the document.
+
+        Returns:
+            The document.
+        """
+        front_matter, content = cls.parse_front_matter(source)
+        return cls(metadata=front_matter, content=content)
+
+    @classmethod
+    def from_file(cls, path: str) -> Document:
+        """Create a document from a file.
+
+        Args:
+            path: The path to the file.
+
+        Returns:
+            The document.
+        """
+        with open(path, "r", encoding="utf-8") as file:
+            return cls.from_source(file.read())

flexdown-0.1.0/flexdown/errors.py

@@ -0,0 +1,9 @@
+"""Exceptions for flexdown."""
+
+
+class TemplateEvaluationError(Exception):
+    """An error when evaluating a template placeholder."""
+
+
+class RenderError(Exception):
+    """An error when rendering a block."""

flexdown-0.1.0/flexdown/flexdown.py

@@ -0,0 +1,194 @@
+"""The main flexdown module."""
+from typing import Callable
+
+import reflex as rx
+
+from flexdown import errors, utils, types
+from flexdown.blocks import block, Block, MarkdownBlock, CodeBlock, ExecBlock, EvalBlock
+from flexdown.document import Document
+
+component_map = {
+    "code": lambda source: rx.code(source, color="#1F1944", bg="#EAE4FD"),
+}
+
+
+class Flexdown(rx.Base):
+    """Class to parse and render flexdown files."""
+
+    # The list of accepted block types to parse.
+    blocks: list[type[Block]] = [
+        ExecBlock,
+        EvalBlock,
+        CodeBlock,
+        MarkdownBlock,
+    ]
+
+    # The default block type.
+    default_block_type: type[Block] = MarkdownBlock
+
+    # List of processors to apply to blocks before rendering.
+    block_processors: list[block.BlockProcessor] = [
+        ExecBlock.process_blocks,
+    ]
+
+    # The template to use when rendering pages.
+    page_template: Callable[[rx.Component], rx.Component] = rx.fragment
+
+    # Mapping from markdown tag to a rendering function for Reflex components.
+    component_map: types.ComponentMap = component_map
+
+    def _get_block(self, line: str, line_number: int) -> Block:
+        """Get the block type for a line of text.
+
+        Args:
+            line: The line of text to check.
+            line_number: The line number of the line.
+
+        Returns:
+            The block type for the line of text.
+        """
+        # Search for a block type that can parse the line.
+        for block_type in self.blocks:
+
+            # Try to create a block from the line.
+            block = block_type.from_line(line, line_number=line_number)
+
+            # If a block was created, then return it.
+            if block is not None:
+                return block
+
+        # If no block was created, then return the default block type.
+        return self.default_block_type().append(line)
+
+    def get_blocks(self, source: str) -> list[Block]:
+        """Parse a Flexdown file into blocks.
+
+        Args:
+            source: The source code of the Flexdown file.
+
+        Returns:
+            The list of blocks in the Flexdown file.
+        """
+        # The list of parsed blocks.
+        blocks: list[Block] = []
+        current_block = None
+
+        # Iterate over each line in the source code.
+        for line_number, line in enumerate(source.splitlines()):
+
+            # If there is no current block, then create a new block.
+            if current_block is None:
+                # If the line is empty, then skip it.
+                if line == "":
+                    continue
+
+                # Otherwise, create a new block.
+                current_block = self._get_block(line, line_number)
+
+            else:
+                # Add the line to the current block.
+                current_block.append(line)
+
+            # Check if the current block is finished.
+            if current_block.is_finished():
+                blocks.append(current_block)
+                current_block = None
+
+        # Add the final block if it exists.
+        if current_block is not None:
+            blocks.append(current_block)
+
+        # Return the list of blocks.
+        return blocks
+
+    def process_blocks(self, blocks: list[Block], env: types.Env) -> list[Block]:
+        """Process a list of blocks to execute any side effects.
+
+        Args:
+            blocks: The list of blocks to process.
+            env: The environment variables to use for processing.
+
+        Returns:
+            The list of processed blocks.
+        """
+        for processor in self.block_processors:
+            processor(blocks, env)
+
+    def render(self, source: str | Document) -> rx.Component:
+        """Render a Flexdown file into a Reflex component.
+
+        Args:
+            source: The source code of the Flexdown file.
+
+        Returns:
+            The Reflex component representing the Flexdown file.
+        """
+        # Convert the source to a document.
+        if isinstance(source, str):
+            source = Document.from_source(source)
+
+        # The environment used for execing and evaling code.
+        env: types.Env = source.metadata
+
+        # Get the content of the document.
+        source = source.content
+
+        # Get the blocks in the source code.
+        blocks = self.get_blocks(source)
+        self.process_blocks(blocks, env)
+
+        # Render each block.
+        out: list[rx.Component] = []
+        for block in blocks:
+            try:
+                out.append(block.render(env=env, component_map=self.component_map))
+            except Exception as e:
+                raise errors.RenderError(
+                    f"Error while rendering block {block.type} on line {block.start_line_number}. "
+                    f"\n{block.get_content(env)}"
+                ) from e
+
+        # Wrap the output in the page template.
+        return self.page_template(rx.fragment(*out))
+
+    def render_file(self, path: str) -> rx.Component:
+        """Render a Flexdown file into a Reflex component.
+
+        Args:
+            path: The path to the Flexdown file.
+
+        Returns:
+            The Reflex component representing the Flexdown file.
+        """
+        # Render the source code.
+        return self.render(Document.from_file(path))
+
+    def create_app(self, path: str) -> rx.App:
+        """Create a Reflex app from a directory of Flexdown files.
+
+        Args:
+            path: The path to the directory of Flexdown files.
+
+        Returns:
+            The Reflex app representing the directory of Flexdown files.
+        """
+        # Get all the flexdown files in the directory.
+        files = utils.get_flexdown_files(path)
+
+        # Create the Reflex app.
+        app = rx.App()
+
+        # Create a base state.
+        class State(rx.State):
+            pass
+
+        # Add each page to the app.
+        for file in files:
+            route = file.replace(path, "").replace(".md", "")
+            app.add_page(self.render_file(file), route=route)
+
+        # Compile the app.
+        app.compile()
+
+        # Return the app.
+        return app

flexdown-0.1.0/flexdown/templates/__init__.py

@@ -0,0 +1 @@
+from .base_template import base_template

flexdown-0.1.0/flexdown/templates/base_template.py

@@ -0,0 +1,8 @@
+import reflex as rx
+
+
+def base_template(content: rx.Component) -> rx.Component:
+    return rx.container(
+        content,
+        margin_y="5em",
+    )

flexdown-0.1.0/flexdown/types.py

@@ -0,0 +1,13 @@
+"""Types for Flexdown.""" ""
+from typing import Any, Callable
+
+import reflex as rx
+
+# An environment for executing and evaluating code.
+Env = dict[str, Any]
+
+# The frontmatter of a Flexdown document.
+Frontmatter = dict[str, Any]
+
+# Mapping from markdown tag to a rendering function for Reflex components.
+ComponentMap = dict[str, Callable[[str], rx.Component]]

flexdown-0.1.0/flexdown/utils.py

@@ -0,0 +1,78 @@
+"""Utility functions for Flexdown."""
+
+import glob
+import inspect
+import os
+import re
+import textwrap
+
+from flexdown import constants, errors, types
+
+
+def get_flexdown_files(path: str) -> list[str]:
+    """Recursively get the Flexdown files in a directory.
+
+    Args:
+        path: The path to the directory to search.
+
+    Returns:
+        The list of Flexdown files in the directory.
+    """
+    flexdown_files = []
+    for root, _, files in os.walk(path):
+        flexdown_files.extend(
+            [
+                os.path.join(root, file)
+                for file in files
+                if file.endswith(constants.FLEXDOWN_EXTENSION)
+            ]
+        )
+    return flexdown_files
+
+
+def evaluate_templates(line: str, env: types.Env):
+    """Evaluate template expressions in a line of text.
+
+    Args:
+        line: The line of text to evaluate.
+        env: The environment variables to use for evaluation.
+    """
+    # Find all template placeholders in the line.
+    matches = re.findall(constants.TEMPLATE_REGEX, line)
+
+    # Iterate over each template placeholder.
+    for match in matches:
+        try:
+            # Evaluate the Python expression and replace the template placeholder
+            eval_result = str(eval(match, env, env))
+            line = line.replace("{" + match + "}", eval_result)
+        except Exception as e:
+            # If the evaluation fails, leave the template placeholder unchanged
+            raise errors.TemplateEvaluationError(
+                f"Failed to evaluate expression '{match}'"
+            ) from e
+
+    # Return the line with the template placeholders replaced.
+    return line
+
+
+def get_source(fn):
+    """Get the source code of a function.
+
+    Args:
+        fn: The function to get the source code of.
+    """
+    # Get the source code of the function.
+    source = inspect.getsource(fn)
+
+    # Remove the function definition.
+    source = re.sub(r"def \w+\(.*?\):", "", source, flags=re.DOTALL)
+
+    # Remove the indentation.
+    source = textwrap.dedent(source)
+
+    # Remove the trailing newline.
+    source = source[:-1]
+
+    # Return the source code.
+    return source

flexdown-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "flexdown"
+version = "0.1.0"
+description = "Write interactive documentation with Markdown and Python."
+authors = ["Nikhil Rao <nikhil@reflex.dev>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+reflex = "^0.2.6"
+mistletoe = "^1.2.1"
+pyyaml = "^6.0.1"
+
+[tool.poetry.scripts]
+flexdown = "flexdown.cli:app"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"