pythoncharmers-meta 0.7.3__tar.gz → 0.7.4__tar.gz

{pythoncharmers_meta-0.7.3 → pythoncharmers_meta-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythoncharmers-meta
-Version: 0.7.3
+Version: 0.7.4
 Summary: Meta package with dependencies for Python Charmers training courses
 License-File: LICENSE
 Requires-Python: >=3.10

{pythoncharmers_meta-0.7.3 → pythoncharmers_meta-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythoncharmers-meta"
-version = "0.7.3"
+version = "0.7.4"
 description = "Meta package with dependencies for Python Charmers training courses"
 readme = "README.md"
 requires-python = ">=3.10"

pythoncharmers_meta-0.7.4/src/pythoncharmers_meta/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(rm:*)",
+      "Bash(git add:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)",
+      "Bash(cd:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

pythoncharmers_meta-0.7.4/src/pythoncharmers_meta/MD_MAGIC.md

@@ -0,0 +1,182 @@
+# Markdown Cell Magic Implementation Design
+
+## Problem Statement
+
+Training participants need a way to copy Markdown cells from trainer notebooks during live sessions. Unlike code cells which have visible execution counts, Markdown cells lack visible identifiers, making them difficult to reference.
+
+## Design Considerations
+
+### Current Magic Commands
+- %code (formerly %nb): Handles code cells (identified by execution_count)
+- %md: Handles markdown cells by sequential index
+- %mdat: Handles markdown cells by position relative to code cells
+- %nb: Kept as alias for %code for backward compatibility
+
+### Challenges with Markdown Cells
+1. **No visible numbering**: Markdown cells don't have execution counts
+2. **Cell IDs not user-friendly**: Internal IDs exist but aren't visible in the UI
+3. **Mixed cell types**: Notebooks interleave code and Markdown cells
+4. **Cell type conversion**: Content retrieved needs manual conversion from Code to Markdown
+
+## Proposed Solutions
+
+### Solution 1: Between Code Cells (Fence Method)
+**Syntax**: `%md 1 2` - Get all Markdown cells between code cells 1 and 2
+
+**Pros**:
+- Uses existing visible code cell numbers
+- Intuitive for contiguous Markdown sections
+
+**Cons**:
+- Ambiguous for non-contiguous selections
+- Doesn't work for Markdown at notebook start/end
+- May return multiple cells when only one is needed
+
+### Solution 2: Position-Based Reference
+**Syntax**: `%md after:3` or `%md before:5` - Get Markdown cell(s) after/before code cell
+
+**Pros**:
+- Precise single-cell selection
+- Clear intent
+- Works at notebook boundaries
+
+**Cons**:
+- Requires multiple commands for multiple cells
+- User needs to know exact positions
+
+### Solution 3: Content Pattern Matching
+**Syntax**: `%md "# Section Title"` - Find Markdown cells containing pattern
+
+**Pros**:
+- Natural for users who can see content
+- Works without knowing cell positions
+- Can use distinctive headers/keywords
+
+**Cons**:
+- Pattern might not be unique
+- Requires exact string matching or regex
+
+### Solution 4: Hybrid Cell Magic (Recommended)
+**Syntax**: `%%md 3` - Cell magic that fetches Markdown after code cell 3
+
+**Pros**:
+- Automatically converts cell type to Markdown
+- No manual cleanup needed
+- Clear one-to-one mapping
+- Can extend to support ranges
+
+**Cons**:
+- Different from line magic pattern
+- Requires cell magic implementation
+
+### Solution 5: Smart Sequential Indexing (Recommended Alternative)
+**Syntax**: `%md 3` or `%md 3-5` - Use sequential index for all Markdown cells
+
+**Implementation**: 
+- Build index of all Markdown cells in order
+- Reference by position (1st, 2nd, 3rd Markdown cell)
+- Optional: `%md --list` to show available Markdown cells with previews
+
+**Pros**:
+- Simple, consistent interface
+- Works like %nb for code cells
+- No ambiguity
+- Can show preview list
+
+**Cons**:
+- Users need to count Markdown cells
+- Numbers change if trainer adds cells
+
+## Recommended Implementation
+
+Implement **two complementary approaches**:
+
+### 1. Primary: Sequential Markdown Index (`%md`)
+```python
+%md 1        # Get 1st Markdown cell
+%md 3-5      # Get 3rd through 5th Markdown cells
+%md --list   # List all Markdown cells with previews
+```
+
+### 2. Secondary: Position-Based Reference (`%mdat`)
+```python
+%mdat after:3   # Markdown cell(s) after code cell 3
+%mdat before:5  # Markdown cell(s) before code cell 5
+%mdat between:3:5  # All Markdown between code cells 3 and 5
+```
+
+## Implementation Details
+
+### Cell Type Handling
+- Unlike %nb, the %md and %mdat magics do NOT add a comment header
+- Content is inserted directly without any prefix
+- Users manually convert cell type (Ctrl+M, M in Jupyter)
+- Future: Investigate IPython API for automatic cell type conversion
+
+### Preview Feature
+```python
+%md --list
+# Output:
+# 1: # Introduction
+#    This notebook covers...
+# 2: ## Data Loading
+#    We'll use pandas to...
+# 3: ### Important Notes
+#    Remember to check...
+```
+
+### Error Handling
+- Clear messages for invalid ranges
+- Warnings when no Markdown cells found
+- Handle notebooks without code cells gracefully
+
+## Alternative Approaches Considered
+
+### Invisible Anchors
+Add hidden HTML comments as anchors in Markdown cells:
+```markdown
+<!-- md-anchor: section1 -->
+# Introduction
+```
+**Rejected**: Requires modifying trainer notebooks
+
+### Visual Cell Numbers
+Propose Jupyter enhancement to show Markdown cell numbers in UI.
+**Rejected**: Outside our control, long-term solution
+
+### Dual Output
+Return both code and Markdown versions, let user choose.
+**Rejected**: Clutters interface, still requires manual work
+
+## Migration Path
+
+1. Rename `%nb` to `%code` as the canonical command for code cells
+2. Keep `%nb` as an alias for backward compatibility
+3. Add `%md` for Markdown cells by index
+4. Add `%mdat` for position-based Markdown cell retrieval
+5. Document all commands in help text
+
+## Usage Examples
+
+### Trainer notebook structure:
+```
+[Code 1] Import statements
+[Markdown] # Data Analysis Workshop
+[Markdown] ## Prerequisites  
+[Code 2] Load data
+[Markdown] ### Understanding the dataset
+[Code 3] Explore data
+```
+
+### Participant commands:
+```python
+%code 1        # Get code cell 1 (preferred)
+%nb 1          # Same as %code 1 (backward compatibility)
+%md 1          # Get "# Data Analysis Workshop"
+%md 2-3        # Get "## Prerequisites" and "### Understanding the dataset"
+%mdat after:1  # Get markdown after code cell 1
+```
+
+## Conclusion
+
+The recommended approach balances usability with implementation simplicity. The sequential index method (`%md`) provides a familiar interface similar to `%nb`, while the position-based method (`%mdat`) offers precision when needed. Together, they cover all common use cases without requiring notebook modifications or complex UI changes.

{pythoncharmers_meta-0.7.3 → pythoncharmers_meta-0.7.4}/src/pythoncharmers_meta/__init__.py

@@ -10,23 +10,26 @@ You can load the IPython extension like so:
 assuming the pythoncharmers_meta packages has been installed system-wide.
 
 This package depends on packages used in Python Charmers training courses. It
-also provides an IPython extension that enables three new magic commands:
+also provides an IPython extension that enables several magic commands:
 
-- %nb
-- %ai
+- %code: Grab code cells from a notebook
+- %md: Grab markdown cells from a notebook (by sequential index)
+- %mdat: Grab markdown cells by position relative to code cells
+- %nb: Alias for %code (for backward compatibility)
+- %ai: Invoke the `llm` package for quick use of an LLM like gpt-4o-mini
 
-The %nb magic is for grabbing a few code or markdown cells (respectively) from
-a notebook on the filesystem. It defaults to the most recently modified
-notebook in the latest ~/Trainer_XYZ folder.
-
-The %ai magic invokes the `llm` package for quick use of an LLM like gpt-4o-mini.
+The %code, %md, and %mdat magics grab cells from a notebook on the filesystem,
+defaulting to the most recently modified notebook in the latest ~/Trainer_XYZ folder.
 
 For help on the magics, add a trailing question mark. For example:
 
-    %nb?
+    %code?
+    %md?
+    %mdat?
+    %ai?
 
 Two additional magics are available for getting and setting the current
-path and/or file that %nb queries. To get help on these, run:
+path and/or file that %code, %md, and %mdat query. To get help on these, run:
 
     %nbfile?
     %nbpath?
@@ -34,6 +37,7 @@ path and/or file that %nb queries. To get help on these, run:
 """
 
 from .nb_magic import NotebookMagic
+
 try:
     from .ai_magic import AIMagic
 except Exception as e:
@@ -54,5 +58,3 @@ def load_ipython_extension(ipython):
         ipython.register_magics(AIMagic)
     except Exception as e:
         print(e)
-
-