Skip to main content

​
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

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

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
  • ls() - List directory contents
  • read() - Read file content
  • tree() - Get directory tree structure