[FEATURE] - deprecate read/write in favor of read_one/read_many/write_one/write_many

[Josh-2]

Type of Feature Request

• [ ] missing feature
  • [ ] feature available in another library: please specify
• [x] change to API
• [ ] enhancing a current feature
• [ ] removal of a broken/unsupported/etc feature
• [ ] other: please specify

Feature Description I was planning on proposing overloads (see below) for read and write but:

• they only help when the length of the arguments are known in advance.
• they are complicated. They need to detect when two or more arguments are provided.

    @overload
    def read(self, __tag: str) -> Tag: ...

    @overload
    def read(self, __tag: str, __tag_: str, *__tags: str) -> List[Tag]: ...

    @with_forward_open
    def read(self, *tags: str) -> ReadWriteReturnType:

    ...

    @overload
    def write(self, __tag: str, __value: TagValueType) -> Tag: ...

    @overload
    def write(self, __tags_values: Tuple[str, TagValueType]) -> Tag: ...

    @overload
    def write(self, __tags_value: Tuple[str, TagValueType],
        __tags_value_: Tuple[str, TagValueType],
        *__tags_values: Tuple[str, TagValueType]) -> List[Tag]: ...

    @with_forward_open
    def write(
        self, *tags_values: Union[str, TagValueType, Tuple[str, TagValueType]]
    ) -> ReadWriteReturnType:

Instead I am proposing the following changes.

Proposed Changes

• [x] splitting the read and write methods into read_one, read_many, write_one, and write_many
• [x] deprecated read and write and update calls to use read_many and write_many while maintaining their existing functionality
• [ ] updated documentation
• [ ] updated tests
• [x] this should've been a separate issue... provide an option to raise errors instead of writing continuing to read / write tags.

I believe this change improves the readability and predictability of the code by making it clear what type each method will return.

@ottowayi I realize this is a very opinionated proposal. Is this something that you're interested in?