Improve code readability of audb.publish()

[hagenw]

Closes #53

Improves the code structure for the private functions _find_media() and _put_media() inside audb.publish().
It also adds docstrings and further comments to the private methods, to make it easier to understand them.
In addition, it adds a custom RuntimeError when failing to download missing media files from a previous version in _put_media(). As this case will happen extremely rarely in reality and it would be very complicated to create a test for it, I did not added a new test for it.

Summary by Sourcery

Improve the structure and documentation of the audb.publish() method, specifically the _find_media() and _put_media() private functions. Add a RuntimeError for a rare edge case in _put_media() when downloading missing media files.

Enhancements:

• Clarify the logic for finding and updating media dependencies, including adding, removing, and updating entries based on file changes.
• Improve the handling of media file uploads, including downloading missing files from previous versions when necessary.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request improves the code readability of the audb.publish() method by refactoring its private functions _find_media() and _put_media(). It adds docstrings and comments to clarify the logic, and introduces a custom RuntimeError for a specific edge case in _put_media() handling missing media files.

Sequence diagram for media file handling in _put_media()

sequenceDiagram
    participant C as Client
    participant PM as _put_media()
    participant BE as Backend Interface
    participant FS as File System

    C->>PM: Upload media archives
    activate PM
    Note over PM: Map archives to files

    loop For each archive
        alt Previous version exists & missing files
            PM->>BE: get_archive()
            BE-->>PM: archive content
            PM->>FS: Copy missing files
        end
        PM->>BE: put_archive()
        BE-->>PM: confirmation
        PM->>PM: Update dependency versions
    end
    PM-->>C: Complete
    deactivate PM

Loading

Sequence diagram for media file processing in _find_media()

sequenceDiagram
    participant C as Client
    participant FM as _find_media()
    participant FS as File System
    participant DT as Dependencies Table

    C->>FM: Process media files
    activate FM
    FM->>DT: Remove old dependencies

    loop For each media file
        alt New media file
            FM->>FS: Calculate checksum
            FM->>DT: Add new entry
        else Existing media file
            FM->>FS: Calculate checksum
            alt Checksum changed
                FM->>DT: Update entry
            end
        end
    end
    FM-->>C: Return updated archives
    deactivate FM

Loading

Class diagram showing the refactored structure

classDiagram
    class _find_media {
        +process_new_media(file: str)
        +process_existing_media(file: str)
        +job(file: str)
    }

    class _put_media {
        +upload_archive(archive: str)
    }

    class Dependencies {
        +_drop(files)
        +_update_media()
        +_add_media()
        +_update_media_version()
    }

    _find_media ..> Dependencies
    _put_media ..> Dependencies

    note for _find_media "Improved with better structure and documentation"
    note for _put_media "Enhanced error handling and clearer organization"

Loading

File-Level Changes

Change	Details	Files
Improved documentation and code structure of _find_media()	Added docstrings and comments to clarify the function's purpose and implementation. Refactored the code for better readability and organization. Added a check for uppercase letters in file extensions of newly added media files. Improved variable naming for better understanding. Sorted media updates for consistent dependency table generation.	audb/core/publish.py
Improved documentation and error handling of _put_media()	Added docstrings and comments to clarify the function's purpose and implementation. Improved variable naming for better understanding. Added a custom RuntimeError when failing to download missing media files from a previous version. Implemented a mechanism to download missing media files from a previous version if necessary. Improved the logic for handling missing files during archive upload. Added error handling to clean up partially copied files in case of download failure.	audb/core/publish.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#53	Revisit and improve the helper functions _find_media() and _put_media() in audb.publish()	✅
#53	Improve code separation of the helper functions	✅
#53	Add more comments to make the functions easier to understand	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[hagenw]

@sourcery-ai review

[sourcery-ai]

Hey @hagenw - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

Hey @hagenw - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟢 General issues: all looks good
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[ChristianGeng]

Remaining discussions have been resolved.
The comments facilitate developing an understanding of the publish mechanism.
I therefore think that it is justified to give approval.