wavemap 2.0.0__tar.gz → 2.1.0__tar.gz

wavemap-2.1.0/PKG-INFO

@@ -0,0 +1,378 @@
+Metadata-Version: 2.4
+Name: wavemap
+Version: 2.1.0
+Summary: 🌊 Memory map WAVE or raw audio files 🌊
+Author: Tom Ritchford
+Author-email: Tom Ritchford <tom@swirly.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy>=1.24.1,<2
+Requires-Dist: xmod>=1.3.2,<2
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+
+🌊 Memory map WAVE files into numpy arrays 🌊
+----------------------------------------------
+
+.. image:: https://raw.githubusercontent.com/rec/wavemap/master/wavemap.png
+   :alt: WaveMap logo
+
+Manipulate huge WAVE or RAW files as numpy matrices - even if they are too
+large to fit into memory.
+
+Memory mapping is a technique where files on disk are directly mapped to
+locations in memory and use the same logic as swap space does.
+
+Samples from a WAVE or RAW audio file are directly memory mapped to entries in
+a ``numpy`` array, letting you manipulate very large audio files as if they
+all fit into memory at one time, and even directly change samples on disk.
+
+Typical usage:
+
+.. code-block:: python
+
+    import wavemap
+
+    wm = wavemap('test.wav', 'r+')  # r+ means read/write
+    # Now you have a numpy matrix that you can use like any other
+
+    wm /= 2
+    # Each sample in the file is scaled by half.
+
+API
+===
+
+``wavemap()``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+  wavemap(
+       filename: str,
+       mode: str='r',
+       order: Union[str, NoneType]=None,
+       always_2d: bool=False,
+       dtype: Union[numpy.dtype, NoneType]=None,
+       shape: Union[NoneType, int, tuple]=None,
+       sample_rate: int=0,
+       roffset: int=0,
+       warn: Union[Callable, NoneType]='<function warn:  print to stderr>',
+  )
+
+(`wavemap/__init__.py, 56-121 <https://github.com/rec/wavemap/blob/master/wavemap/__init__.py#L56-L121>`_)
+
+    Memory map a WAVE file to a ``numpy`` array
+
+    Return an instance of ``ReadMap`` or ``WriteMap``, depending on
+    ``mode``.
+
+ARGUMENTS
+  filename
+    The name of the file being mapped
+
+  mode
+    The file is opened in this mode.
+    Must be one of ``'r'``, ``'r+'``, ``'c'``, ``'w+'``
+
+    In mode ``'r'``, the default, the file is opened read-only and
+    the ``numpy.darray`` is immutable.
+
+    In mode ``'r+'``, the file is opened read-write and changes to the
+    ``numpy.darray`` are automatically applied to the file.
+
+    In mode ``'c'``, "copy-on-write", the file is opened read-only, but
+    the ``numpy.darray`` is *not* immutable: changes to the array are
+    instead stored in memory.
+
+    In mode ``'w+'``, "write", the file is opened for write, and overwrites
+    whatever else is there.
+
+  order
+    Samples usually get laid out in into a ``numpy.darray`` with``
+    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is
+    the number of channels.
+
+    This is called column major order, but this can be toggled by
+    setting the ``order`` parameter to ``F`` for Fortan or row-major row.
+
+    See https://stackoverflow.com/questions/27266338/
+
+  always_2d
+    If ``False``, the default, mono WAVE files with only one channel
+    get special treatment and are mapped to a one-dimensional vector
+    with ``size=(N,)``.
+
+    If ``True``, mono WAVE files are treated the same as any other file
+    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.
+
+  dtype
+    The numpy datatype of the samples in the file.
+
+  shape
+    The shape of the resulting numpy.darray. Can be a tuple, or a positive
+    integer, or ``None``.
+
+  sample_rate
+    The sample rate in Hz (cycles per second)
+
+  roffset
+    How many bytes in the file after the WAV data
+
+  warn
+    Programmers are sloppy so quite a lot of real-world WAVE files have
+    recoverable errors in their format.  ``warn`` is the function used to
+    report those recoverable errors.  By default, it's set to print to
+    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or
+    you can pass your own callback in
+
+Class ``wavemap.RawMap``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+(`wavemap/raw.py, 14-67 <https://github.com/rec/wavemap/blob/master/wavemap/raw.py#L14-L67>`_)
+
+"Memory map raw audio data from a disk file into a numpy matrix
+
+``wavemap.RawMap.__new__()``
+____________________________
+
+.. code-block:: python
+
+  wavemap.RawMap.__new__(
+       cls,
+       filename: str,
+       dtype: numpy.dtype,
+       shape: Union[tuple, int, NoneType]=None,
+       mode: str='r',
+       offset: int=0,
+       roffset: int=0,
+       order: Union[str, NoneType]=None,
+       always_2d: bool=False,
+       warn: Union[Callable, NoneType]='<function warn:  print to stderr>',
+  )
+
+(`wavemap/raw.py, 17-67 <https://github.com/rec/wavemap/blob/master/wavemap/raw.py#L17-L67>`_)
+
+Memory map raw audio data from a disk file into a numpy matrix
+
+ARGUMENTS
+  cls
+    Think of this as ``self``.  (This is because you need to implement ``__new__``
+    and not ``__init__`` when deriving from ``np.darray``.)
+
+  filename
+    The name of the file being mapped
+
+  dtype
+    The numpy datatype of the samples in the file.
+
+  shape
+    The shape of the resulting numpy.darray. Can be a tuple, or a positive
+    integer, or ``None``.
+
+  mode
+    The file is opened in this mode.
+    Must be one of ``'r'``, ``'r+'``, ``'c'``, ``'w+'``
+
+    In mode ``'r'``, the default, the file is opened read-only and
+    the ``numpy.darray`` is immutable.
+
+    In mode ``'r+'``, the file is opened read-write and changes to the
+    ``numpy.darray`` are automatically applied to the file.
+
+    In mode ``'c'``, "copy-on-write", the file is opened read-only, but
+    the ``numpy.darray`` is *not* immutable: changes to the array are
+    instead stored in memory.
+
+    In mode ``'w+'``, "write", the file is opened for write, and overwrites
+    whatever else is there.
+
+  offset
+    How many bytes in the file before the WAV data
+
+  roffset
+    How many bytes in the file after the WAV data
+
+  order
+    Samples usually get laid out in into a ``numpy.darray`` with``
+    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is
+    the number of channels.
+
+    This is called column major order, but this can be toggled by
+    setting the ``order`` parameter to ``F`` for Fortan or row-major row.
+
+    See https://stackoverflow.com/questions/27266338/
+
+  always_2d
+    If ``False``, the default, mono WAVE files with only one channel
+    get special treatment and are mapped to a one-dimensional vector
+    with ``size=(N,)``.
+
+    If ``True``, mono WAVE files are treated the same as any other file
+    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.
+
+  warn
+    Programmers are sloppy so quite a lot of real-world WAVE files have
+    recoverable errors in their format.  ``warn`` is the function used to
+    report those recoverable errors.  By default, it's set to print to
+    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or
+    you can pass your own callback in
+
+Class ``wavemap.ReadMap``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(`wavemap/read.py, 18-84 <https://github.com/rec/wavemap/blob/master/wavemap/read.py#L18-L84>`_)
+
+Memory-map an existing WAVE file into a numpy vector or matrix
+
+``wavemap.ReadMap.__new__()``
+_____________________________
+
+.. code-block:: python
+
+  wavemap.ReadMap.__new__(
+       cls: Type,
+       filename: str,
+       mode: str='r',
+       order: Union[str, NoneType]=None,
+       always_2d: bool=False,
+       warn: Union[Callable, NoneType]='<function warn:  print to stderr>',
+  )
+
+(`wavemap/read.py, 21-84 <https://github.com/rec/wavemap/blob/master/wavemap/read.py#L21-L84>`_)
+
+Memory-map an existing WAVE file into a numpy matrix.
+
+ARGUMENTS
+  cls
+    Think of this as ``self``.  (This is because you need to implement ``__new__``
+    and not ``__init__`` when deriving from ``np.darray``.)
+
+  filename
+    The name of the file being mapped
+
+  mode
+    The file is opened in this mode.
+    Must be one of ``'r'``, ``'r+'`` and ``'c'``.
+
+    In mode ``'r'``, the default, the file is opened read-only and
+    the ``numpy.darray`` is immutable.
+
+    In mode ``'r+'``, the file is opened read-write and changes to the
+    ``numpy.darray`` are automatically applied to the file.
+
+    In mode ``'c'``, "copy-on-write", the file is opened read-only, but
+    the ``numpy.darray`` is *not* immutable: changes to the array are
+    instead stored in memory.
+
+  order
+    Samples usually get laid out in into a ``numpy.darray`` with``
+    shape=(N, C)`` where ``N`` is the number of audio frames, and ``C`` is
+    the number of channels.
+
+    This is called column major order, but this can be toggled by
+    setting the ``order`` parameter to ``F`` for Fortan or row-major row.
+
+    See https://stackoverflow.com/questions/27266338/
+
+  always_2d
+    If ``False``, the default, mono WAVE files with only one channel
+    get special treatment and are mapped to a one-dimensional vector
+    with ``size=(N,)``.
+
+    If ``True``, mono WAVE files are treated the same as any other file
+    and are mapped to a two-dimensional matrix with ``size=(N, 1)``.
+
+  warn
+    Programmers are sloppy so quite a lot of real-world WAVE files have
+    recoverable errors in their format.  ``warn`` is the function used to
+    report those recoverable errors.  By default, it's set to print to
+    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or
+    you can pass your own callback in
+
+Class ``wavemap.WriteMap``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(`wavemap/write.py, 12-115 <https://github.com/rec/wavemap/blob/master/wavemap/write.py#L12-L115>`_)
+
+"Memory-map a new wave file into a new numpy vector or matrix
+
+``wavemap.WriteMap.__new__()``
+______________________________
+
+.. code-block:: python
+
+  wavemap.WriteMap.__new__(
+       cls: Type,
+       filename: str,
+       dtype: numpy.dtype,
+       shape: Union[NoneType, int, tuple],
+       sample_rate: int,
+       roffset: int=0,
+       warn: Union[Callable, NoneType]='<function warn:  print to stderr>',
+  )
+
+(`wavemap/write.py, 15-85 <https://github.com/rec/wavemap/blob/master/wavemap/write.py#L15-L85>`_)
+
+        Open a memory-mapped WAVE file in write mode and overwrite any existing
+        file.
+
+ARGUMENTS
+  cls
+    Think of this as ``self``.  (This is because you need to implement ``__new__``
+    and not ``__init__`` when deriving from ``np.darray``.)
+
+  filename
+    The name of the file being mapped
+
+  dtype
+    The numpy datatype of the samples in the file.
+
+  shape
+    The shape of the resulting numpy.darray. Can be a tuple, or a positive
+    integer, or ``None``.
+
+  sample_rate
+    The sample rate in Hz (cycles per second)
+
+  roffset
+    How many bytes in the file after the WAV data
+
+  warn
+    Programmers are sloppy so quite a lot of real-world WAVE files have
+    recoverable errors in their format.  ``warn`` is the function used to
+    report those recoverable errors.  By default, it's set to print to
+    ``sys.stderr`` but setting it to ``None`` disables errors entirely, or
+    you can pass your own callback in
+
+``wavemap.convert()``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+  wavemap.convert(
+       arr: numpy.ndarray,
+       dtype: Union[numpy.dtype, NoneType],
+       must_copy: bool=False,
+  )
+
+(`wavemap/convert.py, 6-77 <https://github.com/rec/wavemap/blob/master/wavemap/convert.py#L6-L77>`_)
+
+Returns a copy of a numpy array or matrix that represents audio data in
+another type, scaling and shifting as necessary.
+
+ARGUMENTS
+  arr
+    A numpy darray representing an audio signal
+
+  dtype
+    The numpy dtype to convert to - none means "no conversion"
+
+  must_copy
+    If true, ``arr`` is copied even if it is already the requested type
+
+(automatically generated by `doks <https://github.com/rec/doks/>`_ on 2021-02-23T14:37:02.652534)

