fsspec / fsspec/filesystem_spec

fs.cat_files signature consistency

Open
#1,600 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.4k
Forks
490
Avg merge
2d 3h
Merged PRs (30d)
38

Description

In debugging https://github.com/scikit-hep/uproot5/pull/1198 I found I was assuming all implementations fs.cat_files had the same signature. In fact they do not,

>>> help(fsspec.filesystem("s3").cat_file)
Help on function _cat_file in module s3fs.core:

_cat_file(path, version_id=None, start=None, end=None)
...
>>> help(fsspec.filesystem("http").cat_file)
Help on function _cat_file in module fsspec.implementations.http:

_cat_file(url, start=None, end=None, **kwargs)
...
>>> help(fsspec.filesystem("file").cat_file)
Help on method cat_file in module fsspec.spec:

cat_file(path, start=None, end=None, **kwargs) method of fsspec.implementations.local.LocalFileSystem instance

etc. and it was my mistake to not notice version_id is ahead of start and end for the s3 filesystem. I think it might be nice to enforce all signatures to require explicit keywords for all arguments after path, e.g.

def cat_file(self, path, *, start=None, end=None, **kwargs): ...

per https://peps.python.org/pep-3102/

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the cat_file signatures shown for the s3, http, and local fsspec filesystems, then review the keyword-only argument rule in PEP 3102. Done means the implementations consistently require explicit keywords for arguments after path without losing existing options such as version_id.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.