pyact-cli 0.7.3__tar.gz → 0.9.0__tar.gz

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyact-cli
-Version: 0.7.3
+Version: 0.9.0
 Summary: A CLI tool to compile .pamd files to Markdown.
 Home-page: https://github.com/Abstergo2003/PyAct
 Author: Abstergo2003
@@ -86,11 +86,37 @@ Run the compiler from your terminal to generate your final Markdown document:
 pyact path/to/your_file.pamd -o output.md
 ```
 
-### 4. Compile to Word (DOCX)
+### 5. 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!*
 
+### 6. Configure Word Export via `pamd.conf`
+Control document metadata, running headers, and footers with a `pamd.conf` file:
+
+```ini
+[Header]
+left = My Project
+right = 2026
+
+[Footer]
+left = Confidential
+center = Page {page} of {pages}
+
+[Metadata]
+author = Jane Doe
+title = Monthly Report
+```
+
+PyAct will automatically detect `pamd.conf` in your directory, inject dynamic page numbers (`{page}` / `{pages}`), configure tab stops, and populate document metadata!
+
+### 7. Scaffolding New Projects with `pyact init`
+Quickly spin up a new project ready to compile:
+```bash
+pyact init my_project --template engineering
+```
+Templates: `default`, `engineering`, `academic`.
+
 That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/README.md

@@ -63,11 +63,37 @@ Run the compiler from your terminal to generate your final Markdown document:
 pyact path/to/your_file.pamd -o output.md
 ```
 
-### 4. Compile to Word (DOCX)
+### 5. 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!*
 
+### 6. Configure Word Export via `pamd.conf`
+Control document metadata, running headers, and footers with a `pamd.conf` file:
+
+```ini
+[Header]
+left = My Project
+right = 2026
+
+[Footer]
+left = Confidential
+center = Page {page} of {pages}
+
+[Metadata]
+author = Jane Doe
+title = Monthly Report
+```
+
+PyAct will automatically detect `pamd.conf` in your directory, inject dynamic page numbers (`{page}` / `{pages}`), configure tab stops, and populate document metadata!
+
+### 7. Scaffolding New Projects with `pyact init`
+Quickly spin up a new project ready to compile:
+```bash
+pyact init my_project --template engineering
+```
+Templates: `default`, `engineering`, `academic`.
+
 That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/pamd_helpers/__init__.py

@@ -52,6 +52,75 @@ def image(link: str, caption: str) -> str:
     caption_html = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
     return f"{image_link} \n {caption_html}"
 
+def plot(fig_or_plt: Any, caption: str = "", filename: str = None, dpi: int = 300, output_dir: str = "images") -> str:
+    """
+    Saves a Matplotlib/Seaborn figure or pyplot module to an image file and returns a styled Markdown image string.
+    
+    Why it is needed:
+    Allows data analysts and engineers to generate plots directly in Python code cells and 
+    seamlessly embed them into both Markdown and Word (DOCX) documents without manual file saving.
+    
+    Inputs:
+        fig_or_plt: A matplotlib Figure object or the matplotlib.pyplot module.
+        caption (str): Caption text to display below the plot.
+        filename (str): Optional file name (e.g. 'beam_deflection.png'). If omitted, a name is automatically generated.
+        dpi (int): Resolution of the exported image (default 300 dpi for sharp printing).
+        output_dir (str): Directory where the image should be saved (default 'images').
+        
+    Outputs:
+        str: A Markdown image tag with an italicized caption span, ready for injection into the document.
+    """
+    import os
+    import time
+    
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+        
+    if not filename:
+        if caption:
+            import re
+            clean_name = re.sub(r'[^a-zA-Z0-9_-]', '_', caption.strip().lower())[:30].strip('_')
+            filename = f"{clean_name}.png" if clean_name else f"plot_{int(time.time()*1000)}.png"
+        else:
+            filename = f"plot_{int(time.time()*1000)}.png"
+            
+    if not filename.endswith(('.png', '.jpg', '.jpeg', '.svg')):
+        filename += '.png'
+        
+    filepath = os.path.join(output_dir, filename)
+    norm_path = filepath.replace('\\', '/')
+    
+    if hasattr(fig_or_plt, 'savefig'):
+        fig_or_plt.savefig(filepath, dpi=dpi, bbox_inches='tight')
+    elif hasattr(fig_or_plt, 'figure') and hasattr(fig_or_plt.figure, 'savefig'):
+        fig_or_plt.figure.savefig(filepath, dpi=dpi, bbox_inches='tight')
+    elif hasattr(fig_or_plt, 'save'):
+        fig_or_plt.save(filepath)
+    else:
+        raise TypeError(f"Expected a matplotlib Figure or image object with a 'savefig' or 'save' method, got {type(fig_or_plt)}")
+        
+    return image(norm_path, caption)
+
+def callout(text: str, callout_type: str = "note", title: str = None) -> str:
+    """
+    Generates a GitHub-flavored Markdown alert/callout box.
+    
+    Inputs:
+        text (str): The body text of the alert.
+        callout_type (str): 'note', 'tip', 'important', 'warning', or 'caution'.
+        title (str): Optional title overriding the default alert header.
+        
+    Outputs:
+        str: A blockquote formatted alert.
+    """
+    c_type = callout_type.upper()
+    lines = text.strip().split('\n')
+    header = f"> [!{c_type}]"
+    if title:
+        header += f" {title}"
+    body = "\n".join(f"> {line}" for line in lines)
+    return f"{header}\n{body}\n"
+
 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.

