From fbfab2d60acf711853a7c887ea629ae45bb19fc2 Mon Sep 17 00:00:00 2001 From: Alexander Tarasov Date: Sun, 20 Jul 2025 01:09:41 +0300 Subject: [PATCH] udpate README.md --- README.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) diff --git a/README.md b/README.md index e69de29..605d5d4 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file