gselib 0.1.0__tar.gz

gselib-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - run: uv sync --group docs
+
+      - run: uv run sphinx-build -b html docs docs/_build/html
+
+      - run: uv run ghp-import -n -p -f docs/_build/html

gselib-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

gselib-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - run: uv sync --group dev --extra cloud
+
+      - run: uv run pytest

gselib-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+wheels/
+
+# Virtual environments
+.venv/
+
+# OS generated files
+.DS_Store
+._*
+Thumbs.db
+Desktop.ini
+*~
+
+# Tools
+.ruff_cache/
+.pytest_cache/
+
+# Docs build output
+docs/_build/

gselib-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.7
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

gselib-0.1.0/.python-version

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+
+3.14

gselib-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+### Changed
+
+- LICENSE to License.txt
+- Switched to packaging with Hatchling, uv, and versions from git tags
+- Updated pre-commit hooks for Ruff
+- Updated README
+- Updated .gitignore
+- Optional dependencies restructured: base install is now empty, `gselib[cloud]` installs Nextcloud support, `gselib[all]` installs everything
+- `NextcloudClient` constants converted to plain lowercase class attributes (e.g. `perm_read`, `share_type_user`)
+- pytest configured with `--import-mode=importlib` to support identically named test files across subdirectories
+
+### Added
+
+- GitHub Actions to run pytest on push and pull requests to the main branch, with mock cli test
+- Contribution guide
+- Changelog file
+- Added deps.py as a way to check for installed dependency groups
+- Cloud module with Nextcloud support (`gselib[cloud]`) — REST API client (`NextcloudClient`) and `occ` runner (`NextcloudOCC`) for managing external storage and shares
+- CLI subcommand `gselib cloud nextcloud` for storage and share management via flags or environment variables
+- Tests for the cloud module (client, OCC runner, and CLI dispatch)
+- CI matrix extended to macOS and Windows
+- Sphinx documentation with PyData Sphinx Theme, auto-API generation via sphinx-autoapi, and Markdown support via myst-parser
+- GitHub Actions workflow to deploy docs to GitHub Pages on push to main
+- `docs` dependency group with Sphinx, PyData theme, sphinx-autobuild, sphinx-design, and ghp-import
+
+### Fixed
+
+- `NextcloudOCC.__exit__` missing required exception arguments
+- Version removed from CLI arguments and shown in the description instead
+
+### Removed
+
+- maps.py (no longer supported)
+- paths.py (no longer supported)
+- trajectory.py (no longer supported)
+- version.py (no longer supported)
+- .static-version (no longer supported)

