stat

Get resource metadata and statistics

Overview

The stat() method retrieves detailed metadata about a resource, including size, mode, timestamps, and whether it’s a directory.

This method is useful for checking resource existence and getting file attributes without reading content.

Method Signature

Python SDK

def stat(uri: str) -> Dict[str, Any]

Parameters

uri · string · required

The Viking URI of the resource to inspect

Response

name · string

Resource name (filename or directory name)

size · integer

Size in bytes (0 for directories)

mode · integer

File mode/permissions (Unix-style)

isDir · boolean

Whether this is a directory

uri · string

Full Viking URI of the resource

mtime · number

Last modification timestamp

ctime · number

Creation timestamp

Examples

Check if Resource Exists

Python SDK

from openviking import OpenViking

client = OpenViking(path="./data")

# Get resource metadata
info = client.stat("viking://resources/docs/")

print(f"Name: {info['name']}")
print(f"Is directory: {info['isDir']}")
print(f"Size: {info['size']} bytes")

Before Reading Content

# Check resource before reading
try:
    info = client.stat("viking://resources/large-file.pdf")
    
    if info['size'] > 10_000_000:  # 10MB
        print("File is large, consider using offset/limit")
        content = client.read(info['uri'], limit=1000)
    else:
        content = client.read(info['uri'])
        
except Exception as e:
    print(f"Resource not found: {e}")

Response Example

{
  "status": "ok",
  "result": {
    "name": "api.md",
    "size": 15420,
    "mode": 420,
    "isDir": false,
    "uri": "viking://resources/docs/api.md",
    "mtime": 1709712000.0,
    "ctime": 1709712000.0
  },
  "time": 0.002
}

Error Responses

Resource Not Found

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found: viking://resources/nonexistent.md"
  },
  "time": 0.001
}

Use Cases

1. Existence Check - Verify resource exists before operations
2. Size Inspection - Check file size before reading
3. Directory Detection - Determine if URI points to file or directory
4. Metadata Queries - Get timestamps for change tracking

Best Practices

Use stat() before expensive operations to validate resource existence and type.

# Good: Check before reading
if client.stat(uri)['isDir']:
    entries = client.ls(uri)
else:
    content = client.read(uri)
    
# Avoid: Reading without checking
try:
    content = client.read(uri)  # May fail if it's a directory
except Exception:
    pass

Related Methods

• ls() - List directory contents
• read() - Read file content
• tree() - Get directory tree structure