threadlepy 0.1.0__tar.gz → 0.1.2__tar.gz

{threadlepy-0.1.0 → threadlepy-0.1.2}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.2
+
+- Added one-line docstrings for public command wrappers.
+- Added `Literal` type hints for finite-choice parameters to improve editor completions.
+- Marked the package as typed with `py.typed`.
+
+## 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.

{threadlepy-0.1.0 → threadlepy-0.1.2}/MANIFEST.in

@@ -4,6 +4,7 @@ include CHANGELOG.md
 include pyproject.toml
 
 recursive-include src/threadlepy/Examples *.tsv *.txt
+include src/threadlepy/py.typed
 recursive-include docs *.ipynb
 recursive-include scripts *.py
 

threadlepy-0.1.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: threadlepy
+Version: 0.1.2
+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.2/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.0 → threadlepy-0.1.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadlepy"
-version = "0.1.0"
-description = "Python wrapper for the Threadle command-line interface"
+version = "0.1.2"
+description = "Python client for the Threadle CLI JSON interface."
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
@@ -27,4 +27,4 @@ Source = "https://github.com/YukunJiao/threadlepy"
 where = ["src"]
 
 [tool.setuptools.package-data]
-threadlepy = ["Examples/*.tsv", "Examples/Scripts/*.txt"]
+threadlepy = ["py.typed", "Examples/*.tsv", "Examples/Scripts/*.txt"]

{threadlepy-0.1.0 → threadlepy-0.1.2}/src/threadlepy/__init__.py

@@ -2,7 +2,7 @@
 
 from .client import ThreadleStruct, configure, is_available, raw_cmd, session, start, stop
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "ThreadleStruct",

{threadlepy-0.1.0 → threadlepy-0.1.2}/src/threadlepy/client.py

@@ -48,6 +48,7 @@ def configure(
         default_timeout = float(timeout)
 
 def stop():
+    """Stop the running Threadle subprocess, if one is active."""
     global proc
     if proc and proc.poll() is None:
         print("threadle stopped")
@@ -56,6 +57,7 @@ def stop():
     proc = None
 
 def start(path: str | None = None) -> subprocess.Popen[str]:
+    """Start the Threadle CLI JSON subprocess and return the process handle."""
     global proc
     if path is None or not str(path).strip():
         exe = shutil.which("threadle")
@@ -112,9 +114,11 @@ def session(path: str | None = None, **config: Any) -> Iterator[subprocess.Popen
         stop()
 
 def collect_args(**kwargs):
+    """Return keyword arguments whose values are not ``None``."""
     return {k: v for k, v in kwargs.items() if v is not None}
 
 def json_cmd(command: str, args: Optional[Dict[str, Any]] = None, assign: Optional[str] = None) -> str:
+    """Build a JSON command payload for the Threadle CLI."""
     dto = {
         "Assign": assign,
         "Command": str(command),
@@ -123,6 +127,7 @@ def json_cmd(command: str, args: Optional[Dict[str, Any]] = None, assign: Option
     return json.dumps(dto, ensure_ascii=False)
 
 def send_command(cmd_json: str, timeout: Optional[float] = None) -> Dict[str, Any]:
+    """Send a JSON command to Threadle and wait for a JSON response."""
     global proc
     if proc is None or proc.poll() is not None:
         raise RuntimeError("Threadle process is not running.")
@@ -177,6 +182,7 @@ def send_command(cmd_json: str, timeout: Optional[float] = None) -> Dict[str, An
     raise TimeoutError(hint)
 
 def unwrap(resp: Dict[str, Any], *, print_message: bool = True) -> Any:
+    """Validate a Threadle response and return its payload."""
     if resp.get("Success") is not True:
         code = resp.get("Code") or "Error"
         msg = resp.get("Message") or "Threadle error"
@@ -209,6 +215,7 @@ def call(
     return_response: bool = False,
     drop: tuple[str, ...] = (),
 ) -> Any:
+    """Call a typed Threadle command wrapper using the caller's local variables."""
     args = collect_args(**locals_dict)
     args.pop("cmd", None)
     args.pop("assign", None)