Skip to main content
GET
/
resources
/
file
/
{path}
Read File
curl --request GET \
  --url https://api.example.com/resources/file/{path}
{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File does not exist",
    "details": {
      "path": "/workspace/src/missing.py",
      "workspaceRoot": "/workspace"
    }
  }
}

​
Overview

The read-file resource returns the full contents of a specific file in your workspace, along with metadata and encoding information.

​
Resource URI

pylance://file/{path}

​
Request

​
uri
string
required
Resource URI with file path: pylance://file/src/main.py
​
encoding
string
default:"utf-8"
Character encoding (utf-8, ascii, latin-1, utf-16)
​
includeMetadata
boolean
default:"true"
Include file metadata in response
​
lineRange
object
Optional line range to read (e.g., {"start": 10, "end": 50})

​
Response

​
content
string
Full file contents as string
​
path
string
Absolute file path
​
relativePath
string
Path relative to workspace root
​
metadata
object
File metadata (if includeMetadata=true)

​
Example Request

curl -X POST https://api.pylancemcp.dev/v1/resources/read \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "pylance://file/src/models/user.py",
    "params": {
      "encoding": "utf-8",
      "includeMetadata": true
    }
  }'

​
Example Response

{
  "content": "from typing import Optional\nfrom datetime import datetime\n\nclass User:\n    \"\"\"User model representing a system user.\"\"\"\n    \n    def __init__(self, email: str, name: str):\n        self.email = email\n        self.name = name\n        self.created_at = datetime.now()\n    \n    def __repr__(self) -> str:\n        return f\"<User(email='{self.email}')>\"",
  "path": "/workspace/src/models/user.py",
  "relativePath": "src/models/user.py",
  "metadata": {
    "size": 342,
    "lines": 13,
    "encoding": "utf-8",
    "language": "python",
    "lastModified": "2025-12-16T15:20:00Z",
    "hash": "a3f5e8c9d2b1f4e7a6c8d9e2f1b3a4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
  }
}

​
Reading Line Ranges

Read specific line ranges for large files: 
# Read lines 50-100
file = client.read_resource(
    uri="pylance://file/src/large_file.py",
    lineRange={"start": 50, "end": 100}
)

print(file["content"])  # Only lines 50-100
print(f"Lines returned: {file['metadata']['linesReturned']}")
Response: 
{
  "content": "# Lines 50-100 of the file...",
  "metadata": {
    "linesReturned": 51,
    "totalLines": 5000,
    "lineRange": {"start": 50, "end": 100}
  }
}

​
Character Encodings

Supported encodings:
EncodingDescriptionUse Case
utf-8Unicode (default)Modern Python files
asciiASCII onlyLegacy files
latin-1ISO-8859-1Western European
utf-16Unicode 16-bitWindows files
cp1252Windows-1252Windows legacy
Pylance automatically detects encoding from BOM (Byte Order Mark) and file headers. Specify encoding only if detection fails.

​
Common Use Cases

​
Read Complete File

file = client.read_resource(uri="pylance://file/src/main.py")
content = file["content"]

​
Read Large File in Chunks

chunk_size = 100
total_lines = 5000

for start in range(0, total_lines, chunk_size):
    chunk = client.read_resource(
        uri="pylance://file/src/large_file.py",
        lineRange={"start": start, "end": start + chunk_size}
    )
    process_chunk(chunk["content"])

​
Get File Hash for Caching

file = client.read_resource(
    uri="pylance://file/src/models/user.py",
    includeMetadata=True
)

cache_key = file["metadata"]["hash"]
if cache_key in cache:
    content = cache[cache_key]
else:
    content = file["content"]
    cache[cache_key] = content

​
Performance Considerations

Files larger than 10MB will be automatically chunked. Use lineRange to read specific sections.

​
Optimization Tips

Cache file contents using the SHA-256 hash
Use line ranges for large files (>1000 lines)
Disable metadata if not needed to reduce response size
Batch multiple file reads in parallel
Example: Parallel Reads 
import asyncio

async def read_multiple_files(files):
    tasks = [
        client.read_resource_async(uri=f"pylance://file/{file}")
        for file in files
    ]
    return await asyncio.gather(*tasks)

files = ["src/main.py", "src/utils.py", "src/models.py"]
results = asyncio.run(read_multiple_files(files))

​
Error Responses

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File does not exist",
    "details": {
      "path": "/workspace/src/missing.py",
      "workspaceRoot": "/workspace"
    }
  }
}

​
Security

​
Path Traversal Prevention

All paths are validated to prevent directory traversal attacks. Attempts to access files outside the workspace will be rejected.
Blocked Examples: 
# ❌ These will fail with PERMISSION_DENIED
client.read_resource(uri="pylance://file/../../../etc/passwd")
client.read_resource(uri="pylance://file//etc/hosts")
client.read_resource(uri="pylance://file/~/private_data.txt")
Allowed Examples: 
# ✅ These will work (within workspace)
client.read_resource(uri="pylance://file/src/main.py")
client.read_resource(uri="pylance://file/src/../utils/helpers.py")  # Resolves to src/utils/helpers.py
client.read_resource(uri="pylance://file/./src/main.py")  # Resolves to src/main.py

​
Rate Limits

TierRequests/DayMax File Size
Free1001 MB
Hobby5,0005 MB
Pro50,00010 MB
EnterpriseUnlimited50 MB

List Files

Get all files in workspace

Workspace Structure

View project hierarchy