brainstem-python-api-tools 0.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

brainstem_api_tools/cli.py

@@ -0,0 +1,180 @@
+"""Command-line interface for BrainSTEM API tools.
+
+Usage examples
+--------------
+  brainstem login
+  brainstem login --headless
+  brainstem login --url http://127.0.0.1:8000/
+  brainstem logout
+  brainstem load session
+  brainstem load session --portal public --filters name.icontains=rat --sort -name
+  brainstem load session --id <uuid>
+  brainstem load session --limit 20 --offset 40
+  brainstem save session --data '{"name":"New","projects":["<uuid>"]}'
+  brainstem save session --id <uuid> --data '{"description":"updated"}'
+  brainstem delete session --id <uuid>
+"""
+
+import argparse
+import json
+import os
+import sys
+
+from .brainstem_api_client import BrainstemClient, _MODEL_TO_APP, _TOKEN_FILE
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # Shared flags available on every subcommand
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--token",
+        default=os.environ.get("BRAINSTEM_API_TOKEN"),
+        help="API token. Defaults to $BRAINSTEM_API_TOKEN or the cached token.",
+    )
+    common.add_argument(
+        "--headless",
+        action="store_true",
+        help="Print verification URL + code instead of opening a browser.",
+    )
+    common.add_argument(
+        "--url",
+        default=None,
+        help="Base URL of the BrainSTEM server (default: https://www.brainstem.org/).",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="brainstem",
+        description="BrainSTEM command-line API client.",
+        parents=[common],
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ---- login ------------------------------------------------------
+    sub.add_parser(
+        "login",
+        parents=[common],
+        help="Authenticate and cache your API token.",
+    )
+
+    # ---- logout -----------------------------------------------------
+    sub.add_parser(
+        "logout",
+        parents=[common],
+        help="Remove the cached API token.",
+    )
+
+    # ---- load -------------------------------------------------------
+    p_load = sub.add_parser("load", parents=[common], help="Load records from BrainSTEM.")
+    p_load.add_argument("model", choices=sorted(_MODEL_TO_APP), help="Model name.")
+    p_load.add_argument("--portal", default="private", help="'private' or 'public'.")
+    p_load.add_argument("--id", help="UUID of a specific record.")
+    p_load.add_argument(
+        "--filters",
+        nargs="+",
+        metavar="FIELD=VALUE",
+        help="Filter expressions, e.g. name.icontains=rat",
+    )
+    p_load.add_argument(
+        "--sort",
+        nargs="+",
+        metavar="FIELD",
+        help="Sort fields. Prefix with '-' for descending.",
+    )
+    p_load.add_argument(
+        "--include",
+        nargs="+",
+        metavar="RELATION",
+        help="Related models to embed.",
+    )
+    p_load.add_argument("--limit", type=int, help="Max records (API max: 100).")
+    p_load.add_argument("--offset", type=int, help="Records to skip (pagination).")
+
+    # ---- save -------------------------------------------------------
+    p_save = sub.add_parser("save", parents=[common], help="Create or update a record.")
+    p_save.add_argument("model", choices=sorted(_MODEL_TO_APP), help="Model name.")
+    p_save.add_argument("--portal", default="private")
+    p_save.add_argument("--id", help="UUID of the record to update (omit to create).")
+    p_save.add_argument(
+        "--data",
+        required=True,
+        help="JSON string of fields to submit, e.g. '{\"name\":\"x\"}'.",
+    )
+
+    # ---- delete -----------------------------------------------------
+    p_delete = sub.add_parser("delete", parents=[common], help="Delete a record by ID.")
+    p_delete.add_argument("model", choices=sorted(_MODEL_TO_APP), help="Model name.")
+    p_delete.add_argument("--portal", default="private")
+    p_delete.add_argument("--id", required=True, help="UUID of the record to delete.")
+
+    return parser
+
+
+def main():
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.command == "logout":
+        if _TOKEN_FILE.exists():
+            _TOKEN_FILE.unlink()
+            print(f"Logged out. Token removed from {_TOKEN_FILE}")
+        else:
+            print("No cached token found.")
+        return
+
+    client = BrainstemClient(
+        token=args.token,
+        headless=getattr(args, "headless", False),
+        url=getattr(args, "url", None),
+    )
+
+    if args.command == "login":
+        print(f"Token: {client._token}")
+        print(f"Cached at: {_TOKEN_FILE}")
+        return
+
+    if args.command == "load":
+        filters = {}
+        for expr in (args.filters or []):
+            if "=" not in expr:
+                parser.error(f"Invalid filter '{expr}': expected FIELD=VALUE")
+            k, v = expr.split("=", 1)
+            filters[k] = v
+
+        resp = client.load(
+            args.model,
+            portal=args.portal,
+            id=args.id,
+            filters=filters or None,
+            sort=args.sort,
+            include=args.include,
+            limit=args.limit,
+            offset=args.offset,
+        )
+
+    elif args.command == "save":
+        try:
+            data = json.loads(args.data)
+        except json.JSONDecodeError as exc:
+            parser.error(f"Invalid JSON for --data: {exc}")
+
+        resp = client.save(args.model, portal=args.portal, id=args.id, data=data)
+
+    elif args.command == "delete":
+        resp = client.delete(args.model, portal=args.portal, id=args.id)
+
+    # Output
+    if resp.status_code == 204:
+        print("Deleted successfully.")
+    else:
+        try:
+            print(json.dumps(resp.json(), indent=2))
+        except Exception:
+            print(resp.text)
+
+    if not resp.ok:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

brainstem_python_api_tools-2.0.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: brainstem_python_api_tools
+Version: 2.0.0
+Summary: A Python toolset for interacting with the BrainSTEM API.
+Author-email: BrainSTEM Team <petersen.peter@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/brainstem-org/brainstem_python_api_tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# BrainSTEM Python API Tools
+
+The `brainstem_python_api_tools` is a Python toolset for interacting with the [BrainSTEM](https://www.brainstem.org/) API, designed for researchers and developers working with neuroscience data.
+
+## Installation
+You can install the package using `pip`:
+```bash
+pip install brainstem_python_api_tools
+```
+
+## Authentication
+
+Authentication uses a **browser-based device authorization flow** that supports two-factor authentication (2FA). No credentials are entered into the tool itself.
+
+```python
+from brainstem_api_tools import BrainstemClient
+
+# First run: opens a browser window for secure login.
+# The token is cached at ~/.config/brainstem/token and reused automatically.
+client = BrainstemClient()
+```
+
+To skip the browser flow, pass a token directly:
+```python
+client = BrainstemClient(token="YOUR_TOKEN")
+```
+
+For headless environments (no browser available):
+```python
+client = BrainstemClient(headless=True)  # prints a URL + code to enter manually
+```
+
+To connect to a different server (e.g. a local development instance):
+```python
+client = BrainstemClient(url="http://127.0.0.1:8000/")
+```
+
+> **Security note:** The cached token file is stored with owner-read-only permissions (`0600`). Treat it like a password and do not commit it to version control.
+
+## Getting Started
+To get started with the BrainSTEM API tools, please refer to the tutorial script provided:
+
+- **Tutorial:** `brainstem_api_tutorial.py`
+
+The tutorial demonstrates how to:
+
+- **Authenticate:** Load the client and authenticate via your browser.
+- **Load Data:** Load sessions and filter data using flexible options.
+- **Paginate:** Retrieve large datasets using `limit` / `offset` or `load_all=True`.
+- **Convenience Loaders:** Use `load_session()`, `load_subject()`, etc. for common queries.
+- **Update Entries:** Modify existing records and update them in the database.
+- **Create Entries:** Submit new data entries with required fields.
+- **Delete Entries:** Remove records by ID.
+- **Load Public Data:** Access public projects and data using the public portal.
+
+## Example Usage
+```python
+from brainstem_api_tools import BrainstemClient
+
+client = BrainstemClient()
+
+# Load sessions sorted by name
+response = client.load('session', sort=['name'])
+print(response.json())
+
+# Filter and include related data
+response = client.load(
+    'session',
+    filters={'name.icontains': 'Rat'},
+    sort=['-name'],
+    include=['projects'],
+)
+
+# Paginate results (manual)
+page2 = client.load('session', limit=20, offset=20).json()
+
+# Auto-paginate — fetches every page and returns a merged dict
+all_sessions = client.load('session', load_all=True)
+
+# Convenience loaders — sensible defaults with named filter kwargs
+# load_session embeds dataacquisition, behaviors, manipulations, epochs
+sessions = client.load_session(name='Rat', load_all=True)
+
+# load_subject embeds procedures and subjectlogs
+subjects = client.load_subject(sex='M', projects='<project-uuid>', load_all=True)
+
+# load_project embeds sessions, subjects, collections, cohorts
+projects = client.load_project(name='MyProject')
+
+# load_behavior / load_dataacquisition / load_manipulation scope by session UUID
+behaviors = client.load_behavior(session='<session-uuid>', load_all=True)
+
+# load_procedure scopes by subject UUID
+procedures = client.load_procedure(subject='<subject-uuid>', load_all=True)
+
+# Create a record
+client.save('session', data={'name': 'New session', 'projects': ['<project-uuid>']})
+
+# Update a record
+client.save('session', id='<session-uuid>', data={'description': 'updated'})
+
+# Delete a record
+client.delete('session', id='<session-uuid>')
+```
+
+## Command-line Interface
+
+After installation a `brainstem` command is available in your shell.
+
+### Authentication
+```bash
+# Authenticate (opens browser) and cache token
+brainstem login
+
+# Headless — prints URL + code instead of opening browser
+brainstem login --headless
+
+# Connect to a local dev server
+brainstem login --url http://127.0.0.1:8000/
+
+# Remove cached token
+brainstem logout
+```
+
+### Loading data
+```bash
+# Load all sessions (private portal)
+brainstem load session
+
+# Filter, sort and embed related data
+brainstem load session --filters name.icontains=Rat --sort -name --include projects
+
+# Load a single record by UUID
+brainstem load session --id <uuid>
+
+# Manual pagination
+brainstem load session --limit 20 --offset 20
+
+# Public portal
+brainstem load project --portal public
+```
+
+### Creating and updating records
+```bash
+# Create a new session
+brainstem save session --data '{"name":"New session","projects":["<uuid>"]}'
+
+# Update an existing record
+brainstem save session --id <uuid> --data '{"description":"updated"}'
+```
+
+### Deleting records
+```bash
+brainstem delete session --id <uuid>
+```
+
+All subcommands accept `--token`, `--headless`, and `--url` to override defaults.
+
+## Contributing
+Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.
+
+## License
+This project is licensed under the MIT License. See the `LICENSE` file for more details.

brainstem_python_api_tools-2.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+brainstem_api_tools/__init__.py,sha256=fjUyImRQc7gB_6D_a6q-55sMwMPo41famC4lzUqRrRc,117
+brainstem_api_tools/brainstem_api_client.py,sha256=_lkS32E2kOdjF2e0SsENflATLD_S-1zLsX4G4OoQYU0,35267
+brainstem_api_tools/cli.py,sha256=UB5QHFMcUK8Se79lqyEEUU2fIavuz757SHXzqeF_x1Y,5760
+brainstem_python_api_tools-2.0.0.dist-info/licenses/LICENSE,sha256=I4iwel7RmYcQggAinCAw6Gxcup59frUNXxFKf9hXCoc,1092
+brainstem_python_api_tools-2.0.0.dist-info/METADATA,sha256=MpWNZyTQq-q685jXNPj03C9GePOSdwAN4pesL9BrDcA,5575
+brainstem_python_api_tools-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+brainstem_python_api_tools-2.0.0.dist-info/entry_points.txt,sha256=o78cX6aY5foCZ6xskNVWc_Stjxi3dfYn_8l_kszjfZ4,59
+brainstem_python_api_tools-2.0.0.dist-info/top_level.txt,sha256=66OUGJs8UdzQdEqtx32kt84z2x-IpYEHmI1lLGlEwPA,20
+brainstem_python_api_tools-2.0.0.dist-info/RECORD,,

{brainstem_python_api_tools-0.2.0.dist-info → brainstem_python_api_tools-2.0.0.dist-info}/WHEEL

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

brainstem_python_api_tools-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brainstem = brainstem_api_tools.cli:main

brainstem_python_api_tools-0.2.0.dist-info/METADATA

@@ -1,54 +0,0 @@
-Metadata-Version: 2.1
-Name: brainstem_python_api_tools
-Version: 0.2.0
-Summary: A Python toolset for interacting with API of BrainSTEM.
-Home-page: https://github.com/brainstem-org/brainstem_python_api_tools
-Author: BrainSTEM Team
-Author-email: petersen.peter@gmail.com
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: jupyter
-
-# BrainSTEM Python API Tools
-
-The `brainstem_python_api_tools` is a Python toolset for interacting with the [BrainSTEM](https://www.brainstem.org/) API, designed for researchers and developers working with neuroscience data.
-
-## Installation
-You can install the package using `pip`:
-```bash
-pip install brainstem_python_api_tools
-```
-
-## Getting Started
-To get started with the BrainSTEM API tools, please refer to the tutorial script provided:
-
-- **Tutorial:** `brainstem_api_tutorial.py`
-
-The tutorial demonstrates how to:
-
-- **Authenticate:** Load the client and authenticate using your credentials.
-- **Loading Data:** Load sessions and filter data using flexible options.
-- **Updating Entries:** Modify existing models and update them in the database.
-- **Creating Entries:** Submit new data entries with required fields.
-- **Loading Public Data:** Access public projects and data using the public portal.
-
-## Example Usage
-```python
-from brainstem_api_tools import BrainstemClient
-
-client = BrainstemClient()
-response = client.load_model('session', sort=['name'])
-print(response.json())
-```
-
-## Contributing
-Contributions are welcome! Feel free to open issues or submit pull requests on [GitHub](https://github.com/brainstem-org/brainstem_python_api_tools).
-
-## License
-This project is licensed under the MIT License. See the `LICENSE` file for more details.

brainstem_python_api_tools-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-brainstem_api_tools/__init__.py,sha256=mADe7kLRh26hHSsFeqH60SVsJgzDb6PpoSRsmx0bKyU,73
-brainstem_api_tools/brainstem_api_client.py,sha256=TCruvRkMG4RpioxA-IrZZAOAnj8IXvzYK0Z7qEr_8ns,7787
-brainstem_python_api_tools-0.2.0.dist-info/LICENSE,sha256=I4iwel7RmYcQggAinCAw6Gxcup59frUNXxFKf9hXCoc,1092
-brainstem_python_api_tools-0.2.0.dist-info/METADATA,sha256=NzJQpgIBJq3EG_V0gw9Fl4Q55ffY_gO9Uk3WLp9BYDE,1925
-brainstem_python_api_tools-0.2.0.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
-brainstem_python_api_tools-0.2.0.dist-info/top_level.txt,sha256=66OUGJs8UdzQdEqtx32kt84z2x-IpYEHmI1lLGlEwPA,20
-brainstem_python_api_tools-0.2.0.dist-info/RECORD,,