Documentation: File reuse and reference_id mechanism is not documented
- Dominant language
- Python
- Stars
- 5
- Forks
- 1
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 9
Description
## Issue
The PyHPS File class includes a `reference_id` parameter for file reuse, but this mechanism is not documented in the official PyHPS documentation. Users cannot understand when or how to use file reuse to optimize storage and upload performance.
## Current State
The File class API reference documents the parameter exists:
- `reference_id` (str, optional): ID of the reference file that this file was created from
However, there is no explanation of:
- When to use `reference_id`
- How file reuse works (shared blob storage vs. metadata references)
- The difference between creating a new File with `reference_id` vs. uploading the same file multiple times
- Real-world examples
## Proposed Solution
Add a new "File Reuse" section to the User Guide with clear documentation and examples. The mechanism is evident in production PyHPS usage but the public documentation lacks explanation.
### Why File Reuse Matters
- **Storage efficiency**: File bytes are stored once in HPS blob storage; multiple File metadata entries can reference the same storage_id
- **Upload performance**: Upload bytes once, reference many times
- **Workflow efficiency**: Create task variants or edited files without re-uploading unchanged content
### How It Works
PyHPS maintains a two-layer file system:
**Layer 1 - File Metadata** (in HPS database)
- Each File object has a unique id, name, and evaluation_path
- Multiple File objects can reference the same stored content
**Layer 2 - Blob Storage** (actual file bytes)
- Identified by storage_id (typically a hash)
- Each unique file content is stored once
### Example: Creating a Reused File
```python
# Original file (already uploaded)
original_file = project_api.get_files(id="")[0]
# Create a new File metadata entry that references the same blob storage
reused_file = File(
name="variant_name", # Unique name
evaluation_path=original_file.evaluation_path,
type=original_file.type,
reference_id=original_file.id, # Points to existing blob storage
)
created = project_api.create_files([reused_file])[0]
# No data upload needed — the bytes already exist
```
### Real-World Use Cases
1. **Same input file for multiple tasks** - Upload once, reference in many task definitions
2. **Edited variants** - When editing a file, create new File with reference_id then upload modified content to the new File's storage
This mechanism is used in production examples but lacks official documentation.
## Links
- File class API reference: https://hps.docs.pyansys.com/version/stable/api/_autosummary/ansys.hps.client.jms.File.html
- Current User Guide: https://hps.docs.pyansys.com/version/stable/user_guide/index.html
Contributor guide
Research direction
Start with the User Guide index and compare it with the File class API reference linked in the issue. Add a focused File Reuse section covering when reference_id is used, the metadata and blob-storage relationship, the distinction from repeated uploads, and the supplied Python examples; done means users can understand and apply the mechanism from the official guide.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100