### Complete ExApp Example Setup

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

A comprehensive example demonstrating the setup of a Nextcloud ExApp using FastAPI. Includes logging configuration, settings form definition, lifecycle handlers, and middleware.

```python
from contextlib import asynccontextmanager
import logging

from fastapi import FastAPI, Depends
from nc_py_api import AsyncNextcloudApp
from nc_py_api.ex_app import (
    AppAPIAuthMiddleware,
    LogLvl,
    run_app,
    set_handlers,
    setup_nextcloud_logging,
    anc_app,
    SettingsField,
    SettingsFieldType,
    SettingsForm
)

# Configure logging
logger = logging.getLogger(__name__)

# Define settings form
SETTINGS = SettingsForm(
    fields=[
        SettingsField(
            id="api_endpoint",
            label="API Endpoint",
            type=SettingsFieldType.TEXT,
            required=True
        )
    ]
)

# Lifecycle handler
async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
    level = LogLvl.INFO if enabled else LogLvl.WARNING
    await nc.log(level, f"App {'enabled' if enabled else 'disabled'}")
    return ""

# Create app
@asynccontextmanager
async def lifespan(app: FastAPI):
    setup_nextcloud_logging(nc := AsyncNextcloudApp())
    set_handlers(app, enabled_handler)
    yield

app = FastAPI(lifespan=lifespan)
app.add_middleware(AppAPIAuthMiddleware)

# Register settings
@app.post("/settings")
async def register_settings(nc: AsyncNextcloudApp = Depends(anc_app)):
    await nc.ui.register_settings_form("settings", SETTINGS)
    return {"status": "ok"}
```

--------------------------------

### Async Preferences API Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Demonstrates asynchronous operations for getting, setting, and retrieving all user preferences using the AsyncPreferencesAPI.

```python
import asyncio

async def main():
    # Get preference
    theme = await nc.preferences.get_preference("accessibility", "theme", "light")
    
    # Set preference
    await nc.preferences.set_preference("myapp", "setting1", "value")
    
    # Get all
    all_prefs = await nc.preferences.get_all("myapp")

asyncio.run(main())
```

--------------------------------

### Nextcloud Skeleton App in Python

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/README.md

This example demonstrates how to set up a basic Nextcloud application using FastAPI and the AsyncNextcloudApp class. It includes lifespan management for setting handlers and an example handler for logging messages.

```python
from contextlib import asynccontextmanager

from fastapi import FastAPI

from nc_py_api import AsyncNextcloudApp
from nc_py_api.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers


@asynccontextmanager
async def lifespan(app: FastAPI):
    set_handlers(app, enabled_handler)
    yield


APP = FastAPI(lifespan=lifespan)
APP.add_middleware(AppAPIAuthMiddleware)


async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
    if enabled:
        await nc.log(LogLvl.WARNING, "Hello from nc_py_api.")
    else:
        await nc.log(LogLvl.WARNING, "Bye bye from nc_py_api.")
    return ""


if __name__ == "__main__":
    run_app("main:APP", log_level="trace")
```

--------------------------------

### AsyncNextcloudApp FastAPI Integration Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Demonstrates how to integrate AsyncNextcloudApp with FastAPI using an async context manager for lifespan and an authentication middleware. This setup is suitable for running Nextcloud ExApps.

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from nc_py_api import AsyncNextcloudApp
from nc_py_api.ex_app import AppAPIAuthMiddleware, LogLvl, run_app, set_handlers

@asynccontextmanager
async def lifespan(app: FastAPI):
    set_handlers(app, enabled_handler)
    yield

async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
    if enabled:
        await nc.log(LogLvl.WARNING, "Hello from nc_py_api.")
    else:
        await nc.log(LogLvl.WARNING, "Bye bye from nc_py_api.")
    return ""

app = FastAPI(lifespan=lifespan)
app.add_middleware(AppAPIAuthMiddleware)

if __name__ == "__main__":
    run_app("main:app", log_level="trace")
```

--------------------------------

### Install nc-py-api

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/README.md

Install the nc-py-api library using pip.

```bash
pip install nc-py-api
```

--------------------------------

### AsyncAppsAPI - Get List

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Asynchronously gets a list of installed applications, with an option to filter by enabled or disabled status.

```APIDOC
## get_list(enabled: bool | None = None) -> list[str]

### Description
Gets list of installed applications asynchronously.

### Parameters
#### Query Parameters
- **enabled** (bool | None) - Optional - Filter: None=all, True=enabled only, False=disabled only

### Returns
List of application IDs

### Example
```python
async def main():
    enabled = await nc.apps.get_list(enabled=True)
```
```

--------------------------------

### ExApp Environment Setup

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Configure environment variables for ExApp, including application details and Nextcloud instance information. This setup is required for applications developed using AppAPI.

```env
# Application info (required)
APP_ID=my_app
APP_VERSION=1.0.0
APP_SECRET=your_secret_key_here

# Nextcloud instance (required)
NEXTCLOUD_URL=https://nextcloud.example.com

# AppAPI version (optional)
AA_VERSION=2.2.0

# Other options
NPA_TIMEOUT=30
NPA_TIMEOUT_DAV=90
```

--------------------------------

### AsyncAppsAPI - Is Installed

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Asynchronously checks if a specific application is installed on the server.

```APIDOC
## is_installed(app_id: str) -> bool

### Description
Checks if application is installed asynchronously.

