pyact-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyact-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: A CLI tool to compile .pamd files to Markdown.
 Home-page: https://github.com/Abstergo2003/PyAct
 Author: Abstergo2003
@@ -10,11 +10,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Requires-Dist: python-docx
+Requires-Dist: ezdxf
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
@@ -65,10 +68,17 @@ You can also include other pamd files as templates!
 <tmp>path/to/another_file</tmp>
 ```
 
-### 3. Compile!
+### 3. Compile to Markdown
 Run the compiler from your terminal to generate your final Markdown document:
 ```bash
 pyact path/to/your_file.pamd -o output.md
 ```
 
-That's it! You now have a standard Markdown file ready to be shared, published, or converted to PDF.
+### 4. Compile to Word (DOCX)
+You can also compile straight to a native Microsoft Word Document, complete with CSS styling! 
+```bash
+pyact path/to/your_file.pamd -o output.md --docx output.docx
+```
+*Note: If you have a `style.css` file in the same directory, PyAct will automatically load it to style your Word Document. You can also specify one manually using the `--css path/to/style.css` flag!*
+
+That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/README.md

@@ -45,10 +45,17 @@ You can also include other pamd files as templates!
 <tmp>path/to/another_file</tmp>
 ```
 
-### 3. Compile!
+### 3. Compile to Markdown
 Run the compiler from your terminal to generate your final Markdown document:
 ```bash
 pyact path/to/your_file.pamd -o output.md
 ```
 
-That's it! You now have a standard Markdown file ready to be shared, published, or converted to PDF.
+### 4. Compile to Word (DOCX)
+You can also compile straight to a native Microsoft Word Document, complete with CSS styling! 
+```bash
+pyact path/to/your_file.pamd -o output.md --docx output.docx
+```
+*Note: If you have a `style.css` file in the same directory, PyAct will automatically load it to style your Word Document. You can also specify one manually using the `--css path/to/style.css` flag!*
+
+That's it! You now have documents ready to be shared, published, or distributed.

pyact_cli-0.6.0/pamd_helpers/__init__.py

