dmstudio-rm 2.0.0b4__py3-none-any.whl

dmstudio/__init__.py

@@ -0,0 +1,42 @@
+'''
+dmstudio package
+----------------
+
+Python package for Datamine Studio RM scripting via Windows COM automation.
+
+Submodules:
+    dmcommands      - Auto-generated wrappers for all Studio RM commands.
+    dmfiles         - Studio commands that generate Datamine files (INPFIL etc).
+    initialize      - COM initialization helpers.
+    special         - Special/adapted Studio command helpers.
+    superprocess    - Multi-command workflow helpers.
+    agent           - Backward compatibility re-export layer for legacy AI agent scripts.
+    notebook_builder- Jupyter Notebook builder for auditable agent workflows.
+    sandbox         - Sandbox management and dataset copy helpers.
+    dm_io           - High-level DataFrame ↔ Datamine file I/O operations.
+    dialog          - Windows modal dialog auto-dismissal context.
+    bootstrap       - Tutorial bootstrapping and download helpers.
+'''
+
+# Proactively import pandas at the package root to avoid Python 3.14 / Cython circular import conflicts in debuggers
+try:
+    import pandas as _pd
+except ImportError:
+    pass
+
+from dmstudio import dmcommands
+from dmstudio import dmfiles
+from dmstudio import dmcommands_generated
+from dmstudio import dmfiles_generated
+from dmstudio import initialize
+from dmstudio import special
+from dmstudio import superprocess
+from dmstudio import agent
+from dmstudio import notebook_builder
+from dmstudio import sandbox
+from dmstudio import dm_io
+from dmstudio import dialog
+from dmstudio import bootstrap
+
+# Shortcuts
+from dmstudio.bootstrap import download_tutorials

dmstudio/agent.py

@@ -0,0 +1,62 @@
+'''
+dmstudio.agent
+--------------
+
+AI agent helper module for Datamine Studio RM scripting.
+
+Command discovery (list_commands, get_command_schema, search_commands) is
+implemented in dmstudio.command_registry and re-exported here for backwards
+compatibility. Import directly from command_registry when you need discovery
+without COM, threading, or pandas side-effects.
+
+Provides:
+- list_commands()         : Return all available Datamine command names and descriptions.
+- get_command_schema()    : Return the JSON schema (parameters, types) for a given command.
+- search_commands()       : Fuzzy-search commands by name or keyword.
+- read_datamine()         : Read a .dm or .dmx binary file into a pandas DataFrame using
+                            the DmFile.DmTableADO COM object — no proprietary deps required.
+- dialog_dismiss_context(): Context manager that auto-dismisses blocking Studio RM modal
+                            dialogs in a background thread (opt-in).
+'''
+
+
+# ---------------------------------------------------------------------------
+# Command discovery — re-exported from command_registry for backwards compat
+# ---------------------------------------------------------------------------
+from dmstudio.command_registry import (  # noqa: F401
+    list_commands,
+    get_command_schema,
+    search_commands,
+)
+
+# ---------------------------------------------------------------------------
+# DataFrame I/O — re-exported from dm_io for backwards compat
+# ---------------------------------------------------------------------------
+from dmstudio.dm_io import (  # noqa: F401
+    read_datamine,
+    to_datamine,
+    patch_dataframe,
+)
+patch_dataframe()
+
+
+# ---------------------------------------------------------------------------
+# Auto-dialog dismissal context manager — re-exported from dialog for compat
+# ---------------------------------------------------------------------------
+from dmstudio.dialog import dialog_dismiss_context  # noqa: F401
+
+
+# ---------------------------------------------------------------------------
+# Sandbox management — re-exported from sandbox for backwards compat
+# ---------------------------------------------------------------------------
+from dmstudio.sandbox import (  # noqa: F401
+    copy_database_files,
+    initialize_sandbox,
+)
+
+
+# ---------------------------------------------------------------------------
+# Tutorial bootstrapping — re-exported from bootstrap for backwards compat
+# ---------------------------------------------------------------------------
+from dmstudio.bootstrap import download_tutorials  # noqa: F401
+

dmstudio/bootstrap.py