### Parameters
#### Path Parameters
- **app_id** (str) - Required - The ID of the application to check.

### Returns
True if the application is installed, False otherwise.

### Example
```python
async def main():
    has_talk = await nc.apps.is_installed("spreed")
```
```

--------------------------------

### Get All, Enabled, and Disabled Apps

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieve lists of all installed applications, or filter by enabled or disabled status.

```python
all_apps = nc.apps.get_list()
enabled_apps = nc.apps.get_list(enabled=True)
disabled_apps = nc.apps.get_list(enabled=False)
```

--------------------------------

### AppsAPI - Get List

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Gets a list of installed applications, with an option to filter by enabled or disabled status.

```APIDOC
## get_list(enabled: bool | None = None)

### Description
Gets list of installed applications.

### Parameters
#### Query Parameters
- **enabled** (bool | None) - Optional - Filter: None=all, True=enabled only, False=disabled only

### Returns
List of application IDs

### Example
```python
all_apps = nc.apps.get_list()
enabled_apps = nc.apps.get_list(enabled=True)
disabled_apps = nc.apps.get_list(enabled=False)
```
```

--------------------------------

### Async Webhook Management Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Demonstrates asynchronous registration, listing, and unregistration of webhooks using the `AsyncWebhooksAPI`. Requires an `asyncio` event loop.

```python
import asyncio

async def main():
    # Register webhook
    webhook_id = await nc.webhooks.register(
        "https://myapp.example.com/webhook",
        ["file_created"]
    )
    
    # List webhooks
    webhooks = await nc.webhooks.list()
    
    # Unregister
    await nc.webhooks.unregister(webhook_id)

asyncio.run(main())
```

--------------------------------

### ExApp Development with FastAPI

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/README.md

Shows how to build an ExApp using FastAPI, including setting up handlers, authentication middleware, and defining status endpoints. This example uses asynchronous context managers for lifespan events.

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from nc_py_api import AsyncNextcloudApp
from nc_py_api.ex_app import (
    AppAPIAuthMiddleware, 
    LogLvl, 
    run_app, 
    set_handlers
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    set_handlers(app, enabled_handler)
    yield

async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
    if enabled:
        await nc.log(LogLvl.INFO, "App enabled")
    return ""

app = FastAPI(lifespan=lifespan)
app.add_middleware(AppAPIAuthMiddleware)

@app.get("/status")
async def status(nc: AsyncNextcloudApp):
    return {"enabled": await nc.enabled_state}

if __name__ == "__main__":
    run_app("main:app", log_level="info")
```

--------------------------------

### File Action Endpoint Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

An example FastAPI endpoint for processing file actions. It receives file information, converts it to an FsNode, downloads the file content, processes it, and uploads the result. Requires an AsyncNextcloudApp instance.

```python
from fastapi import FastAPI
from nc_py_api.files import ActionFileInfo
from nc_py_api import AsyncNextcloudApp

app = FastAPI()

@app.post("/action/process")
async def process_file_action(
    file: ActionFileInfo,
    nc: AsyncNextcloudApp
):
    # Convert to FsNode for file operations
    node = file.to_fs_node()
    
    # Read file
    content = await nc.files.download(node)
    
    # Process
    result = process_content(content)
    
    # Upload result
    await nc.files.upload(f"{node.user_path}.processed", result)
    
    return {"status": "success"}
```

--------------------------------

### Check App Installation Status

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Verify if a specific application is installed on the Nextcloud instance.

```python
if nc.apps.is_installed("spreed"):
    print("Talk is installed")
```

--------------------------------

### Production Nextcloud Client Setup

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Configure an AsyncNextcloud client for production using environment variables for sensitive credentials. Sets specific timeouts for network operations.

```python
import os
from nc_py_api import AsyncNextcloud

nc = AsyncNextcloud(
    nextcloud_url=os.environ['NEXTCLOUD_URL'],
    nc_auth_user=os.environ['NC_AUTH_USER'],
    nc_auth_pass=os.environ['NC_AUTH_PASS'],
    npa_timeout=30,
    npa_timeout_dav=90,
    npa_nc_cert=True        # Use default CA bundle
)
```

--------------------------------

### run_app

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Launches the ExApp FastAPI server using uvicorn. This function is used to start the application and make it accessible via a specified host and port.

```APIDOC
## run_app

### Description
Launches the ExApp FastAPI server using uvicorn. This function is used to start the application and make it accessible via a specified host and port.

### Parameters
#### Parameters
- **app_module** (str) - Required - Module path (e.g., "main:app")
- **host** (str) - Optional - Bind address. Defaults to "0.0.0.0".
- **port** (int) - Optional - Bind port. Defaults to 9000.
- **log_level** (str) - Optional - Log level: debug, info, warning, error. Defaults to "info".

### Example
```python
if __name__ == "__main__":
    from nc_py_api.ex_app import run_app
    run_app("main:app", log_level="info")
```
```

--------------------------------

### FsNode Usage Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/types.md

Demonstrates how to retrieve an FsNode object using its path and how to pass this FsNode object to file API methods like download.

```python
node = nc.files.by_path("/some/file.txt")
content = nc.files.download(node)  # Can pass FsNode as path
```

--------------------------------

### AppsAPI - Is Installed

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Checks if a specific application is installed on the server.

```APIDOC
## is_installed(app_id: str)

### Description
Checks if application is installed.

### Parameters
#### Path Parameters
- **app_id** (str) - Required - The ID of the application to check.

### Returns
True if the application is installed, False otherwise.

### Example
```python
if nc.apps.is_installed("spreed"):
    print("Talk is installed")