@@ -0,0 +1,243 @@
+import inspect
+from typing import Callable, List, Any
+from pyact.py2tex import py2tex
+
+def equation(func: Callable, values: List[Any]) -> str:
+    """
+    Converts a Python lambda or simple function into a LaTeX math equation string.
+    
+    Why it is needed:
+    To allow users to define equations in Python syntax and automatically render them 
+    as mathematical formulas in the final document, without needing to hand-write LaTeX.
+    
+    Inputs:
+        func (Callable): A simple Python function (e.g., `lambda x: x**2`).
+        values (List[Any]): The arguments to pass to the function to compute the result.
+        
+    Outputs:
+        str: A Markdown math string formatted as `$$ Name = Equation = Value $$`.
+    """
+    source = inspect.getsource(func)
+    value = func(*values)
+    name, sep, tail = source.rpartition("=")
+    head, sep, equ = tail.rpartition(":")
+    return f"$$ {name} = {py2tex(equ.replace(chr(10), ''))} = {value} $$"
+
+def image(link: str, caption: str) -> str:
+    """
+    Generates a Markdown image string with an embedded HTML caption.
+    
+    Why it is needed:
+    Standard Markdown images `![caption](url)` don't display visible captions below the image.
+    This helper injects a styled HTML `<span>` below the image to force a visual caption.
+    
+    Inputs:
+        link (str): The URL or local path to the image.
+        caption (str): The text to display as the caption.
+        
+    Outputs:
+        str: A formatted string containing the Markdown image and HTML span caption.
+    """
+    image_link = f"![{caption}]({link})"
+    caption_html = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
+    return f"{image_link} \n {caption_html}"
+
+def table(headers: List[str], values: List[List[Any]], caption: str, add_no: bool = False, starting_number: int = 1) -> str:
+    """
+    Generates a Markdown table from Python lists, including a caption.
+    
+    Why it is needed:
+    Writing Markdown tables by hand is tedious. This function allows users to programmatically 
+    build tables from 2D data arrays, inject automatic numbering, and append a styled caption.
+    
+    Inputs:
+        headers (List[str]): List of column header names.
+        values (List[List[Any]]): A 2D list containing the row data.
+        caption (str): The text to display above the table.
+        add_no (bool): If True, adds an auto-incrementing "No." column to the left.
+        starting_number (int): The starting index for the "No." column.
+        
+    Outputs:
+        str: A formatted Markdown string containing the caption and the table.
+    """
+    if add_no:
+        headers_string = f"|No.|"
+        breaker_line = "|---|"
+    else:
+        headers_string = f"|"
+        breaker_line = "|"
+
+    for i in headers:
+        headers_string += f"{i}|"
+        breaker_line += "-"*len(i)+"|"
+
+    table_content = ""
+    for i, row in enumerate(values):
+        if add_no:
+            table_content += f"|{i+starting_number}|"
+        else:
+            table_content += "|"
+        for value in row:
+            table_content += f"{value}|"
+        table_content += "\n"
+
+    caption_html = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
+    return f"{caption_html} \n {headers_string}\n{breaker_line}\n{table_content}"
+
+def hyperlink(caption: str, link: str) -> str:
+    """
+    Generates a simple Markdown hyperlink.
+    
+    Why it is needed:
+    Provides a standardized helper method in the PyAct ecosystem for injecting links.
+    
+    Inputs:
+        caption (str): The clickable text to display.
+        link (str): The URL destination.
+        
+    Outputs:
+        str: The Markdown hyperlink string `[caption](link)`.
+    """
+    return f"[{caption}]({link})"
+
+def unordered_list(items: List[str]) -> str:
+    """
+    Generates a Markdown unordered (bullet) list from a Python list.
+    
+    Why it is needed:
+    Allows programmatic generation of bullet points from array data.
+    
+    Inputs:
+        items (List[str]): A list of string items.
+        
+    Outputs:
+        str: A Markdown string where each item is prefixed with `* `.
+    """
+    list_string = ""
+    for i in items:
+        list_string += f"* {i}\n"
+    return list_string
+
+def ordered_list(items: List[str]) -> str:
+    """
+    Generates a Markdown ordered (numbered) list from a Python list.
+    
+    Why it is needed:
+    Allows programmatic generation of numbered lists from array data.
+    
+    Inputs:
+        items (List[str]): A list of string items.
+        
+    Outputs:
+        str: A Markdown string where each item is numbered sequentially (1. 2. 3.).
+    """
+    list_string = ""
+    for i, item in enumerate(items):
+        list_string += f"{i+1}. {item}\n"
+    return list_string
+
+def checklist(items: List[str]) -> str:
+    """
+    Generates a Markdown task checklist from a Python list.
+    
+    Why it is needed:
+    Allows programmatic generation of checkable task items.
+    
+    Inputs:
+        items (List[str]): A list of string items.
+        
+    Outputs:
+        str: A Markdown string where each item is prefixed with `- [ ] `.
+    """
+    list_string = ""
+    for i in items:
+        list_string += f"- [ ] {i}\n"
+    return list_string
+
+class Footnote:
+    """
+    A helper class for managing Markdown footnotes.
+    
+    Why it is needed:
+    Footnotes require two separate parts in Markdown: the annotation mark in the text `[^1]`, 
+    and the definition at the bottom of the document `[^1]: The text`. This class links 
+    the two together to prevent numbering mismatches.
+    """
+    def __init__(self, number: int, text: str):
+        """
+        Inputs:
+            number (int): The footnote reference number.
+            text (str): The expanded text definition of the footnote.
+        """
+        self.number = number
+        self.text = text
+
+    def define_string(self) -> str:
+        """
+        Outputs (str): The full footnote definition block to place at the bottom of the document.
+        """
+        return f"[^{self.number}]: {self.text}"
+
+    def adnotation(self) -> str:
+        """
+        Outputs (str): The short inline reference marker to place in the paragraph text.
+        """
+        return f"[^{self.number}]\n"
+
+def table_to_dxf(headers: List[str], values: List[List[Any]], filename: str, cell_width: float = 50.0, cell_height: float = 10.0) -> str:
+    """
+    Exports a table (headers + values) to a 2D CAD DXF file.
+    
+    Why it is needed:
+    Engineers and designers often need to embed tabulated data (e.g. Bill of Materials, 
+    coordinate tables, parts lists) directly into AutoCAD drawings. This helper converts 
+    a Python table directly into DXF geometry (lines and text) that can be opened in any CAD software.
+    
+    Inputs:
+        headers (List[str]): List of column header names.
+        values (List[List[Any]]): A 2D list containing the row data.
+        filename (str): The output filename (e.g., 'table.dxf').
+        cell_width (float): The width of each cell in drawing units.
+        cell_height (float): The height of each cell in drawing units.
+        
+    Outputs:
+        str: A string confirming the export, formatted as a Markdown link.
+    """
+    try:
+        import ezdxf
+    except ImportError:
+        return f"*(Error: ezdxf library is not installed. Cannot generate {filename})*"
+        
+    doc = ezdxf.new('R2010')
+    msp = doc.modelspace()
+    
+    # Construct full grid data
+    rows = [headers] + values
+    num_rows = len(rows)
+    num_cols = len(headers)
+    
+    # Draw horizontal grid lines
+    for i in range(num_rows + 1):
+        y = -i * cell_height
+        msp.add_line((0, y), (num_cols * cell_width, y))
+        
+    # Draw vertical grid lines
+    for j in range(num_cols + 1):
+        x = j * cell_width
+        msp.add_line((x, 0), (x, -num_rows * cell_height))
+        
+    # Draw text centered in each cell
+    for i, row in enumerate(rows):
+        y = -i * cell_height - (cell_height / 2)
+        for j, cell_val in enumerate(row):
+            if j >= num_cols: continue # Safety bounds
+            x = j * cell_width + (cell_width / 2)
+            msp.add_text(
+                str(cell_val),
+                dxfattribs={
+                    'height': cell_height * 0.4,
+                }
+            ).set_placement((x, y), align=ezdxf.enums.TextEntityAlignment.MIDDLE_CENTER)
+            
+    doc.saveas(filename)
+    return f"*[Successfully exported table to {filename}]({filename})*"

pyact_cli-0.6.0/pamd_helpers/conversions.py