wavemap-2.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "wavemap"
+version = "2.1.0"
+description = "🌊 Memory map WAVE or raw audio files 🌊"
+authors = [{ name = "Tom Ritchford", email = "tom@swirly.com" }]
+requires-python = ">=3.10"
+readme = "README.rst"
+license = "MIT"
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14"]
+dependencies = [
+    "numpy>=1.24.1,<2",
+    "xmod>=1.3.2,<2",
+]
+
+[tool.doks]
+auto = true
+source = 'wavemap/__init__.py'
+
+[tool.ruff]
+[dependency-groups]
+dev = [
+    "coverage>=7.1.0,<8",
+    "pytest>=7.2.1,<8",
+    "pyupgrade>=3.21.2",
+    "ruff>=0.14.14",
+    "stroll>=1.1.0,<2",
+    "tdir>=1.4.1,<2",
+    "ty>=0.0.14",
+]
+
+[tool.uv]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+[tool.coverage.run]
+branch = true
+source = "wavemap"
+
+[tool.coverage.report]
+fail_under = "68"
+skip_covered = true
+exclude_lines = ["pragma: no cover", "if False:", "if __name__ == .__main__.:", "raise NotImplementedError"]
+

{wavemap-2.0.0 → wavemap-2.1.0}/wavemap/__init__.py