```
```

--------------------------------

### Development Nextcloud Client Setup

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Configure an AsyncNextcloud client for local development using explicit connection details. Disables certificate checks and timeouts for easier debugging.

```python
import os
from nc_py_api import AsyncNextcloud

# Use local Nextcloud for development
nc = AsyncNextcloud(
    nextcloud_url="http://localhost:8080",
    nc_auth_user="admin",
    nc_auth_pass="admin",
    npa_nc_cert=False,      # Disable cert check locally
    npa_timeout=None,       # No timeout for debugging
    npa_timeout_dav=None
)
```

--------------------------------

### Async Talk API Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/talk-messaging-api.md

Demonstrates common asynchronous operations using the Talk API, including creating rooms, sending messages, retrieving messages, adding users, reacting to messages, and setting notification levels.

```python
import asyncio
from nc_py_api.talk import ConversationType

async def main():
    # Create room
    room_id = await nc.talk.create_room(ConversationType.ONE_TO_ONE, "john")
    
    # Send message
    msg = await nc.talk.send_message(room_id, "Hello!")
    
    # Get messages
    messages = await nc.talk.get_messages(room_id, limit=50)
    for msg in messages:
        print(f"{msg.actor_display_name}: {msg.message}")
    
    # Add user
    await nc.talk.add_to_room(room_id, "alice")
    
    # React to message
    await nc.talk.react_to_message(room_id, msg.message_id, "👍")
    
    # Set notification level
    from nc_py_api.talk import NotificationLevel
    await nc.talk.set_notification_level(room_id, NotificationLevel.ALWAYS_NOTIFY)

asyncio.run(main())
```

--------------------------------

### Get Application Configuration

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Retrieves an application configuration value by its key. Provides a default value if the key is not found.

```python
debug = nc.appconfig_ex.get_config("debug_mode", "false")
max_retries = nc.appconfig_ex.get_config("max_retries", "3")
```

--------------------------------

### Define ExApp Settings UI

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Defines the structure for application settings using SettingsField and SettingsForm. This example shows how to create text, checkbox, and select fields with various configurations.

```python
from nc_py_api.ex_app import SettingsField, SettingsFieldType, SettingsForm

settings = SettingsForm(
    fields=[
        SettingsField(
            id="api_key",
            label="API Key",
            type=SettingsFieldType.TEXT,
            required=True,
            placeholder="Enter your API key"
        ),
        SettingsField(
            id="debug_mode",
            label="Debug Mode",
            type=SettingsFieldType.CHECKBOX,
            default=False
        ),
        SettingsField(
            id="log_level",
            label="Log Level",
            type=SettingsFieldType.SELECT,
            options=["debug", "info", "warning", "error"],
            default="info"
        )
    ]
)
```

--------------------------------

### Deploy Docker Image with Bot

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot_ai/HOW_TO_INSTALL.md

Use this command to deploy a Docker image containing a bot. Ensure the AppAPI is installed and a deployment daemon is created.

```bash
php occ app_api:app:deploy talk_bot_ai "daemon_deploy_name" \
--info-xml https://raw.githubusercontent.com/cloud-py-api/nc_py_api/main/examples/as_app/talk_bot_ai/appinfo/info.xml
```

--------------------------------

### Async Notifications API Example

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Demonstrates common asynchronous operations for managing notifications, including fetching, marking as read, creating, and deleting.

```python
import asyncio

async def main():
    # Get all notifications
    notifs = await nc.notifications.get_notifications()
    
    # Mark as read
    await nc.notifications.mark_all_as_read()
    
    # Create notification
    notif = await nc.notifications.create(
        "john",
        "New message"
    )
    
    # Delete
    await nc.notifications.delete_notification(notif.notification_id)

asyncio.run(main())
```

--------------------------------

### PreferencesAPI - Get All

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Retrieves all preferences for a specific application ID, or all preferences for all applications if no app_id is provided.

```APIDOC
## get_all

### Description
Gets all preferences for an app.

### Method
`nc.preferences.get_all(app_id: str = "") -> dict[str, str]`

### Parameters
#### Path Parameters
- **app_id** (str) - Optional - Application ID (empty = all)

### Response
Dictionary of key -> value pairs
```

--------------------------------

### Get All App Preferences

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Retrieves all preferences for a specific application or all applications if no app_id is provided.

```python
# Get all preferences for an app
all_prefs = nc.preferences.get_all("myapp")
for key, value in all_prefs.items():
    print(f"{key}: {value}")

# Get all preferences for all apps
all_app_prefs = nc.preferences.get_all()
```

--------------------------------

### AsyncPreferencesAPI - Get All

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Asynchronously retrieves all preferences for a specific application ID, or all preferences for all applications if no app_id is provided.

```APIDOC
## get_all (async)

### Description
Gets all preferences for an app asynchronously.

### Method
`await nc.preferences.get_all(app_id: str = "") -> dict[str, str]`

### Parameters
#### Path Parameters
- **app_id** (str) - Optional - Application ID (empty = all)

### Response
Dictionary of key -> value pairs
```

--------------------------------

### Get Status

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Retrieves the current status of the application, including its name, version, and enabled state.

