threadlepy 0.0.2__tar.gz → 0.1.0__tar.gz

threadlepy-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 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.0/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.0/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.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: threadlepy
+Version: 0.1.0
+Summary: Python wrapper for the Threadle command-line 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
+
+`threadlepy` is a Python client for the **Threadle CLI** JSON interface.
+It starts a Threadle subprocess, sends commands over stdin/stdout, and exposes
+Python wrappers that mirror the core workflow of
+[`YukunJiao/threadleR`](https://github.com/YukunJiao/threadleR).
+
+> Status: experimental. The wrapper names and returned payload shapes follow the
+> Threadle CLI and may evolve with the backend.
+
+`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.
+
+## Installation
+
+```bash
+pip install threadlepy
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+Requirements:
+
+- Python 3.9+
+- A working Threadle CLI executable named `threadle` on `PATH`, or a full path
+  passed to `threadlepy.start()`
+
+## Quick Start
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+threadlepy.configure(timeout=3600)
+threadlepy.start()
+
+examples = th.load_examples("lazega")
+lazega = examples["lazega"]
+
+th.info(lazega)
+th.get_node_alters(lazega, nodeid=23, layernames="friends", direction="out")
+th.shortest_path(lazega, node1id=1, node2id=23, layernames="friends")
+
+threadlepy.stop()
+```
+
+You can also manage the Threadle process with a context manager:
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+with threadlepy.session(timeout=3600):
+    examples = th.load_examples("mynet")
+    print(th.info(examples["mynet"]))
+```
+
+If `threadle` is not on `PATH`, pass the full executable path to
+`threadlepy.start("/full/path/to/threadle")` or
+`threadlepy.session("/full/path/to/threadle")`.
+
+## Integration Test Script
+
+The repository includes a threadleR-style smoke test that exercises the public
+command wrappers against bundled example data:
+
+```bash
+python scripts/test_commands.py
+```
+
+If `threadle` is not on `PATH`, pass the executable explicitly:
+
+```bash
+python scripts/test_commands.py --threadle /full/path/to/threadle
+```
+
+There is also a small lifecycle smoke test for the recommended scripting style
+with `threadlepy.session()`:
+
+```bash
+python scripts/test_session.py
+```
+
+or:
+
+```bash
+python scripts/test_session.py --threadle /full/path/to/threadle
+```
+
+The script:
+
+- starts and stops the Threadle CLI process
+- loads `mynet` from the bundled example data
+- runs inventory, metadata, node, attribute, edge, path, degree, density,
+  component, two-mode, transformation, import/export, raw-command, and cleanup
+  commands
+- creates a scratch network for mutating commands so the example workflow stays
+  easy to inspect
+
+When the Threadle executable is unavailable, the script exits with code `77`
+and prints a skip message.
+
+## Tutorial Notebook
+
+A runnable tutorial notebook is available at:
+
+```text
+docs/threadlepy_tutorial.ipynb
+```
+
+Open it with Jupyter, VS Code, or another notebook UI:
+
+```bash
+jupyter notebook docs/threadlepy_tutorial.ipynb
+```
+
+The notebook follows the same design as the threadleR vignette: start Threadle,
+load example data, inspect nodes and attributes, work with one-mode and two-mode
+layers, derive structures, edit a scratch network, import/export files, and
+clean up.
+
+## Handles
+
+Commands that create or load structures return lightweight Python handles:
+
+```python
+ns = th.create_nodeset("ns", createnodes=5)
+net = th.create_network("net", ns)
+```
+
+A handle stores the backend variable name. Any wrapper that expects a network or
+nodeset also accepts the raw backend name as a string.
+
+Most wrappers are available in two styles: Pythonic names such as
+`create_nodeset()` and `shortest_path()`, plus `threadleR`-style aliases such as
+`th_create_nodeset()` and `th_shortest_path()`.
+
+## Working Directory and Examples
+
+```python
+th.get_workdir()
+th.set_workdir("~/my_threadle_workspace")
+th.sync_wd()
+
+example_dir = th.stage_examples_to_wd("threadle_examples")
+th.set_workdir(example_dir)
+```
+
+Bundled datasets can be loaded directly:
+
+```python
+objs = th.load_examples(["mynet", "lazega"])
+mynet = objs["mynet"]
+```
+
+## Creating and Editing Networks
+
+```python
+ns = th.create_nodeset("people", createnodes=10)
+net = th.create_network("relations", ns)
+
+th.add_layer(net, "friends", mode=1, directed=False, valuetype="binary")
+th.add_edge(net, "friends", 1, 2)
+th.check_edge(net, "friends", 1, 2)
+th.remove_edge(net, "friends", 1, 2)
+
+th.add_layer(net, "clubs", mode=2)
+th.add_hyper(net, "clubs", "club_a", nodes=[1, 2, 3])
+th.add_aff(net, "clubs", nodeid=4, hypername="club_a")
+th.get_hyperedge_nodes(net, "clubs", "club_a")
+```
+
+## Attributes
+
+```python
+th.define_attr(ns, "group", "string")
+th.set_attr(ns, nodeid=1, attrname="group", attrvalue="A")
+th.get_attr(ns, nodeid=1, attrname="group")
+
+th.generate_attr(ns, "score", attrtype="int", min=1, max=10)
+th.get_attr_summary(ns, "score")
+th.get_attrs(ns, nodes=[1, 2, 3], attrname="score")
+```
+
+## Queries and Measures
+
+```python
+th.get_all_nodes(ns, offset=0, limit=100)
+th.get_all_edges(net, "friends", offset=0, limit=1000)
+th.get_degree(net, nodeid=1, layernames="friends", direction="both")
+th.degree(net, "friends", attrname="friends_degree", direction="both")
+th.density(net, "friends", samplesize=500)
+th.components(net, "friends", attrname="component")
+```
+
+Multiple layer names can be passed as a Python list; the client sends the
+semicolon-separated format expected by Threadle:
+
+```python
+th.shortest_path(net, 1, 8, layernames=["friends", "coworkers"])
+```
+
+## Transformations and Random Walks
+
+```python
+th.symmetrize(net, "advice", method="max", newlayername="advice_sym")
+th.project_two_mode(net, "clubs", method="count", newlayername="club_projection")
+th.pack(net, "friends")
+th.unpack(net, "friends")
+
+rw = th.rwdistances("rw_dist", net, attrname="group", maxsteps=100)
+mfpt = th.rwfpt("mfpt", net, attrname="group", maxsteps=100, minpairobs=10)
+```
+
+## File IO
+
+```python
+th.save_file(ns, "people.tsv")
+ns2 = th.load_file("people2", "people.tsv", type="nodeset")
+
+th.export_layer(net, "friends", "friends.tsv", header=True, sep="\t")
+th.import_layer(net, "friends", "friends.tsv", format="edgelist", header=True)
+th.export(net, format="gexf", file="friends.gexf", layername="friends")
+```
+
+## Raw Commands
+
+Use `threadlepy.raw_cmd()` or `th.cmd()` for backend commands that do not yet
+have a typed wrapper:
+
+```python
+payload = threadlepy.raw_cmd("i")
+handle = th.cmd("createnodeset", {"createnodes": 3}, assign="tmp", type="nodeset")
+```
+
+## Function Coverage
+
+`threadlepy.commands` includes wrappers for Threadle process workflow,
+inventory, file IO, layer editing, node editing, attributes, shortest paths,
+degree and density, components, random generation, random walks, packing,
+projection, filtering, subnetwork creation, and export utilities.
+
+## Release Checklist
+
+Before publishing a new PyPI release:
+
+```bash
+python3 -m compileall src/threadlepy scripts/test_commands.py
+python3 -m json.tool docs/threadlepy_tutorial.ipynb > /tmp/threadlepy_tutorial_checked.json
+python3 scripts/test_commands.py
+python3 scripts/test_session.py
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Use TestPyPI first when publishing a new release line.

threadlepy-0.1.0/README.md

@@ -0,0 +1,261 @@
+# threadlepy
+
+`threadlepy` is a Python client for the **Threadle CLI** JSON interface.
+It starts a Threadle subprocess, sends commands over stdin/stdout, and exposes
+Python wrappers that mirror the core workflow of
+[`YukunJiao/threadleR`](https://github.com/YukunJiao/threadleR).
+
+> Status: experimental. The wrapper names and returned payload shapes follow the
+> Threadle CLI and may evolve with the backend.
+
+`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.
+
+## Installation
+
+```bash
+pip install threadlepy
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+Requirements:
+
+- Python 3.9+
+- A working Threadle CLI executable named `threadle` on `PATH`, or a full path
+  passed to `threadlepy.start()`
+
+## Quick Start
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+threadlepy.configure(timeout=3600)
+threadlepy.start()
+
+examples = th.load_examples("lazega")
+lazega = examples["lazega"]
+
+th.info(lazega)
+th.get_node_alters(lazega, nodeid=23, layernames="friends", direction="out")
+th.shortest_path(lazega, node1id=1, node2id=23, layernames="friends")
+
+threadlepy.stop()
+```
+
+You can also manage the Threadle process with a context manager:
+
+```python
+import threadlepy
+import threadlepy.commands as th
+
+with threadlepy.session(timeout=3600):
+    examples = th.load_examples("mynet")
+    print(th.info(examples["mynet"]))
+```
+
+If `threadle` is not on `PATH`, pass the full executable path to
+`threadlepy.start("/full/path/to/threadle")` or
+`threadlepy.session("/full/path/to/threadle")`.
+
+## Integration Test Script
+
+The repository includes a threadleR-style smoke test that exercises the public
+command wrappers against bundled example data:
+
+```bash
+python scripts/test_commands.py
+```
+
+If `threadle` is not on `PATH`, pass the executable explicitly:
+
+```bash
+python scripts/test_commands.py --threadle /full/path/to/threadle
+```
+
+There is also a small lifecycle smoke test for the recommended scripting style
+with `threadlepy.session()`:
+
+```bash
+python scripts/test_session.py
+```
+
+or:
+
+```bash
+python scripts/test_session.py --threadle /full/path/to/threadle
+```
+
+The script:
+
+- starts and stops the Threadle CLI process
+- loads `mynet` from the bundled example data
+- runs inventory, metadata, node, attribute, edge, path, degree, density,
+  component, two-mode, transformation, import/export, raw-command, and cleanup
+  commands
+- creates a scratch network for mutating commands so the example workflow stays
+  easy to inspect
+
+When the Threadle executable is unavailable, the script exits with code `77`
+and prints a skip message.
+
+## Tutorial Notebook
+
+A runnable tutorial notebook is available at:
+
+```text
+docs/threadlepy_tutorial.ipynb
+```
+
+Open it with Jupyter, VS Code, or another notebook UI:
+
+```bash
+jupyter notebook docs/threadlepy_tutorial.ipynb
+```
+
+The notebook follows the same design as the threadleR vignette: start Threadle,
+load example data, inspect nodes and attributes, work with one-mode and two-mode
+layers, derive structures, edit a scratch network, import/export files, and
+clean up.
+
+## Handles
+
+Commands that create or load structures return lightweight Python handles:
+
+```python
+ns = th.create_nodeset("ns", createnodes=5)
+net = th.create_network("net", ns)
+```
+
+A handle stores the backend variable name. Any wrapper that expects a network or
+nodeset also accepts the raw backend name as a string.
+
+Most wrappers are available in two styles: Pythonic names such as
+`create_nodeset()` and `shortest_path()`, plus `threadleR`-style aliases such as
+`th_create_nodeset()` and `th_shortest_path()`.
+
+## Working Directory and Examples
+
+```python
+th.get_workdir()
+th.set_workdir("~/my_threadle_workspace")
+th.sync_wd()
+
+example_dir = th.stage_examples_to_wd("threadle_examples")
+th.set_workdir(example_dir)
+```
+
+Bundled datasets can be loaded directly:
+
+```python
+objs = th.load_examples(["mynet", "lazega"])
+mynet = objs["mynet"]
+```
+
+## Creating and Editing Networks
+
+```python
+ns = th.create_nodeset("people", createnodes=10)
+net = th.create_network("relations", ns)
+
+th.add_layer(net, "friends", mode=1, directed=False, valuetype="binary")
+th.add_edge(net, "friends", 1, 2)
+th.check_edge(net, "friends", 1, 2)
+th.remove_edge(net, "friends", 1, 2)
+
+th.add_layer(net, "clubs", mode=2)
+th.add_hyper(net, "clubs", "club_a", nodes=[1, 2, 3])
+th.add_aff(net, "clubs", nodeid=4, hypername="club_a")
+th.get_hyperedge_nodes(net, "clubs", "club_a")
+```
+
+## Attributes
+
+```python
+th.define_attr(ns, "group", "string")
+th.set_attr(ns, nodeid=1, attrname="group", attrvalue="A")
+th.get_attr(ns, nodeid=1, attrname="group")
+
+th.generate_attr(ns, "score", attrtype="int", min=1, max=10)
+th.get_attr_summary(ns, "score")
+th.get_attrs(ns, nodes=[1, 2, 3], attrname="score")
+```
+
+## Queries and Measures
+
+```python
+th.get_all_nodes(ns, offset=0, limit=100)
+th.get_all_edges(net, "friends", offset=0, limit=1000)
+th.get_degree(net, nodeid=1, layernames="friends", direction="both")
+th.degree(net, "friends", attrname="friends_degree", direction="both")
+th.density(net, "friends", samplesize=500)
+th.components(net, "friends", attrname="component")
+```
+
+Multiple layer names can be passed as a Python list; the client sends the
+semicolon-separated format expected by Threadle:
+
+```python
+th.shortest_path(net, 1, 8, layernames=["friends", "coworkers"])
+```
+
+## Transformations and Random Walks
+
+```python
+th.symmetrize(net, "advice", method="max", newlayername="advice_sym")
+th.project_two_mode(net, "clubs", method="count", newlayername="club_projection")
+th.pack(net, "friends")
+th.unpack(net, "friends")
+
+rw = th.rwdistances("rw_dist", net, attrname="group", maxsteps=100)
+mfpt = th.rwfpt("mfpt", net, attrname="group", maxsteps=100, minpairobs=10)
+```
+
+## File IO
+
+```python
+th.save_file(ns, "people.tsv")
+ns2 = th.load_file("people2", "people.tsv", type="nodeset")
+
+th.export_layer(net, "friends", "friends.tsv", header=True, sep="\t")
+th.import_layer(net, "friends", "friends.tsv", format="edgelist", header=True)
+th.export(net, format="gexf", file="friends.gexf", layername="friends")
+```
+
+## Raw Commands
+
+Use `threadlepy.raw_cmd()` or `th.cmd()` for backend commands that do not yet
+have a typed wrapper:
+
+```python
+payload = threadlepy.raw_cmd("i")
+handle = th.cmd("createnodeset", {"createnodes": 3}, assign="tmp", type="nodeset")
+```
+
+## Function Coverage
+
+`threadlepy.commands` includes wrappers for Threadle process workflow,
+inventory, file IO, layer editing, node editing, attributes, shortest paths,
+degree and density, components, random generation, random walks, packing,
+projection, filtering, subnetwork creation, and export utilities.
+
+## Release Checklist
+
+Before publishing a new PyPI release:
+
+```bash
+python3 -m compileall src/threadlepy scripts/test_commands.py
+python3 -m json.tool docs/threadlepy_tutorial.ipynb > /tmp/threadlepy_tutorial_checked.json
+python3 scripts/test_commands.py
+python3 scripts/test_session.py
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Use TestPyPI first when publishing a new release line.