dash-bucket-upload 0.1.0__tar.gz

dash_bucket_upload-0.1.0/.babelrc

@@ -0,0 +1,23 @@
+{
+  "presets": [
+    "@babel/preset-env",
+    "@babel/preset-react"
+  ],
+  "env": {
+    "production": {
+      "plugins": [
+        "styled-jsx/babel"
+      ]
+    },
+    "development": {
+      "plugins": [
+        "styled-jsx/babel"
+      ]
+    },
+    "test": {
+      "plugins": [
+        "styled-jsx/babel-test"
+      ]
+    }
+  }
+}

dash_bucket_upload-0.1.0/.gitignore

@@ -0,0 +1,295 @@
+# Created by .ignore support plugin (hsz.mobi)
+### Webpack
+.build_cache
+### VisualStudioCode template
+.vscode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+### Node template
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+### SublimeText template
+# Cache files for Sublime Text
+*.tmlanguage.cache
+*.tmPreferences.cache
+*.stTheme.cache
+
+# Workspace files are user-specific
+*.sublime-workspace
+
+# Project files should be checked into the repository, unless a significant
+# proportion of contributors will probably not be using Sublime Text
+# *.sublime-project
+
+# SFTP configuration file
+sftp-config.json
+
+# Package control specific files
+Package Control.last-run
+Package Control.ca-list
+Package Control.ca-bundle
+Package Control.system-ca-bundle
+Package Control.cache/
+Package Control.ca-certs/
+Package Control.merged-ca-bundle
+Package Control.user-ca-bundle
+oscrypto-ca-bundle.crt
+bh_unicode_properties.cache
+
+# Sublime-github package stores a github token in this file
+# https://packagecontrol.io/packages/sublime-github
+GitHub.sublime-settings
+
+# Julia manifest file names
+Manifest.toml
+JuliaManifest.toml
+
+# Project-specific ignores
+.claude/
+
+# Backup files
+*.bak
+
+# Built JS bundle — produced by the hatchling build hook (hatch_build.py) inside
+# `uv build`, or locally via `make build`; no longer git-tracked (#40 phase 2)
+dash_bucket_upload/dash_bucket_upload.min.js
+dash_bucket_upload/dash_bucket_upload.min.js.map
+dash_bucket_upload/dash_bucket_upload.min.js.LICENSE.txt
+
+.ruff_cache

dash_bucket_upload-0.1.0/LICENSE

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