@@ -0,0 +1,92 @@
+'''
+dmstudio.bootstrap
+------------------
+
+Bootstrapping utility to download tutorials and sample datasets.
+'''
+import os
+import shutil
+import tempfile
+import urllib.request
+import zipfile
+
+
+def download_tutorials(target_dir):
+    '''
+    download_tutorials
+    ------------------
+
+    Download the latest tutorials and sample datasets from the GitHub repository
+    and extract them into the specified target directory.
+
+    Parameters:
+    -----------
+    target_dir: str
+        Absolute or relative path to the folder where the "tutorials" directory
+        should be created.
+    '''
+    # 1. Validate target directory
+    target_dir = os.path.abspath(target_dir)
+    os.makedirs(target_dir, exist_ok=True)
+    
+    url = 'https://github.com/nazabrory/dmstudio-rm/archive/refs/heads/master.zip'
+    fallback_url = 'https://github.com/nazabrory/dmstudio-rm/archive/refs/heads/main.zip'
+    
+    # 2. Create temporary file
+    with tempfile.NamedTemporaryFile(delete=False, suffix='.zip') as tmp_file:
+        tmp_path = tmp_file.name
+        
+    try:
+        # Download the zip
+        try:
+            print('Downloading tutorials from {}...'.format(url))
+            urllib.request.urlretrieve(url, tmp_path)
+        except Exception:
+            print('Failed to download from default branch. Trying fallback: {}...'.format(fallback_url))
+            urllib.request.urlretrieve(fallback_url, tmp_path)
+        
+        # 3. Extract the tutorials folder
+        print('Extracting tutorials...')
+        with zipfile.ZipFile(tmp_path, 'r') as zip_ref:
+            # Find the top level directory name inside the zip (typically 'dmstudio-main')
+            top_dir = None
+            for name in zip_ref.namelist():
+                if name.endswith('/tutorials/'):
+                    top_dir = name.split('/')[0]
+                    break
+            
+            if not top_dir:
+                # Try fallback: look for any 'tutorials/' entry
+                for name in zip_ref.namelist():
+                    if 'tutorials/' in name:
+                        top_dir = name.split('/')[0]
+                        break
+            
+            if not top_dir:
+                raise RuntimeError('Could not find \'tutorials\' folder in the downloaded zip archive.')
+            
+            # Extract only files in the tutorials folder
+            tutorials_prefix = '{}/tutorials/'.format(top_dir)
+            extracted_count = 0
+            for member in zip_ref.infolist():
+                if member.filename.startswith(tutorials_prefix) and not member.is_dir():
+                    # Compute relative path under 'tutorials/'
+                    rel_path = member.filename[len(tutorials_prefix):]
+                    out_path = os.path.join(target_dir, 'tutorials', rel_path)
+                    
+                    # Ensure parent dir exists
+                    os.makedirs(os.path.dirname(out_path), exist_ok=True)
+                    
+                    # Write file
+                    with zip_ref.open(member) as source, open(out_path, 'wb') as target:
+                        shutil.copyfileobj(source, target)
+                    extracted_count += 1
+                    
+        print('Successfully extracted {} tutorial files to: {}'.format(
+            extracted_count, os.path.join(target_dir, 'tutorials')
+        ))
+        
+    finally:
+        # Clean up temporary file
+        if os.path.exists(tmp_path):
+            os.remove(tmp_path)

dmstudio/command_registry.py

