Added MD command; fixed module declarations

Author: ThunderStruct

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+
+## [0.1.3] - 2025-02-18
+
+### Added
+- New `$analyze-only` command to handle global imports without creating unnecessary files/folders
+- Improved handling of module declarations within package contexts
+
+### Fixed
+- Fixed issue with imports cell creating unwanted `.py` files
+- Fixed module declaration within package contexts to properly create modules inside their parent packages
+
+## 0.1.2 (2024-09-15)
+
+_Initial version_
+
 <!-- ## 0.1.1 (2024-09-15)
 [Compare the full difference.](https://github.com/ThunderStruct/nbrefactor/compare/0.1.1...0.1.0)
 

TODO.md

@@ -27,6 +27,8 @@
 
 ## Patches
 
+- [x] 🔴 Fixed module declaration within package contexts to properly create modules inside their parent packages rather than as standalone files.
+
 - [ ] 🟠 Add a "before and after" example to the docs
 
 - [ ] 🟢 Restructure the docs' `index.rst` to have a more informative homepage than just the toctree. Also add the version number (already declared in [conf.py](docs/source/conf.py) and accessible through `|version|` in RST).

docs/source/markdown_commands.rst

@@ -46,6 +46,9 @@ The following table lists all the possible Markdown commands and their functions
    ``$ignore-cell``                             Ignores the next code cell regardless of type.
    ``$ignore-markdown``                         Ignores the current Markdown cell (e.g., when used for 
                                                 instructions only).
+   ``$analyze-only``                           Prevents the current markdown cell from creating a module/package
+                                                but still analyzes any following code for dependencies.
+                                                Useful for global imports.
    ``$package=<name>``                          Renames the current package and asserts the node type as 
                                                 'package'.
    ``$module=<name>``                           Renames the current module and asserts the node type as 

src/nbrefactor/datastructs/markdown_element.py

@@ -27,6 +27,9 @@ class MarkdownCommandType(Enum):
     IGNORE_MARKDOWN     = 'ignore-markdown'     # ignores the current Markdown 
                                                 # cell (e.g. when MD is used 
                                                 # for instructions only)
+    ANALYZE_ONLY        = 'analyze-only'        # analyzes the next code cell for
+                                                # dependencies but does not create
+                                                # a file for it
 
     # Node-Manipulation Commands
     RENAME_PACKAGE      = 'package'             # sets the package name 

src/nbrefactor/datastructs/module_node.py

@@ -25,6 +25,7 @@ def __init__(self, name, parent=None, depth=0, node_type=None):
                                             # under this node
         self.ignore_next_cell = False       # ignores the next parsed cell 
                                             # (handled intrinsically)
+        self.analyze_only = False           # analyze but don't create a file
 
 
     def add_child(self, child_node):
@@ -46,6 +47,9 @@ def has_code_cells(self):
         Checks if the node has non-empty code cells (we only write \
             modules/.py files if this is true)
         """
+        # Don't count this node as having code cells if it's analyze_only
+        if self.analyze_only:
+            return False
         return any([True for cell in self.parsed_cells \
                     if isinstance(cell, ParsedCodeCell) \
                         and len(cell.parsed_source.strip())])

src/nbrefactor/processor/processor.py

@@ -76,8 +76,18 @@ def process_notebook(notebook_path, output_path,
                 # command is present
                 continue
 
+            # Check for analyze-only command before processing headers
+            analyze_only = any([True for e in parsed_md.elements \
+                    if isinstance(e, MarkdownCommand) \
+                        and e.type == MarkdownCommandType.ANALYZE_ONLY])
+
             for md_element in parsed_md.elements:
                 if isinstance(md_element, MarkdownHeader):
+                    # Skip header processing; we're only analyzing the cell
+                    # i.e. do not create a file/folder for it
+                    if analyze_only:
+                        continue
+
                     # handle MarkdownHeader
                     header = md_element
                     header_name = __sanitize_node_name(header.name)
@@ -230,6 +240,10 @@ def __handle_markdown_command(command, current_node, node_stack):
         # this is handled externally to avoid the processing cost
         pass
 
+    elif command.type == MarkdownCommandType.ANALYZE_ONLY:
+        # Mark the current node to be analyzed but not written to a file
+        current_node.analyze_only = True
+
     # NODE-MANIPULATION COMMANDS
     elif command.type == MarkdownCommandType.RENAME_PACKAGE:
         # override the current node's name + assert package type
@@ -260,20 +274,57 @@ def __handle_markdown_command(command, current_node, node_stack):
         # create a new node and assert its node type to module
         node_name = __sanitize_node_name(command.value)
 
-        new_node_parent = current_node
-
-        # default to sibling-level if we're not at root level
-        if current_node.parent is not None:    
-            node_stack.pop()
-            new_node_parent = current_node.parent
-
-        new_node = ModuleNode(node_name, new_node_parent, 
-                              depth=new_node_parent.depth + 1)
-        
-        new_node.node_type = 'module'
-        new_node_parent.add_child(new_node)
-
-        node_stack.append(new_node)
+        # If we're in a package context, the module should be created inside that package
+        if current_node.node_type == 'package':
+            # Create module inside the current package
+            new_node = ModuleNode(node_name, current_node, 
+                              depth=current_node.depth + 1)
+            new_node.node_type = 'module'
+            current_node.add_child(new_node)
+            node_stack.append(new_node)
+        else:
+            # Check if this should be a package structure (contains . or /)
+            if '.' in node_name or '/' in node_name:
+                # Split into package/module parts
+                parts = node_name.replace('/', '.').split('.')
+                module_name = parts[-1]
+                package_parts = parts[:-1]
+                
+                # Start from current node's parent if we're not at root
+                new_node_parent = current_node
+                if current_node.parent is not None:
+                    node_stack.pop()
+                    new_node_parent = current_node.parent
+                
+                # Create package structure
+                for package_part in package_parts:
+                    package_node = ModuleNode(package_part, new_node_parent,
+                                          depth=new_node_parent.depth + 1)
+                    package_node.node_type = 'package'
+                    new_node_parent.add_child(package_node)
+                    new_node_parent = package_node
+                    node_stack.append(package_node)
+                
+                # Create the actual module at the leaf
+                new_node = ModuleNode(module_name, new_node_parent,
+                                  depth=new_node_parent.depth + 1)
+                new_node.node_type = 'module'
+                new_node_parent.add_child(new_node)
+                node_stack.append(new_node)
+            else:
+                new_node_parent = current_node
+
+                # default to sibling-level if we're not at root level
+                if current_node.parent is not None:    
+                    node_stack.pop()
+                    new_node_parent = current_node.parent
+
+                new_node = ModuleNode(node_name, new_node_parent, 
+                                  depth=new_node_parent.depth + 1)
+                
+                new_node.node_type = 'module'
+                new_node_parent.add_child(new_node)
+                node_stack.append(new_node)
 
     elif command.type == MarkdownCommandType.DECLARE_NODE:
         # create a new generic node (type will be automatically inferred)