```APIDOC
## GET /status

### Description
Retrieves the current status of the application, including its name, version, and enabled state.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **app** (string) - The name of the application.
- **version** (string) - The version of the application.
- **enabled** (boolean) - The enabled state of the application.

### Response Example
{
  "app": "example_app",
  "version": "1.0.0",
  "enabled": true
}
```

--------------------------------

### Check and Use Nextcloud Talk

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/errors.md

Attempts to create a Talk room, catching NextcloudMissingCapabilities if the Talk app is not installed or enabled. Use this to conditionally use Talk functionality.

```python
async def use_talk():
    try:
        room_id = await nc.talk.create_room(ConversationType.ONE_TO_ONE, "user123")
    except NextcloudMissingCapabilities:
        print("Talk (messaging) is not available on this Nextcloud instance")
        print("Install the 'spreed' app to enable Talk")
        return None
    return room_id
```

--------------------------------

### Register OCC Command

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Example of how to register a new OCC (command-line) command using the OccCommandsAPI. This allows users to interact with the app via the Nextcloud command line.

```python
@app.post("/register-commands")
async def register_occ_commands(nc: AsyncNextcloudApp):
    # Register a simple command
    await nc.occ_commands.register({
        "name": "myapp:process",
        "description": "Process files",
        "usage": "myapp:process [--options]"
    })
```

--------------------------------

### Get ExApp User Preference

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Retrieves a specific user's preference for an ExApp, with an optional default value.

```python
# Get user's preference for this ExApp
pref = nc.preferences_ex.get_user_preference(
    "my_app",
    "notifications",
    "john",
    "enabled"
)
```

--------------------------------

### Register Task Processor

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Example of how to register a task processor with the Providers API. This allows the application to handle specific task types. Requires an AsyncNextcloudApp instance.

```python
# Register task processor
await nc.providers.register_task_processor({
    "id": "my_processor",
    "name": "My Task Processor",
    "input_types": ["text"],
    "output_types": ["text"],
    "description": "Process text tasks"
})
```

--------------------------------

### Async Operations for Apps API

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Demonstrates asynchronous usage of Apps API methods for fetching app lists, checking installation status, and listing external apps.

```python
import asyncio

async def main():
    # Get enabled apps
    enabled = await nc.apps.get_list(enabled=True)
    
    # Check if installed
    has_talk = await nc.apps.is_installed("spreed")
    
    # List ExApps
    ex_apps = await nc.apps.ex_app_list()

asyncio.run(main())
```

--------------------------------

### Get System Tags

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Retrieves the system tags assigned to a file. Iterates through the returned list to display tag names.

```python
tags = nc.files.get_tags("/document.pdf")
for tag in tags:
    print(f"Tag: {tag.display_name}")
```

--------------------------------

### Initialize Nextcloud Client from Environment Variables

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Initialize the AsyncNextcloud client using configuration loaded from environment variables. Ensure relevant variables like NEXTCLOUD_URL are set.

```python
from nc_py_api import AsyncNextcloud

# From environment variables
nc = AsyncNextcloud()
```

--------------------------------

### Configuration from Environment Variables

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/README.md

Illustrates how to configure the `AsyncNextcloud` client by reading credentials and settings from environment variables, optionally using a `.env` file loaded by `python-dotenv`. This is recommended for security and flexibility.

```python
import os
from dotenv import load_dotenv

load_dotenv()  # Loads .env file
nc = AsyncNextcloud()  # Reads from environment
```

--------------------------------

### Async Group Management Operations

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Demonstrates various asynchronous operations for managing groups, including creation, retrieval of members, listing all groups, searching, and getting subadmins. Use this for non-blocking group management in async applications.

```python
import asyncio

async def main():
    # Create group
    await nc.users_groups.create("developers")
    
    # Get members
    members = await nc.users_groups.get_members("developers")
    
    # List all groups
    groups = await nc.users_groups.list_all()
    
    # Search
    results = await nc.users_groups.search("dev")
    
    # Get subadmins
    subadmins = await nc.users_groups.get_subadmins("developers")

asyncio.run(main())
```

--------------------------------

### Get User Preference

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Retrieves a user's preference value for a given application and key. Provides a default value if the preference is not found.

```python
# Get user's dark mode preference
dark_mode = nc.preferences.get_preference("accessibility", "theme", "light")

# Get custom app setting
setting = nc.preferences.get_preference("myapp", "setting1", "default_value")
```

--------------------------------

### Get Nextcloud Server Capabilities

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Retrieve the server capabilities as a dictionary using the `capabilities` property. Check for specific features like 'spreed'.

```python
caps = nc.capabilities
if "spreed" in caps:
    print("Talk (messaging) is available")
```

--------------------------------

### Create Directory

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Creates a new directory at the specified path. Use `exist_ok=True` to prevent errors if the directory already exists.

```python
nc.files.mkdir("/NewFolder", exist_ok=True)
```

--------------------------------

### Get Theme Information

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Access the `theme` property to get parsed theme information. Check if theme information is available before accessing its properties.

```python
if nc.theme:
    print(f"Theme name: {nc.theme.name}")
```

--------------------------------

### Get Server Version Information

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Access the `srv_version` property to get server version details, including major, minor, and micro versions.

```python
version = nc.srv_version
print(f"Nextcloud {version['string']}")
```

--------------------------------

### Process Incoming Webhooks with FastAPI

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/preferences-webhooks.md

Example of a FastAPI endpoint to receive and process Nextcloud webhook events. Includes signature verification using HMAC-SHA256 and parsing of event data.

