arabianq/yndx-disk
1
0
Fork 0
mirror of https://github.com/arabianq/yndx-disk.git synced 2026-04-27 22:21:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

udpate README.md

Browse Source
This commit is contained in:
Tarasov Aleksandr
2025-07-20 01:09:41 +03:00
parent dcd6a1d0bb
commit fbfab2d60a
1 changed files with 172 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+172
View File
@@ -0,0 +1,172 @@
# yndx-disk
A modern, object-oriented Python wrapper for the Yandex.Disk REST API, featuring both synchronous and asynchronous
clients.
`yndx-disk` provides a clean and intuitive interface for managing your Yandex.Disk files, directories, public resources,
and trash. The library is built on `aiohttp` and `aiofiles`, ensuring efficient asynchronous operations, and provides a
synchronous client for simpler, blocking use cases.
## Features
- **Dual Clients**: Use the `AsyncDiskClient` for modern `asyncio` applications or the simple `DiskClient` for
synchronous scripts.
- **Object-Oriented**: Interact with `File` and `Directory` objects that hold resource metadata.
- **Full API Coverage**: Manage files and directories (list, upload, download, move, copy, delete).
- **Trash Management**: List, restore, or permanently delete items from the trash.
- **Public Resources**: Publish files and directories to create public links.
- **Type Hinting**: Fully type-hinted codebase for better autocompletion and static analysis.
## Installation
Install the library using pip:
```sh
pip install yndx-disk
```
## Getting Started
First, you need to obtain a Yandex.Disk OAuth token. You can get one for development purposes from
the [Yandex.Disk Polygon](https://yandex.ru/dev/disk/poligon/).
### Synchronous Client Example
The `DiskClient` provides a straightforward, blocking interface.
```python
from yndx_disk.clients import DiskClient
# You must provide your OAuth token
TOKEN = "YOUR_OAUTH_TOKEN_HERE"
if TOKEN == "YOUR_OAUTH_TOKEN_HERE":
print("Please provide your Yandex.Disk OAuth token.")
else:
# 1. Initialize the client
client = DiskClient(token=TOKEN)
# 2. Get and print basic disk information
client.update_disk_info()
print(f"Total Space: {client.total_space // 1024 ** 3} GB")
print(f"Used Space: {client.used_space // 1024 ** 3} GB")
# 3. Create a dummy file to upload
with open("hello.txt", "w") as f:
f.write("Hello, Yandex.Disk!")
# 4. Upload the file to the root of the disk
try:
print("\nUploading 'hello.txt'...")
client.upload_file("hello.txt", "/hello.txt", overwrite=True)
print("Upload successful.")
except Exception as e:
print(f"Upload failed: {e}")
# 5. List files in the root directory
print("\nListing files in '/':")
items = client.listdir("/")
for item in items:
item_type = "d" if "Directory" in str(type(item)) else "f"
print(f"[{item_type}] {item.path}")
# 6. Delete the file from the disk
try:
print("\nDeleting '/hello.txt'...")
client.delete("/hello.txt")
print("Deletion successful.")
except Exception as e:
print(f"Deletion failed: {e}")
```
### Asynchronous Client Example
The `AsyncDiskClient` is perfect for non-blocking I/O operations in `asyncio`-based applications.
```python
import asyncio
from yndx_disk.clients import AsyncDiskClient
# You must provide your OAuth token
TOKEN = "YOUR_OAUTH_TOKEN_HERE"
async def main():
if TOKEN == "YOUR_OAUTH_TOKEN_HERE":
print("Please provide your Yandex.Disk OAuth token.")
return
# 1. Initialize the async client
client = AsyncDiskClient(token=TOKEN)
# 2. Get and print basic disk information
await client.update_disk_info()
print(f"Total Space: {client.total_space // 1024 ** 3} GB")
print(f"Used Space: {client.used_space // 1024 ** 3} GB")
# 3. Create a dummy file to upload
with open("hello_async.txt", "w") as f:
f.write("Hello, Async Yandex.Disk!")
# 4. Upload the file to the root of the disk
try:
print("\nUploading 'hello_async.txt'...")
await client.upload_file("hello_async.txt", "/hello_async.txt", overwrite=True)
print("Upload successful.")
except Exception as e:
print(f"Upload failed: {e}")
# 5. List files in the root directory
print("\nListing files in '/':")
items = await client.listdir("/")
for item in items:
item_type = "d" if "Directory" in str(type(item)) else "f"
print(f"[{item_type}] {item.path}")
# 6. Delete the file from the disk
try:
print("\nDeleting '/hello_async.txt'...")
await client.delete("/hello_async.txt")
print("Deletion successful.")
except Exception as e:
print(f"Deletion failed: {e}")
# Remember to close the session when you're done
await client.session.close()
if __name__ == "__main__":
asyncio.run(main())
```
## API Overview
Both `DiskClient` and `AsyncDiskClient` share the same methods. For the async client, all methods are coroutines and
must be awaited.
### Disk and Resource Management
| Method | Description |
|-------------------------------------------|-----------------------------------------------------------------|
| `update_disk_info()` | Refreshes disk info (space, user, etc.) on the client instance. |
| `get_object(path)` | Retrieves a `File` or `Directory` object for the given path. |
| `listdir(path, limit, offset)` | Lists the contents of a directory. |
| `upload_file(file_path, path, overwrite)` | Uploads a local file to the specified path on the disk. |
| `get_url(path)` | Gets a download URL for a file or folder. |
| `delete(path, permanently)` | Deletes a file or folder (moves to trash by default). |
| `copy(source_path, destination_path)` | Copies a file or folder. |
| `move(source_path, destination_path)` | Moves a file or folder. |
| `publish(path)` | Makes a resource public and returns its public URL. |
| `unpublish(path)` | Reverts a public resource to private. |
### Trash Management
| Method | Description |
|--------------------------------------|------------------------------------------------------------------------------------------|
| `listdir_trash(path, limit, offset)` | Lists items in the trash. |
| `restore_trash(path, new_name)` | Restores a file or folder from the trash, optionally renaming it. |
| `delete_trash(path)` | Permanently deletes an item from the trash. If `path` is empty, clears the entire trash. |
## License
This project is licensed under the MIT License.