This defines the function _open_file, which opens an input data file
as a random-access file object.

This module is intended to eventually replace the "streaming I/O"
functions in the wfdb.io.download module (_remote_file_size,
_stream_header, _stream_dat, and _stream_annotation.)

Some notes on the implementation:

- Contrary to many existing functions, I've deliberately made pn_dir
  the first argument rather than the second, since putting the prefix
  first seems more natural.

- There's no dir_name argument; instead, callers should include the
  local directory name as part of file_name.  I consider it a bug that
  some functions have a separate dir_name argument that is ignored
  when pn_dir is set.

- This function does not do automatic version number resolution for
  PhysioNet projects.  That's something the caller (still) needs to do
  and should be handled elsewhere.

The soundfile library provides a python wrapper for libsndfile, which
in turn provides an interface to libFLAC for reading and writing FLAC
files.

"build": pip install will install the Python soundfile package.  On
Windows/MacOS, this will install a binary wheel package that includes
a private copy of libsndfile; on Ubuntu, it will install a generic
package that requires us to install libsndfile separately.

"test-deb10-i386": python3-soundfile installs the Python soundfile
package and also depends on libsndfile1.

The _digi_bounds function previously did not handle formats 310, 311,
61, 160, or 8 (which are not supported by wrsamp).  Add these formats
to SAMPLE_VALUE_RANGE for consistency even though they're currently
not used.

This will also raise an exception for unknown formats, rather than
silently returning None.

This will also raise an exception for unknown formats, rather than
silently returning None.

These format codes are used to designate FLAC signal files.  Format
508 indicates 8-bit, format 516 indicates 16-bit, and format 524
indicates 24-bit resolution.  Other format codes between 500 and 532
(inclusive) are reserved.

A FLAC signal file contains between one and eight channels, which are
sampled at the same frequency.  Therefore, all signals stored in the
same signal file must have the same number of samples per frame.  (If
a record contains more than eight signals, or if they have differing
sampling frequencies, they will require more than one signal file.)

Note that the number of samples per frame has no effect on the
encoding or decoding of the FLAC signal file; there is no interleaving
like there is in a binary signal file.  There is also no requiremement
that WFDB frame boundaries match up with FLAC compression-block
boundaries.

(Perhaps confusingly, the FLAC specification uses the word "frame" to
refer to the encoded form of a block of samples; this has nothing to
do with WFDB frames, and unless otherwise noted, the word "frame"
refers to a WFDB frame.)

To simplify this initial implementation, the function
_rd_compressed_file is nearly a drop-in replacement for _rd_dat_file,
which means that this function must rearrange the input data into the
format that _rd_dat_signals expects.

The fmt argument is the format of the singular dat file.  It is not a
list and that wouldn't make any sense here.

The record "flacformats" contains one signal in each of the three WFDB
FLAC signal formats.  As with the "binformats" record, sample j of
signal i is equal to:

   (i + 16843019 * j) % ((1 << adcres) - 1) + 1 - (1 << (adcres - 1)))

Use this record to test that it is possible to read all of the formats
correctly, including when we skip one or two samples from the start
and/or end of the record.

We want to be sure that the soundfile library is compatible with
wfdb.io._url.NetFile, since wfdb.io._signal._rd_compressed_file relies
on this.

This isn't a complete test of WFDB/FLAC functionality, in part because
the sample files are very small so we can't really exercise the
seeking functionality.  However, this should be sufficient to verify
that soundfile doesn't make silly assumptions (like assuming the input
file corresponds to an OS file descriptor.)