```python
from fastapi import FastAPI, Request, HTTPException
import hashlib
import hmac

app = FastAPI()
WEBHOOK_SECRET = "your_webhook_secret"

@app.post("/webhook")
async def handle_webhook(request: Request):
    # Verify signature if using HMAC
    signature = request.headers.get("X-Signature")
    body = await request.body()
    
    if signature:
        expected = hmac.new(
            WEBHOOK_SECRET.encode(),
            body,
            hashlib.sha256
        ).hexdigest()
        if not hmac.compare_digest(signature, expected):
            raise HTTPException(status_code=403, detail="Invalid signature")
    
    # Parse event
    data = await request.json()
    event = data.get("event")
    user_id = data.get("userId")
    
    if event == "file_created":
        file_path = data.get("filePath")
        print(f"File created: {file_path}")
    elif event == "user_created":
        print(f"User created: {user_id}")
    
    return {"status": "ok"}
```

--------------------------------

### Register and Deploy Talk Bot App

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot/HOW_TO_INSTALL.md

Use this command to register and deploy the talk_bot ExApp. Ensure you have created a deployment daemon according to the AppPI instructions.

```bash
php occ app_api:app:register talk_bot --force-scopes \
--info-xml https://raw.githubusercontent.com/cloud-py-api/nc_py_api/main/examples/as_app/talk_bot/appinfo/info.xml
```

--------------------------------

### Get AI Model Path

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Utility function to get the designated path for storing AI models within an ExApp. This ensures models are stored in a consistent and accessible location.

```python
from nc_py_api.ex_app import get_model_path

model_dir = get_model_path()  # Returns Path to model directory
```

--------------------------------

### Initialize AsyncNextcloud Client

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Instantiate the asynchronous Nextcloud client with server credentials. This is the primary entry point for interacting with the Nextcloud API asynchronously.

```python
import asyncio
from nc_py_api import AsyncNextcloud

async def main():
    nc = AsyncNextcloud(nextcloud_url="https://nextcloud.example.com",
                        nc_auth_user="user",
                        nc_auth_pass="password")
    
    files = await nc.files.listdir()
    print(f"Found {len(files)} items")

asyncio.run(main())
```

--------------------------------

### Initialize Nextcloud Client with Explicit Parameters

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Initialize the AsyncNextcloud client by explicitly providing connection parameters such as URL, username, and password.

```python
from nc_py_api import AsyncNextcloud

# With explicit parameters
nc = AsyncNextcloud(
    nextcloud_url="https://nextcloud.example.com",
    nc_auth_user="admin",
    nc_auth_pass="password123"
)
```

--------------------------------

### NotificationsAPI - Get Notifications

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves all notifications for the current user.

```APIDOC
## get_notifications()

### Description
Gets all notifications for current user.

### Returns
List of Notification objects

### Example
```python
notifs = nc.notifications.get_notifications()
for notif in notifs:
    print(f"[{notif.app}] {notif.short_message}")
```
```

--------------------------------

### AsyncActivityAPI - Get Filters

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Asynchronously retrieves the available activity filters.

```APIDOC
## get_filters() -> list[ActivityFilter]

### Description
Gets available activity filters asynchronously.

### Returns
List of ActivityFilter objects

### Example
```python
filters = await nc.activity.get_filters()
for filter in filters:
    print(f"{filter.name} (priority: {filter.priority})")
```
```

--------------------------------

### Get all note categories

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Retrieves a list of all available note categories.

```python
categories = await nc.notes.get_categories()
```

--------------------------------

### Get Computation Device Utility

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Detects and returns the available computation device.

```APIDOC
## get_computation_device()

### Description
Detects and returns the available computation device (e.g., 'cpu', 'cuda', 'mps').

### Method
(Function Call)

### Endpoint
(Accessed via `nc_py_api.ex_app.get_computation_device`)

### Returns
- **string** - The name of the detected computation device.
```

--------------------------------

### Initialize NextcloudApp with Handlers and Middleware

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/configuration.md

Initialize an AsyncNextcloudApp and set up FastAPI with AppAPI authentication middleware and lifecycle handlers. This is used for applications developed using AppAPI.

```python
from nc_py_api import AsyncNextcloudApp
from nc_py_api.ex_app import AppAPIAuthMiddleware, set_handlers, run_app
from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Lifecycle handler for FastAPI app."""
    set_handlers(app, enabled_handler)
    yield

async def enabled_handler(enabled: bool, nc: AsyncNextcloudApp) -> str:
    """Called when app is enabled/disabled."""
    log_level = LogLvl.INFO if enabled else LogLvl.WARNING
    await nc.log(log_level, f"App {'enabled' if enabled else 'disabled'}")
    return ""

# Create FastAPI app
app = FastAPI(lifespan=lifespan)

# Add AppAPI authentication middleware
app.add_middleware(AppAPIAuthMiddleware)
```

--------------------------------

### Get Model Path Utility

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Retrieves the path for storing AI models.

```APIDOC
## get_model_path()

### Description
Gets the path for storing AI models within the ExApp.

### Method
(Function Call)

### Endpoint
(Accessed via `nc_py_api.ex_app.get_model_path`)

### Returns
- **Path** - The path to the AI model directory.
```

--------------------------------

### get_rooms()

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/talk-messaging-api.md

Gets all conversations the user is a member of. Returns a list of Room objects.