gselib-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+All contributions to the GSELib project are welcome! Here are some ways you can help:
+
+- Report a bug by opening a [GitHub](https://github.com/gsecars/gselib/issues) or a [GitLab](https://gitlab.com/gsecars/gselib/-/boards) issue.
+- Add new features, fix bugs or improve documentation by submitting a [GitHub](https://github.com/gsecars/gselib/pulls) or a [GitLab](https://gitlab.com/gsecars/gselib/-/merge_requests) pull request.
+
+Please adhere to the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) model when making your contributions! This means creating a new branch for each feature of bug fix, and submitting your changes as a pull request against the main branch. If you're not sure how to contribute, please open an issue and we'll be happy to help you out.
+
+By contributing to the GSELib project, you agree that your contributions will be licensed under the MIT License.

gselib-0.1.0/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-2026 GSECARS, University of Chicago, USA
+Copyright (c) 2024-2026 Christofanis Skordas
+
+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.

gselib-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: gselib
+Version: 0.1.0
+Summary: A collection of tools for GSECARS.
+Project-URL: Homepage, https://github.com/gsecars/gselib
+Project-URL: Issues, https://github.com/gsecars/gselib/issues
+Author-email: Christofanis Skordas <skordasc@uchicago.edu>
+Maintainer-email: Christofanis Skordas <skordasc@uchicago.edu>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Requires-Python: ==3.14.*
+Provides-Extra: all
+Requires-Dist: paramiko>=3.0; extra == 'all'
+Requires-Dist: requests>=2.32; extra == 'all'
+Provides-Extra: cloud
+Requires-Dist: paramiko>=3.0; extra == 'cloud'
+Requires-Dist: requests>=2.32; extra == 'cloud'
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  &nbsp;GSELib
+</h1>
+
+
+[![License](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE.txt) [![Python](https://img.shields.io/badge/Python-3.14-22558a.svg?logo=python&color=22558a)](https://www.python.org/)
+[![Tests](https://github.com/gsecars/gselib/actions/workflows/tests.yml/badge.svg)](https://github.com/gsecars/gselib/actions/workflows/tests.yml)
+[![Docs](https://github.com/gsecars/gselib/actions/workflows/docs.yml/badge.svg)](https://github.com/gsecars/gselib/actions/workflows/docs.yml)
+
+A collection of tools for GSECARS.
+
+## Installation
+
+```bash
+pip install gselib          # base (no extras)
+pip install 'gselib[cloud]' # with Nextcloud support
+pip install 'gselib[all]'   # everything
+```
+
+## Modules
+
+| Module | Extras | Documentation |
+|---|---|---|
+| `gselib.cloud` | `gselib[cloud]` | [Cloud](https://gsecars.github.io/gselib/cloud/) |
+
+## Contribution
+Read more [here](CONTRIBUTING.md) for contribution guidance.
+
+## License
+GSELib is distributed under the MIT License. You should have received a [copy](LICENSE.txt) of the MIT License along with this program. If not, see https://mit-license.org/ for additional details.

gselib-0.1.0/README.md

@@ -0,0 +1,30 @@
+<h1 align="center">
+  &nbsp;GSELib
+</h1>
+
+
+[![License](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE.txt) [![Python](https://img.shields.io/badge/Python-3.14-22558a.svg?logo=python&color=22558a)](https://www.python.org/)
+[![Tests](https://github.com/gsecars/gselib/actions/workflows/tests.yml/badge.svg)](https://github.com/gsecars/gselib/actions/workflows/tests.yml)
+[![Docs](https://github.com/gsecars/gselib/actions/workflows/docs.yml/badge.svg)](https://github.com/gsecars/gselib/actions/workflows/docs.yml)
+
+A collection of tools for GSECARS.
+
+## Installation
+
+```bash
+pip install gselib          # base (no extras)
+pip install 'gselib[cloud]' # with Nextcloud support
+pip install 'gselib[all]'   # everything
+```
+
+## Modules
+
+| Module | Extras | Documentation |
+|---|---|---|
+| `gselib.cloud` | `gselib[cloud]` | [Cloud](https://gsecars.github.io/gselib/cloud/) |
+
+## Contribution
+Read more [here](CONTRIBUTING.md) for contribution guidance.
+
+## License
+GSELib is distributed under the MIT License. You should have received a [copy](LICENSE.txt) of the MIT License along with this program. If not, see https://mit-license.org/ for additional details.

gselib-0.1.0/cloud_test.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+
+import os
+from pathlib import Path
+
+from gselib.cloud import NextcloudOCC
+
+
+def load_env(path: str = ".env") -> None:
+    env_path = Path(path)
+    if not env_path.exists():
+        return
+    for line in env_path.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, _, value = line.partition("=")
+            os.environ.setdefault(key.strip(), value.strip())
+
+
+load_env()
+
+host = os.environ["NEXTCLOUD_SSH_HOST"]
+user = os.environ["NEXTCLOUD_SSH_USER"]
+password = os.environ.get("NEXTCLOUD_SSH_PASSWORD") or None
+key = os.environ.get("NEXTCLOUD_SSH_KEY") or None
+occ_cmd = os.environ.get("NEXTCLOUD_OCC_CMD", "php /var/www/html/occ")
+
+with NextcloudOCC(host=host, user=user, password=password, key_path=key, occ_cmd=occ_cmd) as occ:
+    print("Creating storage...")
+    mount = occ.create_local_storage("test3", "/var/www/html")
+    print(f"Created: id={mount['id']}  mount={mount['mount_point']}")
+
+    print("\nAll storages:")
+    for m in occ.list_storages():
+        print(f"  id={str(m.get('mount_id') or m.get('id', '?')):<4} {m.get('mount_point') or m.get('mountPoint', '?')}")

gselib-0.1.0/docs/_templates/gselib-copyright.html

@@ -0,0 +1,4 @@
+<p class="copyright">
+  &copy; 2024-2026 GSECARS, University of Chicago, USA<br>
+  &copy; 2024-2026 Christofanis Skordas
+</p>

gselib-0.1.0/docs/cloud.md

@@ -0,0 +1,136 @@
+# Cloud
+
+The `cloud` module provides storage and share management for cloud services. Currently supported: **Nextcloud**.
+
+## Installation
+
+```bash
+pip install 'gselib[cloud]'
+```
+
+## Nextcloud CLI
+
+All commands are available under `gselib cloud nextcloud`. Storage commands (create, list, delete) run `occ` on the server; share commands use the Nextcloud REST API.
+
+### Configuration
+
+**Storage management** runs `occ` locally or over SSH. Configure via flags or environment variables:
+
+| Flag | Environment variable | Description |
+|---|---|---|
+| `--occ-cmd` | `NEXTCLOUD_OCC_CMD` | Full `occ` invocation (required) |
+| `--ssh-host` | `NEXTCLOUD_SSH_HOST` | SSH host (omit to run locally) |
+| `--ssh-user` | `NEXTCLOUD_SSH_USER` | SSH username |
+| `--ssh-key` | `NEXTCLOUD_SSH_KEY` | Path to private key (prompts for password if omitted) |
+
+**Share management** uses the OCS REST API. Configure via flags or environment variables:
+
+| Flag | Environment variable | Description |
+|---|---|---|
+| `--url` | `NEXTCLOUD_URL` | Nextcloud base URL |
+| `--user` | `NEXTCLOUD_USER` | Admin username |
+| `--password` | `NEXTCLOUD_PASSWORD` | Admin password (prompted if omitted) |
+
+### External storage
+
+Local (no SSH):
+
+```bash
+gselib cloud nextcloud --occ-cmd "php occ" create-storage --mount MyData --path /srv/data
+```
+
+Via SSH with key:
+
+```bash
+gselib cloud nextcloud \
+    --occ-cmd "php occ" \
+    --ssh-host myserver --ssh-user admin --ssh-key ~/.ssh/id_ed25519 \
+    create-storage --mount MyData --path /srv/data
+```
+
+Nextcloud AIO (Docker over SSH):
+
+```bash
+gselib cloud nextcloud \
+    --occ-cmd "docker exec --user www-data nextcloud-aio-nextcloud php occ" \
+    --ssh-host myserver --ssh-user admin --ssh-key ~/.ssh/id_ed25519 \
+    create-storage --mount MyData --path /srv/data --users alice bob
+```
+
+With groups:
+
+```bash
+gselib cloud nextcloud --occ-cmd "php occ" \
+    create-storage --mount Shared --path /srv/shared --groups scientists
+```
+
+List storages:
+
+```bash
+gselib cloud nextcloud --occ-cmd "php occ" list-storages
+```
+
+Delete a storage:
+
+```bash
+gselib cloud nextcloud --occ-cmd "php occ" delete-storage --id 3
+```
+
+### Shares
+
+Share a path:
+
+```bash
+gselib cloud nextcloud \
+    --url https://nextcloud.example.org --user admin \
+    share --nc-path /MyData --recipients alice bob@external.org \
+    --permissions read update
+```
+
+Available permissions: `read`, `update`, `create`, `delete`, `share`, `all`.
+
+List shares:
+
+```bash
+gselib cloud nextcloud --url https://nextcloud.example.org --user admin \
+    list-shares --nc-path /MyData
+```
+
+Delete a share:
+
+```bash
+gselib cloud nextcloud --url https://nextcloud.example.org --user admin \
+    delete-share --id 7
+```
+
+## Nextcloud library
+
+```python
+from gselib.cloud import NextcloudClient, NextcloudOCC
+
+# External storage via occ (local)
+with NextcloudOCC(occ_cmd="php occ") as occ:
+    mount = occ.create_local_storage("MyData", "/srv/data", applicable_users=["alice"])
+    print(mount["id"])
+    mounts = occ.list_storages()
+    occ.delete_storage(mount["id"])
+
+# External storage via SSH
+with NextcloudOCC(host="myserver", user="admin", key_path="~/.ssh/id_ed25519", occ_cmd="php occ") as occ:
+    occ.create_local_storage("MyData", "/srv/data")
+
+# Nextcloud AIO (Docker over SSH)
+with NextcloudOCC(
+    host="myserver",
+    user="admin",
+    key_path="~/.ssh/id_ed25519",
+    occ_cmd="docker exec --user www-data nextcloud-aio-nextcloud php occ",
+) as occ:
+    occ.create_local_storage("MyData", "/srv/data")
+
+# Shares via REST API
+client = NextcloudClient("https://nextcloud.example.org", "admin", "password")
+client.share_with_many("/MyData", ["alice", "bob@external.org"], permissions=NextcloudClient.perm_read)
+shares = client.list_shares(path="/MyData")
+client.delete_share(shares[0]["id"])
+```

gselib-0.1.0/docs/conf.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+
+project = "GSELib"
+author = "Christofanis Skordas"
+copyright = "2024-2026 GSECARS, University of Chicago, USA"
+
+extensions = [
+    "autoapi.extension",
+    "myst_parser",
+    "sphinx_design",
+]
+
+myst_enable_extensions = ["colon_fence"]
+myst_heading_anchors = 3
+
+autoapi_dirs = ["../gselib"]
+autoapi_type = "python"
+autoapi_options = ["members", "undoc-members", "show-inheritance", "show-module-summary"]
+
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "github_url": "https://github.com/gsecars/gselib",
+    "navigation_with_keys": True,
+    "show_toc_level": 2,
+    "footer_start": ["gselib-copyright"],
+    "footer_center": [],
+    "footer_end": [],
+}
+
+html_sidebars = {
+    "index": [],
+}
+
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build"]

gselib-0.1.0/docs/index.md

@@ -0,0 +1,40 @@
+# GSELib
+
+A collection of tools for GSECARS.
+
+## Installation
+
+```bash
+pip install gselib          # base (no extras)
+pip install 'gselib[cloud]' # with Nextcloud support
+pip install 'gselib[all]'   # everything
+```
+
+## Modules
+
+::::{grid} 1 2 2 2
+:gutter: 3
+
+:::{grid-item-card} Cloud
+:link: cloud
+:link-type: doc
+
+Storage and share management for cloud services. Currently supports Nextcloud via REST API and `occ`.
+:::
+
+:::{grid-item-card} API Reference
+:link: autoapi/index
+:link-type: doc
+
+Auto-generated reference for all public classes and functions.
+:::
+
+::::
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+cloud
+API Reference <autoapi/index>
+```