@@ -0,0 +1,126 @@
+"""
+Engineering Unit Conversions for PyAct
+
+A collection of helper functions to seamlessly convert values between 
+Metric (SI) and Imperial / US Customary systems.
+"""
+
+# ==========================================
+# LENGTH CONVERSIONS
+# ==========================================
+
+def mm_to_inch(mm: float) -> float:
+    """Converts millimeters [mm] to inches [in]"""
+    return mm / 25.4
+
+def inch_to_mm(inch: float) -> float:
+    """Converts inches [in] to millimeters [mm]"""
+    return inch * 25.4
+
+def m_to_ft(m: float) -> float:
+    """Converts meters [m] to feet [ft]"""
+    return m * 3.280839895
+
+def ft_to_m(ft: float) -> float:
+    """Converts feet [ft] to meters [m]"""
+    return ft / 3.280839895
+
+# ==========================================
+# AREA & VOLUME CONVERSIONS
+# ==========================================
+
+def mm2_to_in2(mm2: float) -> float:
+    """Converts square millimeters [mm^2] to square inches [in^2]"""
+    return mm2 / 645.16
+
+def in2_to_mm2(in2: float) -> float:
+    """Converts square inches [in^2] to square millimeters [mm^2]"""
+    return in2 * 645.16
+
+def m3_to_ft3(m3: float) -> float:
+    """Converts cubic meters [m^3] to cubic feet [ft^3]"""
+    return m3 * 35.3146667
+
+def ft3_to_m3(ft3: float) -> float:
+    """Converts cubic feet [ft^3] to cubic meters [m^3]"""
+    return ft3 / 35.3146667
+
+# ==========================================
+# MASS & FORCE CONVERSIONS
+# ==========================================
+
+def kg_to_lbs(kg: float) -> float:
+    """Converts kilograms [kg] to pounds-mass [lbs]"""
+    return kg * 2.20462262
+
+def lbs_to_kg(lbs: float) -> float:
+    """Converts pounds-mass [lbs] to kilograms [kg]"""
+    return lbs / 2.20462262
+
+def kn_to_kips(kn: float) -> float:
+    """Converts kilonewtons [kN] to kilopounds-force [kips]"""
+    return kn * 0.224808943
+
+def kips_to_kn(kips: float) -> float:
+    """Converts kilopounds-force [kips] to kilonewtons [kN]"""
+    return kips / 0.224808943
+
+def n_to_lbf(n: float) -> float:
+    """Converts newtons [N] to pounds-force [lbf]"""
+    return n * 0.224808943
+
+def lbf_to_n(lbf: float) -> float:
+    """Converts pounds-force [lbf] to newtons [N]"""
+    return lbf / 0.224808943
+
+# ==========================================
+# PRESSURE & STRESS CONVERSIONS
+# ==========================================
+
+def mpa_to_psi(mpa: float) -> float:
+    """Converts Megapascals [MPa] (or N/mm^2) to pounds per square inch [psi]"""
+    return mpa * 145.037738
+
+def psi_to_mpa(psi: float) -> float:
+    """Converts pounds per square inch [psi] to Megapascals [MPa]"""
+    return psi / 145.037738
+
+def mpa_to_ksi(mpa: float) -> float:
+    """Converts Megapascals [MPa] to kilopounds per square inch [ksi]"""
+    return mpa * 0.145037738
+
+def ksi_to_mpa(ksi: float) -> float:
+    """Converts kilopounds per square inch [ksi] to Megapascals [MPa]"""
+    return ksi / 0.145037738
+
+# ==========================================
+# MOMENT & TORQUE CONVERSIONS
+# ==========================================
+
+def knm_to_kipft(knm: float) -> float:
+    """Converts kilonewton-meters [kNm] to kilopound-feet [kip-ft]"""
+    return knm * 0.737562149
+
+def kipft_to_knm(kipft: float) -> float:
+    """Converts kilopound-feet [kip-ft] to kilonewton-meters [kNm]"""
+    return kipft / 0.737562149
+
+def knm_to_lbfft(knm: float) -> float:
+    """Converts kilonewton-meters [kNm] to pound-force feet [lbf-ft]"""
+    return knm * 737.562149
+
+def lbfft_to_knm(lbfft: float) -> float:
+    """Converts pound-force feet [lbf-ft] to kilonewton-meters [kNm]"""
+    return lbfft / 737.562149
+
+# ==========================================
+# TEMPERATURE CONVERSIONS
+# ==========================================
+
+def c_to_f(celsius: float) -> float:
+    """Converts degrees Celsius [°C] to degrees Fahrenheit [°F]"""
+    return (celsius * 9/5) + 32
+
+def f_to_c(fahrenheit: float) -> float:
+    """Converts degrees Fahrenheit [°F] to degrees Celsius [°C]"""
+    return (fahrenheit - 32) * 5/9

pyact_cli-0.6.0/pamd_helpers/unit.py

@@ -0,0 +1,43 @@
+class Unit:
+    def __init__(self, value: float, unit: str):
+        self.value: float = value
+        self.unit: str = unit
+
+    def __repr__(self) -> str:
+        return f"{self.value} {self.unit}"
+        
+    def _extract(self, other) -> float:
+        return float(other.value) if isinstance(other, Unit) else float(other)
+
+    def __add__(self, other):
+        return float(self.value) + self._extract(other)
+
+    def __radd__(self, other):
+        return self._extract(other) + float(self.value)
+
+    def __sub__(self, other):
+        return float(self.value) - self._extract(other)
+
+    def __rsub__(self, other):
+        return self._extract(other) - float(self.value)
+
+    def __mul__(self, other):
+        return float(self.value) * self._extract(other)
+
+    def __rmul__(self, other):
+        return self._extract(other) * float(self.value)
+
+    def __truediv__(self, other):
+        return float(self.value) / self._extract(other)
+
+    def __rtruediv__(self, other):
+        return self._extract(other) / float(self.value)
+
+    def __pow__(self, power):
+        return float(self.value) ** self._extract(power)
+
+    def __neg__(self):
+        return -float(self.value)
+        
+    def __abs__(self):
+        return abs(float(self.value))

pyact_cli-0.6.0/pyact/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

pyact_cli-0.6.0/pyact/cli.py