pyact_cli-0.9.0/pyact/__init__.py

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

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/pyact/cli.py

@@ -2,7 +2,7 @@ import argparse
 import sys
 import os
 import time
-from .core import map_content, process_content, build_logs
+from .core import map_content, process_content, build_logs, generate_markdown_toc
 
 def is_cache_valid(build_tree, cache_mtime, root_dir=None):
     if root_dir is not None:
@@ -38,11 +38,22 @@ def main():
         Writes the generated `.md` and `.docx` files to the filesystem and prints 
         status messages to stdout/stderr.
     """
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        init_parser = argparse.ArgumentParser(description="PyAct Project Initializer")
+        init_parser.add_argument("command", choices=["init"])
+        init_parser.add_argument("name", nargs="?", default=".", help="Project folder name (default: current directory)")
+        init_parser.add_argument("--template", choices=["default", "engineering", "academic"], default="default", help="Project template to scaffold")
+        init_args = init_parser.parse_args()
+        from .scaffold import init_project
+        init_project(init_args.name, init_args.template)
+        return
+
     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("--conf", help="Optional path to pamd.conf configuration file")
     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()
@@ -100,13 +111,14 @@ def main():
                     f.write(f"- {log['file']}: {log['time_ms']:.2f} ms\n")
                 f.write(f"\nTotal Build Time: {total_ms:.2f} ms\n")
         
+        md_output = generate_markdown_toc(content)
         if args.output:
             with open(args.output, "w", encoding="utf-8") as f:
-                f.write(content)
+                f.write(md_output)
             print(f"Successfully compiled to {args.output}")
         else:
             if not args.docx:
-                print(content)
+                print(md_output)
             
         if args.docx:
             from .mdTOword import style_parser, markdown_parser, docx_writer
@@ -123,8 +135,25 @@ def main():
                     default_css = os.path.join(os.path.dirname(__file__), "style.css")
                     styles = style_parser(default_css)
                     
+            # Load pamd.conf configuration
+            conf = {}
+            conf_path = None
+            if args.conf:
+                conf_path = os.path.abspath(args.conf)
+            else:
+                local_conf = os.path.join(directory, "pamd.conf")
+                cwd_conf = os.path.join(os.getcwd(), "pamd.conf")
+                if os.path.exists(local_conf):
+                    conf_path = local_conf
+                elif os.path.exists(cwd_conf):
+                    conf_path = cwd_conf
+
+            if conf_path and os.path.exists(conf_path):
+                from .conf_parser import conf_parser
+                conf = conf_parser(conf_path)
+                    
             blocks = markdown_parser(content)
-            docx_writer(blocks, styles, args.docx)
+            docx_writer(blocks, styles, args.docx, config=conf)
             print(f"Successfully compiled DOCX to {args.docx}")
             
     except Exception as e:

pyact_cli-0.9.0/pyact/conf_parser.py

@@ -0,0 +1,44 @@
+import os
+
+def conf_parser(conf_path: str) -> dict:
+    """
+    Parses a pamd.conf configuration file into a dictionary of sections and settings.
+    
+    Why it is needed:
+    Allows PyAct projects to define global Word export settings such as Headers, Footers, 
+    Page margins/orientations, and document Metadata without cluttering Markdown templates 
+    or Python code cells.
+    
+    Inputs:
+        conf_path (str): Path to the pamd.conf file.
+        
+    Outputs:
+        dict: A nested dictionary of sections and their key-value options.
+              Example: {'Header': {'left': 'PyAct'}, 'Metadata': {'author': 'Radek'}}
+    """
+    if not conf_path or not os.path.exists(conf_path):
+        return {}
+        
+    parsed_dict = {}
+    current_header = "General"
+    
+    with open(conf_path, 'r', encoding='utf-8') as f:
+        for line in f:
+            stripped = line.strip()
+            # Skip empty lines and comment lines starting with # or ;
+            if not stripped or stripped.startswith(('#', ';')):
+                continue
+                
+            if stripped.startswith('[') and stripped.endswith(']'):
+                current_header = stripped[1:-1].strip()
+                if current_header not in parsed_dict:
+                    parsed_dict[current_header] = {}
+            elif '=' in stripped:
+                head, tail = stripped.split('=', 1)
+                key = head.strip()
+                val = tail.strip()
+                if current_header not in parsed_dict:
+                    parsed_dict[current_header] = {}
+                parsed_dict[current_header][key] = val
+                
+    return parsed_dict

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/pyact/core.py

@@ -257,4 +257,83 @@ def process_content(build_tree: dict, globals_dict: dict = None):
         "time_ms": elapsed_ms
     })
         
-    return file_text
+    return file_text
+
+def make_github_slug(heading: str) -> str:
+    """Creates a GitHub-compatible anchor slug from heading text."""
+    clean = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', heading)
+    clean = re.sub(r'[*_`]', '', clean)
+    clean = clean.lower().strip()
+    clean = re.sub(r'[^\w\s-]', '', clean, flags=re.UNICODE)
+    clean = re.sub(r'\s', '-', clean)
+    return clean
+
+def generate_markdown_toc(text: str) -> str:
+    """
+    Replaces `<toc/>`, `<toc>`, `[toc]`, or `<toc title="..."/>` with a GitHub-compatible
+    Markdown Table of Contents.
+    """
+    toc_pattern = r'<(?:toc|TOC)(?:\s+title=["\'](.*?)["\'])?\s*/?>|\[toc\]|\[TOC\]'
+    m = re.search(toc_pattern, text)
+    if not m:
+        return text
+        
+    toc_pos = m.start()
+    title_override = m.group(1)
+    
+    # Scan headings after the TOC tag
+    text_after = text[toc_pos:]
+    lines = text_after.split('\n')
+    
+    in_code = False
+    headings = []
+    for line in lines:
+        ls = line.strip()
+        if ls.startswith('```'):
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+        h_match = re.match(r'^(#{1,6})\s+(.*)$', ls)
+        if h_match:
+            level = len(h_match.group(1))
+            h_text = h_match.group(2).strip()
+            headings.append((level, h_text))
+            
+    if not headings:
+        # Fallback to scanning whole document if no headings were found after TOC tag
+        lines = text.split('\n')
+        in_code = False
+        for line in lines:
+            ls = line.strip()
+            if ls.startswith('```'):
+                in_code = not in_code
+                continue
+            if in_code:
+                continue
+            h_match = re.match(r'^(#{1,6})\s+(.*)$', ls)
+            if h_match:
+                level = len(h_match.group(1))
+                h_text = h_match.group(2).strip()
+                headings.append((level, h_text))
+                
+    if not headings:
+        return re.sub(toc_pattern, '', text, count=1)
+        
+    base_level = min(h[0] for h in headings)
+    toc_lines = []
+    for level, h_text in headings:
+        indent = "  " * (level - base_level)
+        clean_title = re.sub(r'[*_`]', '', h_text).strip()
+        slug = make_github_slug(h_text)
+        toc_lines.append(f"{indent}- [{clean_title}](#{slug})")
+        
+    toc_header = ""
+    if title_override:
+        if title_override.lower() not in ('none', 'false', 'no'):
+            toc_header = f"## {title_override}\n"
+    else:
+        toc_header = "## Table of Contents\n"
+        
+    full_toc = toc_header + "\n".join(toc_lines) + "\n"
+    return re.sub(toc_pattern, lambda _: full_toc, text, count=1)

{pyact_cli-0.7.3 → pyact_cli-0.9.0}/pyact/css2json.py

@@ -36,7 +36,8 @@ def css_to_dict(css_string: str) -> dict:
                 continue
             if ':' in line:
                 key, val = line.split(':', 1)
-                rules[key.strip()] = val.strip()
+                val_clean = re.sub(r'\s*!important\s*$', '', val.strip(), flags=re.IGNORECASE).strip()
+                rules[key.strip()] = val_clean
         
         # Handle comma-separated selectors (e.g., 'h1, h2, h3')
         for sel in selector.split(','):