threadlepy 0.0.2__tar.gz → 0.1.1__tar.gz

threadlepy-0.1.1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.1
+
+- Updated PyPI project description to match README.
+- Synchronized package metadata version with the 0.1.1 release.
+
+## 0.1.0
+
+- Expanded Python command wrappers to better correspond to Threadle.
+- Added `th_*` aliases for users moving between threadleR and threadlepy.
+- Added bundled example-data workflow through `load_examples()`.
+- Added `scripts/test_commands.py` integration smoke test.
+- Added `scripts/test_session.py` smoke test for context-managed sessions.
+- Added `docs/threadlepy_tutorial.ipynb` tutorial notebook.
+- Added `threadlepy.session()` for context-managed Threadle process lifecycle.
+- Improved Threadle executable checks and process-exit error reporting.
+- Improved API compatibility for `layername` / `layernames`, `th_cmd(cmd=...)`, `addmissingaffiliation`, and related legacy arguments.
+- Added package-data configuration for example TSV and script files.
+- Cleaned generated artifacts from the repository and updated `.gitignore`.
+
+threadlepy follows its own PyPI versioning. Its API is designed to correspond
+to Threadle CLI commands and is inspired by threadleR, but version numbers are
+not synchronized with threadleR releases.

threadlepy-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yukun Jiao
+
+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.

threadlepy-0.1.1/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+
+recursive-include src/threadlepy/Examples *.tsv *.txt
+recursive-include docs *.ipynb
+recursive-include scripts *.py
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store
+global-exclude .Rhistory

threadlepy-0.1.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: threadlepy
+Version: 0.1.1
+Summary: Python client for the Threadle CLI JSON interface.
+Author: Yukun Jiao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YukunJiao/threadlepy
+Project-URL: Issues, https://github.com/YukunJiao/threadlepy/issues
+Project-URL: Documentation, https://github.com/YukunJiao/threadlepy#readme
+Project-URL: Source, https://github.com/YukunJiao/threadlepy
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# threadlepy
+
+Python client for the Threadle CLI JSON interface.
+
+`threadlepy` starts a Threadle subprocess and exposes Python wrappers for core Threadle workflows.
+
+## Installation
+
+```bash
+pip install threadlepy
+```
+
+Requirements:
+
+- Python 3.9+
+- A working `threadle` executable available on `PATH`
+
+## Quick Start
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+with threadlepy.session(timeout=3600):
+    examples = th.load_examples("lazega")
+    lazega = examples["lazega"]
+
+    print(th.info(lazega))
+
+    path = th.shortest_path(
+        lazega,
+        node1id=1,
+        node2id=23,
+        layernames="friends",
+    )
+
+    print(path)
+```
+
+If `threadle` is not on `PATH`, pass the executable path explicitly:
+
+```python
+threadlepy.start("/full/path/to/threadle")
+```
+
+## Documentation
+
+For more examples and workflows, see:
+
+```text
+docs/threadlepy_tutorial.ipynb
+```

threadlepy-0.1.1/README.md

@@ -0,0 +1,52 @@
+# threadlepy
+
+Python client for the Threadle CLI JSON interface.
+
+`threadlepy` starts a Threadle subprocess and exposes Python wrappers for core Threadle workflows.
+
+## Installation
+
+```bash
+pip install threadlepy
+```
+
+Requirements:
+
+- Python 3.9+
+- A working `threadle` executable available on `PATH`
+
+## Quick Start
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+with threadlepy.session(timeout=3600):
+    examples = th.load_examples("lazega")
+    lazega = examples["lazega"]
+
+    print(th.info(lazega))
+
+    path = th.shortest_path(
+        lazega,
+        node1id=1,
+        node2id=23,
+        layernames="friends",
+    )
+
+    print(path)
+```
+
+If `threadle` is not on `PATH`, pass the executable path explicitly:
+
+```python
+threadlepy.start("/full/path/to/threadle")
+```
+
+## Documentation
+
+For more examples and workflows, see:
+
+```text
+docs/threadlepy_tutorial.ipynb
+```

threadlepy-0.1.1/docs/threadlepy_tutorial.ipynb