@@ -0,0 +1,113 @@
+import argparse
+import sys
+import os
+from .core import map_content, process_content
+
+def is_cache_valid(build_tree, cache_mtime):
+    file_path = os.path.join(build_tree.get("path", ""), build_tree.get("name", "") + ".pamd")
+    if os.path.exists(file_path) and os.path.getmtime(file_path) > cache_mtime:
+        return False
+    for t in build_tree.get("templates", []):
+        if not is_cache_valid(t, cache_mtime):
+            return False
+    return True
+
+def main():
+    """
+    Main entry point for the PyAct Command Line Interface.
+    
+    Why it is needed:
+    This acts as the bridge between the terminal and the PyAct compilation engine. 
+    It parses command-line arguments, triggers the document mapping/compilation process, 
+    and handles file I/O for outputting the compiled Markdown and DOCX files.
+    
+    Inputs (via sys.argv):
+        input (str): Positional argument for the target `.pamd` file path.
+        --output (str): Optional path to save the generated `.md` file.
+        --docx (str): Optional path to save the generated `.docx` file.
+        --css (str): Optional path to a `.css` file for styling the DOCX output.
+        --lint (bool): Run the linter to check for unused files and variables.
+        
+    Outputs:
+        Writes the generated `.md` and `.docx` files to the filesystem and prints 
+        status messages to stdout/stderr.
+    """
+    parser = argparse.ArgumentParser(description="PyAct CLI - PAMD to Markdown compiler")
+    parser.add_argument("input", help="Path to the main .pamd file")
+    parser.add_argument("-o", "--output", help="Output file path (default prints to stdout)")
+    parser.add_argument("--docx", help="Also generate a DOCX file at this path")
+    parser.add_argument("--css", help="Optional CSS file path to style the DOCX")
+    parser.add_argument("--lint", action="store_true", help="Run the linter on the project to check for unused variables and files")
+    
+    args = parser.parse_args()
+    
+    input_path = os.path.abspath(args.input)
+    directory = os.path.dirname(input_path)
+    filename = os.path.basename(input_path)
+    
+    if filename.endswith(".pamd"):
+        filename = filename[:-5]
+        
+    if args.lint:
+        from .linter import run_linter
+        run_linter(filename, directory)
+        return
+        
+    try:
+        build_tree = map_content(filename, directory)
+        
+        cache_dir = os.path.join(directory, ".pamd-cache")
+        cache_file = os.path.join(cache_dir, f"{filename}.cache.md")
+        use_cache = False
+        
+        if os.path.exists(cache_file):
+            cache_mtime = os.path.getmtime(cache_file)
+            if is_cache_valid(build_tree, cache_mtime):
+                use_cache = True
+                
+        if use_cache:
+            print("pamd-cache: Using cached markdown...")
+            with open(cache_file, "r", encoding="utf-8") as f:
+                content = f.read()
+        else:
+            print("pamd-cache: Cache invalid or missing. Rebuilding...")
+            content = process_content(build_tree)
+            # Write cache
+            if not os.path.exists(cache_dir):
+                os.makedirs(cache_dir)
+            with open(cache_file, "w", encoding="utf-8") as f:
+                f.write(content)
+        
+        if args.output:
+            with open(args.output, "w", encoding="utf-8") as f:
+                f.write(content)
+            print(f"Successfully compiled to {args.output}")
+        else:
+            if not args.docx:
+                print(content)
+            
+        if args.docx:
+            from .mdTOword import style_parser, markdown_parser, docx_writer
+            styles = {}
+            if args.css:
+                styles = style_parser(args.css)
+            else:
+                # Try to look for style.css in the active directory
+                local_css = os.path.join(directory, "style.css")
+                if os.path.exists(local_css):
+                    styles = style_parser(local_css)
+                else:
+                    # Fallback to the default one packaged in pyact
+                    default_css = os.path.join(os.path.dirname(__file__), "style.css")
+                    styles = style_parser(default_css)
+                    
+            blocks = markdown_parser(content)
+            docx_writer(blocks, styles, args.docx)
+            print(f"Successfully compiled DOCX to {args.docx}")
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

pyact_cli-0.6.0/pyact/core.py

