peekin 0.1.0__tar.gz

peekin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: ci
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv run --python ${{ matrix.python }} pytest -q

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

@@ -0,0 +1,18 @@
+name: publish
+on:
+  release:
+    types: [published]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing: no API token stored anywhere
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check the release tag matches the package version
+        run: test "${GITHUB_REF_NAME#v}" = "$(uv run python -c 'import peekin; print(peekin.__version__)')"
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uv publish

peekin-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.superpowers/

peekin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suman Michael
+
+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.

peekin-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: peekin
+Version: 0.1.0
+Summary: Lightweight read-only file browser and previewer in your web browser
+Project-URL: Homepage, https://github.com/sumanmichael/peekin
+Author: Suman Michael
+License-Expression: MIT
+License-File: LICENSE
+Keywords: file browser,file viewer,gallery,pdf,syntax highlighting
+Classifier: Environment :: Web Environment
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment :: File Managers
+Requires-Python: >=3.10
+Requires-Dist: pygments>=2.17
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: thumbs
+Requires-Dist: pillow>=10; extra == 'thumbs'
+Description-Content-Type: text/markdown
+
+# peekin
+
+A lightweight, read-only file browser for your web browser. Browse a folder and
+preview images (swipeable gallery), video, audio, PDF, and source code with
+syntax highlighting. Works on desktop and phone. Fully offline.
+
+## Run
+
+```bash
+uvx peekin                     # share the current folder on http://127.0.0.1:8000
+uvx peekin ~/Pictures --open   # share a folder and open the browser
+python -m peekin               # after: pip install peekin
+```
+
+Until the first PyPI release:
+
+```bash
+uvx --from git+https://github.com/sumanmichael/peekin peekin
+```
+
+## Share on your network
+
+```bash
+uvx peekin --host 0.0.0.0
+```
+
+peekin needs a password whenever it listens on something other than
+localhost. If you don't set one, it generates one and prints it at startup.
+Set your own with `PEEKIN_PASSWORD=...` or `--password-file FILE`.
+`--no-password` turns the password off (not recommended on shared networks).
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `FOLDER` | `.` | Folder to share |
+| `--host` | `127.0.0.1` | Address to listen on (`0.0.0.0` for your network) |
+| `--port` | `8000` | Port |
+| `--password-file` | | Read the password from this file's first line |
+| `--no-password` | off | Never ask for a password |
+| `--thumbs` | off | Image thumbnails in grid view (install with `uvx --from 'peekin[thumbs]' peekin --thumbs`) |
+| `--show-hidden` | off | Show dotfiles |
+| `--open` | off | Open the browser |
+
+## Security
+
+- Read-only: nothing in the shared folder can be changed through peekin.
+- Paths cannot escape the shared folder, including through symlinks.
+- Five wrong passwords lock that IP address out for 60 seconds, doubling each time.
+- HTML and SVG files are downloaded, never rendered, so files you share can't run scripts in peekin.
+- Other websites you visit can't read your files through peekin: cross-site requests are blocked, and
+  without a password peekin only answers to IP addresses, `localhost`, and `*.local` names.
+- No HTTPS: use it on networks you trust, not on the public internet.
+
+## Develop
+
+```bash
+uv run pytest
+uv run peekin .
+```
+
+## Release
+
+1. Bump `__version__` in `src/peekin/__init__.py` and commit.
+2. `gh release create vX.Y.Z --generate-notes` (the tag must match the version).
+3. The `publish` workflow tests, builds, and uploads to PyPI via trusted publishing.
+
+## License
+
+MIT

peekin-0.1.0/README.md

@@ -0,0 +1,70 @@
+# peekin
+
+A lightweight, read-only file browser for your web browser. Browse a folder and
+preview images (swipeable gallery), video, audio, PDF, and source code with
+syntax highlighting. Works on desktop and phone. Fully offline.
+
+## Run
+
+```bash
+uvx peekin                     # share the current folder on http://127.0.0.1:8000
+uvx peekin ~/Pictures --open   # share a folder and open the browser
+python -m peekin               # after: pip install peekin
+```
+
+Until the first PyPI release:
+
+```bash
+uvx --from git+https://github.com/sumanmichael/peekin peekin
+```
+
+## Share on your network
+
+```bash
+uvx peekin --host 0.0.0.0
+```
+
+peekin needs a password whenever it listens on something other than
+localhost. If you don't set one, it generates one and prints it at startup.
+Set your own with `PEEKIN_PASSWORD=...` or `--password-file FILE`.
+`--no-password` turns the password off (not recommended on shared networks).
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `FOLDER` | `.` | Folder to share |
+| `--host` | `127.0.0.1` | Address to listen on (`0.0.0.0` for your network) |
+| `--port` | `8000` | Port |
+| `--password-file` | | Read the password from this file's first line |
+| `--no-password` | off | Never ask for a password |
+| `--thumbs` | off | Image thumbnails in grid view (install with `uvx --from 'peekin[thumbs]' peekin --thumbs`) |
+| `--show-hidden` | off | Show dotfiles |
+| `--open` | off | Open the browser |
+
+## Security
+
+- Read-only: nothing in the shared folder can be changed through peekin.
+- Paths cannot escape the shared folder, including through symlinks.
+- Five wrong passwords lock that IP address out for 60 seconds, doubling each time.
+- HTML and SVG files are downloaded, never rendered, so files you share can't run scripts in peekin.
+- Other websites you visit can't read your files through peekin: cross-site requests are blocked, and
+  without a password peekin only answers to IP addresses, `localhost`, and `*.local` names.
+- No HTTPS: use it on networks you trust, not on the public internet.
+
+## Develop
+
+```bash
+uv run pytest
+uv run peekin .
+```
+
+## Release
+
+1. Bump `__version__` in `src/peekin/__init__.py` and commit.
+2. `gh release create vX.Y.Z --generate-notes` (the tag must match the version).
+3. The `publish` workflow tests, builds, and uploads to PyPI via trusted publishing.
+
+## License
+
+MIT