dash_bucket_upload-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: dash-bucket-upload
+Version: 0.1.0
+Summary: Large-file upload component for Plotly Dash that stores files in an S3-compatible bucket
+Project-URL: Homepage, https://github.com/slemke/dash-bucket-upload
+Author-email: Scott Lemke <scott.r.lemke@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dash,minio,multipart,plotly,s3,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Dash
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: dash<5,>=3.0.0
+Description-Content-Type: text/markdown
+
+# dash-bucket-upload
+
+Large-file uploads for [Plotly Dash](https://dash.plotly.com/), stored in any
+S3-compatible bucket (AWS S3, MinIO, Ceph, …).
+
+A drop-in replacement for the `dcc.Upload` experience — drag-and-drop or file
+picker, multiple files, per-file progress bars — that streams files into a
+bucket with S3 multipart uploads instead of base64-encoding them through a
+Dash callback (which adds ~33% overhead and falls over past a few hundred MB).
+Handles multi-gigabyte files. Callbacks receive the bucket location and
+metadata, never the file contents; end users see a normal upload widget and
+nothing else.
+
+- **Two transports, one API.** Files go either **direct** from the browser to
+  the bucket via presigned multipart URLs (no bytes touch the Dash server), or
+  are **relayed** through a streaming route on the Dash server (no bucket CORS
+  or browser-to-bucket connectivity needed). Your callback code is identical
+  in both modes.
+- **Collision-free keys.** Objects are stored as
+  `<prefix>/<uuid4>/<original-filename>` — original names preserved, no
+  collisions.
+- **Airgap-safe.** All JavaScript ships inside the wheel and is served locally
+  by Dash. No CDN, no external assets, ever.
+- **Robust engine.** Parallel part uploads, exponential-backoff retries,
+  presigned-URL refresh on expiry, cancellation with server-side multipart
+  abort, throttled progress reporting.
+
+## Installation
+
+```bash
+pip install dash-bucket-upload      # or: uv add dash-bucket-upload
+```
+
+## Quickstart
+
+```python
+from dash import Dash, Input, Output, html
+from dash_bucket_upload import BucketUpload, BucketUploadManager
+
+app = Dash(__name__)
+
+mgr = BucketUploadManager(
+    app,
+    endpoint_url = 'http://localhost:9000',   # any S3-compatible store; omit for AWS S3
+    access_key = 'minioadmin',
+    secret_key = 'minioadmin',
+    region = 'us-east-1',
+    bucket = 'uploads',
+    prefix = 'incoming',
+    mode = 'direct',                          # or 'relay'
+)
+
+app.layout = html.Div([
+    BucketUpload(id = 'up', manager = mgr),
+    html.Div(id = 'out'),
+])
+
+@app.callback(Output('out', 'children'), Input('up', 'lastUploadedBatch'))
+def on_upload(batch):
+    if not batch:
+        return 'Nothing uploaded yet.'
+    # batch: [{'bucket': ..., 'key': ..., 'filename': ..., 'size': ..., 'etag': ..., 'status': 'done'}]
+    return f"Uploaded {len(batch)} file(s): " + ', '.join(f['key'] for f in batch)
+
+if __name__ == '__main__':
+    app.run(debug = True)
+```
+
+Try it locally with MinIO:
+
+```bash
+docker compose -f examples/docker-compose.minio.yml up -d
+uv run python examples/direct_mode.py
+```
+
+## S3-compatible stores
+
+The manager speaks the S3 protocol (via boto3 as a protocol library), not
+"AWS": point `endpoint_url` at any S3-compatible store and pass its
+access/secret key pair using the provider-neutral parameter names
+(`access_key`, `secret_key`, `session_token`, `region`,
+`addressing_style`). The boto3 spellings (`aws_access_key_id`, …) are
+accepted as aliases. `bucket` is a Swift *container* / GCS *bucket* /
+Ceph *bucket* — same concept everywhere.
+
+| Store | Setup notes |
+|---|---|
+| AWS S3 | Omit `endpoint_url`; omit credentials to use the normal AWS chain (env vars, config files, instance/IRSA roles). |
+| MinIO | `endpoint_url='http(s)://minio:9000'` + root or service-account keys. Path-style addressing is applied automatically. |
+| Ceph RGW | `endpoint_url` at the RGW endpoint + S3 keys from `radosgw-admin user create`. |
+| OpenStack Swift (s3api middleware) | `endpoint_url` at the Swift proxy's S3 endpoint; credentials are Keystone EC2-style: `openstack ec2 credentials create` → pass the resulting access/secret pair. `region` should match the Keystone region if SigV4 validation is strict (often `RegionOne`). Multipart uploads are backed by SLO segments and honor the same ≥5 MiB part rule. For direct mode, CORS lives on the container: `swift post uploads -H 'X-Container-Meta-Access-Control-Allow-Origin: https://your-app' -H 'X-Container-Meta-Access-Control-Expose-Headers: etag'`. |
+| Anything else | If `mc`/`aws s3api` works against it, this does too. `addressing_style='virtual'` for stores behind wildcard DNS; `signature_version` and `botocore_config` are escape hatches for exotic setups. |
+
+Relay mode is the lowest-friction path on stores where you can't (or don't
+want to) configure CORS — the browser never talks to the store directly.
+
+## Choosing a transport
+
+| | `mode='direct'` | `mode='relay'` |
+|---|---|---|
+| Data path | browser → bucket | browser → Dash server → bucket |
+| Dash server load | none (metadata only) | streams every byte (bounded memory) |
+| Browser must reach bucket | yes | no |
+| Bucket CORS required | yes (see below) | no |
+| Best for | biggest files, many users | locked-down networks, no CORS control |
+
+Both modes use S3 multipart uploads under the hood and never buffer whole
+files in server memory.
+
+## Multiple widgets, buckets, and limits
+
+```python
+mgr = BucketUploadManager(app, ..., bucket = 'uploads')      # registers 'default'
+mgr.register('videos', bucket = 'media', prefix = 'video', mode = 'relay',
+             max_file_size = 10 * 2**30, allowed_extensions = ['.mp4', '.mkv'])
+
+BucketUpload(id = 'up1', manager = mgr)                       # -> uploads/
+BucketUpload(id = 'up2', manager = mgr, upload_id = 'videos') # -> media/video/
+```
+
+Size/extension/MIME limits are enforced server-side; the component also
+mirrors them client-side for instant feedback.
+
+## Callback-facing props
+
+| prop | fires | contents |
+|---|---|---|
+| `lastUploadedBatch` | once per completed drop/selection batch | the new files: `[{bucket, key, filename, size, etag, status}]` — **use this as your callback Input** |
+| `uploadedFiles` | after each file | same shape, cumulative for the component's lifetime — useful as `State` |
+| `isUploading` | on change | `True` while any file is in flight |
+| `progress` | throttled (~4/s) | per-file `{filename, size, loaded, percent, speedBps, status}` for custom progress UI (set `show_file_list=False`) |
+| `lastError` | on failure | `{filename, message, phase}` |
+
+## Bucket CORS (direct mode only)
+
+Direct mode PUTs parts from the browser straight to the bucket, so the bucket
+must allow it — **including exposing the `ETag` response header**, without
+which the browser cannot finish the multipart upload (the widget raises a
+targeted error if this is missing).
+
+AWS S3 (`aws s3api put-bucket-cors --bucket uploads --cors-configuration file://cors.json`):
+
+```json
+{
+  "CORSRules": [{
+    "AllowedOrigins": ["https://your-app.example.com"],
+    "AllowedMethods": ["PUT", "GET", "HEAD"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 3600
+  }]
+}
+```
+
+MinIO (`mc cors set local/uploads examples/minio-init/cors.xml`) — see
+`examples/minio-init/cors.xml`; the example compose file applies it
+automatically.
+
+## Production checklist
+
+- **Authentication.** The upload routes are open by default. Gate them:
+
+  ```python
+  from flask_login import current_user
+  BucketUploadManager(app, ..., auth_check = lambda request: current_user.is_authenticated)
+  ```
+
+- **Limits.** Set `max_file_size`, and `allowed_extensions` /
+  `allowed_mime_types` where applicable.
+- **Abandoned uploads.** Add a bucket lifecycle rule aborting incomplete
+  multipart uploads (browsers closed mid-upload leave invisible parts behind):
+  see `examples/minio-init/lifecycle.json`; on AWS use
+  `AbortIncompleteMultipartUpload` with `DaysAfterInitiation: 1`.
+- **Reverse proxies (relay mode).** Every part travels as one request of up to
+  the part size (16 MiB default, larger for huge files). Raise
+  `client_max_body_size` (nginx) or equivalent accordingly, and keep Flask's
+  `MAX_CONTENT_LENGTH` above the part size if your app sets one.
+- **Credentials.** The browser never sees bucket credentials in either mode —
+  direct mode uses short-lived presigned URLs (`presign_expiration`, default
+  1h; the engine refreshes expired URLs automatically).
+
+## How it works
+
+1. The component POSTs `create` → the server validates, generates the
+   collision-free key, starts an S3 multipart upload, and picks a part size
+   (files are split so they always fit S3's 10,000-part limit; parts are
+   `Blob.slice` views, so browser memory stays flat regardless of file size).
+2. Parts upload in parallel (4 per file, 6 total by default) — via presigned
+   URLs (direct) or the streaming `part` route (relay) — with retry and
+   backoff.
+3. `complete` finishes the multipart upload; the server reads the final size
+   from the bucket and the component fires your callback.
+
+Cancel buttons, unmount, and failures all abort the S3 multipart upload
+server-side.
+
+## Development
+
+Requires Python ≥ 3.12, Node ≥ 20, [uv](https://docs.astral.sh/uv/).
+
+```bash
+npm install            # JS toolchain
+npm run build          # webpack bundle + regenerate the Dash component classes
+uv sync                # Python env (.venv)
+npm test               # vitest (JS engine)
+uv run pytest          # Python suite (moto-backed, no Docker needed)
+make quality           # ruff + pyright
+```
+
+The wheel is self-building: `uv build` compiles the JS bundle via a hatchling
+hook, so the bundle is never committed to git.
+
+## License
+
+MIT