[Feature] Allow read_xdf to read from URLs, and some typing/documentation improvements

[LebombJames]

Description

This PR adds new functionality to the read_xdf function, allowing it to read XDF files from URLs.
It also fixes some out of date documentation and types, and explicitly outlines the function's return types.
(Various formatting changes were caused by linting)

Proposed Changes

If filename is a URL, read_xdf will now read the file from the URL as a BytesIO stream and pass it to load_xdf.
References to the dict of data frames returned have been removed. This seems like an artifact of an older version of the function, as it now returns a merged df of all streams
The function parameters and return values now have type hints, which improves the dev experience in the code editor, specifically with info, which can now autocomplete its properties.

Checklist

Here are some things to check before creating the PR. If you encounter any issues, do let us know :)

• I have read the CONTRIBUTING file.
• My PR is targeted at the dev branch (and not towards the master branch).
• I ran the CODE CHECKS on the files I added or modified and fixed the errors.
• I have added the newly added features to News.rst (if applicable)

[welcome]

Thanks for opening this pull request! We'll make sure it's perfect before merging 🤗
Make sure to read the contributing guide. Also, if you think that your contribution is worthy of it, you can consider adding yourself to the Contributors list (feel free to ask us if you have any doubts).

[gemini-code-assist]

Summary of Changes

Hello @LebombJames, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the read_xdf function by adding the ability to read XDF files from URLs, improving type hinting, and updating documentation to reflect the current function behavior. The URL support allows for more flexible data loading, while the typing and documentation changes improve the developer experience.

Highlights

• New Feature: URL Support: The read_xdf function can now read XDF files directly from URLs, using requests to stream the file content.
• Typing Improvements: Added type hints to the function parameters and return values, improving code editor support and readability. A ReadXDFInfo TypedDict was introduced to explicitly outline the function's return types.
• Documentation Updates: Outdated documentation has been corrected, specifically removing references to the function returning a dictionary of DataFrames, as it now returns a merged DataFrame.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a great new feature for reading XDF files directly from URLs, along with valuable typing and documentation enhancements. The code is generally well-structured.

My review focuses on improving the robustness of the new URL-handling logic and correcting a minor inaccuracy in the documentation. I've identified one critical issue that could lead to a crash and one medium-severity documentation issue. Suggestions are provided to fix these issues.

[DominiqueMakowski]

Nice one Sam! lgtm, let me know if I can merge

[DominiqueMakowski]

Now that I think of it, could you perhaps add another note in the docstrings with details about channel syncing with a link to this thread: xdf-modules/pyxdf#1

Basically, syncing channels with different SRs is not a trivial issue, and in this function our method is currently to upsample the signals and then interpolate, in my testing it worked well, but that's a thing worth mentioning (and in the thread mentioned above we discuss alternatives & pros and cons).

I am bringing this so that you can have a look as it crossed my mind that our issue with the alleged Muse delay might come from the way we sync the signals (maybe we inadvertently introduce the delay in this function)

The tests are failing but that's because the current dev is broken, we need to fix that

[LebombJames]

Hopefully the new docstring makes sense, everything should be ready now

[DominiqueMakowski]

I'm not s ure this will work does it 🤔
the goal is to create a vector of mins and then get its min

[LebombJames]

I double checked and it produces identical results. It's just a little micro-optimisation that reduces memory usage a bit, but I mainly did it to appease pylint

[DominiqueMakowski]

Why do we need a new class?

[LebombJames]

It's to document the structure of info in the return type. It doesn't do anything at runtime. Couldn't find a more elegant solution than using a class unfortunately

[welcome]

Congrats on merging your first pull request! 🎉🍾 We're looking forward to your next one!