Metadata-Version: 2.2
Name: Files-VC
Version: 1.0.0
Summary: A Python wrapper and CLI for the Files.VC API, designed to upload, download, and manage files efficiently.
Author-email: Sasivarnasarma <sasivarnasarma@protonmail.com>
License: MIT
Project-URL: homepage, https://github.com/Sasivarnasarma/files-vc
Project-URL: repository, https://github.com/Sasivarnasarma/files-vc
Project-URL: issues, https://github.com/Sasivarnasarma/files-vc/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: requests-toolbelt
Requires-Dist: tabulate

# Files.VC Python Library

An Unofficial Python wrapper and CLI tool for the Files.VC API, designed to download, upload, and manage files efficiently.

## Features

- **Command-Line Interface (CLI)** – Manage files directly from the terminal.
- **Python Library** – Easily embed `files_vc` into your Python programs.
- **Beautiful Output** – Using the `tabulate` library, 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.
## Installation

Install the package from PyPI:

```bash
python3 -m pip install Files-VC -U
```

Ensure you have Python 3.7 or later.

---

## Using Files-VC as a Command Line Interface

Once installed, you can use the `files-vc` command to interact with the files.vc API.

```bash
files-vc --help
```
Use the `-h`/`--help` flag with any command to see the available options for that specific command.

```bash
file-vc <command> --help
```
### Usage

```bash
files-vc <command> <positional_arguments> [options]
```
#### Available Commands & Arguments
- **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
- **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
    - `-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](https://github.com/astanin/python-tabulate#table-format) for a list of available formats and more details.
**"This option must be used before the command."**

```	bash
files-vc --tablefmt grid <command> <args>
```

#### Examples

```bash
# Get file info
files-vc info <file_hash_or_url>
# List files for an account
files-vc list <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 --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.

---

## Using Files-VC in Python Programs

You can also embed Files-VC directly into your Python code:

```python
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)

# 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](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/__main__.py#L166-L190) file for reference/ideas.

## API Reference
**Each class and function includes a docstring. For more details, refer to it.**

### `FilesVC`

The core class for interacting with the files.vc API.

#### Methods

- `get_file_info(file_hash: str, ...) -> FileInfo`: Get information about a file. [(Docstring)](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/_main.py#L124-L138)
- `list_files(account_id: str) -> list[FileInfo]`: Retrieve a list of files for an account. [(Docstring)](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/_main.py#L160-L171)
- `check_file(file_path: str, ...) -> FileInfo | None`: Check if a file already exists on the server. [(Docstring)](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/_main.py#L189-L204)
- `download_file(file_hash: str, save_path: str, ...) -> str`: Download a file by hash. [(Docstring)](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/_main.py#L312-L330)
- `upload_file(file_path: str, account_id: str, ...) -> tuple[str, FileInfo]`: Upload a file to the server. [(Docstring)](https://github.com/Sasivarnasarma/files-vc/blob/main/files_vc/_main.py#L228-L251)


### `FileInfo`

Represents metadata for a file.

- `name`: File name
- `file_hash`: MD5 hash of the file
- `size`: File size in bytes
- `upload_time`: Time the file was uploaded
- `mime_type`: File's MIME type
- `download_count`: Number of downloads
- `view_url`: URL to view the file
- `download_url`: URL to download the file
- `expiration_time`: Expiration time (if any)

### Exception

- `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.
---

## Contributing
Contributions are welcome! Please open an issue or submit a pull request with your improvements.

## License
This project is licensed under the **MIT License**. See the `LICENSE` file for more details.

### With ❤️ Made By @Sasivarnasarma