@@ -26,31 +26,34 @@ Typical usage:
     wm /= 2
     # Each sample in the file is scaled by half.
 """
+
+from typing import Optional, Union
+from collections.abc import Callable
+
+import numpy as np
+import xmod
+
 from . import docs
 from .convert import convert
 from .raw import RawMap, warn
 from .read import ReadMap as ReadMap
 from .write import WriteMap as WriteMap
-from typing import Callable, Optional, Union
-import numpy as np
-import xmod
 
 __all__ = (
-    'wavemap',
-    'RawMap',
-    'ReadMap',
-    'WriteMap',
-    'copy_to',
-    'new_like',
-    'convert',
+    "wavemap",
+    "RawMap",
+    "ReadMap",
+    "WriteMap",
+    "copy_to",
+    "new_like",
+    "convert",
 )
-__version__ = '2.0.0'
 
 copy_to = WriteMap.copy_to
 new_like = WriteMap.new_like
-_DOKS = {warn: '<function warn: print to stderr>'}
-_WRITE_PARAMETERS = 'dtype', 'shape', 'sample_rate'
-_READ_PARAMETERS = 'order', 'always_2d'
+_DOKS = {warn: "<function warn: print to stderr>"}
+_WRITE_PARAMETERS = "dtype", "shape", "sample_rate"
+_READ_PARAMETERS = "order", "always_2d"
 
 
 @xmod(mutable=True)
@@ -60,20 +63,20 @@ def wavemap(
     #
     # Read parameters
     #
-    mode: str = 'r',
-    order: Optional[str] = None,
+    mode: str = "r",
+    order: str | None = None,
     always_2d: bool = False,
     #
     # Write parameters
     #
-    dtype: Optional[np.dtype] = None,
-    shape: Union[None, int, tuple] = None,
+    dtype: np.dtype | None = None,
+    shape: None | int | tuple = None,
     sample_rate: int = 0,
     roffset: int = 0,
     #
     # Read and write parameters
     #
-    warn: Optional[Callable] = warn,
+    warn: Callable | None = warn,
 ):
     """
     Memory map a WAVE file to a `numpy` array
