Overview
The list-files resource returns a comprehensive list of all Python files in your workspace, including metadata about each file.
Resource URI
pylance://workspace/files
Request
Resource URI: pylance://workspace/files
Optional glob pattern to filter files (e.g., **/models/*.py)
Include test files in the results
Array of glob patterns to exclude (e.g., ["**/__pycache__/**", "**/node_modules/**"])
Response
Array of file objects in the workspace
Path relative to workspace root
ISO 8601 timestamp of last modification
Whether the file is a test file (contains test_ or _test.py)
Language identifier (python, python-stub)
Total number of Python files
Absolute path to workspace root
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://workspace/files",
"params": {
"filter": "src/**/*.py",
"includeTests": false
}
}'
Example Response
{
"files": [
{
"path": "/workspace/src/main.py",
"relativePath": "src/main.py",
"size": 2048,
"lastModified": "2025-12-17T10:30:00Z",
"isTest": false,
"language": "python"
},
{
"path": "/workspace/src/models/user.py",
"relativePath": "src/models/user.py",
"size": 4096,
"lastModified": "2025-12-16T15:20:00Z",
"isTest": false,
"language": "python"
},
{
"path": "/workspace/src/utils/helpers.py",
"relativePath": "src/utils/helpers.py",
"size": 1536,
"lastModified": "2025-12-15T09:45:00Z",
"isTest": false,
"language": "python"
}
],
"totalCount": 3,
"workspaceRoot": "/workspace"
}
Filter Patterns
Use glob patterns to filter results:
| Pattern | Description |
|---|
**/*.py | All Python files recursively |
src/**/*.py | All Python files in src/ directory |
**/test_*.py | All test files starting with test_ |
models/*.py | Python files directly in models/ |
!**/__pycache__/** | Exclude __pycache__ directories |
Common Use Cases
Get All Source Files
files = client.read_resource(
uri="pylance://workspace/files",
filter="src/**/*.py",
excludePatterns=["**/test_*.py", "**/*_test.py"]
)
Find All Test Files
tests = client.read_resource(
uri="pylance://workspace/files",
filter="**/test_*.py"
)
Get Files by Directory
models = client.read_resource(
uri="pylance://workspace/files",
filter="src/models/**/*.py"
)
File listing is cached for 5 minutes. Changes to the workspace trigger automatic cache invalidation.
Large workspaces (>10,000 files) may experience slower response times. Consider using more specific filter patterns.
Optimization Tips
Use specific filter patterns to reduce result size
Exclude unnecessary directories (__pycache__, .venv, node_modules)
Cache results on the client side when possible
Use includeTests=false if test files aren’t needed
Error Responses
{
"error": {
"code": "WORKSPACE_NOT_FOUND",
"message": "Workspace directory does not exist",
"details": {
"workspaceRoot": "/invalid/path"
}
}
}
Rate Limits
| Tier | Requests/Day | Requests/Hour |
|---|
| Free | 100 | 20 |
| Hobby | 5,000 | 500 |
| Pro | 50,000 | 5,000 |
| Enterprise | Unlimited | Unlimited |
