Warning
An Unofficial Python wrapper and CLI tool for the Files.VC API, designed to download, upload, and manage files efficiently.
- Command-Line Interface (CLI) – Manage files directly from the terminal.
- Python Library – Easily embed
files_vcinto your Python programs. - Beautiful Output – Using the
tabulatelibrary, provides a well-formatted table for file information. - Progress Tracking – Shows real-time progress for uploads and downloads.
- Dynamic Progress Bar – In CLI mode, displays terminal size based progress bar with speed, remaining time, and elapsed time.
- Error Handling – Graceful handling of network failures and interruptions.
- Cross-Platform – Works on Windows, macOS, and Linux.
Install the package from PyPI:
python3 -m pip install Files-VC -UEnsure you have Python 3.7 or later.
Once installed, you can use the files-vc command to interact with the files.vc API.
files-vc --helpUse the -h/--help flag with any command to see the available options for that specific command.
file-vc <command> --helpfiles-vc <command> <positional_arguments> [options]- Common options:
-h/--help: Display help-v/--version: Display version information-t/--tablefmt: Set File info output format
- info: Get file information by file hash or URL
- list: List all files for a given account ID
- delete: Delete a file from the server
-a/--account_id: Specify the account ID that belongs to the file. (Required)
- check: Check if a file already exists on the server
- download/dl: Download a file using its hash or URL
-s/--save: Specify the folder path to save the downloaded file
- upload/ul: Upload a file to the server
k/--api_key: Specify API Key for authentication. (Required) Get API Key-a/--account_id: Specify the account ID to upload the file
You can customize table output format using the -t/--tablefmt option, which supports formats like plain, grid, etc.
Check out the Tabulate README for a list of available formats and more details.
Important
To upload a file, you must provide a valid API token. Obtain your API key from the Files.VC
"This option must be used before the command."
files-vc --tablefmt grid <command> <args># Get file info
files-vc info <file_hash_or_url>
# List files for an account
files-vc list <account_id>
# Delete a file from the server
files-vc delete <file_hash_or_url> --account_id <account_id>
# Check if a file exists on the server
files-vc check /path/to/file
# Download a file (with optional save location)
files-vc download <file_hash_or_url> --save /path/to/save/location
# Upload a file (with optional account ID)
files-vc upload /path/to/file --api_key <api_key> --account_id <account_id>Note
After uploading, it may take a few seconds (depending on the file size) to display the file info, so please be patient. This is because the server takes some time to send a response.
You can also embed Files-VC directly into your Python code:
from files_vc import FilesVC
files_vc = FilesVC()
# Get file info
file_info = files_vc.get_file_info(file_hash="your_file_hash")
print(file_info.name, file_info.size)
# List files
files = files_vc.list_files(account_id="your_account_id")
for file in files:
print(file.name, file.download_url)
# Delete a file
message = files_vc.delete_file(file_hash="your_file_hash", account_id="your_account_id")
print(message)
# Check if a file exists
file_info = files_vc.check_file(file_path="/path/to/file")
print(file_info)
# Upload a file
message, file_info = files_vc.upload_file("/path/to/file", account_id="your_account_id")
print(message, file_info.view_url)
# Download a file
downloaded_path = files_vc.download_file(file_hash="your_file_hash", save_path="/path/to/save")
print(f"File saved at {downloaded_path}")Tip
Always verify if the file already exists on the server using the FilesVC().check_file(file_path} function before uploading it.
This will reduce unwanted bandwidth usage.
Check the __main__.py file for reference/ideas.
Each class and function includes a docstring. For more details, refer to it.
The core class for interacting with the files.vc API.
get_file_info(file_hash: str, ...) -> FileInfo: Get information about a file. (Docstring)list_files(account_id: str) -> list[FileInfo]: Retrieve a list of files for an account. (Docstring)delete_file(file_hash: str, account_id: str, ...) -> str: Delete a file from the server. (Docstring)check_file(file_path: str, ...) -> FileInfo | None: Check if a file already exists on the server. (Docstring)download_file(file_hash: str, save_path: str, ...) -> str: Download a file by hash. (Docstring)upload_file(file_path: str, account_id: str, ...) -> tuple[str, FileInfo]: Upload a file to the server. (Docstring)
Tip
The check_file, download_file, and upload_file functions include progress and progress_args parameters, which allow you to customize the progress.
Check the __main__.py file for reference/ideas.
Represents metadata for a file.
name: File namefile_hash: MD5 hash of the filesize: File size in bytesupload_time: Time the file was uploadedmime_type: File's MIME typedownload_count: Number of downloadsview_url: URL to view the filedownload_url: URL to download the fileexpiration_time: Expiration time (if any)
FilesVCException: Custom exception for handling errors related to files.vc API operations.HTTPError: Exception raised when there is an HTTP error. (Same as requests.exceptions.HTTPError)- And other exceptions from the requests library.
- Creating tests – Unit and integration tests for core functions.
- Creating documentation – Generate API documentation for better developer experience.
Contributions are welcome! Please open an issue or submit a pull request with your improvements.
This project is licensed under the MIT License. See the LICENSE file for more details.