@@ -81,18 +84,18 @@ def wavemap(
     Return an instance of `ReadMap` or `WriteMap`, depending on
     `mode`.
     """
-    if mode.startswith('w'):
+    if mode.startswith("w"):
         if not dtype:
-            raise ValueError('dtype must be set for write')
+            raise ValueError("dtype must be set for write")
         if not shape:
-            raise ValueError('shape must be set for write')
+            raise ValueError("shape must be set for write")
         if not sample_rate:
-            raise ValueError('sample_rate must be set for write')
+            raise ValueError("sample_rate must be set for write")
 
         if order:
-            raise ValueError('order cannot be set for write')
+            raise ValueError("order cannot be set for write")
         if always_2d:
-            raise ValueError('always_2d cannot be set for write')
+            raise ValueError("always_2d cannot be set for write")
 
         return WriteMap(
             filename=filename,
@@ -104,9 +107,9 @@ def wavemap(
         )
     else:
         if shape:
-            raise ValueError('shape cannot be set for write')
+            raise ValueError("shape cannot be set for write")
         if sample_rate:
-            raise ValueError('sample_rate cannot be set for write')
+            raise ValueError("sample_rate cannot be set for write")
 
         result = ReadMap(
             filename=filename,

{wavemap-2.0.0 → wavemap-2.1.0}/wavemap/convert.py

@@ -1,11 +1,10 @@
-from numpy.lib.stride_tricks import as_strided
 from typing import Optional
+
 import numpy as np
+from numpy.lib.stride_tricks import as_strided
 
 
-def convert(
-    arr: np.ndarray, dtype: Optional[np.dtype], must_copy: bool = False
-):
+def convert(arr: np.ndarray, dtype: np.dtype | None, must_copy: bool = False):
     """
     Returns a copy of a numpy array or matrix that represents audio data in
     another type, scaling and shifting as necessary.
@@ -27,8 +26,8 @@ def convert(
             arr = np.copy(arr)
         return arr
 
-    old_int = 'int' in str(old_t)
-    new_int = 'int' in str(new_t)
+    old_int = "int" in str(old_t)
+    new_int = "int" in str(new_t)
 
     if not (new_int or old_int):
         # Convert between floats
@@ -96,8 +95,15 @@ def _twenty_four_bit(shape, new, raw, itemsize):
     assert not (frames % 4)
 
     # https://stackoverflow.com/a/34128171/4383
-    raw = new(shape=(itemsize * frames // 4,), dtype='int32')
-    strided = as_strided(raw, strides=(12, 3,), shape=(frames, 4))
+    raw = new(shape=(itemsize * frames // 4,), dtype="int32")
+    strided = as_strided(
+        raw,
+        strides=(
+            12,
+            3,
+        ),
+        shape=(frames, 4),
+    )
     reshaped = np.reshape(strided, shape=shape)
 
     result = reshaped & 0x00FFFFFF

{wavemap-2.0.0 → wavemap-2.1.0}/wavemap/docs.py

@@ -15,9 +15,9 @@ Think of this as `self`.  (This is because you need to implement `__new__`
 and not `__init__` when deriving from `np.darray`.)
 """
 
-DTYPE = 'The numpy datatype of the samples in the file.'
+DTYPE = "The numpy datatype of the samples in the file."
 
-FILENAME = 'The name of the file being mapped'
+FILENAME = "The name of the file being mapped"
 
 ORDER = """
 Samples usually get laid out in into a `numpy.darray` with`
@@ -63,9 +63,9 @@ In mode `'w+'`, "write", the file is opened for write, and overwrites
 whatever else is there.
 """
 
-OFFSET = 'How many bytes in the file before the WAV data'
-ROFFSET = 'How many bytes in the file after the WAV data'
-SAMPLE_RATE = 'The sample rate in Hz (cycles per second)'
+OFFSET = "How many bytes in the file before the WAV data"
+ROFFSET = "How many bytes in the file after the WAV data"
+SAMPLE_RATE = "The sample rate in Hz (cycles per second)"
 
 SHAPE = """
 The shape of the resulting numpy.darray. Can be a tuple, or a positive
@@ -87,19 +87,19 @@ def arguments(*names, subs=None):
     names = [(i, subs.get(i, i).upper()) for i in names]
     missing = [n for (n, a) in names if a not in globals()]
     if missing:
-        raise ValueError(f'Cannot document arguments {missing}')
+        raise ValueError(f"Cannot document arguments {missing}")
 
-    yield 'ARGUMENTS'
+    yield "ARGUMENTS"
     for name, attr in names:
-        yield f'  {name}'
+        yield f"  {name}"
         for line in globals()[attr].strip().splitlines():
-            yield line and f'    {line}'
-        yield ''
+            yield line and f"    {line}"
+        yield ""
 
 
 def add_arguments(func, names, subs=None):
     params = arguments(*names, subs=subs)
-    func.__doc__ = func.__doc__.rstrip() + '\n\n' + '\n'.join(params)
+    func.__doc__ = func.__doc__.rstrip() + "\n\n" + "\n".join(params)
     return func