Clarify which parameters are accepted by Traversable.open

Documentation

The docs for the open method of the importlib.resources.abc.Traversable protocol state:

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

It would be helpful to clarify exactly which parameters are accepted here. In particular, is the newline parameter covered by this? That parameter is accepted by io.TextIOWrapper, but is arguably not an "encoding parameter", so it's unclear whether it's supported.

An aside: typeshed does not seem to think that newline is supported here, but I'm wondering whether that might be a defect in typeshed. If the consensus here is that newline is supported, I'll open a typeshed issue.

The precise case I ran into was reading CSV data from a package resource. For portable CSV file reading, using newline="" is recommended, so I'm doing:

with csv_data.open(newline="") as f:
    reader = csv.DictReader(f)
    for row in reader:
        ... #  do something with row

where csv_data implements importlib.resources.abc.Traversable. The open call is flagged as invalid by mypy and pyright, but the code appears to work correctly (including in the case where the resource is zipfile-based).

If newline is not intended to be accepted here, then I guess I instead have to do:

with importlib.resources.as_file(csv_data) as csv_file:
    with csv_file.open(newline="") as f:
        reader = csv.DictReader(f)
        for row in reader:
            ... #  do something with row

That's fine, but it would be cleaner to be able to stream data straight from the resource without having to materialise the resource as a file first.

Linked PRs

• gh-137076
• gh-157294

Bắt đầu với tài liệu về Traversable.open tại trang importlib.resources.abc được liên kết, sau đó xem xét các tham số được ghi trong tài liệu và các tham số thực tế của phương thức open, đặc biệt là encoding và newline. Hãy kiểm tra cuộc thảo luận và các PR được liên kết gh-137076 và gh-157294 trước khi quyết định liệu tài liệu có nên mô tả rõ ràng newline hay không; hoàn tất khi các tham số được chấp nhận và cách sử dụng CSV dự kiến là rõ ràng, không mơ hồ.