scilog-viewer 0.2.9__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. scilog_viewer-0.2.9/.githooks/pre-push +55 -0
  2. scilog_viewer-0.2.9/.github/workflows/build.yml +86 -0
  3. scilog_viewer-0.2.9/.github/workflows/publish.yml +36 -0
  4. scilog_viewer-0.2.9/.gitignore +11 -0
  5. scilog_viewer-0.2.9/PKG-INFO +180 -0
  6. scilog_viewer-0.2.9/README.md +165 -0
  7. scilog_viewer-0.2.9/android/app/build.gradle.kts +83 -0
  8. scilog_viewer-0.2.9/android/app/src/main/AndroidManifest.xml +26 -0
  9. scilog_viewer-0.2.9/android/app/src/main/java/ch/psi/scilogviewer/LoginActivity.kt +87 -0
  10. scilog_viewer-0.2.9/android/app/src/main/java/ch/psi/scilogviewer/MainActivity.kt +192 -0
  11. scilog_viewer-0.2.9/android/app/src/main/python/android_main.py +29 -0
  12. scilog_viewer-0.2.9/android/app/src/main/res/drawable/ic_launcher_foreground.xml +8 -0
  13. scilog_viewer-0.2.9/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml +5 -0
  14. scilog_viewer-0.2.9/android/app/src/main/res/values/colors.xml +4 -0
  15. scilog_viewer-0.2.9/android/app/src/main/res/xml/network_security_config.xml +8 -0
  16. scilog_viewer-0.2.9/android/build.gradle.kts +5 -0
  17. scilog_viewer-0.2.9/android/gradle/wrapper/gradle-wrapper.jar +0 -0
  18. scilog_viewer-0.2.9/android/gradle/wrapper/gradle-wrapper.properties +7 -0
  19. scilog_viewer-0.2.9/android/gradle.properties +3 -0
  20. scilog_viewer-0.2.9/android/gradlew +252 -0
  21. scilog_viewer-0.2.9/android/gradlew.bat +94 -0
  22. scilog_viewer-0.2.9/android/settings.gradle.kts +15 -0
  23. scilog_viewer-0.2.9/packaging/build.sh +9 -0
  24. scilog_viewer-0.2.9/packaging/scilog_viewer_app.py +5 -0
  25. scilog_viewer-0.2.9/packaging/smoke_test.py +40 -0
  26. scilog_viewer-0.2.9/pyproject.toml +33 -0
  27. scilog_viewer-0.2.9/scilog_viewer/__init__.py +114 -0
  28. scilog_viewer-0.2.9/scilog_viewer/__main__.py +86 -0
  29. scilog_viewer-0.2.9/scilog_viewer/client.py +573 -0
  30. scilog_viewer-0.2.9/scilog_viewer/content.py +293 -0
  31. scilog_viewer-0.2.9/scilog_viewer/demo.py +633 -0
  32. scilog_viewer-0.2.9/scilog_viewer/launch.py +15 -0
  33. scilog_viewer-0.2.9/scilog_viewer/server.py +1315 -0
  34. scilog_viewer-0.2.9/scilog_viewer/static/app.css +603 -0
  35. scilog_viewer-0.2.9/scilog_viewer/static/app.js +1701 -0
  36. scilog_viewer-0.2.9/scilog_viewer/static/editor.js +350 -0
  37. scilog_viewer-0.2.9/scilog_viewer/static/headings.js +109 -0
  38. scilog_viewer-0.2.9/scilog_viewer/static/index.html +76 -0
  39. scilog_viewer-0.2.9/scilog_viewer/static/map.js +266 -0
  40. scilog_viewer-0.2.9/scilog_viewer/static/pin.js +122 -0
  41. scilog_viewer-0.2.9/scilog_viewer/static/postmenu.js +125 -0
  42. scilog_viewer-0.2.9/scilog_viewer/static/rail.js +187 -0
  43. scilog_viewer-0.2.9/scilog_viewer/static/search-worker.js +77 -0
  44. scilog_viewer-0.2.9/scilog_viewer/static/tasks.js +231 -0
  45. scilog_viewer-0.2.9/scilog_viewer/static/views.js +220 -0
  46. scilog_viewer-0.2.9/scilog_viewer.egg-info/PKG-INFO +180 -0
  47. scilog_viewer-0.2.9/scilog_viewer.egg-info/SOURCES.txt +59 -0
  48. scilog_viewer-0.2.9/scilog_viewer.egg-info/dependency_links.txt +1 -0
  49. scilog_viewer-0.2.9/scilog_viewer.egg-info/entry_points.txt +2 -0
  50. scilog_viewer-0.2.9/scilog_viewer.egg-info/requires.txt +9 -0
  51. scilog_viewer-0.2.9/scilog_viewer.egg-info/scm_file_list.json +55 -0
  52. scilog_viewer-0.2.9/scilog_viewer.egg-info/scm_version.json +8 -0
  53. scilog_viewer-0.2.9/scilog_viewer.egg-info/top_level.txt +1 -0
  54. scilog_viewer-0.2.9/setup.cfg +4 -0
  55. scilog_viewer-0.2.9/tests/test_demo.py +66 -0
  56. scilog_viewer-0.2.9/tests/test_lightbox.mjs +132 -0
  57. scilog_viewer-0.2.9/tests/test_lightbox.py +15 -0
  58. scilog_viewer-0.2.9/tests/test_panes.mjs +285 -0
  59. scilog_viewer-0.2.9/tests/test_panes.py +20 -0
  60. scilog_viewer-0.2.9/tests/test_viewer.py +863 -0
  61. scilog_viewer-0.2.9/tools/make_test_logbook.py +26 -0