@@ -0,0 +1,407 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# threadlepy tutorial\n",
+    "\n",
+    "This notebook mirrors the public workflow of `YukunJiao/threadleR`, but uses Python wrappers from `threadlepy`. It loads bundled example data, explores nodes and layers, edits a scratch network, and demonstrates import/export.\n",
+    "\n",
+    "You need a working Threadle CLI executable. This tutorial assumes `threadle` is already on `PATH`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a211e5be",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "import threadlepy\n",
+    "import threadlepy.commands as th\n",
+    "\n",
+    "threadlepy.__version__, threadlepy.is_available()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e7e3e731",
+   "metadata": {},
+   "source": [
+    "## Start Threadle\n",
+    "\n",
+    "Start a background Threadle process in JSON mode. The client sends one JSON command per wrapper call and returns the backend payload.\n",
+    "\n",
+    "For scripts, `with threadlepy.session():` is the most convenient lifecycle helper. In a notebook, explicit `start()` / `stop()` cells make it easier to rerun sections interactively."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "45f9c4d3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "threadlepy.configure(print_messages=False, timeout=1800)\n",
+    "threadlepy.start()\n",
+    "tutorial_workdir = th.get_workdir()\n",
+    "tutorial_workdir"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "77370a1b",
+   "metadata": {},
+   "source": [
+    "## Load example data\n",
+    "\n",
+    "`load_examples()` loads the package data under `src/threadlepy/Examples`. The returned objects are lightweight handles that store the backend variable name."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "324095ef",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "examples = th.load_examples(\"mynet\")\n",
+    "mynet = examples[\"mynet\"]\n",
+    "mynet_nodeset = examples[\"mynet_nodeset\"]\n",
+    "\n",
+    "# `load_examples()` switches Threadle to the example-data folder.\n",
+    "# Switch back so Threadle file exports and Python open() use the same folder.\n",
+    "th.set_workdir(tutorial_workdir)\n",
+    "\n",
+    "th.i(), th.info(mynet), th.info(mynet_nodeset)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9518caff",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_workdir()\n",
+    "th.dir()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8a49716",
+   "metadata": {},
+   "source": [
+    "## Nodes and attributes\n",
+    "\n",
+    "Node commands work on either a nodeset handle or a network handle, since Threadle networks carry an underlying nodeset."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aa877fd0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_nbr_nodes(mynet)\n",
+    "th.get_all_nodes(mynet, offset=0, limit=8)\n",
+    "th.get_nodeid_by_index(mynet, index=0)\n",
+    "th.get_random_node(mynet)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "91099c34",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_attr(mynet_nodeset, nodeid=123, attrname=\"gender\")\n",
+    "th.get_attrs(mynet_nodeset, nodes=[123, 234, 345], attrname=\"gender\")\n",
+    "th.get_attr_summary(mynet_nodeset, attrname=\"gender\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e1dfd3ef",
+   "metadata": {},
+   "source": [
+    "## One-mode layers\n",
+    "\n",
+    "`mynet` includes one-mode layers named `kinship` and `trade`. Use them for edge, alter, degree, density, component, and shortest-path commands."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8ef3910f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_edge(mynet, \"trade\", node1id=123, node2id=345)\n",
+    "th.check_edge(mynet, \"kinship\", node1id=123, node2id=345)\n",
+    "th.get_all_edges(mynet, \"trade\", offset=0, limit=10)\n",
+    "th.get_random_edge(mynet, \"trade\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "47b059f8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_node_alters(mynet, nodeid=345, layernames=\"trade\", direction=\"both\")\n",
+    "th.get_degree(mynet, nodeid=345, layernames=\"trade\", direction=\"both\")\n",
+    "th.get_random_alter(mynet, nodeid=345, layernames=\"trade\", direction=\"both\")\n",
+    "th.density(mynet, \"kinship\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2d4ed293",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.components(mynet, \"kinship\", attrname=\"kinship_component\")\n",
+    "th.degree(mynet, \"kinship\", attrname=\"kinship_degree\", direction=\"both\")\n",
+    "th.get_attr_summary(mynet, \"kinship_degree\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3f9f6401",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.shortest_path(mynet, node1id=123, node2id=567, layernames=\"kinship\")\n",
+    "paths_by_gender = th.shortest_paths(\"paths_by_gender\", mynet, attrname=\"gender\", layernames=\"kinship\")\n",
+    "th.info(paths_by_gender)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c850d95b",
+   "metadata": {},
+   "source": [
+    "## Two-mode layers\n",
+    "\n",
+    "The `work` layer is a two-mode affiliation layer. Hyperedge helpers use `hypername` for the affiliation name."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "799c7042",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.get_all_hyperedges(mynet, \"work\", offset=0, limit=10)\n",
+    "th.get_hyperedge_nodes(mynet, \"work\", hypername=\"ias\")\n",
+    "th.get_node_hyperedges(mynet, \"work\", nodeid=123)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "eea3beb8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.add_hyper(mynet, \"work\", hypername=\"py_temp\", nodes=[123, 234])\n",
+    "th.add_aff(mynet, \"work\", nodeid=345, hypername=\"py_temp\")\n",
+    "th.get_hyperedge_nodes(mynet, \"work\", hypername=\"py_temp\")\n",
+    "\n",
+    "th.remove_aff(mynet, \"work\", nodeid=345, hypername=\"py_temp\")\n",
+    "th.remove_hyper(mynet, \"work\", hypername=\"py_temp\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e31d7274",
+   "metadata": {},
+   "source": [
+    "## Derived structures and transformations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "65e52e2f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "female_nodeset = th.filter(\"female_nodeset\", mynet_nodeset, attrname=\"gender\", cond=\"eq\", attrvalue=\"f\")\n",
+    "female_mynet = th.subnet(\"female_mynet\", mynet, female_nodeset)\n",
+    "th.info(female_nodeset), th.info(female_mynet)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "70453631",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.symmetrize(mynet, \"trade\", method=\"max\", newlayername=\"trade_sym\")\n",
+    "th.dichotomize(mynet, \"trade\", cond=\"ge\", threshold=1000, truevalue=1, falsevalue=0, newlayername=\"trade_hi\")\n",
+    "th.project_two_mode(mynet, \"work\", method=\"count\", newlayername=\"work_projected\")\n",
+    "\n",
+    "th.get_edge(mynet, \"trade_sym\", 123, 345)\n",
+    "th.get_edge(mynet, \"trade_hi\", 890, 234)\n",
+    "th.get_edge(mynet, \"work_projected\", 123, 456)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d893d41e",
+   "metadata": {},
+   "source": [
+    "## Scratch network editing\n",
+    "\n",
+    "Use scratch structures when learning mutating commands. This keeps the bundled example network easy to inspect."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6f6cf7c2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "scratch_nodes = th.create_nodeset(\"scratch_nodes\", name=\"Scratch nodes\", createnodes=5)\n",
+    "scratch_net = th.create_network(\"scratch_net\", scratch_nodes, name=\"Scratch network\")\n",
+    "\n",
+    "th.add_layer(scratch_net, \"friendship\", mode=1, directed=False, valuetype=\"binary\")\n",
+    "th.add_edge(scratch_net, \"friendship\", node1id=1, node2id=2)\n",
+    "th.check_edge(scratch_net, \"friendship\", node1id=1, node2id=2)\n",
+    "th.remove_edge(scratch_net, \"friendship\", node1id=1, node2id=2)\n",
+    "th.clear_layer(scratch_net, \"friendship\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "65f4f4a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.add_node(scratch_nodes, nodeid=10)\n",
+    "th.get_all_nodes(scratch_nodes, offset=0, limit=20)\n",
+    "th.remove_node(scratch_nodes, nodeid=10)\n",
+    "\n",
+    "th.define_attr(scratch_nodes, \"score\", \"int\")\n",
+    "th.set_attr(scratch_nodes, nodeid=1, attrname=\"score\", attrvalue=7)\n",
+    "th.get_attr(scratch_nodes, nodeid=1, attrname=\"score\")\n",
+    "th.remove_attr(scratch_nodes, nodeid=1, attrname=\"score\")\n",
+    "th.undefine_attr(scratch_nodes, \"score\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "eaa65364",
+   "metadata": {},
+   "source": [
+    "## Import and export"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9fc188d4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exported_file = os.path.join(tutorial_workdir, \"kinship_export.tsv\")\n",
+    "import_file = os.path.join(tutorial_workdir, \"imported_edges.tsv\")\n",
+    "saved_nodes_file = os.path.join(tutorial_workdir, \"scratch_nodes_saved.tsv\")\n",
+    "\n",
+    "th.export_layer(mynet, \"kinship\", file=exported_file, header=True, sep=\"\\t\")\n",
+    "with open(exported_file, encoding=\"utf-8\") as f:\n",
+    "    print(f.read().splitlines()[:3])\n",
+    "\n",
+    "with open(import_file, \"w\", encoding=\"utf-8\") as f:\n",
+    "    f.write(\"1\\t2\\t4\\n2\\t3\\t5\\n\")\n",
+    "\n",
+    "th.add_layer(scratch_net, \"imported_edges\", mode=1, directed=False, valuetype=\"valued\")\n",
+    "th.import_layer(scratch_net, \"imported_edges\", file=import_file, format=\"edgelist\", header=False, addmissingnodes=True)\n",
+    "print(th.get_edge(scratch_net, \"imported_edges\", node1id=1, node2id=2))\n",
+    "\n",
+    "th.save_file(scratch_nodes, file=saved_nodes_file)\n",
+    "scratch_copy = th.load_file(\"scratch_nodes_copy\", file=saved_nodes_file, type=\"nodeset\")\n",
+    "print(th.get_nbr_nodes(scratch_copy))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Remove files created by the import/export example.\n",
+    "for file in [exported_file, import_file, saved_nodes_file]:\n",
+    "    try:\n",
+    "        os.remove(file)\n",
+    "    except FileNotFoundError:\n",
+    "        pass"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8334003a",
+   "metadata": {},
+   "source": [
+    "## Low-level commands and cleanup"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d0e2ee3c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "th.cmd(\"info\", args={\"structure\": mynet})\n",
+    "th.delete_all()\n",
+    "th.i()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "81c36469",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "threadlepy.stop()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

threadlepy-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "threadlepy"
+version = "0.1.1"
+description = "Python client for the Threadle CLI JSON interface."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Yukun Jiao" }
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/YukunJiao/threadlepy"
+Issues = "https://github.com/YukunJiao/threadlepy/issues"
+Documentation = "https://github.com/YukunJiao/threadlepy#readme"
+Source = "https://github.com/YukunJiao/threadlepy"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+threadlepy = ["Examples/*.tsv", "Examples/Scripts/*.txt"]