qdir 1.0.0rc1__py3-none-any.whl

qdir/__init__.py

@@ -0,0 +1,275 @@
+#!/bin/env python3
+"""Implementation of a first-in, first-out job queue for the local machine.
+
+The queue is maintained as a directory of tiny job queue files.
+When a new job is submitted, this script will identify any existing job queue files and then add its own queue file to the directory.
+No job will begin until all the preceeding queue files are gone.
+Each job will delete its own queue file upon completion so the next job can begin.
+A shared queue directory should be specified on a multi-user system.
+"""
+
+__author__ = "Carl Osterwisch"
+__version__ = "1.0.0rc1"
+__url__ = "https://github.com/costerwi/qdir/"
+
+import os
+import signal
+import subprocess
+import sys
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+from tempfile import gettempdir
+from time import asctime, perf_counter, sleep
+
+from filelock import FileLock
+
+default = Namespace
+
+parser = ArgumentParser(epilog=f"qdir {__version__} {__url__}")
+default.queue = Path(os.environ.get("QDIR_QUEUE", gettempdir()))
+parser.add_argument(
+    "-q",
+    "--queue",
+    type=Path,
+    help="Directory to store the queue files. "
+    f"Default is environment variable QDIR_QUEUE or {default.queue}",
+    default=default.queue,
+)
+default.verbose = int(os.environ.get("QDIR_VERBOSE", "2"))
+parser.add_argument(
+    "-v",
+    "--verbose",
+    type=int,
+    help="Verbosity level. "
+    f"Default is environment variable QDIR_VERBOSE or {default.verbose}",
+    default=default.verbose,
+)
+
+qFileSuffix = os.environ.get("QDIR_SUFFIX", ".qdir")  # suffix for queue files
+
+
+class Queue:
+    def __init__(self, **kwargs):
+        """Create the queue, allowing parameters to override defaults"""
+        for parameter, value in vars(default).items():
+            setattr(self, parameter, kwargs.pop(parameter, value))
+        if not self.queue.is_dir():
+            raise FileNotFoundError(f"The QDIR directory {self.queue} does not exist")
+        if not os.access(self.queue, os.W_OK):
+            raise PermissionError(f"The QDIR directory {self.queue} is not writable")
+
+    def getQueuedJobs(self) -> list[Path]:
+        """Return a list of qFilePath for currently queued jobs, sorted oldest to newest."""
+        # Collecct a set of active process ids
+        if os.name == "nt":
+            import win32process
+
+            processIds = {str(pid) for pid in win32process.EnumProcesses()}
+        else:
+            procPath = Path("/proc")
+            processIds = {p.stem for p in procPath.iterdir() if p.stem.isnumeric()}
+
+        def is_qFile(path):
+            """Verify the path is an active job file with a matching process id"""
+            if not path.stem.isnumeric():
+                return False  # file name must be an integer
+            if not (path.is_file()):
+                return False  # path must represent a file
+            if path.stem in processIds:
+                return True  # file name must match a running process number
+
+            # Otherwise, the process may have died or the computer was rebooted with
+            # this job in the queue. This orphaned qFile may be removed.
+            print(
+                "Removing orphaned queue file",
+                self.info.format(**self.getJobInfo(path)),
+                file=sys.stderr,
+            )
+            try:
+                path.unlink(missing_ok=True)
+            except OSError as e:
+                print(e, file=sys.stderr)
+
+        queuedJobs = [
+            filePath
+            for filePath in self.queue.glob("*" + qFileSuffix)
+            if is_qFile(filePath)
+        ]
+        return sorted(queuedJobs, key=lambda qFilePath: qFilePath.stat().st_mtime)
+
+    def getJobInfo(self, qFilePath: Path) -> dict:
+        """Return information about the job specified in qFilePath"""
+        jobInfo = {
+            "jobId": qFilePath.stem,
+            "owner": qFilePath.owner(),
+            "name": "",
+            "command": "",
+            "directory": "",
+            "behind": "",
+            "status": "",
+            "history": [],  # list[str]
+        }
+        try:
+            with qFilePath.open() as qFile:
+                for line in qFile:
+                    keyValue = line.strip().split("\t", 2)
+                    if len(keyValue) == 2:
+                        jobInfo.update([keyValue])
+                    else:
+                        status = keyValue[0]
+                        jobInfo["history"].append(status)
+                        jobInfo["status"] = status  # latest update
+        except OSError as e:
+            status = repr(e)
+            jobInfo["history"].append(status)
+            jobInfo["status"] = status
+        return jobInfo
+
+    def dequeue(self, qFilePath: Path):
+        """Remove a job from the queue"""
+        assert qFilePath.parent == self.queue
+        assert qFilePath.suffix == qFileSuffix
+        assert qFilePath.stem.isnumeric()
+        # Removing qFile will dequeue the job but the effect is delayed by polling interval
+        qFilePath.unlink(missing_ok=True)
+        if os.name == "posix":
+            # On Linux the SIGTERM signal has immediate effect
+            try:
+                os.kill(int(qFilePath.stem), signal.SIGTERM)
+            except OSError:  # no such process
+                pass
+
+    def enqueue(self, cmd: list[str]):
+        """Wait in queue until prior jobs finish, then run cmd"""
+        import getpass
+        import shutil
+
+        if len(cmd) < 1:
+            raise SyntaxError("Missing cmd")
+        if self.verbose >= 1 and not shutil.which(cmd[0]):
+            print(f"WARNING: {cmd[0]} is not in PATH", file=sys.stderr)
+        if not self.interval > 0:
+            self.interval = 1
+
+        startTime = perf_counter()  # time job was enqueued
+        job = None  # subprocess running the cmd, if any
+
+        jobInfo = {  # information about this job
+            "jobId": str(os.getpid()),  # process id of this script
+            "owner": getpass.getuser(),
+            "name": self.name or cmd[-1],
+            "command": " ".join(cmd),
+            "directory": Path.cwd(),
+        }
+
+        def updateStatus(priority, status, file=None):
+            """Notify user of status change and optionally record in file"""
+            jobInfo["status"] = status
+            jobInfo["time"] = asctime()
+            jobInfo["duration"] = humanDuration(perf_counter() - startTime)
+            if self.verbose >= priority:
+                # Echo status to the terminal
+                print(self.status.format(**jobInfo))
+            if file is not None:
+                # Record status history in specified qFile
+                print("{time} {status}".format(**jobInfo), file=file)
+
+        qFilePath = (self.queue / jobInfo["jobId"]).with_suffix(qFileSuffix)
+        lock = FileLock(self.queue / "qdir.lock")  # prevent previousJobs race
+        with lock.acquire(timeout=5):
+            previousJobs = self.getQueuedJobs()
+            jobInfo["behind"] = " ".join([job.stem for job in previousJobs])
+            with qFilePath.open("w") as qFile:
+                os.environ["QDIR_FILE"] = qFile.name  # will be exported to cmd
+                # Initialize qFile contents
+                for key in "name", "command", "directory", "behind":
+                    value = jobInfo.get(key)
+                    if value:
+                        print(key, value, sep="\t", file=qFile)
+                updateStatus(priority=2, status="Queued", file=qFile)
+
+        def terminateJob(sig=None, frame=None):
+            """Terminate this job if running or dequeue if not"""
+            nonlocal job
+            result = ""
+            qFilePath.unlink(missing_ok=True)  # remove its qFile
+            if job is None:
+                # removed from the queue before starting
+                result = ".. Dequeued"
+            elif hasattr(job, "pid"):  # job is or was running
+                if job.poll() is None:
+                    # job is still running
+                    if self.verbose >= 2:
+                        result = ".. Killed"
+                    if os.name == "nt":
+                        job.send_signal(signal.CTRL_BREAK_EVENT)
+                    else:
+                        # pass SIGTERM signal to all child processes in this process group
+                        os.killpg(os.getpgid(job.pid), signal.SIGTERM)
+                elif self.verbose >= 1:
+                    # job is no longer running; check returncode
+                    if job.returncode <= 0:
+                        result = "** Done"
+                    else:
+                        result = "-- Error"
+            if result:
+                updateStatus(priority=2, status=result)
+                job = result  # prevent this from duplicate reporting
+
+        signal.signal(
+            signal.SIGTERM, terminateJob
+        )  # catch termination signal (ignored on Windows)
+
+        # Wait for all previousJobs to complete
+        previousJobs.reverse()  # check newest jobs first
+        while qFilePath.exists() and any(
+            otherFile.exists() for otherFile in previousJobs
+        ):
+            sleep(self.interval)
+
+        # Launch the cmd only if this job's qFile still exists
+        if qFilePath.exists():
+            try:
+                # Append the job starting status to qFile
+                stat = qFilePath.stat()
+                with qFilePath.open("a") as qFile:
+                    print(
+                        "Waited in queue",
+                        humanDuration(perf_counter() - startTime),
+                        file=qFile,
+                    )
+                    updateStatus(priority=3, status="Started", file=qFile)
+                # Keep mtime unchanged so the job files sort correctly
+                os.utime(qFilePath, (stat.st_atime, stat.st_mtime))
+            except OSError:
+                pass  # ignore status update exceptions
+            logFilePath = Path(self.output.format(**jobInfo))
+            with logFilePath.open("w") as logFile:
+                opts = {}
+                if os.name == "nt":
+                    opts["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+                try:
+                    job = subprocess.Popen(
+                        cmd,
+                        shell=False,
+                        start_new_session=True,
+                        stdin=subprocess.DEVNULL,
+                        stdout=logFile,
+                        stderr=subprocess.STDOUT,
+                        **opts,
+                    )
+                    startTime = perf_counter()  # reset to time job started running
+                    while qFilePath.exists() and job.poll() is None:
+                        # job is still running
+                        sleep(self.interval)
+                except OSError as e:
+                    print(e, file=logFile)
+
+        terminateJob()  # Clean up at the end
+
+
+def humanDuration(seconds: float) -> str:
+    for unit, per in ("days", 86400), ("hours", 3600), ("minutes", 60):
+        if seconds >= 1.1 * per:
+            return f"{seconds / per:.2g} {unit}"
+    return f"{seconds:.2g} seconds"

qdir/abaqus/__init__.py

@@ -0,0 +1,5 @@
+"""Modules to help Abaqus interact with the qdir job queue
+
+Install with:
+    python3 -m qdir.abaqus install
+"""

qdir/abaqus/__main__.py

@@ -0,0 +1,66 @@
+"""Install or uninstall qdir for Abaqus.
+
+This script will modify the user's abaqus_v6.env file with
+settings for the qdir job queue.
+"""
+
+from __future__ import print_function, with_statement  # use Python3 syntax
+
+import os
+import sys
+from argparse import ArgumentParser
+
+settings = """# Settings for qdir job queue
+sys.path.append(r"{}")  # directory of qdir_submit.py
+import qdir_submit
+qdir_submit.init(queues)
+plugin_central_dir += os.pathsep + qdir_submit.dirname
+run_mode = BATCH  # command line will submit to queue by default"""
+
+parser = ArgumentParser(description=__doc__)
+parser.add_argument(
+    "action",
+    choices=["install", "uninstall"],
+    help="Specify what to do.",
+)
+default = os.path.expanduser("~/abaqus_v6.env")
+parser.add_argument(
+    "env",
+    nargs="?",
+    default=default,
+    help="Optionally specify the .env file to modify. Default is {}".format(default),
+)
+
+
+def uninstall(user_env):
+    """Remove qdir settings from user's abaqus_v6.env"""
+    new_env = user_env + ".new"
+    with open(new_env, "w") as new_env_file:
+        try:
+            # copy current settings
+            with open(user_env) as env_file:
+                for line in env_file:
+                    if not "qdir" in line:  # skip any qdir settings
+                        print(line.rstrip(), file=new_env_file)
+            os.remove(user_env)
+        except FileNotFoundError:
+            pass
+    os.rename(new_env, user_env)
+
+
+def install(user_env):
+    """Append qdir settings to user's abaqus_v6.env"""
+    uninstall(user_env)  # remove any previous settings
+    dirname = os.path.dirname(os.path.normpath(__file__))
+    with open(user_env, "a") as user_env_file:
+        print(settings.format(dirname), file=user_env_file)
+
+
+if __name__ == "__main__":
+    options = parser.parse_args(sys.argv[1:])
+    if "uninstall" == options.action:
+        print("Removing qdir settings from", options.env)
+        uninstall(options.env)
+    else:
+        print("Adding qdir settings to", options.env)
+        install(options.env)

qdir/abaqus/qdir_plugin.py

@@ -0,0 +1,223 @@
+"""Abaqus CAE plugin to interact with qdir Queue"""
+
+from __future__ import print_function, with_statement
+
+__version__ = "1.0.0"
+__author__ = "Carl Osterwisch"
+__url__ = "https://github.com/costerwi/qdir/"
+
+import json
+import os
+from subprocess import PIPE, Popen
+
+from abaqusGui import *
+
+if isinstance("unicode", str):
+
+    def a(unicodeString):
+        "Do nothing for Python3, Abaqus >=2024"
+        return unicodeString
+else:
+
+    def a(unicodeString):
+        "Convert unicode to str for Abaqus <2024"
+        return unicodeString.encode("ascii", "ignore")
+
+
+class QDirQueueMonitor(AFXDataDialog):
+    (ID_TABLE, ID_REFRESH, ID_HELP, ID_SUBMITALL, ID_LAST) = range(
+        AFXDataDialog.ID_LAST, AFXDataDialog.ID_LAST + 5
+    )
+
+    def __init__(self, form):
+        AFXDataDialog.__init__(
+            self,
+            form,
+            title="QDir Job Queue Monitor",
+            opts=DIALOG_NORMAL | DECOR_RESIZE,
+        )
+        self.appendActionButton("Queue all Jobs", self, self.ID_SUBMITALL)
+        FXMAPFUNC(self, SEL_COMMAND, self.ID_SUBMITALL, QDirQueueMonitor.submitAll)
+        self.appendActionButton("Help", self, self.ID_HELP)
+        FXMAPFUNC(self, SEL_COMMAND, self.ID_HELP, QDirQueueMonitor.getHelp)
+        self.appendActionButton(self.DISMISS)
+        self.updateTimer = None
+        self.headings = ("jobId", "status", "name")
+        self.jobData = {}
+
+        sp = FXSplitter(self, LAYOUT_FILL_X | LAYOUT_FILL_Y | SPLITTER_VERTICAL)
+        self.table = AFXTable(
+            p=sp,
+            numVisRows=6,
+            numVisColumns=len(self.headings),
+            numRows=1,
+            numColumns=len(self.headings),
+            tgt=self,
+            sel=self.ID_TABLE,
+            opts=AFXTABLE_NORMAL | AFXTABLE_ROW_MODE,
+        )
+        FXMAPFUNC(self, SEL_SELECTED, self.ID_TABLE, QDirQueueMonitor.onSelected)
+        FXMAPFUNC(self, SEL_DELETED, self.ID_TABLE, QDirQueueMonitor.onDelete)
+        self.table.setLeadingRows(numRows=1)
+        self.table.setLeadingRowLabels("\t".join([h.title() for h in self.headings]))
+        self.table.setColumnWidth(column=0, width=0)  # Hide the jobIds
+        self.table.setColumnWidthInChars(column=1, numChars=30)
+        self.table.setStretchableColumn(
+            len(self.headings) - 1
+        )  # Expand name as necessary
+        self.table.setPopupOptions(AFXTable.POPUP_DELETE_ROW)
+        self.jobDetails = FXText(p=sp, opts=TEXT_READONLY | LAYOUT_FILL_Y)
+        self.jobDetails.setVisRows(5)
+        try:
+            self.interval = max(1, int(os.environ.get("QDIR_POLL_INTERVAL", "5")))
+        except ValueError:
+            self.interval = 5
+        FXMAPFUNC(self, SEL_TIMEOUT, self.ID_REFRESH, QDirQueueMonitor.updateTable)
+
+    def qstat(self):
+        """Collect jobInfo of currently queued jobs"""
+        self.jobData.clear()
+        cmd = ["qstat", "--json"]
+        env = os.environ.copy()
+        env["PYTHONPATH"] = ""  # remove Abaqus modified PYTHONPATH
+        try:
+            process = Popen(cmd, stdout=PIPE, stderr=PIPE, env=env)
+            stdout, stderr = process.communicate()
+            returncode = process.returncode
+        except OSError as e:
+            returncode = "OSError"
+            stdout = ""
+            stderr = str(e)
+        if returncode:
+            # report error data
+            jobInfo = {
+                "status": "Error {}".format(returncode),
+                "name": " ".join(cmd),
+                "stdout": stdout,
+                "stderr": stderr,
+            }
+            self.jobData["1"] = "1", jobInfo
+        else:
+            queuedJobs = json.loads(stdout)
+            for qFilePath, jobInfo in queuedJobs.items():
+                self.jobData[jobInfo["jobId"]] = qFilePath, jobInfo
+
+    def detailedText(self, jobInfo):
+        """Summarize full job status"""
+        h = []
+        for key, value in jobInfo.items():
+            if "status" == key:
+                continue
+            if not value:
+                continue
+            if isinstance(value, list):
+                h.append(key.upper())
+                h.extend(value)
+            else:
+                h.append("{}\t{}".format(key.upper(), value))
+        return "\n".join(h)
+
+    def updateTable(self, *args):
+        """Update manager with list of currently queued jobs"""
+        row = self.table.getCurrentRow()
+        if row < 1:
+            selected = None  # nothing is selected
+        else:
+            selected = self.table.getItemText(row, column=0)
+        self.qstat()
+        diff = len(self.jobData) + 1 - self.table.getNumRows()
+        if diff < 0:
+            self.table.deleteRows(
+                startRow=1,
+                numRows=-diff,
+                notify=FALSE,  # delete from top
+            )
+        elif diff > 0:
+            self.table.insertRows(
+                startRow=self.table.getNumRows(),  # add to bottom
+                numRows=diff,
+                notify=FALSE,
+            )
+        jobDetails = ""
+        for row, (qFilePath, jobInfo) in enumerate(self.jobData.values(), 1):
+            for column, heading in enumerate(self.headings):
+                self.table.setItemValue(
+                    row=row,
+                    column=column,
+                    valueText=a(jobInfo.get(heading, "")),
+                )
+            if jobInfo["jobId"] == selected or (selected is None and row == 1):
+                jobDetails = self.detailedText(jobInfo)
+        self.jobDetails.setText(a(jobDetails))
+        self.updateTimer = getAFXApp().addTimeout(
+            1000 * self.interval, self, self.ID_REFRESH
+        )
+
+    def onSelected(self, sender, sel, ptr):
+        """Show the details for selected job"""
+        row = sender.getCurrentRow()
+        if row > 0:
+            selected = self.table.getItemText(row, column=0)
+            _qFilePath, jobInfo = self.jobData.get(selected, ("", {}))
+            jobDetails = self.detailedText(jobInfo)
+            self.jobDetails.setText(a(jobDetails))
+
+    def onDelete(self, sender, sel, ptr):
+        """Dequeue jobs for selected table rows"""
+        cmd = ["qdel"]
+        cmd.extend(
+            self.table.getItemText(row, column=0)
+            for row in range(1, self.table.getNumRows())
+            if self.table.isRowSelected(row)
+        )
+        if len(cmd) > 1:
+            self.jobDetails.setText("")
+            env = os.environ.copy()
+            env["PYTHONPATH"] = ""  # remove Abaqus modified PYTHONPATH
+            process = Popen(cmd, env=env)
+            process.wait()
+
+    def submitAll(self, sender, sel, ptr):
+        """Submit all CAE jobs"""
+        sendCommand("qdir_submit.submitCAEJobs()")
+        return 1
+
+    def getHelp(self, sender, sel, ptr):
+        """Open webbrowser to plugin helpUrl"""
+        import webbrowser
+
+        webbrowser.open(__url__)
+        return 1
+
+    def show(self):
+        """Update the job data"""
+        AFXDataDialog.show(self)
+        self.updateTable()  # update the table and start the updateTimer
+
+    def hide(self):
+        """Remove the updateTimer"""
+        if self.updateTimer is not None:
+            getAFXApp().removeTimeout(self.updateTimer)
+            self.updateTimer = None
+        AFXDataDialog.hide(self)
+
+
+class QDirForm(AFXForm):
+    def getFirstDialog(self):
+        return QDirQueueMonitor(self)
+
+
+###########################################################################
+# Register the plugin
+###########################################################################
+toolset = getAFXApp().getAFXMainWindow().getPluginToolset()
+
+toolset.registerGuiMenuButton(
+    buttonText="&QDir Job Queue Monitor...",
+    object=QDirForm(toolset),
+    kernelInitString="import qdir_submit # {}".format(__version__),
+    author=__author__,
+    version=str(__version__),
+    helpUrl=__url__,
+    description="Check status of jobs in the QDir Queue",
+)

qdir/abaqus/qdir_submit.py

@@ -0,0 +1,165 @@
+"""Abaqus Queue class to create a job script and submit it to qdir
+
+This module is compatible with at least Abaqus 2019 thru 2026.
+This module works under Windows and Linux.
+
+Carl Osterwisch, January 2024
+"""
+
+from __future__ import print_function, with_statement  # use Python3 syntax
+
+__all__ = ["QDirQueue"]
+
+import os
+from string import Template
+from textwrap import dedent
+
+import uti
+from driverQueues import Queue
+
+dirname = os.path.dirname(os.path.normpath(__file__))
+
+
+def init(queues, queue=None):
+    """Add the queue instance, QDirQueue() by default, to dict of solver queues"""
+    if queue is None:
+        queue = QDirQueue()
+    qName = getattr(queue, "name", "qdir")
+    queues[qName] = queue  # add to solver
+    queues.setdefault("default", queue)
+    initCAE(qName)  # also add to CAE
+    return qName
+
+
+def initCAE(qName):
+    """Register callback to add qName to Abaqus CAE Job queues"""
+    try:
+        from abaqus import addImportCallback, session
+    except ImportError:
+        return  # not running within CAE
+
+    def addQueue(*args):
+        """Add qName to list of selectable Abaqus CAE Job queues"""
+        if qName not in session.queues:
+            session.Queue(name=qName, queueName=qName)
+
+    addImportCallback("job", addQueue)
+
+
+def submitCAEJobs(jobList=None, qName="qdir"):
+    """For specified CAE Jobs (all by default), set the queue and submit to queue"""
+    from abaqus import mdb
+
+    for job in mdb.jobs.values():
+        if not jobList or job.name in jobList:
+            print("Submitting {} to {}".format(job.name, qName))
+            job.setValues(queue=qName)
+            job.submit()
+
+
+class QDirQueue(Queue):
+    """Creates a job script and submits it to a qdir queue."""
+
+    def __init__(self):
+        if hasattr(Queue, "__init__"):
+            Queue.__init__(self)
+        self.name = "qdir"
+        if uti.getPlatform().startswith("win"):
+            # Windows OS
+            self.extension = ".cmd"  # job script filename extension
+            self.setenv = "set"  # shell command to set environment variables
+            self.template = Template(  # job script template
+                dedent(
+                    """\
+                @echo off
+                rem QDIR --name "$job"
+                rem QDIR --output "{name}.log"
+                set JOB="$job"
+                set ABAQUS="$abaqus"
+                $exports
+                cd /D "%~dp0"
+
+                set t=0
+                :do
+                if not exist %JOB%.lck goto done
+                    set /a t+=5
+                    echo Paused %t% seconds for %JOB%.lck to clear
+                    ping 127.0.0.1 -n 6 >nul
+                    if not %t%==90 goto do
+                :done
+
+                %ABAQUS% python -u %JOB%.com
+                """
+                )
+            )
+
+        else:
+            # Non-Windows OS
+            self.extension = ".sh"  # job script filename extension
+            self.setenv = "export"  # shell command to set environment variables
+            self.template = Template(  # job script template
+                dedent(
+                    """\
+                #!/bin/sh
+                #QDIR --name "$job"
+                #QDIR --output "{name}.log"
+                JOB="$job"
+                ABAQUS="$abaqus"
+                $exports
+                cd "$$(dirname "$$0")"
+
+                let t=0
+                while [[ -e "$$JOB.lck" && $$t != 90 ]]
+                do
+                    let t+=5
+                    echo Paused $$t seconds for $$JOB.lck to clear
+                    sleep 5
+                done
+
+                umask 0007
+                exec "$$ABAQUS" python -u "$$JOB.com"
+                """
+                )
+            )
+
+    def exports(self, options, env):
+        """Return a dict of os.environ settings to be inserted into the command script"""
+        extraEnviron = {}
+        if uti.getProductVersion() == "Abaqus 2026":
+            extraEnviron["ABQ_DLALLOCATOR"] = "1"  # example usage for BR10000415659
+        return extraEnviron
+
+    def createJobScript(self, options, env):
+        """Create shell script to run Abaqus job"""
+        job = options["job"]
+        scriptName = os.path.join(".", job + self.extension)
+        exports = self.exports(options, env) or ""
+        if isinstance(exports, dict):
+            # expand dict of os.environ settings to multiline str
+            exports = "\n".join(
+                self.setenv + " {0}={1}".format(*i) for i in sorted(exports.items())
+            )
+
+        with open(scriptName, "w") as jobFile:
+            print(
+                self.template.substitute(
+                    abaqus=env["ABA_COMMAND"],
+                    job=job,
+                    exports=exports,
+                ),
+                file=jobFile,
+            )
+        try:
+            os.chmod(scriptName, 0o775)  # Set permissions
+        except OSError:
+            pass
+        return scriptName
+
+    def submit(self, options, env):
+        """Create Abaqus job script and submit it to qdir"""
+        scriptName = self.createJobScript(options, env)
+        cmd = "qsub {!r}".format(scriptName)
+        localenv = env.copy()
+        if "PYTHONPATH" in localenv:
+            del localenv["PYTHONPATH"]  # avoid version conflicts
+        return self.spawn(cmd, localenv, options.get("verbose", 0))

qdir/qdel.py

@@ -0,0 +1,51 @@
+#!/bin/env python3
+"""Dequeue (remove) specified jobs from the qdir job queue"""
+
+import sys
+from pathlib import Path
+
+from qdir import Queue, parser
+
+parser.description = __doc__
+parser.add_argument(
+    "job", nargs="+", help="The list of job Ids or job names to dequeue."
+)
+
+
+def dequeueJobs(queue, jobList: list[str]):
+    """Remove a list of jobIds or job names from the queue."""
+    queuedJobs: dict[Path, dict] = {}
+    queuedJobs.update(
+        [
+            (qFilePath, queue.getJobInfo(qFilePath))
+            for qFilePath in queue.getQueuedJobs()
+        ]
+    )
+    if not queuedJobs and queue.verbose >= 2:
+        print("No jobs queued", file=sys.stderr)
+    for job in jobList:
+        matched = 0
+        for qFilePath, jobInfo in queuedJobs.items():
+            if job == jobInfo.get("jobId") or job == jobInfo.get("name"):
+                # Matched either jobId or job name
+                matched += 1
+                if queue.verbose >= 3:
+                    print("Dequeing", queue.info.format(**jobInfo))
+                queue.dequeue(qFilePath)
+        if matched == 0 and queue.verbose >= 1:
+            print(job, "is not queued", file=sys.stderr)
+
+
+def qdel(argv):
+    """Dequeue the specified jobId numbers or job names"""
+    options = parser.parse_args(argv[1:])
+    queue = Queue(**vars(options))
+    dequeueJobs(queue, options.job)
+
+
+def main():
+    qdel(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

qdir/qstat.py

@@ -0,0 +1,142 @@
+#!/bin/env python3
+"""Report currrent status of the qdir job queue"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from qdir import Queue, default, parser
+
+parser.description = __doc__
+parser.add_argument(
+    "-f",
+    "--full",
+    action="store_true",
+    help="Report full detailed information in text format.",
+)
+parser.add_argument(
+    "-j",
+    "--json",
+    action="store_true",
+    help="Report full detailed queue status in json format.",
+)
+default.info = os.environ.get("QDIR_INFO", "{jobId:8} {owner:12} {status:35} {name}")
+parser.add_argument(
+    "-i",
+    "--info",
+    help="Specify the shortened format of job information "
+    "when neither --full nor --json are specified. "
+    f"Default is environment variable QDIR_INFO or {default.info!r}",
+    default=default.info,
+)
+parser.add_argument(
+    "job",
+    nargs="*",
+    help="An optional list of job Ids or job names to get status. "
+    "If no jobs are specified then all currently queued jobs will be listed.",
+)
+
+
+if os.name == "nt":
+
+    def winOwner(self) -> str:
+        "Return name of the WindowsPath owner"
+        try:
+            import win32security
+        except ImportError:
+            return "unknown"
+        sd = win32security.GetFileSecurity(
+            str(self), win32security.OWNER_SECURITY_INFORMATION
+        )
+        owner_sid = sd.GetSecurityDescriptorOwner()
+        name, _domain, _type = win32security.LookupAccountSid(None, owner_sid)
+        return name
+
+    try:
+        _ = Path(".").owner()  # test if Path has owner method
+    except NotImplementedError:
+        Path.owner = winOwner  # monkey patch if needed
+
+
+def printStatus(queue, jobList: list[str]):
+    """Print a list of queued jobs"""
+    if queue.verbose >= 2:
+        print("Queue directory", queue.queue)
+    queuedJobs = queue.getQueuedJobs()
+    if not queuedJobs and queue.verbose >= 2:
+        print("No jobs queued")
+    jobHeadings = None
+    for qFilePath in queuedJobs:
+        jobInfo = queue.getJobInfo(qFilePath)
+        if (
+            len(jobList) == 0
+            or jobInfo["jobId"] in jobList
+            or jobInfo["name"] in jobList
+        ):
+            if not jobHeadings and queue.verbose >= 1:
+                jobHeadings = {k: k.upper() for k in jobInfo}
+                print(queue.info.format(**jobHeadings))
+            print(queue.info.format(**jobInfo))
+
+
+def printDetails(queue, jobList: list[str]):
+    """Report full details about queued jobs"""
+    if queue.verbose >= 2:
+        print("Queue directory", queue.queue)
+    queuedJobs = queue.getQueuedJobs()
+    if not queuedJobs and queue.verbose >= 2:
+        print("No jobs queued")
+
+    for qFilePath in queuedJobs:
+        jobInfo = queue.getJobInfo(qFilePath)
+        if (
+            len(jobList) == 0
+            or jobInfo["jobId"] in jobList
+            or jobInfo["name"] in jobList
+        ):
+            print()
+            for key, value in jobInfo.items():
+                if "status" == key:
+                    continue  # Will be included with full history
+                if isinstance(value, list):
+                    print(key.upper(), *value, sep="\n")
+                elif value:
+                    print(f"{key.upper():10} {value}")
+
+
+def printJSON(queue, jobList: list[str]):
+    """Output detailed queue status in JSON format"""
+    jobs = {}
+    for qFilePath in queue.getQueuedJobs():
+        jobInfo = queue.getJobInfo(qFilePath)
+        if (
+            len(jobList) == 0
+            or jobInfo["jobId"] in jobList
+            or jobInfo["name"] in jobList
+        ):
+            jobs[str(qFilePath)] = jobInfo
+    print(json.dumps(jobs, indent=2))
+
+
+def qstat(argv):
+    """Report status of the queue"""
+    options = parser.parse_args(argv[1:])
+    queue = Queue(**vars(options))
+    if options.full:
+        # Report detailed information about jobs in the queue
+        printDetails(queue, options.job)
+    elif options.json:
+        # Report detailed queue status in json format
+        printJSON(queue, options.job)
+    else:
+        # Report list of jobs in queue
+        printStatus(queue, options.job)
+
+
+def main():
+    qstat(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

qdir/qsub.py

@@ -0,0 +1,139 @@
+#!/bin/env python3
+"""Submit a job (command) to the qdir job queue"""
+
+import os
+import subprocess
+import sys
+
+from qdir import Queue, default, parser
+
+dprefix = os.environ.get(
+    "QDIR_DPREFIX",
+    os.environ.get("PBS_DPREFIX", "(#|@?(?i:rem ))(QDIR|PBS)"),
+)  # regular expression prefix used to recognize optional file directives
+
+parser.description = __doc__
+default.name = os.environ.get("PBS_JOBNAME")
+parser.add_argument(
+    "-N",
+    "--name",
+    help="Name for the job. Default is cmd[-1]",
+    default=default.name,
+)
+try:
+    default.interval = max(1, int(os.environ.get("QDIR_POLL_INTERVAL", "5")))
+except ValueError:
+    default.interval = 5
+parser.add_argument(
+    "-c",
+    "--interval",
+    type=int,
+    help="Polling interval in seconds. "
+    f"Default is environment variable QDIR_POLL_INTERVAL or {default.interval}",
+    default=default.interval,
+)
+parser.add_argument(
+    "-f",
+    "--foreground",
+    action="store_true",
+    help="Prevent qsub from forking to wait in background.",
+    default=False,
+)
+default.output = os.environ.get("QDIR_LOGNAME", "{name}._{jobId}")
+parser.add_argument(
+    "-o",
+    "--output",
+    help="File name for combined stdout and stderr. "
+    f"Default is environment variable QDIR_LOGNAME or {default.output!r}",
+    default=default.output,
+)
+default.status = os.environ.get(
+    "QDIR_STATUS", "{jobId} {name} {status} after {duration}"
+)
+parser.add_argument(
+    "-s",
+    "--status",
+    help="Specify the format of job status messages output to terminal. "
+    f"Default is environment variable QDIR_STATUS or {default.status!r}",
+    default=default.status,
+)
+parser.add_argument(
+    "cmd",
+    nargs="+",
+    help="The command to enqueue plus any optional arguments. "
+    "This command must be in your PATH or explicitly specified. ",
+)
+
+
+def parseArguments(argv: list[str]):
+    """Parse the given list of arguments
+
+    Uses commandline arguments for top priority followed by in-file directives
+    and lastly default values.
+
+    In-file directives are the same format as commandline options and should
+    occur in comment lines at the beginning of the job script.
+    Directive lines and are preceeded by the dprefix regular expression.
+    """
+
+    import re
+    import shlex
+
+    # Parse commandline arguments to find cmd
+    argvNamespace = parser.parse_args(argv)
+
+    # Scan cmd[0] for optional file directives
+    directives = []
+    dprefixRe = re.compile(dprefix)
+    commentRe = re.compile("(#|@?(?i:rem|echo))")
+    try:
+        with open(argvNamespace.cmd[0]) as jobScript:
+            for line in jobScript:
+                m = dprefixRe.match(line)
+                if m:
+                    directives.extend(shlex.split(line[m.end() :]))
+                elif len(line.strip()) == 0:
+                    continue  # ignore blank lines
+                elif commentRe.match(line):
+                    continue  # ignore non-directive comment lines
+                else:
+                    break  # otherwise stop processing
+    except OSError:
+        pass
+    directives.append("cmd")
+    _, unknown = parser.parse_known_args(directives)
+
+    # Finally, parse the combined options with priority for argv
+    options, _ = parser.parse_known_args(directives + argv)
+
+    # The cmd may only come from argv
+    options.cmd = argvNamespace.cmd
+
+    if not options.name and len(options.cmd) > 0:
+        options.name = options.cmd[-1]  # default name
+    if unknown and options.verbose >= 2:
+        print("WARNING: Unknown file directives", *unknown, file=sys.stderr)
+    if options.verbose >= 5:
+        print("Arguments", argv, file=sys.stderr)
+        print("Directives", directives, file=sys.stderr)
+        print("options", options, file=sys.stderr)
+    return options
+
+
+def qsub(argv):
+    """Enqueue a new command"""
+    options = parseArguments(argv[1:])
+    if not options.foreground:
+        cmd = [sys.executable, "-m", "qdir.qsub", "-f"] + argv[1:]
+        subprocess.Popen(cmd, start_new_session=True)  # re-run in background
+    else:
+        queue = Queue(**vars(options))
+        queue.enqueue(options.cmd)
+
+
+def main():
+    qsub(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

qdir-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: qdir
+Version: 1.0.0rc1
+Summary: A very low overhead first-in, first-out job queue for the local machine
+Author-email: Carl Osterwisch <costerwi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/costerwi/qdir
+Project-URL: Issues, https://github.com/costerwi/qdir/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: filelock
+Requires-Dist: pywin32; sys_platform == "win32"
+Dynamic: license-file
+
+# qdir
+A very low overhead first-in, first-out job queue for the local machine
+
+The queue is maintained as a directory of tiny job queue files.
+When a new job is submitted, this script will identify any existing job queue files and then add its own queue file to the directory.
+No job will begin until all the preceeding queue files are gone.
+Each job will delete its own queue file upon completion so the next job can begin.
+A shared queue directory can be specified on a multi-user system.
+On Linux this is `/tmp` by default.
+
+Any command may be submitted to the job queue using qsub (see usage below).
+You may check the status of the queue (qstat) and remove jobs (qdel).
+
+# Installation
+Requires python3 running on Windows or Linux.
+One way to get python3 on Windows is through the [Microsoft Store](https://apps.microsoft.com/detail/9PNRBTZXMB4Z).
+Here is the command to install qdir once you have python3 available:
+```bash
+python3 -m pip install qdir
+```
+
+See [here](https://pip.pypa.io/en/stable/installation/) if there is "no module named pip."
+
+## Abaqus Finite Element Analysis (FEA) extras
+The package includes additional files to help Abaqus users submit and monitor the qdir job queue.
+Use the following command to configure Abaqus after qdir itself has been installed:
+```bash
+python3 -m qdir.abaqus install
+```
+
+By default, the necessary settings are appended to the end of your user `abaqus_v6.env` file.
+To uninstall you may removed the settings manually or with this command:
+```bash
+python3 -m qdir.abaqus uninstall
+```
+
+# Usage
+
+## Command line job submission
+Submit commands or scripts to the queue using the `qsub` command.
+For example, on Linux:
+```bash
+qsub ./myJobFile.sh
+```
+or on Windows:
+```bash
+qsub myJobFile.cmd
+```
+
+Any printed output from the command will be saved to a file based on the job name with the job Id appended to the end.
+
+Display command options with `qsub -h`
+
+## Command line queue status
+Check status with the `qstat` command, for example:
+```bash
+qstat
+```
+or, for full details:
+```bash
+qstat -f
+```
+
+## Command line job removal
+First use the `qstat` command above to find the jobIds and job names in the queue.
+Delete or kill jobs with the `qdel` command followed by a jobId or job name.
+For example, to delete job 12343:
+```bash
+qdel 12343
+```
+
+## Abaqus extras
+Submit Abaqus jobs as usual from the command line:
+```bash
+abaqus job=whatever
+```
+This will invoke the `qdir_submit.py` module to create a job script and submit it to qdir.
+
+You may submit jobs within Abaqus CAE by selecting `qdir` as the Job's queue before submitting.
+You may check the queue status within CAE in the menu `Plug-ins > QDir Job Queue Monitor...`
+Click on a Job to see more detailed information.
+Right-click on a Job to expose the menu allowing you to delete the Job.
+
+## Customization
+Most parameters used by the script may be customized with command line options, system environment variables, or directives within the job file itself.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| -N *NAME*, --name *NAME*  | Name for the job. | The last argument of the command |
+| -q *QUEUE*, --queue *QUEUE* | Directory to store the queue files. | environment variable `QDIR_QUEUE` or `/tmp` on Linux |
+| -c *INTERVAL*, --interval *INTERVAL* | Polling interval in seconds. | environment variable `QDIR_POLL_INTERVAL` or 5 |
+| -i *INFO*, --info *INFO*  | Specify the format of information about jobs in queue | environment variable `QDIR_INFO` or `{jobId:8} {owner:12} {status:35} {name}` |
+| -o *OUTPUT*, --output *OUTPUT* | File name for combined stdout and stderr. | environment variable `QDIR_LOGNAME` or `{name}._{jobId}`
+| -s *STATUS*, --status *STATUS* | Specify the format of job status messages output to terminal. | environment variable `QDIR_STATUS` or `{jobId} {name} {status} after {duration}`
+| -v *VERBOSE*, --verbose *VERBOSE* | Set the verbosity level. | environment variable `QDIR_VERBOSE` or 2 |

qdir-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,14 @@
+qdir/__init__.py,sha256=fXPPseM-MlxfFttcdmJYw0uhwTpDWrEqLZeoDN0x5r0,11072
+qdir/qdel.py,sha256=vjDD_zBhtu4R8KkWXMNtxZg6KMXlRU8vO2gEFGHqC7k,1440
+qdir/qstat.py,sha256=J_hsmZASpHGdeqGDFqlmwgrHEQ6N3yuwRHpWtBPHEmQ,4190
+qdir/qsub.py,sha256=0lxm3WAfewV4ebZYufQROuoEubsA3Noq2qL33c6kbnk,4182
+qdir/abaqus/__init__.py,sha256=AqfK9oYkq0oSbXHb-2wZmL5KxbKcvsVy4DS3wbzvkbc,113
+qdir/abaqus/__main__.py,sha256=93NgqW2IAntLmPFFewBdFXnTpMLolm3yfkqbIQDWhws,2034
+qdir/abaqus/qdir_plugin.py,sha256=MsP5goZO2Dqp27xIfxt00pTo6lfampHGJX-XYx40yw8,7864
+qdir/abaqus/qdir_submit.py,sha256=3rLQlRyIWimNAfwxyGG6k50Yc9sflV0AF6s2XC2Lvhg,5349
+qdir-1.0.0rc1.dist-info/licenses/LICENSE,sha256=MuZbvuvcRPehx5RAJMdgAuV0yvzxWaPcQGKPeihaIZY,1072
+qdir-1.0.0rc1.dist-info/METADATA,sha256=MIRNGNHJ5yJz07OzRcieVhTsGuSwbV0j2_8FsUZO00c,4561
+qdir-1.0.0rc1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+qdir-1.0.0rc1.dist-info/entry_points.txt,sha256=zBcB1NgRBXkzcAWnk9jHgHhn1Mk2Yo-oFJFBEWymw8A,86
+qdir-1.0.0rc1.dist-info/top_level.txt,sha256=fRgcgmSYWhMIV8wvfnG7YYMu5qS8PfIabbjXLe6Cj9E,5
+qdir-1.0.0rc1.dist-info/RECORD,,

qdir-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qdir-1.0.0rc1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+qdel = qdir.qdel:main
+qstat = qdir.qstat:main
+qsub = qdir.qsub:main

qdir-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Osterwisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qdir-1.0.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+qdir