@@ -0,0 +1,55 @@
1
+ #!/usr/bin/env bash
2
+ # Auto-bumps and pushes a new PATCH tag whenever `main` is pushed to origin,
3
+ # so every push to main becomes a release: .github/workflows/publish.yml puts it on PyPI,
4
+ # build.yml builds the programs and the Android app and attaches them to a GitHub
5
+ # release. See "Releasing" in README.md.
6
+ #
7
+ # This only ever bumps the last digit (PATCH). If a push is a MINOR release
8
+ # (only when asked for: a breaking change), tag it yourself BEFORE pushing
9
+ # (`git tag vX.Y.0`) — this hook skips auto-tagging when the commit being
10
+ # pushed already carries a v*.*.* tag.
11
+ #
12
+ # Bypass for a single push (e.g. pushing a WIP/experimental commit to main
13
+ # without releasing it): SKIP_AUTOTAG=1 git push
14
+ set -euo pipefail
15
+
16
+ remote="$1"
17
+
18
+ if [ -n "${SKIP_AUTOTAG:-}" ]; then
19
+ exit 0
20
+ fi
21
+
22
+ zero="0000000000000000000000000000000000000000"
23
+
24
+ while read -r local_ref local_sha _remote_ref _remote_sha; do
25
+ [ "$local_ref" = "refs/heads/main" ] || continue
26
+ [ "$local_sha" = "$zero" ] && continue # branch deletion
27
+
28
+ # Already tagged at this exact commit (e.g. a deliberate manual MINOR
29
+ # bump) -- don't also add a patch tag on top of it.
30
+ if [ -n "$(git tag --points-at "$local_sha" --list 'v*.*.*')" ]; then
31
+ continue
32
+ fi
33
+
34
+ latest=$(git tag --list 'v*.*.*' --sort=-v:refname --merged "$local_sha" | head -1)
35
+ if [ -z "$latest" ]; then
36
+ echo "pre-push: no existing v*.*.* tag reachable from $local_sha, skipping auto-tag" >&2
37
+ continue
38
+ fi
39
+
40
+ version="${latest#v}"
41
+ IFS='.' read -r major minor patch <<< "$version"
42
+ next="v${major}.${minor}.$((patch + 1))"
43
+
44
+ echo "pre-push: auto-tagging $next on $local_sha and pushing to $remote" >&2
45
+ if ! git tag "$next" "$local_sha" 2>/dev/null; then
46
+ echo "pre-push: tag $next already exists, skipping auto-tag" >&2
47
+ continue
48
+ fi
49
+ if ! git push "$remote" "$next" </dev/null; then
50
+ echo "pre-push: failed to push tag $next; deleting local tag. Push of main continues." >&2
51
+ git tag -d "$next"
52
+ fi
53
+ done
54
+
55
+ exit 0
@@ -0,0 +1,86 @@
1
+ # The SciLog viewer as one program per system, and as an Android app. Runs on
2
+ # demand and for tags v*; a tag also makes a release with all of them attached.
3
+ # Android signing key: repository secrets SCILOG_KEYSTORE_B64 / SCILOG_KEYSTORE_PASSWORD
4
+ # (otherwise debug-signed, and an update must then be installed after removing the old app).
5
+ name: build
6
+ on:
7
+ workflow_dispatch:
8
+ push:
9
+ tags: ["v*"]
10
+ permissions:
11
+ contents: write
12
+ jobs:
13
+ test:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ with: { fetch-depth: 0 }
18
+ - uses: actions/setup-python@v5
19
+ with: { python-version: "3.12" }
20
+ - run: pip install ".[dev]"
21
+ - run: pytest -q
22
+ program:
23
+ needs: test
24
+ strategy:
25
+ fail-fast: false
26
+ matrix:
27
+ include:
28
+ - { os: ubuntu-22.04, name: scilog-viewer-linux-x86_64 }
29
+ - { os: windows-latest, name: scilog-viewer-windows-x86_64.exe }
30
+ - { os: macos-14, name: scilog-viewer-macos-arm64 }
31
+ - { os: macos-13, name: scilog-viewer-macos-x86_64 }
32
+ runs-on: ${{ matrix.os }}
33
+ steps:
34
+ - uses: actions/checkout@v4
35
+ with: { fetch-depth: 0 }
36
+ - uses: actions/setup-python@v5
37
+ with: { python-version: "3.12" }
38
+ - run: pip install ".[build]"
39
+ - run: sh packaging/build.sh
40
+ shell: bash
41
+ - name: smoke test (starts, serves the page, stops)
42
+ shell: bash
43
+ run: |
44
+ exe=dist/scilog-viewer; [ -f dist/scilog-viewer.exe ] && exe=dist/scilog-viewer.exe
45
+ python packaging/smoke_test.py "$exe"
46
+ - name: name it
47
+ shell: bash
48
+ run: |
49
+ src=dist/scilog-viewer; [ -f dist/scilog-viewer.exe ] && src=dist/scilog-viewer.exe
50
+ mkdir out && cp "$src" "out/${{ matrix.name }}"
51
+ - uses: actions/upload-artifact@v4
52
+ with: { name: "${{ matrix.name }}", path: "out/${{ matrix.name }}" }
53
+ android:
54
+ needs: test
55
+ runs-on: ubuntu-latest
56
+ steps:
57
+ - uses: actions/checkout@v4
58
+ with: { fetch-depth: 0 }
59
+ - uses: actions/setup-java@v4
60
+ with: { distribution: temurin, java-version: "17" }
61
+ - uses: actions/setup-python@v5
62
+ with: { python-version: "3.12" } # Chaquopy builds with the same Python version as the app's
63
+ - name: Build the APK
64
+ working-directory: android
65
+ env:
66
+ SCILOG_KEYSTORE_B64: ${{ secrets.SCILOG_KEYSTORE_B64 }}
67
+ SCILOG_KEYSTORE_PASSWORD: ${{ secrets.SCILOG_KEYSTORE_PASSWORD }}
68
+ run: |
69
+ if [ -n "$SCILOG_KEYSTORE_B64" ]; then
70
+ echo "$SCILOG_KEYSTORE_B64" | base64 -d > "$RUNNER_TEMP/scilog.jks"
71
+ export SCILOG_KEYSTORE="$RUNNER_TEMP/scilog.jks"
72
+ fi
73
+ chmod +x gradlew
74
+ ./gradlew :app:assembleRelease --console=plain
75
+ mkdir -p ../out && cp app/build/outputs/apk/release/app-release.apk ../out/scilog-viewer-android.apk
76
+ - uses: actions/upload-artifact@v4
77
+ with: { name: scilog-viewer-android.apk, path: out/scilog-viewer-android.apk }
78
+ release:
79
+ if: startsWith(github.ref, 'refs/tags/v')
80
+ needs: [program, android]
81
+ runs-on: ubuntu-latest
82
+ steps:
83
+ - uses: actions/download-artifact@v4
84
+ with: { path: programs, merge-multiple: true }
85
+ - uses: softprops/action-gh-release@v2
86
+ with: { files: "programs/*" }
@@ -0,0 +1,36 @@
1
+ # The Python package to PyPI, for tags v*: tested, built, uploaded through PyPI's
2
+ # trusted publishing (the pending publisher for this file and the "pypi" environment),
3
+ # so no API token is kept anywhere.
4
+ name: publish
5
+ on:
6
+ push:
7
+ tags: ["v*.*.*"]
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ with: { fetch-depth: 0 } # setuptools-scm takes the version from the tag
14
+ - uses: actions/setup-python@v5
15
+ with: { python-version: "3.12" }
16
+ - run: pip install ".[dev]" build twine
17
+ - run: pytest -q
18
+ - run: python -m build && python -m twine check --strict dist/*
19
+ - name: the built version is the tag's
20
+ run: |
21
+ want="${GITHUB_REF_NAME#v}"; ls dist/
22
+ test -f "dist/scilog_viewer-${want}.tar.gz" || { echo "sdist is not version $want (tag not on this commit?)"; exit 1; }
23
+ - uses: actions/upload-artifact@v4
24
+ with: { name: dist, path: dist/ }
25
+ pypi:
26
+ needs: build
27
+ runs-on: ubuntu-latest
28
+ environment:
29
+ name: pypi
30
+ url: https://pypi.org/p/scilog-viewer
31
+ permissions:
32
+ id-token: write
33
+ steps:
34
+ - uses: actions/download-artifact@v4
35
+ with: { name: dist, path: dist/ }
36
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ build/
4
+ dist/
5
+ .pytest_cache/
6
+ *.spec
7
+ build/
8
+ android/.gradle/
9
+ android/build/
10
+ android/app/build/
11
+ android/local.properties
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: scilog-viewer
3
+ Version: 0.2.9
4
+ Summary: Read and write SciLog (PSI's electronic logbook) in the browser: a flow of days, outline and map, fuzzy search, editing, views.
5
+ Project-URL: Homepage, https://github.com/swissfel/scilog-viewer
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: tornado>=6
9
+ Requires-Dist: requests>=2.28
10
+ Requires-Dist: nh3>=0.2.14
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=7; extra == "dev"
13
+ Provides-Extra: build
14
+ Requires-Dist: pyinstaller>=6.3; extra == "build"
15
+
16
+ # SciLog viewer
17
+
18
+ Read and write [SciLog](https://scilog.psi.ch), PSI's electronic logbook, in the browser:
19
+
20
+ - one logbook as a continuous flow of days, newest at the bottom, new posts appearing by themselves;
21
+ - a long logbook is read from its end: the newest posts are on the screen at once and the older days
22
+ fill in above them while you read, each piece larger than the last; a quick flick upwards offers the
23
+ way back to the top, and goes away again by itself (Home does the same);
24
+ - the day header stays at the top while its day is read and says which part of the day is on the screen
25
+ (night, morning, noon, afternoon, evening, late);
26
+ - a **scroll rail** down the right: a handle wide enough for a thumb, a mark for every day on the track,
27
+ and, while it is held (or pointed at), a sign saying where it would take you -- the day, the part of
28
+ that day and the heading above that place;
29
+ - a left pane with either the **outline** (headings across all posts), the **stream** (months, days, posts)
30
+ or the **map**: the flow drawn small, with figures, tables, lists and code recognisable by their look;
31
+ a click jumps there. The pane grows with the logbook the same way the flow does -- the older days are
32
+ put in above what it shows, so it stays where you are reading -- and only the pane on show is drawn;
33
+ - fuzzy search (typos allowed) with previews;
34
+ - interactive HTML plots inline, images on their own on a tap or a click, there pinch- (or wheel-) zoomable,
35
+ dragged about and zoomed in and out again by a double tap: on a phone a figure can be read, not only seen;
36
+ - writing and editing posts with the editor SciLog itself uses (CKEditor 5), images uploaded as they are pasted,
37
+ drafts kept in the browser; a composer at the bottom, double-click your own post to edit it;
38
+ - views of the flow (all, mine, by tag) and **SciLog's own views** (dashboard layouts) listed side by side,
39
+ with what tells same-named ones apart, and renamed, changed or deleted (a local copy is kept first);
40
+ - links to a single post, in context or alone;
41
+ - comments and replies as in SciLog, and a post's info;
42
+ - the logbook's **tasks** in a pane: changed at any time and dragged into order, which is stored in SciLog (its own
43
+ page lists tasks by when they were added, until it sorts them too).
44
+
45
+ ## Run it
46
+
47
+ **As a program** (no Python needed): download the one for your system from the
48
+ [releases](../../releases) (or the latest [build](../../actions/workflows/build.yml) run's artifacts) and start it:
49
+
50
+ | system | file |
51
+ |---|---|
52
+ | Linux (x86-64) | `scilog-viewer-linux-x86_64` (make it executable: `chmod +x`) |
53
+ | Windows | `scilog-viewer-windows-x86_64.exe` |
54
+ | Android | `scilog-viewer-android.apk` (see [From a phone](#from-a-phone)) |
55
+
56
+ No macOS program for now (GitHub runs no macOS builds for this repository); on a Mac use `pip install` below.
57
+
58
+ It opens the viewer in your browser and runs until its window is closed.
59
+
60
+ **With Python:**
61
+
62
+ ```bash
63
+ pip install -e . # tornado, requests, nh3
64
+ python -m scilog_viewer # or: scilog-viewer
65
+ ```
66
+
67
+ ### The token
68
+
69
+ The viewer reads and writes SciLog with your own token. The first time (and whenever the token has run out) the page
70
+ asks for it and says how to get it:
71
+
72
+ 1. log in at https://scilog.psi.ch;
73
+ 2. copy the token: on a computer press F12, Console, `copy(localStorage.id_token)`; on a phone, or without the
74
+ developer tools, once make a bookmark with the address
75
+ `javascript:void(prompt('SciLog token (select all, copy):',localStorage.id_token))` and open it while SciLog is
76
+ shown (Android Chrome: type the bookmark's name in the address bar);
77
+ 3. paste it into the viewer's window.
78
+
79
+ The viewer checks it with SciLog and keeps it in `~/.config/scilog-viewer/token` (mode 600). **A token lasts 14 days
80
+ from the login and cannot be renewed**; three days before, a badge in the bar says so. `python -m scilog_viewer --token`
81
+ and `$SCILOG_TOKEN` work too, and eco's `~/.eco/scilog_token` is used if present. Never keep a personal token on an
82
+ account several people use: there (listed in `$SCILOG_VIEWER_SHARED_ACCOUNTS`) the viewer only *borrows* a
83
+ token, held in memory for at most 8 hours and never written to disk. Anywhere, the token window's "Keep it" box
84
+ decides between keeping a token and borrowing it.
85
+
86
+ ### From a phone
87
+
88
+ The viewer is a small local server plus a web page; SciLog's API does not accept calls from pages served elsewhere
89
+ (no CORS), so a page alone (e.g. on GitHub Pages) cannot do it. Ways that work:
90
+
91
+ - **through a computer that runs it:** `ssh -L 8798:localhost:8798 that-computer` from the phone (e.g. Termux or
92
+ any SSH app with port forwarding), then open the printed address on the phone;
93
+ - **on the phone itself** (Android, untested so far): in [Termux](https://termux.dev),
94
+ `pkg install python rust && pip install git+https://github.com/swissfel/scilog-dev && scilog-viewer --no-browser`,
95
+ then open the printed address in the phone's browser;
96
+ - **the Android app**: on the phone, sign in to github.com in the browser (the repository is private), open this
97
+ repository's **Releases**, tap `scilog-viewer-android.apk` and open the download. The same server and page
98
+ inside the app; newer releases install over it. Install the APK (Android asks once to allow installs from your browser or file manager),
99
+ open *SciLog viewer*, tap **Log in to SciLog here**: SciLog's own login (PSI account, MFA) opens in the app and
100
+ the token is taken over by itself. Links to other sites open in your browser; attachments go to Downloads.
101
+ A picture opened from a post zooms with a pinch; Back closes it.
102
+
103
+ ## What it may do
104
+
105
+ The server binds 127.0.0.1 only and checks a random token (a cookie after the first visit). Writes need a header
106
+ only the page itself sends, from the page's own origin. Everything is done with your token, so SciLog decides
107
+ what you can read and change, as in its own page.
108
+
109
+ Writing is off until you switch it on per logbook (the page's "Allow writing here", or
110
+ `~/.config/scilog-viewer/config.json`: `{"write_logbooks": [ids] or "all"}`); until then nothing is written.
111
+
112
+ ## A logbook to try it on, without SciLog
113
+
114
+ ```bash
115
+ python -m scilog_viewer --demo # makes one the first time (a few seconds), then reads it
116
+ ```
117
+
118
+ A made-up logbook: 1729 posts over three months, 43 days with posts, bursts of 212 in a day, a figure in
119
+ every fifth post, a third of them a scan report with a table and a data file -- the shape of a real beamtime
120
+ logbook, so the viewer is slow in the same places. Everything in it is generated by `scilog_viewer/demo.py`:
121
+ the words come from a word list and ten sentence patterns, the figures (scans, detector frames, spectra,
122
+ camera pictures) are drawn pixel by pixel and written out as PNGs by hand, the names are invented. Nothing
123
+ is taken from SciLog or anywhere else, nothing is sent anywhere, and no token is needed, so the logbook can
124
+ be passed on freely. It is read-only.
125
+
126
+ `python tools/make_test_logbook.py DIR --posts 6000` makes a bigger one somewhere else
127
+ (`--demo DIR` then reads it); the same `--seed` always gives the same logbook.
128
+
129
+ ## Development
130
+
131
+ ```bash
132
+ pip install -e ".[dev]"
133
+ pytest
134
+ ```
135
+
136
+ Two of the tests run the page itself in node: the gestures of the picture window, and a logbook of
137
+ 600 posts read from its end with all three panes (`tests/test_panes.mjs`, which needs jsdom --
138
+ `npm install jsdom` here, or `NODE_PATH` to one; without it that test is skipped).
139
+
140
+ Releasing: `git config core.hooksPath .githooks` once per clone. Then every push of `main` is a release:
141
+ the pre-push hook tags the next patch version (`v0.2.9` after `v0.2.8`), `publish.yml` puts it on PyPI and
142
+ `build.yml` attaches the programs and the Android app to a GitHub release. The version comes from that tag
143
+ (setuptools-scm). `SKIP_AUTOTAG=1 git push` pushes without releasing; a bigger step is tagged by hand before
144
+ the push (`git tag v0.3.0`).
145
+
146
+ ## A site's own parts (plugins)
147
+
148
+ `python -m scilog_viewer --plugin MODULE` (or `$SCILOG_VIEWER_PLUGIN`, or `scilog_viewer.start(plugin=...)`)
149
+ imports `MODULE` and calls its `setup(client, server)` before the server starts. It may set:
150
+
151
+ - `client.FUNCTIONAL_USER` and `client.functional_login(url, session, timeout)` -- a beamline account whose
152
+ token the function returns (`client.login(user, password)` does SciLog's local login), or `None` when its
153
+ password is not readable; give the function an `available()` attribute to say so without logging in;
154
+ - `client.SHARED_ACCOUNTS` -- accounts several people use: no personal token is kept or used there;
155
+ - `server.CONFIG_PATH`, `server.DEFAULT_WRITE_LOGBOOKS` -- where the settings live, and which logbooks are
156
+ writable until a user says otherwise.
157
+
158
+ eco (gitea.psi.ch: Bernina/eco), where the viewer was first written, uses this for the Bernina beamline
159
+ account (`eco.scilog_viewer_plugin`); `scilog.viewer()` in an eco session starts this package.
160
+
161
+ ## Where this could go
162
+
163
+ - **A purely static version** (e.g. on GitHub Pages, no local server) needs two things from SciLog: its API
164
+ answering requests from another site (CORS for that site), and its login sending the browser back to that site
165
+ with a token. Both are SciLog configuration, not code here.
166
+
167
+ ## Building the programs
168
+
169
+ **Android** (`android/`): a Kotlin app with [Chaquopy](https://chaquo.com/chaquopy/), which packs Python 3.12,
170
+ tornado, requests and bleach with this repository's `scilog_viewer/`; `MainActivity` starts the server on
171
+ 127.0.0.1 and shows the page, `LoginActivity` is SciLog's login whose token it hands over. `cd android &&
172
+ ./gradlew :app:assembleRelease` (Android SDK 35, Java 17, Python 3.12 on the PATH). The build workflow signs it with
173
+ the key in the repository secrets `SCILOG_KEYSTORE_B64` / `SCILOG_KEYSTORE_PASSWORD` (alias `scilog-viewer`), so that
174
+ new versions install over old ones; without them it is debug-signed.
175
+
176
+ **Desktop:**
177
+
178
+ `pip install ".[build]" && sh packaging/build.sh` makes `dist/scilog-viewer` for the system it runs on;
179
+ `packaging/smoke_test.py dist/scilog-viewer` starts it and checks that it serves the page. The `build` workflow does
180
+ both on Linux and Windows (macOS when GitHub provides runners again) (on demand, and for tags `v*`, which also publish a release).
@@ -0,0 +1,165 @@
1
+ # SciLog viewer
2
+
3
+ Read and write [SciLog](https://scilog.psi.ch), PSI's electronic logbook, in the browser:
4
+
5
+ - one logbook as a continuous flow of days, newest at the bottom, new posts appearing by themselves;
6
+ - a long logbook is read from its end: the newest posts are on the screen at once and the older days
7
+ fill in above them while you read, each piece larger than the last; a quick flick upwards offers the
8
+ way back to the top, and goes away again by itself (Home does the same);
9
+ - the day header stays at the top while its day is read and says which part of the day is on the screen
10
+ (night, morning, noon, afternoon, evening, late);
11
+ - a **scroll rail** down the right: a handle wide enough for a thumb, a mark for every day on the track,
12
+ and, while it is held (or pointed at), a sign saying where it would take you -- the day, the part of
13
+ that day and the heading above that place;
14
+ - a left pane with either the **outline** (headings across all posts), the **stream** (months, days, posts)
15
+ or the **map**: the flow drawn small, with figures, tables, lists and code recognisable by their look;
16
+ a click jumps there. The pane grows with the logbook the same way the flow does -- the older days are
17
+ put in above what it shows, so it stays where you are reading -- and only the pane on show is drawn;
18
+ - fuzzy search (typos allowed) with previews;
19
+ - interactive HTML plots inline, images on their own on a tap or a click, there pinch- (or wheel-) zoomable,
20
+ dragged about and zoomed in and out again by a double tap: on a phone a figure can be read, not only seen;
21
+ - writing and editing posts with the editor SciLog itself uses (CKEditor 5), images uploaded as they are pasted,
22
+ drafts kept in the browser; a composer at the bottom, double-click your own post to edit it;
23
+ - views of the flow (all, mine, by tag) and **SciLog's own views** (dashboard layouts) listed side by side,
24
+ with what tells same-named ones apart, and renamed, changed or deleted (a local copy is kept first);
25
+ - links to a single post, in context or alone;
26
+ - comments and replies as in SciLog, and a post's info;
27
+ - the logbook's **tasks** in a pane: changed at any time and dragged into order, which is stored in SciLog (its own
28
+ page lists tasks by when they were added, until it sorts them too).
29
+
30
+ ## Run it
31
+
32
+ **As a program** (no Python needed): download the one for your system from the
33
+ [releases](../../releases) (or the latest [build](../../actions/workflows/build.yml) run's artifacts) and start it:
34
+
35
+ | system | file |
36
+ |---|---|
37
+ | Linux (x86-64) | `scilog-viewer-linux-x86_64` (make it executable: `chmod +x`) |
38
+ | Windows | `scilog-viewer-windows-x86_64.exe` |
39
+ | Android | `scilog-viewer-android.apk` (see [From a phone](#from-a-phone)) |
40
+
41
+ No macOS program for now (GitHub runs no macOS builds for this repository); on a Mac use `pip install` below.
42
+
43
+ It opens the viewer in your browser and runs until its window is closed.
44
+
45
+ **With Python:**
46
+
47
+ ```bash
48
+ pip install -e . # tornado, requests, nh3
49
+ python -m scilog_viewer # or: scilog-viewer
50
+ ```
51
+
52
+ ### The token
53
+
54
+ The viewer reads and writes SciLog with your own token. The first time (and whenever the token has run out) the page
55
+ asks for it and says how to get it:
56
+
57
+ 1. log in at https://scilog.psi.ch;
58
+ 2. copy the token: on a computer press F12, Console, `copy(localStorage.id_token)`; on a phone, or without the
59
+ developer tools, once make a bookmark with the address
60
+ `javascript:void(prompt('SciLog token (select all, copy):',localStorage.id_token))` and open it while SciLog is
61
+ shown (Android Chrome: type the bookmark's name in the address bar);
62
+ 3. paste it into the viewer's window.
63
+
64
+ The viewer checks it with SciLog and keeps it in `~/.config/scilog-viewer/token` (mode 600). **A token lasts 14 days
65
+ from the login and cannot be renewed**; three days before, a badge in the bar says so. `python -m scilog_viewer --token`
66
+ and `$SCILOG_TOKEN` work too, and eco's `~/.eco/scilog_token` is used if present. Never keep a personal token on an
67
+ account several people use: there (listed in `$SCILOG_VIEWER_SHARED_ACCOUNTS`) the viewer only *borrows* a
68
+ token, held in memory for at most 8 hours and never written to disk. Anywhere, the token window's "Keep it" box
69
+ decides between keeping a token and borrowing it.
70
+
71
+ ### From a phone
72
+
73
+ The viewer is a small local server plus a web page; SciLog's API does not accept calls from pages served elsewhere
74
+ (no CORS), so a page alone (e.g. on GitHub Pages) cannot do it. Ways that work:
75
+
76
+ - **through a computer that runs it:** `ssh -L 8798:localhost:8798 that-computer` from the phone (e.g. Termux or
77
+ any SSH app with port forwarding), then open the printed address on the phone;
78
+ - **on the phone itself** (Android, untested so far): in [Termux](https://termux.dev),
79
+ `pkg install python rust && pip install git+https://github.com/swissfel/scilog-dev && scilog-viewer --no-browser`,
80
+ then open the printed address in the phone's browser;
81
+ - **the Android app**: on the phone, sign in to github.com in the browser (the repository is private), open this
82
+ repository's **Releases**, tap `scilog-viewer-android.apk` and open the download. The same server and page
83
+ inside the app; newer releases install over it. Install the APK (Android asks once to allow installs from your browser or file manager),
84
+ open *SciLog viewer*, tap **Log in to SciLog here**: SciLog's own login (PSI account, MFA) opens in the app and
85
+ the token is taken over by itself. Links to other sites open in your browser; attachments go to Downloads.
86
+ A picture opened from a post zooms with a pinch; Back closes it.
87
+
88
+ ## What it may do
89
+
90
+ The server binds 127.0.0.1 only and checks a random token (a cookie after the first visit). Writes need a header
91
+ only the page itself sends, from the page's own origin. Everything is done with your token, so SciLog decides
92
+ what you can read and change, as in its own page.
93
+
94
+ Writing is off until you switch it on per logbook (the page's "Allow writing here", or
95
+ `~/.config/scilog-viewer/config.json`: `{"write_logbooks": [ids] or "all"}`); until then nothing is written.
96
+
97
+ ## A logbook to try it on, without SciLog
98
+
99
+ ```bash
100
+ python -m scilog_viewer --demo # makes one the first time (a few seconds), then reads it
101
+ ```
102
+
103
+ A made-up logbook: 1729 posts over three months, 43 days with posts, bursts of 212 in a day, a figure in
104
+ every fifth post, a third of them a scan report with a table and a data file -- the shape of a real beamtime
105
+ logbook, so the viewer is slow in the same places. Everything in it is generated by `scilog_viewer/demo.py`:
106
+ the words come from a word list and ten sentence patterns, the figures (scans, detector frames, spectra,
107
+ camera pictures) are drawn pixel by pixel and written out as PNGs by hand, the names are invented. Nothing
108
+ is taken from SciLog or anywhere else, nothing is sent anywhere, and no token is needed, so the logbook can
109
+ be passed on freely. It is read-only.
110
+
111
+ `python tools/make_test_logbook.py DIR --posts 6000` makes a bigger one somewhere else
112
+ (`--demo DIR` then reads it); the same `--seed` always gives the same logbook.
113
+
114
+ ## Development
115
+
116
+ ```bash
117
+ pip install -e ".[dev]"
118
+ pytest
119
+ ```
120
+
121
+ Two of the tests run the page itself in node: the gestures of the picture window, and a logbook of
122
+ 600 posts read from its end with all three panes (`tests/test_panes.mjs`, which needs jsdom --
123
+ `npm install jsdom` here, or `NODE_PATH` to one; without it that test is skipped).
124
+
125
+ Releasing: `git config core.hooksPath .githooks` once per clone. Then every push of `main` is a release:
126
+ the pre-push hook tags the next patch version (`v0.2.9` after `v0.2.8`), `publish.yml` puts it on PyPI and
127
+ `build.yml` attaches the programs and the Android app to a GitHub release. The version comes from that tag
128
+ (setuptools-scm). `SKIP_AUTOTAG=1 git push` pushes without releasing; a bigger step is tagged by hand before
129
+ the push (`git tag v0.3.0`).
130
+
131
+ ## A site's own parts (plugins)
132
+
133
+ `python -m scilog_viewer --plugin MODULE` (or `$SCILOG_VIEWER_PLUGIN`, or `scilog_viewer.start(plugin=...)`)
134
+ imports `MODULE` and calls its `setup(client, server)` before the server starts. It may set:
135
+
136
+ - `client.FUNCTIONAL_USER` and `client.functional_login(url, session, timeout)` -- a beamline account whose
137
+ token the function returns (`client.login(user, password)` does SciLog's local login), or `None` when its
138
+ password is not readable; give the function an `available()` attribute to say so without logging in;
139
+ - `client.SHARED_ACCOUNTS` -- accounts several people use: no personal token is kept or used there;
140
+ - `server.CONFIG_PATH`, `server.DEFAULT_WRITE_LOGBOOKS` -- where the settings live, and which logbooks are
141
+ writable until a user says otherwise.
142
+
143
+ eco (gitea.psi.ch: Bernina/eco), where the viewer was first written, uses this for the Bernina beamline
144
+ account (`eco.scilog_viewer_plugin`); `scilog.viewer()` in an eco session starts this package.
145
+
146
+ ## Where this could go
147
+
148
+ - **A purely static version** (e.g. on GitHub Pages, no local server) needs two things from SciLog: its API
149
+ answering requests from another site (CORS for that site), and its login sending the browser back to that site
150
+ with a token. Both are SciLog configuration, not code here.
151
+
152
+ ## Building the programs
153
+
154
+ **Android** (`android/`): a Kotlin app with [Chaquopy](https://chaquo.com/chaquopy/), which packs Python 3.12,
155
+ tornado, requests and bleach with this repository's `scilog_viewer/`; `MainActivity` starts the server on
156
+ 127.0.0.1 and shows the page, `LoginActivity` is SciLog's login whose token it hands over. `cd android &&
157
+ ./gradlew :app:assembleRelease` (Android SDK 35, Java 17, Python 3.12 on the PATH). The build workflow signs it with
158
+ the key in the repository secrets `SCILOG_KEYSTORE_B64` / `SCILOG_KEYSTORE_PASSWORD` (alias `scilog-viewer`), so that
159
+ new versions install over old ones; without them it is debug-signed.
160
+
161
+ **Desktop:**
162
+
163
+ `pip install ".[build]" && sh packaging/build.sh` makes `dist/scilog-viewer` for the system it runs on;
164
+ `packaging/smoke_test.py dist/scilog-viewer` starts it and checks that it serves the page. The `build` workflow does
165
+ both on Linux and Windows (macOS when GitHub provides runners again) (on demand, and for tags `v*`, which also publish a release).
@@ -0,0 +1,83 @@
1
+ // The SciLog viewer on Android: the same Python server as on a computer
2
+ // (scilog_viewer/, run by Chaquopy inside the app, on 127.0.0.1 only) and its
3
+ // page in a WebView.
4
+ plugins {
5
+ id("com.android.application")
6
+ id("org.jetbrains.kotlin.android")
7
+ id("com.chaquo.python")
8
+ }
9
+
10
+ android {
11
+ namespace = "ch.psi.scilogviewer"
12
+ compileSdk = 35
13
+
14
+ defaultConfig {
15
+ applicationId = "ch.psi.scilogviewer"
16
+ minSdk = 26
17
+ targetSdk = 35
18
+ // every CI build counts up, so a phone takes it as an update of the one before
19
+ versionCode = System.getenv("GITHUB_RUN_NUMBER")?.toIntOrNull() ?: 1
20
+ versionName = System.getenv("GITHUB_REF_NAME")?.takeIf { it.startsWith("v") }?.removePrefix("v") ?: "0.0.0-dev"
21
+ ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
22
+ }
23
+
24
+ signingConfigs {
25
+ // CI signs with a fixed key (repository secrets), so that updates install over older versions
26
+ create("release") {
27
+ val ks = System.getenv("SCILOG_KEYSTORE")
28
+ if (ks != null && file(ks).exists()) {
29
+ storeFile = file(ks)
30
+ storePassword = System.getenv("SCILOG_KEYSTORE_PASSWORD")
31
+ keyAlias = System.getenv("SCILOG_KEY_ALIAS") ?: "scilog-viewer"
32
+ keyPassword = System.getenv("SCILOG_KEYSTORE_PASSWORD")
33
+ }
34
+ }
35
+ }
36
+
37
+ buildTypes {
38
+ release {
39
+ isMinifyEnabled = false
40
+ signingConfig = if (System.getenv("SCILOG_KEYSTORE") != null) signingConfigs.getByName("release")
41
+ else signingConfigs.getByName("debug")
42
+ }
43
+ }
44
+
45
+ compileOptions {
46
+ sourceCompatibility = JavaVersion.VERSION_17
47
+ targetCompatibility = JavaVersion.VERSION_17
48
+ }
49
+ kotlinOptions { jvmTarget = "17" }
50
+ }
51
+
52
+ // the viewer's Python package, as it is in this repository
53
+ val viewerPython = layout.buildDirectory.dir("viewer-python")
54
+ val copyViewer by tasks.registering(Copy::class) {
55
+ from(rootProject.file("../scilog_viewer")) {
56
+ exclude("__pycache__", "**/__pycache__")
57
+ }
58
+ into(viewerPython.map { it.dir("scilog_viewer") })
59
+ }
60
+ tasks.named("preBuild") { dependsOn(copyViewer) }
61
+ // Chaquopy's own tasks do not run after preBuild, so they need the copy declared themselves.
62
+ tasks.matching { it.name.startsWith("merge") && it.name.endsWith("PythonSources") }
63
+ .configureEach { dependsOn(copyViewer) }
64
+
65
+ chaquopy {
66
+ defaultConfig {
67
+ version = "3.12"
68
+ pip {
69
+ install("tornado")
70
+ install("requests")
71
+ install("bleach[css]") // cleans the posts' HTML (nh3 has no Android build)
72
+ }
73
+ }
74
+ sourceSets {
75
+ getByName("main") {
76
+ srcDir("build/viewer-python")
77
+ }
78
+ }
79
+ }
80
+
81
+ dependencies {
82
+ implementation("androidx.webkit:webkit:1.12.1")
83
+ }
@@ -0,0 +1,26 @@
1
+ <?xml version="1.0" encoding="utf-8"?>
2
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
3
+ <uses-permission android:name="android.permission.INTERNET" />
4
+ <application
5
+ android:label="SciLog viewer"
6
+ android:icon="@mipmap/ic_launcher"
7
+ android:roundIcon="@mipmap/ic_launcher"
8
+ android:networkSecurityConfig="@xml/network_security_config"
9
+ android:theme="@android:style/Theme.Material.Light.NoActionBar"
10
+ android:allowBackup="false">
11
+ <activity
12
+ android:name=".MainActivity"
13
+ android:exported="true"
14
+ android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|uiMode"
15
+ android:windowSoftInputMode="adjustResize">
16
+ <intent-filter>
17
+ <action android:name="android.intent.action.MAIN" />
18
+ <category android:name="android.intent.category.LAUNCHER" />
19
+ </intent-filter>
20
+ </activity>
21
+ <activity
22
+ android:name=".LoginActivity"
23
+ android:exported="false"
24
+ android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|uiMode" />
25
+ </application>
26
+ </manifest>