PutPlace Assist
Local assistant daemon for file uploads to the PutPlace server.
Overview
PutPlace Assist is a local FastAPI daemon that runs on client machines to assist with file uploads. It provides:
- Path Registration: Register directories to be scanned and uploaded
- File Watching: Automatic detection of file changes via watchdog
- SHA256 Checksums: Automatic calculation and tracking of file hashes
- Upload Queue: Background file uploads with retry logic
- Real-time Activity: SSE and WebSocket endpoints for monitoring
- SQLite Database: Local tracking of files, upload status, and activity
Installation
pip install putplace-assist
Quick Start
Start the Daemon
# Start in background
ppassist start
# Start in foreground (for development)
ppassist start --foreground
# Check status
ppassist status
# Stop daemon
ppassist stop
Using the API
Register a path:
curl -X POST http://localhost:8765/paths \
-H "Content-Type: application/json" \
-d '{"path": "/path/to/watch", "recursive": true}'
Add exclude patterns:
curl -X POST http://localhost:8765/excludes \
-H "Content-Type: application/json" \
-d '{"pattern": "*.log"}'
Configure remote server:
curl -X POST http://localhost:8765/servers \
-H "Content-Type: application/json" \
-d '{"name": "production", "url": "https://app.putplace.org", "username": "user", "password": "pass"}'
Trigger uploads:
curl -X POST http://localhost:8765/uploads \
-H "Content-Type: application/json" \
-d '{"upload_content": true}'
Monitor activity (SSE):
curl http://localhost:8765/activity/stream
API Endpoints
Status
GET /- Root endpointGET /health- Health checkGET /status- Daemon status
Paths
GET /paths- List registered pathsPOST /paths- Register a new pathGET /paths/{id}- Get path detailsDELETE /paths/{id}- Unregister a pathPOST /paths/{id}/scan- Trigger rescan
Excludes
GET /excludes- List exclude patternsPOST /excludes- Add exclude patternDELETE /excludes/{id}- Remove pattern
Files
GET /files- List tracked filesGET /files/{id}- Get file detailsDELETE /files/{id}- Remove from trackingGET /files/stats- File statistics
Servers
GET /servers- List configured serversPOST /servers- Add server configurationDELETE /servers/{id}- Remove serverPOST /servers/{id}/default- Set as default
Uploads
POST /uploads- Trigger file uploadsGET /uploads/status- Upload statusGET /uploads/queue- Queue status
Activity
GET /activity- Recent activity eventsGET /activity/stream- SSE event streamWS /ws/activity- WebSocket events
Scanning
POST /scan- Full scan of all paths
Configuration
Configuration can be set via:
- Environment variables (prefix:
PPASSIST_) - TOML config file (
ppassist.toml) - Command-line defaults
Environment Variables
| Variable | Default | Description |
|---|---|---|
PPASSIST_SERVER_HOST |
127.0.0.1 |
Host to bind to |
PPASSIST_SERVER_PORT |
8765 |
Port to bind to |
PPASSIST_SERVER_LOG_LEVEL |
INFO |
Logging level |
PPASSIST_DB_PATH |
~/.local/share/putplace/assist.db |
Database path |
PPASSIST_WATCHER_ENABLED |
true |
Enable file watching |
Config File Example
Create ~/.config/putplace/ppassist.toml:
[server]
host = "127.0.0.1"
port = 8765
log_level = "INFO"
[database]
path = "~/.local/share/putplace/assist.db"
[watcher]
enabled = true
debounce_seconds = 2.0
[uploader]
parallel_uploads = 4
retry_attempts = 3
Development
# Install dev dependencies
uv pip install -e '.[dev]'
# Run tests
invoke test
# Run linter
invoke lint
# Format code
invoke format
# Run all checks
invoke check
# Run development server
invoke serve
License
MIT
Metadata
Release files for putplace-assist 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| putplace_assist-0.3.0.tar.gz | 89.0 kB | Without provenance | Details for putplace_assist-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| putplace_assist-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for putplace_assist-0.3.0-py3-none-any.whl |
Total release size: 169.9 kB
Release files / putplace_assist-0.3.0.tar.gz
| Download URL | putplace_assist-0.3.0.tar.gz |
|---|---|
| Size | 89.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
de370820968b3c62f1080f36f38b9d94add0561eb0111bd5347d087f7a21f747
|
|
BLAKE2b-256 checksum How to use checksums |
a024cb3165818e091ab8cea4ac9fec2f32cedc67aac13940e4011c58548163ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / putplace_assist-0.3.0-py3-none-any.whl
| Download URL | putplace_assist-0.3.0-py3-none-any.whl |
|---|---|
| Size | 80.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7fdad867de9ce1d92092d2fb00005733c3b9cff40dcb6d810119c00020e20846
|
|
BLAKE2b-256 checksum How to use checksums |
e43a016adb4cd9638394025dc187106380280768d610f43d0b444bf23d2aa16b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for putplace-assist 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.