@@ -0,0 +1,198 @@
+import re
+import json
+
+def get_directory(path: str) -> list:
+    """
+    Splits a full file path into its directory component and its filename component.
+    
+    Why it is needed:
+    When resolving nested templates or generating output files, the engine needs to 
+    know the base directory of the current `.pamd` file so it can correctly locate 
+    sibling template files.
+    
+    Inputs:
+        path (str): The full path to a file (e.g., './main/retro.pamd').
+        
+    Outputs:
+        list: A two-element list `[directory_path, filename]`.
+    """
+    head, sep, tail = path.rpartition('/')
+    return [head + sep, tail]
+
+def read_pamd_cells(file_path: str):
+    """
+    Reads a .pamd (JSON Notebook) file and extracts the Markdown and Python code.
+    
+    Why it is needed:
+    `.pamd` files are stored exactly like Jupyter Notebooks (a list of cell objects). 
+    This function parses the JSON structure and concatenates all 'code' cells into a 
+    single executable Python script, and all 'markdown' cells into a single Markdown document.
+    
+    Inputs:
+        file_path (str): Path to the `.pamd` file to read.
+        
+    Outputs:
+        tuple (str, str): A tuple containing `(code_content, markdown_content)`.
+    """
+    with open(file_path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    
+    code_content = ""
+    markdown_content = ""
+    
+    for cell in data.get("cells", []):
+        cell_type = cell.get("cell_type", "")
+        source = cell.get("source", "")
+        if isinstance(source, list):
+            source = "".join(source)
+            
+        if cell_type == "code":
+            code_content += source + "\n"
+        elif cell_type == "markdown":
+            markdown_content += source + "\n"
+            
+    return code_content, markdown_content
+
+def get_imports(file: str, code_text: str):
+    """
+    Executes the Python code from a .pamd file and retrieves the context variables.
+    
+    Why it is needed:
+    To inject dynamic data into the Markdown document, PyAct executes the user's Python 
+    script. The user must define a `context()` function that returns a dictionary mapping 
+    variable names (like 'title') to their computed values. This function safely executes 
+    that code and extracts the resulting dictionary.
+    
+    Inputs:
+        file (str): The name of the file being executed (for error reporting).
+        code_text (str): The raw Python code extracted from the `.pamd` file.
+        
+    Outputs:
+        dict: The dictionary of variables returned by the user's `context()` function.
+    """
+    file_namespace = {"__file__": f"{file}.pamd"}
+    if not code_text.strip():
+        raise ValueError(f"The file {file}.pamd needs a 'context()' function but has no code cell.")
+        
+    try:
+        exec(code_text, file_namespace)
+    except Exception as e:
+        raise RuntimeError(f"Error executing code in {file}.pamd: {e}")
+
+    if "context" not in file_namespace:
+        raise ValueError(f"The file {file}.pamd is missing the required 'context()' function.")
+
+    context_func = file_namespace["context"]
+
+    if not callable(context_func):
+        raise TypeError(f"In {file}.pamd, 'context' was found but it is not a function!")
+
+    result_dict = context_func()
+
+    if not isinstance(result_dict, dict):
+        raise TypeError(f"The 'context()' function in {file}.pamd must return a dictionary.")
+
+    return result_dict
+
+def find_imports(text: str):
+    """
+    Finds all `<ctx>var_name</ctx>` tags in a markdown string.
+    
+    Why it is needed:
+    Identifies which variables the Markdown document is requesting from the Python context.
+    
+    Inputs:
+        text (str): The raw Markdown text.
+        
+    Outputs:
+        list: A list of variable names extracted from the tags.
+    """
+    pattern = r"<ctx>(.*?)</ctx>"
+    return re.findall(pattern, text)
+
+
+def find_templates(text: str):
+    """
+    Finds all `<tmp>file_name</tmp>` tags in a markdown string.
+    
+    Why it is needed:
+    Identifies nested `.pamd` template files that need to be recursively compiled 
+    and injected into the current document.
+    
+    Inputs:
+        text (str): The raw Markdown text.
+        
+    Outputs:
+        list: A list of template file names extracted from the tags.
+    """
+    pattern = r"<tmp>(.*?)</tmp>"
+    return re.findall(pattern, text)
+
+def map_content(file: str, path: str):
+    """
+    Recursively maps the dependency tree of a `.pamd` file.
+    
+    Why it is needed:
+    Before compiling, PyAct needs to build an Abstract Syntax Tree (AST) of the document, 
+    mapping out all required context variables and any nested child templates that need 
+    to be resolved. This allows for deep, nested project structures.
+    
+    Inputs:
+        file (str): The target `.pamd` file name (without extension).
+        path (str): The directory where the file is located.
+        
+    Outputs:
+        dict: A recursive "build tree" dictionary containing metadata, required imports, 
+              and the build trees of all nested templates.
+    """
+    if path and not path.endswith('/'):
+        full_path = f"{path}/{file}"
+    elif path.endswith('/'):
+        full_path = f"{path}{file}"
+    else:
+        full_path = file
+        
+    code_text, main_file = read_pamd_cells(f"{full_path}.pamd")
+    templates = find_templates(main_file)
+    imports = find_imports(main_file)
+    meta = get_directory(full_path)
+    
+    ready_t = []
+    for i in templates:
+        ready_t.append(map_content(i, meta[0]))
+
+    return {
+        "tag_name": file,
+        "name": meta[1],
+        "path": meta[0],
+        "imports": imports,
+        "templates": ready_t
+    }
+
+def process_content(build_tree: dict):
+    """
+    Compiles a mapped build tree into a final flat Markdown string.
+    
+    Why it is needed:
+    This is the core renderer. It reads the `.pamd` files, executes their Python code 
+    to fetch the context dictionary, replaces all `<ctx>` tags with dynamic data, 
+    and recursively replaces all `<tmp>` tags with their fully compiled child documents.
+    
+    Inputs:
+        build_tree (dict): The AST mapping generated by `map_content()`.
+        
+    Outputs:
+        str: The final, fully compiled Markdown text string ready for export.
+    """
+    file_path_base = build_tree.get("path", "") + build_tree.get("name", "")
+    code_text, file_text = read_pamd_cells(file_path_base + ".pamd")
+    
+    needed_imports = build_tree.get("imports", [])
+    if needed_imports:
+        imports = get_imports(file_path_base, code_text)
+        for i in needed_imports:
+            file_text = file_text.replace(f"<ctx>{i}</ctx>", str(imports.get(i, '')))
+
+    for i in build_tree.get("templates", []):
+        file_text = file_text.replace(f"<tmp>{i.get('tag_name')}</tmp>", process_content(i))
+    return file_text

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/pyact/css2json.py

@@ -2,7 +2,21 @@ import re
 import json
 
 def css_to_dict(css_string: str) -> dict:
-    """Parses a CSS string into a Python dictionary."""
+    """
+    Parses a raw CSS string into a nested Python dictionary.
+    
+    Why it is needed:
+    CSS is text-based and formatted with selectors, curly braces, and semicolons.
+    To programmatically apply these styles to python-docx elements, we need to 
+    convert the syntax into a highly structured, queryable dictionary map.
+    
+    Inputs:
+        css_string (str): The raw contents of a CSS file as a string.
+        
+    Outputs:
+        dict: A dictionary where keys are CSS selectors (e.g., 'p', 'h1') and 
+              values are dictionaries of style properties (e.g., {'color': '#000'}).
+    """
     # Remove CSS comments
     css_string = re.sub(r'/\*[\s\S]*?\*/', '', css_string)
     
@@ -36,8 +50,19 @@ def css_to_dict(css_string: str) -> dict:
 
 def parse_css_file(file_path: str, as_json_string: bool = False):
     """
-    Reads a CSS file and converts it to a dictionary map. 
-    If as_json_string is True, returns a formatted JSON string instead.
+    Reads a CSS file from disk and parses it into a dictionary or JSON string.
+    
+    Why it is needed:
+    Provides a clean interface for reading a physical file from the OS, extracting 
+    its contents, and piping it into the core `css_to_dict` parser.
+    
+    Inputs:
+        file_path (str): The path to the `.css` file on disk.
+        as_json_string (bool): If True, returns the output as a serialized JSON string 
+                               instead of a Python dictionary. Defaults to False.
+                               
+    Outputs:
+        dict or str: The parsed CSS dictionary, or a JSON-formatted string if requested.
     """
     with open(file_path, 'r', encoding='utf-8') as f:
         css_string = f.read()

pyact_cli-0.6.0/pyact/linter.py

@@ -0,0 +1,85 @@
+import os
+from .core import read_pamd_cells, get_imports, find_imports, map_content
+
+def run_linter(main_filename: str, directory: str):
+    """
+    Runs the linter on a PyAct project.
+    
+    Checks for:
+    1. Unused .pamd files in the directory.
+    2. Context keys exported but not used in the markdown.
+    3. Context tags requested in the markdown but missing from the context dictionary.
+    """
+    print(f"--- PyAct Linter ---")
+    print(f"Analyzing project starting from: {main_filename}.pamd\n")
+    
+    try:
+        build_tree = map_content(main_filename, directory)
+    except Exception as e:
+        print(f"Error mapping project: {e}")
+        return
+        
+    used_files = set()
+    
+    def collect_used_files(tree):
+        file_path = os.path.join(tree['path'], tree['name'])
+        used_files.add(os.path.abspath(file_path + ".pamd"))
+        for child in tree.get("templates", []):
+            collect_used_files(child)
+            
+    collect_used_files(build_tree)
+    
+    # Check for unused .pamd files in the base directory
+    all_pamd_files = set()
+    for root, _, files in os.walk(directory):
+        for f in files:
+            if f.endswith(".pamd"):
+                all_pamd_files.add(os.path.abspath(os.path.join(root, f)))
+                
+    unused_files = all_pamd_files - used_files
+    if unused_files:
+        print(f"[WARNING] Unused .pamd files found in project directory:")
+        for uf in unused_files:
+            print(f"   - {os.path.relpath(uf, directory)}")
+    else:
+        print("[OK] No unused .pamd files found.")
+        
+    print("\n--- Context Check ---")
+    
+    # Check context in each used file
+    for used_file in used_files:
+        rel_path = os.path.relpath(used_file, directory)
+        try:
+            code_text, md_text = read_pamd_cells(used_file)
+        except Exception:
+            continue
+            
+        try:
+            # Need to pass base name for error reporting in core.py
+            base_name = os.path.splitext(os.path.basename(used_file))[0]
+            context_dict = get_imports(base_name, code_text)
+            exported_keys = set(context_dict.keys())
+        except Exception:
+            # If a file has no code cell or no context(), it returns an empty dict effectively, 
+            # or throws ValueError in get_imports. Let's just treat as empty if error.
+            exported_keys = set()
+            
+        requested_keys = set(find_imports(md_text))
+        
+        unused_exports = exported_keys - requested_keys
+        missing_exports = requested_keys - exported_keys
+        
+        if unused_exports or missing_exports:
+            print(f"\nFile: {rel_path}")
+            if unused_exports:
+                print(f"  [WARNING] Unused context exports (defined in python, not used in markdown):")
+                for k in unused_exports:
+                    print(f"     - {k}")
+            if missing_exports:
+                print(f"  [ERROR] Missing context exports (used in markdown, missing in python):")
+                for k in missing_exports:
+                    print(f"     - {k}")
+        else:
+            pass
+
+    print("\nLinting complete!")

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/pyact/mdTOword.py

@@ -7,9 +7,22 @@ from docx.oxml.ns import nsdecls
 import math2docx
 from . import css2json
 
-def style_parser(css_path):
+def style_parser(css_path: str) -> dict:
     """
-    Reads a CSS file and converts it into a style dictionary using css2json.
+    Parses a CSS file and converts it into a Python dictionary containing style maps.
+    
+    Why it is needed:
+    To allow users to style their exported Word Documents using standard CSS syntax, 
+    we must first translate that CSS into a structured Python dictionary that the 
+    DOCX generation engine can query.
+    
+    Inputs:
+        css_path (str): The absolute or relative file path to the target .css file.
+        
+    Outputs:
+        dict: A nested dictionary where keys are CSS selectors (e.g., 'h1', 'p') 
+              and values are dictionaries of property-value pairs (e.g., {'color': '#000', 'font-size': '12pt'}).
+              Returns an empty dictionary {} if parsing fails.
     """
     try:
         return css2json.parse_css_file(css_path)
@@ -17,10 +30,26 @@ def style_parser(css_path):
         print(f"Warning: Could not parse CSS ({e})")
         return {}
 
-def markdown_parser(md_text):
+def markdown_parser(md_text: str) -> list:
     """
-    Parses Markdown text into a list of structured blocks.
-    Supported blocks: heading, paragraph, list, table, math
+    Parses raw Markdown text into a structured list of block tuples.
+    
+    Why it is needed:
+    Because python-docx generates documents block-by-block (paragraphs, tables, headings), 
+    we need to break down the raw string of Markdown text into distinct, classified chunks 
+    that our DOCX writer can loop through and translate into native Word elements.
+    
+    Inputs:
+        md_text (str): The complete raw Markdown text string.
+        
+    Outputs:
+        list: A list of tuples where each tuple represents a block element.
+              Examples: 
+              - ('heading', 2, 'Title Text')
+              - ('paragraph', 'Some plain text')
+              - ('list', 'List item text', 'ordered')
+              - ('math', 'x = 2')
+              - ('table', ['|Header|', '|---|', '|Data|'])
     """
     blocks = []
     lines = md_text.split('\n')
@@ -355,6 +384,19 @@ def _process_inline(paragraph, text, styles, tag):
 def docx_writer(blocks: list, styles: dict, output_file: str):
     """
     Translates parsed markdown blocks into a Word document and applies CSS styling.
+    
+    Why it is needed:
+    This is the core generation engine. It takes the abstract syntax structure generated 
+    by `markdown_parser()` and the style rules from `style_parser()`, loops through them, 
+    and issues the corresponding `python-docx` commands to physically build the `.docx` file.
+    
+    Inputs:
+        blocks (list): The list of parsed Markdown block tuples (from `markdown_parser`).
+        styles (dict): The nested dictionary of CSS rules (from `style_parser`).
+        output_file (str): The absolute or relative file path where the resulting .docx should be saved.
+        
+    Outputs:
+        None: This function does not return a value, but it writes a binary .docx file to disk.
     """
     doc = Document()
     

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/pyact_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyact-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: A CLI tool to compile .pamd files to Markdown.
 Home-page: https://github.com/Abstergo2003/PyAct
 Author: Abstergo2003
@@ -10,11 +10,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Requires-Dist: python-docx
+Requires-Dist: ezdxf
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
@@ -65,10 +68,17 @@ You can also include other pamd files as templates!
 <tmp>path/to/another_file</tmp>
 ```
 
-### 3. Compile!
+### 3. Compile to Markdown
 Run the compiler from your terminal to generate your final Markdown document:
 ```bash
 pyact path/to/your_file.pamd -o output.md
 ```
 
-That's it! You now have a standard Markdown file ready to be shared, published, or converted to PDF.
+### 4. Compile to Word (DOCX)
+You can also compile straight to a native Microsoft Word Document, complete with CSS styling! 
+```bash
+pyact path/to/your_file.pamd -o output.md --docx output.docx
+```
+*Note: If you have a `style.css` file in the same directory, PyAct will automatically load it to style your Word Document. You can also specify one manually using the `--css path/to/style.css` flag!*
+
+That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/pyact_cli.egg-info/SOURCES.txt

@@ -1,14 +1,18 @@
 README.md
 setup.py
 pamd_helpers/__init__.py
+pamd_helpers/conversions.py
+pamd_helpers/unit.py
 pyact/__init__.py
 pyact/cli.py
 pyact/core.py
 pyact/css2json.py
+pyact/linter.py
 pyact/mdTOword.py
 pyact/py2tex.py
 pyact_cli.egg-info/PKG-INFO
 pyact_cli.egg-info/SOURCES.txt
 pyact_cli.egg-info/dependency_links.txt
 pyact_cli.egg-info/entry_points.txt
+pyact_cli.egg-info/requires.txt
 pyact_cli.egg-info/top_level.txt

pyact_cli-0.6.0/pyact_cli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+python-docx
+ezdxf

{pyact_cli-0.4.0 → pyact_cli-0.6.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="pyact-cli",
-    version="0.4.0",
+    version="0.6.0",
     author="Abstergo2003",
     author_email="",
     description="A CLI tool to compile .pamd files to Markdown.",
@@ -19,6 +19,10 @@ setup(
         "Operating System :: OS Independent",
     ],
     python_requires=">=3.8",
+    install_requires=[
+        "python-docx",
+        "ezdxf"
+    ],
     entry_points={
         "console_scripts": [
             "pyact=pyact.cli:main",

pyact_cli-0.4.0/pamd_helpers/__init__.py

@@ -1,76 +0,0 @@
-import inspect
-from pyact.py2tex import py2tex
-
-def equation(func: function, values: list) -> str:
-    source = inspect.getsource(func)
-    value = func(*values)
-    name, sep, tail = source.rpartition("=")
-    head, sep, equ = tail.rpartition(":")
-    return f"$$ {name} = {py2tex(equ.replace("\n", ""))} = {value} $$"
-
-
-def image(link: str, caption: str) -> str:
-    image_link = f"![{caption}]({link})"
-    caption = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
-    return f"{image_link} \n {caption}"
-
-def table(headers: list, values: list, caption: str, add_no: bool = False, starting_number: int = 1) -> str:
-    if add_no:
-        headers_string = f"|No.|"
-        breaker_line = "|---|"
-    else:
-        headers_string = f"|"
-        breaker_line = "|"
-
-
-    for i in headers:
-        headers_string += f"{i}|"
-        breaker_line += "-"*len(i)+"|"
-
-    table_content = ""
-
-    for i, row in enumerate(values):
-        if add_no:
-            table_content += f"|{i+starting_number}|"
-        else:
-            table_content += "|"
-
-        for value in row:
-            table_content += f"{value}|"
-        table_content += "\n"
-
-    caption = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
-    return f"{caption} \n {headers_string}\n{breaker_line}\n{table_content}"
-
-
-def hyperlink(caption: str, link: str) -> str:
-    return f"[{caption}]({link})"
-
-def unordered_list(items: list) -> str:
-    list_string = ""
-    for i in items:
-        list_string += f"* {i}\n"
-    return list_string
-
-def ordered_list(items: list) -> str:
-    list_string = ""
-    for i, item in enumerate(items):
-        list_string += f"{i+1}. {item}\n"
-    return list_string
-
-def checklist(items: list) -> str:
-    list_string = ""
-    for i in items:
-        list_string += f"- [ ] {i}\n"
-    return list_string
-
-class Footnote:
-    def __init__(self, number, text):
-        self.number = number
-        self.text = text
-
-    def define_string(self) -> str:
-        return f"[^{self.number}]: {self.text}"
-
-    def adnotation(self) -> str:
-        return f"[^{self.number}]\n"

pyact_cli-0.4.0/pyact/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.4.0"

pyact_cli-0.4.0/pyact/cli.py

@@ -1,57 +0,0 @@
-import argparse
-import sys
-import os
-from .core import map_content, process_content
-
-def main():
-    parser = argparse.ArgumentParser(description="PyAct CLI - PAMD to Markdown compiler")
-    parser.add_argument("input", help="Path to the main .pamd file")
-    parser.add_argument("-o", "--output", help="Output file path (default prints to stdout)")
-    parser.add_argument("--docx", help="Also generate a DOCX file at this path")
-    parser.add_argument("--css", help="Optional CSS file path to style the DOCX")
-    
-    args = parser.parse_args()
-    
-    input_path = os.path.abspath(args.input)
-    directory = os.path.dirname(input_path)
-    filename = os.path.basename(input_path)
-    
-    if filename.endswith(".pamd"):
-        filename = filename[:-5]
-        
-    try:
-        build_tree = map_content(filename, directory)
-        content = process_content(build_tree)
-        
-        if args.output:
-            with open(args.output, "w", encoding="utf-8") as f:
-                f.write(content)
-            print(f"Successfully compiled to {args.output}")
-        else:
-            print(content)
-            
-        if args.docx:
-            from .mdTOword import style_parser, markdown_parser, docx_writer
-            styles = {}
-            if args.css:
-                styles = style_parser(args.css)
-            else:
-                # Try to look for style.css in the active directory
-                local_css = os.path.join(directory, "style.css")
-                if os.path.exists(local_css):
-                    styles = style_parser(local_css)
-                else:
-                    # Fallback to the default one packaged in pyact
-                    default_css = os.path.join(os.path.dirname(__file__), "style.css")
-                    styles = style_parser(default_css)
-                    
-            blocks = markdown_parser(content)
-            docx_writer(blocks, styles, args.docx)
-            print(f"Successfully compiled DOCX to {args.docx}")
-            
-    except Exception as e:
-        print(f"Error: {e}", file=sys.stderr)
-        sys.exit(1)
-
-if __name__ == "__main__":
-    main()

pyact_cli-0.4.0/pyact/core.py

@@ -1,103 +0,0 @@
-import re
-import json
-
-def get_directory(path: str) -> list:
-    # Splits path into: ('./main', '/', 'retro.pamd')
-    head, sep, tail = path.rpartition('/')
-    # Recombine the first part and the slash
-    return [head + sep, tail]
-
-def read_pamd_cells(file_path: str):
-    with open(file_path, 'r', encoding='utf-8') as f:
-        data = json.load(f)
-    
-    code_content = ""
-    markdown_content = ""
-    
-    for cell in data.get("cells", []):
-        cell_type = cell.get("cell_type", "")
-        source = cell.get("source", "")
-        if isinstance(source, list):
-            source = "".join(source)
-            
-        if cell_type == "code":
-            code_content += source + "\n"
-        elif cell_type == "markdown":
-            markdown_content += source + "\n"
-            
-    return code_content, markdown_content
-
-def get_imports(file: str, code_text: str):
-    file_namespace = {"__file__": f"{file}.pamd"}
-    if not code_text.strip():
-        raise ValueError(f"The file {file}.pamd needs a 'context()' function but has no code cell.")
-        
-    try:
-        exec(code_text, file_namespace)
-    except Exception as e:
-        raise RuntimeError(f"Error executing code in {file}.pamd: {e}")
-
-    if "context" not in file_namespace:
-        raise ValueError(f"The file {file}.pamd is missing the required 'context()' function.")
-
-    context_func = file_namespace["context"]
-
-    if not callable(context_func):
-        raise TypeError(f"In {file}.pamd, 'context' was found but it is not a function!")
-
-    result_dict = context_func()
-
-    if not isinstance(result_dict, dict):
-        raise TypeError(f"The 'context()' function in {file}.pamd must return a dictionary.")
-
-    return result_dict
-
-def find_imports(text: str):
-    # <ctx></ctx>
-    pattern = r"<ctx>(.*?)</ctx>"
-    return re.findall(pattern, text)
-
-
-def find_templates(text: str):
-    # <tmp></tmp>
-    pattern = r"<tmp>(.*?)</tmp>"
-    return re.findall(pattern, text)
-
-def map_content(file: str, path: str):
-    if path and not path.endswith('/'):
-        full_path = f"{path}/{file}"
-    elif path.endswith('/'):
-        full_path = f"{path}{file}"
-    else:
-        full_path = file
-        
-    code_text, main_file = read_pamd_cells(f"{full_path}.pamd")
-    templates = find_templates(main_file)
-    imports = find_imports(main_file)
-    meta = get_directory(full_path)
-    
-    ready_t = []
-    for i in templates:
-        ready_t.append(map_content(i, meta[0]))
-
-    return {
-        "tag_name": file,
-        "name": meta[1],
-        "path": meta[0],
-        "imports": imports,
-        "templates": ready_t
-    }
-
-def process_content(build_tree: dict):
-    file_path_base = build_tree.get("path", "") + build_tree.get("name", "")
-    code_text, file_text = read_pamd_cells(file_path_base + ".pamd")
-    
-    needed_imports = build_tree.get("imports", [])
-    if needed_imports:
-        imports = get_imports(file_path_base, code_text)
-        for i in needed_imports:
-            file_text = file_text.replace(f"<ctx>{i}</ctx>", str(imports.get(i, '')))
-
-    for i in build_tree.get("templates", []):
-        file_text = file_text.replace(f"<tmp>{i.get('tag_name')}</tmp>", process_content(i))
-    return file_text