```APIDOC
## get_rooms()

### Description
Gets all conversations the user is a member of.

### Returns
list[Room] - List of Room objects.

### Example
```python
rooms = nc.talk.get_rooms()
for room in rooms:
    print(f"Room: {room.display_name} ({room.conversation_type})")
```
```

--------------------------------

### Register UI Elements with ExApp

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Demonstrates registering various UI elements with the Nextcloud ExApp framework via the `nc.ui` API. This includes settings forms, file actions, and top menu items.

```python
# Register settings form
await nc.ui.register_settings_form("my_settings", settings_form)

# Register file action
await nc.ui.register_file_action({
    "displayName": "Process File",
    "mime": ["text/plain"],
    "handlers": [{"verb": "process", "displayName": "Process"}]
})

# Register top menu item
await nc.ui.register_top_menu_item({
    "id": "app_menu",
    "label": "My App",
    "icon": "icon-url",
    "href": "/index.php/apps/my_app"
})
```

--------------------------------

### Get User Groups

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Retrieves a list of all groups that a specific user belongs to.

```python
groups = nc.users.get_user_groups("john")
```

--------------------------------

### Get Inherited Shares

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Retrieves shares that are inherited from parent directories for a given path.

```python
inherited = nc.files.sharing.get_inherited_shares("/Documents/file.pdf")
```

--------------------------------

### Run ExApp FastAPI Server

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Launches the ExApp FastAPI server using uvicorn. Specify the module path for your app, and optionally configure the host, port, and log level.

```python
if __name__ == "__main__":
    from nc_py_api.ex_app import run_app
    run_app("main:app", log_level="info")
```

--------------------------------

### setup_nextcloud_logging

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Configures Python logging to write to Nextcloud. This utility allows application logs to be sent to the Nextcloud logging system.

```APIDOC
## setup_nextcloud_logging

### Description
Configures Python logging to write to Nextcloud. This utility allows application logs to be sent to the Nextcloud logging system.

### Parameters
#### Parameters
- **nc** (AsyncNextcloudApp) - Required - The NextcloudApp instance.
- **log_level** (int) - Optional - The logging level. Defaults to `logging.INFO`.

### Example
```python
import logging
from nc_py_api.ex_app import setup_nextcloud_logging
from nc_py_api import AsyncNextcloudApp

# Assuming 'nc' is an instance of AsyncNextcloudApp
async def startup(nc: AsyncNextcloudApp):
    setup_nextcloud_logging(nc, logging.INFO)
    logger = logging.getLogger(__name__)
    logger.info("App started")
```
```

--------------------------------

### Instantiate Synchronous Nextcloud Client

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Create an instance of the synchronous Nextcloud client using URL, username, and password. Parameters can also be read from environment variables.

```python
from nc_py_api import Nextcloud

nc = Nextcloud(nextcloud_url="https://nextcloud.example.com", 
               nc_auth_user="user", 
               nc_auth_pass="password")

# Use the API
files = nc.files.listdir()
users = nc.users.list_all()
```

--------------------------------

### Basic Synchronous File Listing

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/README.md

Demonstrates basic synchronous usage of the Nextcloud client to list files. Ensure you have the Nextcloud URL and authentication credentials.

```python
from nc_py_api import Nextcloud

nc = Nextcloud(
    nextcloud_url="https://nextcloud.example.com",
    nc_auth_user="admin",
    nc_auth_pass="password"
)

# List files
files = nc.files.listdir()

```

--------------------------------

### AsyncActivityAPI - Get Activities

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Asynchronously retrieves activity logs with various filtering and sorting options.

```APIDOC
## get_activities(filter_id: ActivityFilter | str = "", since: int | bool = 0, limit: int = 50, object_type: str = "", object_id: int = 0, sort: str = "desc") -> list[Activity]

### Description
Gets activity logs asynchronously.

### Parameters
#### Query Parameters
- **filter_id** (ActivityFilter | str) - Optional - Filter to apply
- **since** (int | bool) - Optional - Start from activity ID (True=use last_given)
- **limit** (int) - Optional - Max activities to return
- **object_type** (str) - Optional - Filter by object type
- **object_id** (int) - Optional - Filter by object ID
- **sort** (str) - Optional - Sort order: "asc" or "desc"

### Returns
List of Activity objects

### Raises
NextcloudExceptionNotModified if no new activities

### Example
```python
# Get latest activities
activities = await nc.activity.get_activities(limit=100)
for activity in activities:
    print(f"{activity.actor_id}: {activity.subject}")

# Get activities since last call
new = await nc.activity.get_activities(since=True)

# Filter by object
file_activities = await nc.activity.get_activities(
    object_type="files",
    object_id=12345
)
```
```

--------------------------------

### Get All User Notifications

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves all notifications for the current user, displaying the app and short message for each.

```python
notifs = nc.notifications.get_notifications()
for notif in notifs:
    print(f"[{notif.app}] {notif.short_message}")
```

--------------------------------

### AsyncNextcloudApp Method Usage

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Illustrates common asynchronous operations using the AsyncNextcloudApp instance, such as checking enabled state, retrieving app configuration, logging, listing users, setting init status, and registering Talk bots.

```python
enabled = await nc.enabled_state
config = await nc.app_cfg
await nc.log(LogLvl.INFO, "Async logging")
all_users = await nc.users_list()
await nc.set_init_status(100)
bot_id, bot_secret = await nc.register_talk_bot("/bot", "Bot")
await nc.set_user("test_user")
```

--------------------------------