@@ -0,0 +1,264 @@
+'''
+dmstudio.command_registry
+--------------------------
+
+Command discovery module for Datamine Studio RM.
+
+Provides a read-only index over all command wrappers exposed by
+dmstudio.dmcommands.init, dmstudio.dmfiles.init, and their generated fallback equivalents.
+
+Interface (seam):
+    list_commands()             -> list[dict]
+    get_command_schema(str)     -> dict
+    search_commands(str)        -> list[dict]
+
+No COM, threading, or pandas dependency — safe to import in any context,
+including environments without Datamine Studio RM installed.
+'''
+import inspect
+
+from dmstudio import dmcommands, dmfiles
+
+try:
+    from dmstudio import dmcommands_generated
+except ImportError:
+    dmcommands_generated = None
+
+try:
+    from dmstudio import dmfiles_generated
+except ImportError:
+    dmfiles_generated = None
+
+
+# Canonical list of verified commands
+VERIFIED_COMMANDS = {
+    'accmlt', 'append', 'cokrig', 'compdh', 'copy',
+    'count', 'delete', 'diffrn', 'dmedit', 'extra',
+    'holes3d', 'ijkgen', 'join', 'mgsort', 'modtra',
+    'output', 'selcop', 'seldel', 'selexy', 'sortx',
+    'stats', 'tongrad', 'inpfil', 'estima', 'protom'
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers (implementation — not part of the interface)
+# ---------------------------------------------------------------------------
+
+def _get_init_classes():
+    '''Return the list of init classes to inspect (both dmcommands/dmfiles and generated/experimental).'''
+    classes = []
+    if inspect.isclass(dmcommands.init):
+        classes.append(dmcommands.init)
+    else:
+        classes.append(type(dmcommands.init))
+    if inspect.isclass(dmfiles.init):
+        classes.append(dmfiles.init)
+    else:
+        classes.append(type(dmfiles.init))
+
+    if dmcommands_generated is not None:
+        if inspect.isclass(dmcommands_generated.init):
+            classes.append(dmcommands_generated.init)
+        else:
+            classes.append(type(dmcommands_generated.init))
+
+    if dmfiles_generated is not None:
+        if inspect.isclass(dmfiles_generated.init):
+            classes.append(dmfiles_generated.init)
+        else:
+            classes.append(type(dmfiles_generated.init))
+
+    return classes
+
+
+# ---------------------------------------------------------------------------
+# Public interface
+# ---------------------------------------------------------------------------
+
+def list_commands():
+    '''
+    list_commands
+    -------------
+
+    Return a list of all available Datamine command wrapper names exposed
+    by verified and experimental modules. Each entry is a dict
+    with 'name', 'doc', and 'experimental' keys.
+
+    Returns:
+    --------
+    list of dict
+        [{'name': 'copy', 'doc': 'COPY ...', 'experimental': False}, ...]
+    '''
+    results = []
+    seen = set()
+    classes = _get_init_classes()
+
+    for cls in classes:
+        for name in dir(cls):
+            if name.startswith('_') or name in ('run_command', 'parse_infields_list'):
+                continue
+            if name in seen:
+                continue
+            try:
+                attr = getattr(cls, name)
+            except Exception:
+                continue
+            if callable(attr):
+                doc = inspect.getdoc(attr) or ''
+                first_line = doc.split('\n')[0].strip()
+                experimental = name.lower() not in VERIFIED_COMMANDS
+                results.append({
+                    'name': name,
+                    'doc': first_line,
+                    'experimental': experimental
+                })
+                seen.add(name)
+
+    return sorted(results, key=lambda x: x['name'])
+
+
+def get_command_schema(cmd_name):
+    '''
+    get_command_schema
+    ------------------
+
+    Return a JSON-serialisable schema for a given Datamine command wrapper.
+
+    Parameters:
+    -----------
+    cmd_name: str
+        Name of the command (case-insensitive), e.g. 'copy', 'COPY', 'protom'.
+
+    Returns:
+    --------
+    dict
+        {
+          'name': str,
+          'doc': str,
+          'parameters': [{'name': str, 'default': any, 'annotation': str}, ...],
+          'experimental': bool
+        }
+
+    Raises:
+    -------
+    ValueError
+        If the command is not found.
+    '''
+    cmd_name_lower = cmd_name.lower()
+    classes = _get_init_classes()
+    func = None
+
+    # Search init class methods first (where all wrappers live)
+    for cls in classes:
+        for name in dir(cls):
+            if name.lower() == cmd_name_lower:
+                try:
+                    func = getattr(cls, name)
+                    if callable(func):
+                        break
+                except Exception:
+                    pass
+        if func is not None:
+            break
+
+    # Fallback 1: search module-level names in dmcommands
+    if func is None:
+        for name in dir(dmcommands):
+            if name.lower() == cmd_name_lower:
+                try:
+                    attr = getattr(dmcommands, name)
+                    if callable(attr):
+                        func = attr
+                        break
+                except Exception:
+                    pass
+
+    # Fallback 2: search module-level names in dmfiles
+    if func is None:
+        for name in dir(dmfiles):
+            if name.lower() == cmd_name_lower:
+                try:
+                    attr = getattr(dmfiles, name)
+                    if callable(attr):
+                        func = attr
+                        break
+                except Exception:
+                    pass
+
+    # Fallback 3: search module-level names in dmcommands_generated
+    if func is None and dmcommands_generated is not None:
+        for name in dir(dmcommands_generated):
+            if name.lower() == cmd_name_lower:
+                try:
+                    attr = getattr(dmcommands_generated, name)
+                    if callable(attr):
+                        func = attr
+                        break
+                except Exception as e:
+                    pass
+
+    # Fallback 4: search module-level names in dmfiles_generated
+    if func is None and dmfiles_generated is not None:
+        for name in dir(dmfiles_generated):
+            if name.lower() == cmd_name_lower:
+                try:
+                    attr = getattr(dmfiles_generated, name)
+                    if callable(attr):
+                        func = attr
+                        break
+                except Exception as e:
+                    pass
+
+    if func is None:
+        raise ValueError('Command not found: {}'.format(cmd_name))
+
+    try:
+        sig = inspect.signature(func)
+    except (ValueError, TypeError):
+        sig = None
+
+    params = []
+    if sig:
+        for pname, param in sig.parameters.items():
+            if pname in ('self', 'cls'):
+                continue
+            default = param.default
+            if default is inspect.Parameter.empty:
+                default = None
+            annotation = str(param.annotation) if param.annotation is not inspect.Parameter.empty else 'any'
+            params.append({'name': pname, 'default': str(default), 'annotation': annotation})
+
+    doc = inspect.getdoc(func) or ''
+
+    return {
+        'name': cmd_name,
+        'doc': doc,
+        'parameters': params,
+        'experimental': cmd_name_lower not in VERIFIED_COMMANDS,
+    }
+
+
+def search_commands(query):
+    '''
+    search_commands
+    ---------------
+
+    Search command names and docstrings for a keyword or phrase.
+
+    Parameters:
+    -----------
+    query: str
+        Search term (case-insensitive).
+
+    Returns:
+    --------
+    list of dict
+        Matching commands: [{'name': str, 'doc': str, 'experimental': bool}, ...]
+    '''
+    query_lower = query.lower()
+    results = []
+    for entry in list_commands():
+        if query_lower in entry['name'].lower() or query_lower in entry['doc'].lower():
+            results.append(entry)
+    return results
+

dmstudio/dialog.py

@@ -0,0 +1,81 @@
+'''
+dmstudio.dialog
+---------------
+
+Context manager that spawns a background thread to automatically dismiss
+blocking "#32770" modal dialogs produced by Datamine Studio RM.
+'''
+import threading
+import time
+import contextlib
+
+try:
+    import win32gui
+    import win32con
+    import win32api
+    WIN32_AVAILABLE = True
+except ImportError:
+    WIN32_AVAILABLE = False
+
+
+@contextlib.contextmanager
+def dialog_dismiss_context(title='Studio RM', interval=1.0):
+    '''
+    dialog_dismiss_context
+    ----------------------
+
+    Context manager that spawns a background thread to automatically dismiss
+    blocking "#32770" modal dialogs produced by Datamine Studio RM (e.g.
+    "Duplicate Project File" prompts). This is opt-in: it only runs when
+    explicitly used as a context manager.
+
+    Parameters:
+    -----------
+    title: str
+        Window title to match for dismissal. Default: 'Studio RM'.
+    interval: float
+        Polling interval in seconds. Default: 1.0.
+
+    Usage:
+    ------
+    from dmstudio import dialog, dmcommands
+    cmd = dmcommands.init(version='StudioRM')
+
+    with dialog.dialog_dismiss_context():
+        cmd.copy(in_i='source', out_o='dest')
+    '''
+    stop_event = threading.Event()
+    t = None
+
+    def _dismiss_loop():
+        if not WIN32_AVAILABLE:
+            return
+        while not stop_event.is_set():
+            try:
+                def _enum_callback(hwnd, _):
+                    if not win32gui.IsWindowVisible(hwnd):
+                        return
+                    cls = win32gui.GetClassName(hwnd)
+                    ttl = win32gui.GetWindowText(hwnd)
+                    if cls == '#32770' and title in ttl:
+                        # Try 'Yes' button (ID=6), then 'OK' button (ID=1)
+                        for btn_id in (6, 1):
+                            try:
+                                win32api.SendMessage(hwnd, win32con.WM_COMMAND, btn_id, 0)
+                            except Exception:
+                                pass
+                win32gui.EnumWindows(_enum_callback, None)
+            except Exception:
+                pass
+            time.sleep(interval)
+
+    if WIN32_AVAILABLE:
+        t = threading.Thread(target=_dismiss_loop, daemon=True)
+        t.start()
+
+    try:
+        yield
+    finally:
+        stop_event.set()
+        if t is not None:
+            t.join(timeout=interval * 2)