fix: Enhance error messages for missing audio dependencies improve docs

[everettVT]

• Updated error messages in AudioFile and related functions to provide clearer instructions for installing required modules (soundfile and librosa).
• Enhanced docstrings to include detailed metadata descriptions for audio files.
• Added new documentation files for daft.File types and updated existing documentation links for better navigation.
• Improved test cases to ensure informative error handling when dependencies are missing.

This change aims to improve user experience by providing clearer guidance on required dependencies and enhancing the overall documentation structure.

[greptile-apps]

Greptile Summary

This PR enhances error messages and documentation for audio file handling in Daft. The changes improve the user experience by providing clear installation instructions when optional audio dependencies (soundfile and librosa) are missing, moving dependency checks to expression definition time for earlier error reporting, and adding comprehensive docstrings with metadata field descriptions and practical examples.

Key Changes:

• Updated error messages across AudioFile, File.as_audio(), audio_metadata(), and resample() to include helpful instructions (e.g., "pip install 'daft[audio]'")
• Enhanced docstrings with detailed field descriptions and real-world usage examples in audio.py and functions/audio.py
• Restructured test organization with better section comments and moved dependency skipping to individual tests for finer control
• Added comprehensive test coverage for missing dependency scenarios
• Reorganized documentation structure with renamed datatypes/index.md to datatypes/all_datatypes.md and created new daft_file_types.md documentation file
• Updated documentation navigation in SUMMARY.md with new modality sections (Documents, Code) and reorganized API sections

Issues Found:

• Inline imports in daft/functions/audio.py (lines 91, 163) violate style guidelines and should be moved to the top of the file

Confidence Score: 4/5

• This PR is safe to merge with minor style issues that don't affect functionality
• The changes are focused and well-tested. Error message improvements are straightforward and beneficial. Documentation additions are well-structured. The main concern is the inline imports in daft/functions/audio.py which violates the import style guideline but does not affect functionality or behavior. All existing tests continue to work, and new tests provide good coverage for edge cases. The file renaming and documentation reorganization is properly tracked across files.
• daft/functions/audio.py - inline imports need to be moved to top of file per style guidelines

Important Files Changed

Filename	Overview
daft/file/audio.py	Updated error messages to be more helpful by including installation instructions for missing dependencies. Enhanced docstrings with detailed metadata field descriptions.
daft/file/file.py	Improved error message in as_audio() method with installation instructions. Removed unnecessary example from to_tempfile() docstring.
daft/functions/audio.py	Added comprehensive docstrings with examples and field descriptions. Moved dependency checks to expression definition time for better error messages. Contains style issue: inline imports should be moved to top of file.
tests/file/test_audio.py	Improved test structure with better organization and section comments. Restructured dependency skipping to be per-test rather than module-level. Added comprehensive tests for missing dependency error messages.
docs/SUMMARY.md	Reorganized navigation structure, added new documentation links for Documents and Code modalities, reordered API sections for better organization, and updated reference to renamed DataTypes file.
docs/api/datatypes/daft_file_types.md	New documentation file for daft.File types including File, AudioFile, and VideoFile with proper docstring extraction configuration.

Sequence Diagram

sequenceDiagram
    participant User
    participant AudioFunc as audio_metadata()<br/>resample()
    participant Dependencies as Dependency<br/>Check
    participant Expression as Expression<br/>Creation
    participant Runtime as Runtime<br/>Execution

    User->>AudioFunc: Call audio_metadata or resample
    AudioFunc->>Dependencies: Check sf/librosa available
    alt Dependencies Missing
        Dependencies-->>User: ImportError with helpful message<br/>(Early, at definition time)
    else Dependencies Available
        Dependencies->>Expression: Create Daft expression
        Expression-->>User: Return expression
        User->>Runtime: Call .collect()
        Runtime->>Runtime: Execute audio processing
        Runtime-->>User: Return result
    end

Loading

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

style: Import statements should be at the top of the file. Move from daft.dependencies import sf to the top with the other imports.

Context Used: Rule from dashboard - Import statements should be placed at the top of the file rather than inline within functions or met... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: daft/functions/audio.py
Line: 91:91

Comment:
**style:** Import statements should be at the top of the file. Move `from daft.dependencies import sf` to the top with the other imports.

**Context Used:** Rule from `dashboard` - Import statements should be placed at the top of the file rather than inline within functions or met... ([source](https://app.greptile.com/review/custom-context?memory=430ffc3f-245c-4a7f-8039-aba31c0ed558))

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: Import statements should be at the top of the file. Move from daft.dependencies import librosa, sf to the top with the other imports.

Context Used: Rule from dashboard - Import statements should be placed at the top of the file rather than inline within functions or met... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: daft/functions/audio.py
Line: 163:163

Comment:
**style:** Import statements should be at the top of the file. Move `from daft.dependencies import librosa, sf` to the top with the other imports.

**Context Used:** Rule from `dashboard` - Import statements should be placed at the top of the file rather than inline within functions or met... ([source](https://app.greptile.com/review/custom-context?memory=430ffc3f-245c-4a7f-8039-aba31c0ed558))

How can I resolve this? If you propose a fix, please make it concise.

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 72.47%. Comparing base (3e87822) to head (1131743).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
daft/functions/audio.py	87.50%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5877   +/-   ##
=======================================
  Coverage   72.47%   72.47%           
=======================================
  Files         966      966           
  Lines      125830   125840   +10     
=======================================
+ Hits        91196    91206   +10     
  Misses      34634    34634           

Files with missing lines	Coverage Δ
daft/file/audio.py	63.15% <100.00%> (+10.38%)	⬆️
daft/file/file.py	68.49% <100.00%> (+2.73%)	⬆️
daft/functions/audio.py	81.81% <87.50%> (+3.24%)	⬆️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.