### Get all user statuses

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Retrieves a dictionary containing the status of all users, mapped by user ID.

```python
all_statuses = await nc.user_status.get_all_statuses()
for user_id, status in all_statuses.items():
    print(f"{user_id}: {status.status}")
```

--------------------------------

### mkdir

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Creates a directory at the specified path. Optionally, it can avoid raising an error if the directory already exists.

```APIDOC
## mkdir

### Description
Creates a directory.

### Parameters
#### Path Parameters
- **path** (str) - Required - Directory path to create
- **exist_ok** (bool) - Optional - Don't raise error if exists. Defaults to False.

### Returns
FsNode of created directory or None if exists and exist_ok=True

### Example
```python
nc.files.mkdir("/NewFolder", exist_ok=True)
```
```

--------------------------------

### Get Current User ID

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Access the `user` property to retrieve the current user's ID.

```python
current_user = nc.user
```

--------------------------------

### _AsyncTeamsAPI.create

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Creates a new team or circle with a display name and optional configuration.

```APIDOC
## create

### Description
Creates a new team/circle.

### Method
`POST` (inferred)

### Endpoint
`/teams` (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **display_name** (str) - Required - Team display name
- **config** (CircleConfig | int) - Optional - Configuration flags (default: CircleConfig.DEFAULT)

### Request Example
```python
from nc_py_api.teams import CircleConfig

# Simple team
await nc.teams.create("Development Team")

# Open team (anyone can join)
await nc.teams.create(
    "Public Team",
    config=CircleConfig.VISIBLE | CircleConfig.OPEN
)
```

### Response
#### Success Response (200)
- **Circle** (object) - Created Circle object
```

--------------------------------

### Nextcloud Constructor

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Initializes a synchronous Nextcloud client. Parameters can be provided directly or will be read from environment variables or a .env file if not specified.

```APIDOC
## `Nextcloud` Constructor

### Description
Initializes a synchronous Nextcloud client for connecting to Nextcloud instances using username/password authentication.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **nextcloud_url** (str) - Required - URL of the Nextcloud instance
- **nc_auth_user** (str) - Optional - Login username
- **nc_auth_pass** (str) - Optional - Password or app-password
- **npa_timeout** (int | None) - Optional - OCS API timeout in seconds (default: 30)
- **npa_timeout_dav** (int | None) - Optional - File operations timeout in seconds (default: 90)
- **npa_nc_cert** (bool | str) - Optional - SSL certificate verification or path to CA bundle (default: True)
- **chunked_upload_v2** (bool) - Optional - Enable chunked upload protocol v2 (default: True)

### Request Example
```python
from nc_py_api import Nextcloud

nc = Nextcloud(nextcloud_url="https://nextcloud.example.com", 
               nc_auth_user="user", 
               nc_auth_pass="password")
```

### Response
None

### Raises
`DeprecationWarning` - Sync API is deprecated, migrate to `AsyncNextcloud`
```

--------------------------------

### get_room(room_id: str)

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/talk-messaging-api.md

Gets a specific room/conversation by its ID. Returns the Room object or None if not found.

```APIDOC
## get_room(room_id: str)

### Description
Gets a specific room/conversation.

### Parameters
#### Path Parameters
- **room_id** (str) - Required - Room identifier

### Returns
Room | None - Room object or None if not found

### Example
```python
room = nc.talk.get_room("abc123")
if room:
    print(f"Type: {room.conversation_type}")
    print(f"Participants: {room.participant_count}")
```
```

--------------------------------

### create

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Creates a new user account with the specified user ID, password, and an optional display name.

```APIDOC
## create

### Description
Creates a new user account.

### Method
`create`

### Parameters
#### Path Parameters
- **user_id** (str) - Required - Username
- **password** (str) - Required - User password
- **display_name** (str) - Optional - User's display name

### Request Example
```python
nc.users.create("newuser", "password123", "New User")
```

### Response
#### Success Response
None

### Raises
`NextcloudException` on error
```

--------------------------------

### Get Group Subadmins

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Lists the user IDs of subadministrators for a given group. Useful for understanding group delegation.

```python
subadmins = nc.users_groups.get_subadmins("developers")
```

--------------------------------

### Get a Specific Notification

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves a single notification by its ID. Accepts either an integer ID or a Notification object.

```python
notif = nc.notifications.get_notification(123)
```

--------------------------------

### Create User

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Use this method to create a new user account. Provide the user ID, password, and an optional display name.

```python
nc.users.create("newuser", "password123", "New User")
```

--------------------------------

### Get a Specific Team

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Retrieves a specific team by its ID. Use this when you need to access details of a single team.

```python
circle = await nc.teams.get_circle("team123")
if circle:
    print(f"Members: {circle.member_count}")
```

--------------------------------

### AsyncNextcloud Constructor

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Initializes the asynchronous Nextcloud client. It accepts the same parameters as the synchronous `Nextcloud` client, allowing for configuration of the connection and authentication.

```APIDOC
## Constructor

```python
async def __init__(self, **kwargs) -> None:
```

Initializes the asynchronous Nextcloud client. Accepts the same parameters as `Nextcloud`.
```

--------------------------------

### NextcloudApp Constructor

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/nextcloud-client.md

Initializes the Nextcloud client for ExApp development using AppAPI authentication. Parameters are typically read from the environment and direct instantiation is discouraged.

