sftp-pilot 2.0.0__tar.gz

sftp_pilot-2.0.0/CHANGE_LOG.md

@@ -0,0 +1,352 @@
+# Change Log
+
+All notable changes to SFTP Pilot (formerly WinSCP Manager) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+**Repository:** [https://github.com/Pandiyarajk/sftp-pilot](https://github.com/Pandiyarajk/sftp-pilot)  
+**Author:** Pandiyaraj Karuppasamy
+
+---
+
+## [2.0.0] - 2026-10-18
+
+Renamed from **WinSCP Manager** to **SFTP Pilot**. The app never used WinSCP,
+and WinSCP is another project's name. Behaviour is unchanged from 1.1.0.
+
+### Changed (breaking)
+| Was | Now |
+| --- | --- |
+| repository `winscp_tools` | `sftp-pilot` (GitHub redirects the old URL) |
+| package `winscp_manager` | `sftp_pilot` |
+| command `winscp-manager` | `sftp-pilot` |
+| `python -m winscp_manager` | `python -m sftp_pilot` |
+| class `WinSCPHandler` (`winscp_handler.py`) | `SFTPHandler` (`sftp_handler.py`) |
+| env `WINSCP_MANAGER_PASSWORD` | `SFTP_PILOT_PASSWORD` |
+| env `WINSCP_MANAGER_KEY_PASSPHRASE` | `SFTP_PILOT_KEY_PASSPHRASE` |
+| default log file `winscp_manager.log` | `sftp_pilot.log` |
+
+`config.ini`, `known_hosts` and `scheduled_tasks.json` keep their names and
+format, so existing files carry over. If you set `log_file` explicitly, it is
+kept as written.
+
+---
+
+## [1.1.0] - 2026-10-17
+
+Review fixes. Several 1.0.0 entries below described behaviour the code did not
+have; this release either implements it or says so.
+
+### Fixed
+- **Installed `winscp-manager` command crashed** with `ModuleNotFoundError: No
+  module named 'main'`; the entry point is now `winscp_manager.cli:main`.
+- **Host keys were never verified** (`AutoAddPolicy` accepted any server). The
+  default is now `accept_new`: remember a server on first connect, refuse it if
+  its key changes. `reject` and `auto_add` are available.
+- Key authentication only accepted RSA keys and had no passphrase support;
+  RSA, ECDSA and Ed25519 keys, encrypted or not, now work.
+- Scheduled tasks ignored `private_key_path` and connected with the password
+  only, and shared the GUI's SFTP connection across threads. Each run now opens
+  its own connection from the config file.
+- GUI worker threads updated widgets and opened dialogs directly, which Tk does
+  not support. All UI updates now go through the main thread. Connect and
+  delete no longer freeze the window.
+- Console: pressing Enter at "task ID to remove" removed the first task; IDs
+  now need four or more characters and must match exactly one task. Ctrl+C or
+  end of input no longer crash it.
+- A recurring task that failed once was never run again; it now keeps its
+  schedule and records the error.
+- A task running when the app closed stayed `running` forever; it is now
+  rescheduled on the next start.
+- `stop()` could take 10 seconds and tasks could be lost by concurrent saves;
+  the task file is now written atomically under a lock.
+- Progress callbacks divided by zero on empty files.
+- A failed download left a truncated file; downloads now go to `.part` first.
+- `config.ini` was committed despite being in `.gitignore`; it is untracked.
+
+### Changed
+- Python 3.11+ (3.7 to 3.10 are end of life). Packaging moved to
+  `pyproject.toml`; unused `python-dateutil` and `pytz` dependencies dropped.
+- `check_interval`, `enabled` and the `[LOGGING]` settings are now honoured.
+- `--config` and `--tasks-file` options; `python -m winscp_manager` works.
+- `WINSCP_MANAGER_PASSWORD` and `WINSCP_MANAGER_KEY_PASSPHRASE` environment
+  variables override the config file.
+- The `scp` protocol option was removed: it never existed (everything ran over
+  SFTP). `protocol` must be `sftp`.
+- The unused `temp_dir` setting was removed.
+
+### Added
+- Test suite, including integration tests against a local SFTP server.
+- Disclaimer in the README, `DISCLAIMER.md`, and a warning in `--help`.
+
+### Corrected claims from 1.0.0
+- There is no automatic reconnection and no resume of interrupted transfers.
+  Scheduled runs reconnect each time, which covers the unattended case.
+
+---
+
+## [1.0.0] - 2025-10-19
+
+**Initial Release** - Complete feature set
+
+### Added
+
+#### Core Features
+- **WinSCP/SFTP Protocol Handler**
+  - Full SFTP protocol support using paramiko library
+  - Connection management with automatic reconnection
+  - Support for password and key-based authentication
+  - Secure file transfer operations
+
+#### File Operations
+- **Upload Functionality**
+  - Upload files of any size to remote server
+  - Progress tracking with callback support
+  - Automatic remote directory creation
+  - Large file support with efficient streaming
+
+- **Download Functionality**
+  - Download files from remote server
+  - Progress tracking and reporting
+  - Automatic local directory creation
+  - Resume capability for interrupted transfers
+
+- **Delete Functionality**
+  - Delete files from remote server
+  - Safety confirmations in both interfaces
+  - Batch delete support through scheduler
+
+- **File Management**
+  - List files in remote directories
+  - Check file existence
+  - Get file metadata
+
+#### Scheduling System
+- **Task Scheduler**
+  - Background task execution engine
+  - Support for three task types: Upload, Download, Delete
+  - Persistent task storage (JSON-based)
+  - Automatic task state management
+
+- **Recurring Tasks**
+  - Configure tasks to run at regular intervals
+  - Customizable interval in minutes
+  - Automatic rescheduling after execution
+
+- **Task Management**
+  - Add new scheduled tasks
+  - View all scheduled tasks with details
+  - Remove/cancel tasks
+  - Task status tracking (pending, running, completed, failed)
+  - Error logging for failed tasks
+
+#### Configuration Management
+- **Config File Support**
+  - INI-based configuration file
+  - Separate sections for connection, paths, scheduling, and logging
+  - Easy credential management
+  - Support for multiple authentication methods
+
+- **Path Management**
+  - Default remote upload directory
+  - Default local download directory
+  - Temporary file directory configuration
+
+#### User Interfaces
+
+##### GUI Interface (Tkinter)
+- **Main Window**
+  - Modern tabbed interface design
+  - 1000x700 default window size
+  - Status bar with connection status
+  - Real-time updates
+
+- **Connection Tab**
+  - Server configuration form
+  - Protocol selection (SFTP, SCP)
+  - Connect/disconnect buttons
+  - Load configuration from file
+  - Visual connection status
+
+- **File Operations Tab**
+  - Upload section with file browser
+  - Download section with save dialog
+  - Delete section with confirmation
+  - Progress bar for transfers
+  - Real-time transfer statistics
+
+- **Scheduler Tab**
+  - Add scheduled task form
+  - Task type selection dropdown
+  - File browser integration
+  - Recurring task configuration
+  - Task list view (TreeView)
+  - Start/stop scheduler controls
+  - Refresh and remove task buttons
+
+- **Logs Tab**
+  - Scrollable log viewer
+  - Real-time log updates
+  - Formatted log entries with timestamps
+  - Color-coded log levels
+
+##### Console Interface
+- **Interactive Menu System**
+  - 12 menu options
+  - Clear, numbered interface
+  - Input validation
+  - User-friendly prompts
+
+- **All File Operations**
+  - Upload with progress display
+  - Download with progress display
+  - Delete with confirmation
+  - List remote files
+
+- **Scheduler Management**
+  - Schedule new tasks interactively
+  - View all scheduled tasks
+  - Remove tasks by ID
+  - Start/stop scheduler
+  - Full task configuration
+
+#### Cross-Platform Support
+- **Windows Compatibility**
+  - Full GUI support on Windows
+  - Console interface with cmd.exe support
+  - Path handling for Windows file system
+
+- **Linux/Mac Support**
+  - Full GUI support (with tkinter)
+  - Console interface with terminal support
+  - Unix path handling
+
+#### Logging
+- **Comprehensive Logging**
+  - File-based logging
+  - Console output
+  - Configurable log levels
+  - Timestamped entries
+  - Error tracking
+
+- **GUI Log Integration**
+  - Custom TextHandler for tkinter
+  - Thread-safe log updates
+  - Auto-scrolling log view
+
+#### Documentation
+- **README.md**
+  - Complete feature documentation
+  - Installation instructions
+  - Usage examples
+  - Configuration guide
+  - Troubleshooting section
+  - Security considerations
+
+- **CHANGE_LOG.md**
+  - Version history
+  - Detailed change tracking
+  - Semantic versioning
+
+- **Code Documentation**
+  - Comprehensive docstrings
+  - Type hints
+  - Module documentation
+  - Function documentation
+
+#### Development
+- **Project Structure**
+  - Modular package design
+  - Separation of concerns
+  - Clean architecture
+  - Easy to extend
+
+- **Requirements Management**
+  - requirements.txt with version pinning
+  - Minimal dependencies
+  - Clear dependency purposes
+
+### Technical Details
+
+#### Architecture
+- **Modular Design**
+  - config_manager.py - Configuration handling
+  - winscp_handler.py - SFTP protocol operations
+  - scheduler.py - Task scheduling and execution
+  - gui.py - GUI interface with tkinter
+  - console.py - Console interface
+  - main.py - Application entry point
+
+#### Dependencies
+- paramiko >= 3.3.1 - SSH/SFTP implementation
+- cryptography >= 41.0.5 - Cryptographic operations
+- python-dateutil >= 2.8.2 - Date handling
+- pytz >= 2023.3 - Timezone support
+
+#### Python Version Support
+- Python 3.7+
+- Tested on Python 3.8, 3.9, 3.10, 3.11
+
+### Security Features
+- Secure password handling
+- Key-based authentication support
+- Auto-host-key-acceptance with warnings
+- Secure configuration file storage
+- Connection encryption via SSH/SFTP
+
+### Performance
+- Efficient large file handling
+- Non-blocking UI operations
+- Background task execution
+- Threaded file operations
+- Progress tracking with minimal overhead
+
+### Known Limitations
+- GUI requires tkinter (not included on some Linux distributions)
+- Scheduler checks every 10 seconds (configurable in code)
+- Task storage limited to JSON file (no database)
+- Single connection per instance
+- No multi-threading for concurrent transfers
+
+### Future Enhancements (Planned)
+- Multiple simultaneous connections
+- Drag-and-drop file upload in GUI
+- Batch file operations
+- File synchronization
+- Bandwidth throttling
+- Resume failed transfers
+- Email notifications for scheduled tasks
+- Database backend for task storage
+- Web interface
+- REST API
+
+---
+
+## Version History Summary
+
+- **[1.0.0]** - 2025-10-19 - Initial release with full feature set
+
+---
+
+## How to Report Issues
+
+Found a bug or have a feature request? Please:
+1. Check [existing issues](https://github.com/Pandiyarajk/sftp-pilot/issues) first
+2. Create a [new issue](https://github.com/Pandiyarajk/sftp-pilot/issues/new) with detailed information
+3. Include version number, OS, and steps to reproduce
+
+---
+
+**Note:** This is the initial release of WinSCP Manager. Future versions will be documented here with detailed change tracking following semantic versioning principles.
+
+---
+
+<div align="center">
+
+Copyright © 2025 [Pandiyaraj Karuppasamy](https://github.com/Pandiyarajk)  
+Licensed under the [MIT License](LICENSE)
+
+</div>

sftp_pilot-2.0.0/DISCLAIMER.md

@@ -0,0 +1,28 @@
+# Disclaimer
+
+SFTP Pilot uploads, overwrites and deletes files on remote servers, and
+its scheduler does so unattended, repeatedly, at times you choose in advance.
+A wrong path or a wrong server can destroy data.
+
+- The software is provided **AS IS**, without warranty of any kind, express or
+  implied, including fitness for a particular purpose.
+- You use it **entirely at your own risk**. The author accepts no liability for
+  data loss or corruption, overwritten or deleted files, hardware damage,
+  unbootable or unreachable systems, business interruption, or any direct,
+  indirect or consequential damages.
+- **You are responsible** for checking every source and destination path and
+  every target server before running or scheduling a task, for keeping tested
+  backups of anything it can touch, and for being authorised to change the
+  servers you connect to.
+- It is **not certified** for regulated, forensic, safety-critical or other
+  high-assurance use.
+- Host key checking defaults to `accept_new`, which trusts a server the first
+  time it is seen. Verify the fingerprint of a new server through another
+  channel if that first connection matters.
+
+This file is a plain-language summary. The [MIT License](LICENSE) is the
+governing text and prevails wherever the two differ.
+
+SFTP Pilot is not affiliated with or endorsed by WinSCP or any other file
+transfer product; it talks SFTP directly through
+[paramiko](https://www.paramiko.org/).

sftp_pilot-2.0.0/LICENSE

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

sftp_pilot-2.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include CHANGE_LOG.md
+include DISCLAIMER.md
+include LICENSE
+include example_config.ini
+include requirements.txt
+recursive-include tests *.py
+
+exclude config.ini
+exclude scheduled_tasks.json
+exclude known_hosts
+global-exclude *.py[cod] *.log
+prune downloads

sftp_pilot-2.0.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: sftp-pilot
+Version: 2.0.0
+Summary: SFTP file transfer manager with a GUI, a console menu and a persistent task scheduler
+Author: Pandiyaraj Karuppasamy
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Pandiyarajk/sftp-pilot
+Project-URL: Issues, https://github.com/Pandiyarajk/sftp-pilot/issues
+Project-URL: Changelog, https://github.com/Pandiyarajk/sftp-pilot/blob/main/CHANGE_LOG.md
+Keywords: sftp,file-transfer,scheduler,automation,paramiko
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Environment :: X11 Applications
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paramiko>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: asyncssh>=2.14; extra == "dev"
+Dynamic: license-file
+
+# SFTP Pilot
+
+> **Disclaimer:** this tool uploads, overwrites and deletes files on remote
+> servers, including unattended through its scheduler. It is provided **AS IS**,
+> without warranty of any kind, and you use it **entirely at your own risk**: the
+> author is not liable for data loss, corruption, downtime or any other damage.
+> You are responsible for checking every target, keeping tested backups and being
+> authorised to change the servers you connect to. It is not certified for
+> regulated or safety-critical use. See [DISCLAIMER.md](DISCLAIMER.md); the
+> [LICENSE](LICENSE) is the governing text and prevails where the two differ.
+
+A Python SFTP client with a tkinter GUI, a console menu, and a persistent task
+scheduler for one-off or recurring uploads, downloads and deletes.
+
+It speaks SFTP directly through [paramiko](https://www.paramiko.org/), so it
+runs anywhere Python does. It was called WinSCP Manager (`winscp_tools`) up to
+version 1.1.0; see [CHANGE_LOG.md](CHANGE_LOG.md) for what moved.
+
+**Version:** 2.0.0 · **Python:** 3.11+ · **License:** MIT
+
+## Features
+
+- Upload, download, delete and list over SFTP, with progress for large files
+- Password or key authentication (RSA, ECDSA, Ed25519, encrypted keys included)
+- Host key verification: new servers are remembered, a changed key is refused
+- Remote folders are created on upload; downloads land under a temporary
+  `.part` name, so a failed transfer never leaves a truncated file behind
+- Scheduler with one-off and recurring tasks, saved to disk between sessions;
+  each run opens its own connection, so a dropped interactive session does not
+  stop scheduled work
+- Secrets can come from environment variables instead of the config file
+
+## Quick start
+
+```bash
+git clone https://github.com/Pandiyarajk/sftp-pilot.git
+cd sftp-pilot
+pip install .
+cp example_config.ini config.ini     # then edit config.ini
+sftp-pilot                       # GUI
+sftp-pilot --console             # console menu
+```
+
+From a checkout without installing: `pip install -r requirements.txt`, then
+`python main.py` (or `python -m sftp_pilot`).
+
+Options:
+
+| Option | Meaning |
+| --- | --- |
+| `--gui` / `--console` | Choose the interface (GUI is the default) |
+| `-c`, `--config PATH` | Configuration file (default `config.ini` in the current folder) |
+| `--tasks-file PATH` | Where scheduled tasks are saved (default `scheduled_tasks.json`) |
+| `--version` | Print the version |
+
+On Linux the GUI needs tkinter (`sudo apt-get install python3-tk`); the console
+interface works without it.
+
+## Configuration
+
+`config.ini` is git-ignored because it holds credentials. Start from
+[example_config.ini](example_config.ini):
+
+```ini
+[DEFAULT]
+protocol = sftp
+host = example.com
+port = 22
+username = your_username
+password =
+# private_key_path = ~/.ssh/id_ed25519
+# private_key_passphrase =
+host_key_policy = accept_new
+known_hosts_file = known_hosts
+timeout = 30
+
+[PATHS]
+remote_upload_dir = /remote/upload/path
+local_download_dir = ./downloads
+
+[SCHEDULING]
+enabled = true
+check_interval = 30
+
+[LOGGING]
+log_file = sftp_pilot.log
+log_level = INFO
+```
+
+| Key | Meaning |
+| --- | --- |
+| `protocol` | Only `sftp` is supported |
+| `password` | Overridden by the `SFTP_PILOT_PASSWORD` environment variable |
+| `private_key_path` | Key file; when set, key authentication is used |
+| `private_key_passphrase` | Overridden by `SFTP_PILOT_KEY_PASSPHRASE` |
+| `host_key_policy` | `accept_new` (default): trust on first connect, refuse a changed key. `reject`: only hosts already known. `auto_add`: no checking, testing only |
+| `known_hosts_file` | Where accepted host keys are stored; `~/.ssh/known_hosts` is also read |
+| `timeout` | Seconds allowed for connect and authentication |
+| `remote_upload_dir`, `local_download_dir` | Defaults offered by the upload and download prompts |
+| `enabled` | `false` stops the scheduler from being started |
+| `check_interval` | Seconds between checks for due tasks |
+| `log_file`, `log_level` | Log file (empty for console only) and level |
+
+### Keeping the password out of the file
+
+```powershell
+$env:SFTP_PILOT_PASSWORD = "..."     # PowerShell
+```
+
+```bash
+export SFTP_PILOT_PASSWORD='...'     # bash
+```
+
+Key authentication is the better option for anything unattended.
+
+### Host keys
+
+The first connection to a server stores its key in `known_hosts_file`. If the
+server later presents a different key, the connection is refused with a
+warning, since that is what a man-in-the-middle attack looks like. If the key
+really did change (server rebuilt), delete that server's line from the file.
+
+## Using it
+
+### GUI
+
+- **Connection:** host, port, user, password or key. Fields start from the
+  config file; **Reload Config** reads it again.
+- **File Operations:** upload (a remote path ending in `/` keeps the local file
+  name), download, delete (asks first). One transfer runs at a time and the
+  window stays responsive.
+- **Scheduler:** add tasks, start or stop the scheduler, remove the selected
+  tasks. The list refreshes every few seconds. A recurring task whose last run
+  failed shows `pending (last run failed)` and keeps its schedule.
+- **Logs:** everything that is written to the log.
+
+Scheduled tasks connect with the settings saved in the config file, not with
+whatever is typed in the Connection tab.
+
+### Console
+
+```
+1. Connect to server        7. Schedule task
+2. Disconnect from server   8. View scheduled tasks
+3. Upload file              9. Remove scheduled task
+4. Download file           10. Start scheduler
+5. Delete file             11. Stop scheduler
+6. List remote files       12. Exit
+```
+
+Remove a task by its full ID or an unambiguous prefix of at least four
+characters. Ctrl+C exits cleanly, stopping the scheduler and disconnecting.
+
+### Scheduling notes
+
+- The scheduler only runs while the application is open. For jobs that must
+  run with nobody logged in, use the operating system's scheduler (Task
+  Scheduler, cron) instead.
+- A task that was running when the application closed is run again at the next
+  start, and is marked as interrupted.
+- Scheduled deletes run unattended and every interval for recurring tasks.
+  Check the path twice.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The integration tests start a throwaway SFTP server (asyncssh) on localhost, so
+they need no external server. They cover transfers, key authentication, host
+key changes and a scheduled run end to end.
+
+```
+sftp_pilot/
+  cli.py             command-line entry point (sftp-pilot)
+  config_manager.py  config.ini reading, environment overrides
+  sftp_handler.py  SFTP connection and file operations
+  scheduler.py       task model, persistence, scheduler thread
+  runner.py          runs a task on its own connection
+  gui.py             tkinter interface
+  console.py         console menu
+tests/               pytest suite
+```
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| `Host key ... does not match` | The server key changed. Confirm why before removing its line from `known_hosts` |
+| `not a known host and host_key_policy is 'reject'` | Add the key to `known_hosts`, or use `accept_new` |
+| Authentication failed | Credentials, key path and passphrase; the server's allowed auth methods |
+| Scheduled task never runs | The scheduler is started, `enabled = true`, and the app is still open |
+| GUI does not start | `python -m tkinter`; on Linux install `python3-tk`; or use `--console` |
+
+## License
+
+MIT, see [LICENSE](LICENSE). Change history is in [CHANGE_LOG.md](CHANGE_LOG.md).