```APIDOC
## Class: NextcloudApp

### Constructor

```python
def __init__(self, **kwargs) -> None:
```

Initializes the Nextcloud client for ExApp development. Parameters are read from the environment. Should not be instantiated directly.
```

--------------------------------

### Get Available Activity Filters

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves a list of available filters for activity logs, including their names and priorities.

```python
filters = await nc.activity.get_filters()
for filter in filters:
    print(f"{filter.name} (priority: {filter.priority})")
```

--------------------------------

### Create Share with User

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Creates a share for a specific user with read permissions. Requires importing `ShareType` and `FilePermissions`.

```python
from nc_py_api.files import ShareType, FilePermissions

# Share with user
share = nc.files.sharing.create(
    "/Documents/report.pdf",
    ShareType.TYPE_USER,
    "john",
    permissions=FilePermissions.PERMISSION_READ
)
```

--------------------------------

### List All System Tags

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Retrieves a list of all available system tags in the system.

```python
all_tags = nc.files.list_tags()
```

--------------------------------

### Get Group Details

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Retrieves detailed information about a specific group, returned as a dictionary. Useful for inspecting group properties.

```python
details = nc.users_groups.get_group_details("developers")
```

--------------------------------

### List External Applications (ExApps)

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves a list of external applications and their details, including version and enabled status.

```python
ex_apps = nc.apps.ex_app_list()
for app in ex_apps:
    print(f"App: {app.app_id} v{app.version} - {'enabled' if app.enabled else 'disabled'}")
```

--------------------------------

### Get Group Members

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Retrieves a list of user IDs that are members of a specific group. Useful for checking group composition.

```python
members = nc.users_groups.get_members("developers")
for user_id in members:
    print(f"Member: {user_id}")
```

--------------------------------

### AsyncAppsAPI - Ex App List

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Asynchronously lists external applications (ExApps) with their details.

```APIDOC
## ex_app_list() -> list[ExAppInfo]

### Description
Lists external applications (ExApps) asynchronously.

### Returns
List of ExAppInfo objects

### Example
```python
async def main():
    ex_apps = await nc.apps.ex_app_list()
```
```

--------------------------------

### Get Latest Activities

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Retrieves a list of the latest activities, with a specified limit. Each activity includes actor ID and subject.

```python
# Get latest activities
activities = await nc.activity.get_activities(limit=100)
for activity in activities:
    print(f"{activity.actor_id}: {activity.subject}")
```

--------------------------------

### AsyncFilesAPI - mkdir

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Asynchronously creates a directory. Optionally, it can avoid raising an error if the directory already exists.

```APIDOC
## mkdir (async)

### Description
Asynchronously creates a directory.

### Parameters
#### Path Parameters
- **path** (str) - Required - Directory path to create
- **exist_ok** (bool) - Optional - Don't raise error if exists. Defaults to False.

### Example
```python
await nc.files.mkdir("/NewFolder", exist_ok=True)
```
```

--------------------------------

### Get User Information

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Retrieves detailed information for a specific user. Returns a UserInfo object or None if the user is not found.

```python
user = nc.users.get_user("admin")
if user:
    print(f"User: {user.display_name} ({user.email})")
    print(f"Quota: {user.quota}")
```

--------------------------------

### Get a specific note

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Retrieves a note by its ID or Note object. Returns the Note object if found, otherwise None.

```python
note = await nc.notes.get_note(42)
if note:
    print(f"Title: {note.title}")
    print(f"Content: {note.content}")
```

--------------------------------

### Get Computation Device

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/exapp-framework.md

Utility function to detect the available computation device for running intensive tasks, such as 'cpu', 'cuda', or 'mps'.

```python
from nc_py_api.ex_app import get_computation_device

device = get_computation_device()  # Returns "cpu", "cuda", "mps", etc.
```

--------------------------------

### Async User Management Operations

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/users-api.md

Demonstrates various asynchronous operations for managing users, including creation, retrieval, listing, searching, updating, group assignment, and quota setting. Use this for non-blocking user management in async applications.

```python
import asyncio

async def main():
    # Create user
    await nc.users.create("newuser", "password", "New User")
    
    # Get user info
    user = await nc.users.get_user("admin")
    print(f"Email: {user.email}")
    
    # List all users
    all_users = await nc.users.list_all()
    print(f"Total: {len(all_users)}")
    
    # Search
    results = await nc.users.search("john")
    
    # Update
    await nc.users.update("john", "email", "john@example.com")
    
    # Add to group
    await nc.users.add_to_group("john", "developers")
    
    # Set quota
    await nc.users.set_quota("john", 1073741824)

asyncio.run(main())
```

--------------------------------

### Get FsNode by Path

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/files-api.md

Retrieve a file or directory FsNode object using its exact path. Returns None if the path is not found.

```python
node = nc.files.by_path("/Documents/report.pdf")
print(f"Size: {node.info.content_length} bytes")
```

--------------------------------

### Get Team Members

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/notes-user-status-teams.md

Retrieves a list of all members belonging to a specific team. Accepts either a team ID or a Circle object.

```python
members = await nc.teams.get_members("team123")
for member in members:
    print(f"{member.display_name} ({member.level.name})")
```

--------------------------------

### Get New Activities Since Last Call

Source: https://github.com/cloud-py-api/nc_py_api/blob/main/_autodocs/api-reference/apps-activity-notifications.md

Fetches activities that have occurred since the last call to `get_activities` by setting `since=True`.

```python
# Get activities since last call
new = await nc.activity.get_activities(since=True)
```