riffy 0.1.0__tar.gz

riffy-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

riffy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John McMeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

riffy-0.1.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: riffy
+Version: 0.1.0
+Summary: A low-dependency Python library for parsing and managing RIFF format files
+Project-URL: Homepage, https://github.com/jmcmeen/riffy
+Project-URL: Repository, https://github.com/jmcmeen/riffy
+Project-URL: Issues, https://github.com/jmcmeen/riffy/issues
+Author-email: John McMeen <johnmcmeen@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 John McMeen
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: audio,chunk,parser,riff,wav
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# riffy
+
+A low-dependency Python library for parsing and managing RIFF (Resource Interchange File Format) files.
+
+Riffy provides a pure Python implementation for working with RIFF format files, with initial support for WAV audio files. The library is designed to have **zero external dependencies** while providing robust parsing capabilities for managing RIFF chunks.
+
+## Features
+
+- **Zero Dependencies**: Pure Python implementation with no external dependencies
+- **WAV File Support**: Complete WAV file parsing with format validation
+- **RIFF Chunk Management**: Access and inspect individual RIFF chunks
+- **Audio Metadata Extraction**: Extract sample rate, channels, bit depth, and duration
+- **Format Validation**: Automatic validation of file format and integrity
+- **Type Safety**: Full type hints for better IDE support and code quality
+- **Lightweight**: Minimal footprint, perfect for embedded systems or restricted environments
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install riffy
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/jmcmeen/riffy.git
+cd riffy
+
+# Install in development mode
+pip install -e .
+
+# Or build and install
+pip install build
+python -m build
+pip install dist/riffy-*.whl
+```
+
+### For Development
+
+```bash
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic WAV File Parsing
+
+```python
+from riffy import WAVParser
+
+# Parse a WAV file
+parser = WAVParser("audio.wav")
+info = parser.parse()
+
+# Access format information
+print(f"Sample Rate: {info['format']['sample_rate']} Hz")
+print(f"Channels: {info['format']['channels']}")
+print(f"Bit Depth: {info['format']['bits_per_sample']} bits")
+print(f"Duration: {info['duration_seconds']:.2f} seconds")
+```
+
+### Accessing RIFF Chunks
+
+```python
+from riffy import WAVParser
+
+parser = WAVParser("audio.wav")
+parser.parse()
+
+# Access all chunks
+for chunk_id, chunk in parser.chunks.items():
+    print(f"Chunk: {chunk_id}, Size: {chunk.size} bytes, Offset: {chunk.offset}")
+
+# Access specific chunk
+if 'fmt ' in parser.chunks:
+    fmt_chunk = parser.chunks['fmt ']
+    print(f"Format chunk size: {fmt_chunk.size}")
+```
+
+### Working with Audio Data
+
+```python
+from riffy import WAVParser
+
+parser = WAVParser("audio.wav")
+parser.parse()
+
+# Access raw audio data
+audio_data = parser.audio_data
+print(f"Audio data size: {len(audio_data)} bytes")
+
+# Get sample count
+info = parser.get_info()
+print(f"Total samples: {info['sample_count']}")
+```
+
+### Getting Detailed File Information
+
+```python
+from riffy import WAVParser
+import json
+
+parser = WAVParser("audio.wav")
+info = parser.parse()
+
+# Pretty print all information
+print(json.dumps(info, indent=2))
+```
+
+Output example:
+
+```json
+{
+  "file_path": "/path/to/audio.wav",
+  "file_size": 1234567,
+  "format": {
+    "audio_format": 1,
+    "channels": 2,
+    "sample_rate": 44100,
+    "byte_rate": 176400,
+    "block_align": 4,
+    "bits_per_sample": 16,
+    "is_pcm": true
+  },
+  "duration_seconds": 3.5,
+  "audio_data_size": 617400,
+  "sample_count": 154350,
+  "chunks": {
+    "fmt ": 16,
+    "data": 617400
+  }
+}
+```
+
+## API Reference
+
+### WAVParser
+
+The main class for parsing WAV files.
+
+#### Constructor
+
+```python
+WAVParser(file_path: Union[str, Path])
+```
+
+**Parameters:**
+
+- `file_path`: Path to the WAV file (string or `pathlib.Path`)
+
+#### Methods
+
+##### `parse() -> Dict`
+
+Parse the WAV file and return comprehensive information.
+
+**Returns:** Dictionary containing file information, format details, and chunk data
+
+**Raises:**
+
+- `FileNotFoundError`: If the file doesn't exist
+- `InvalidWAVFormatError`: If the file is not a valid WAV file
+- `CorruptedFileError`: If the file is corrupted or incomplete
+
+##### `get_info() -> Dict`
+
+Get comprehensive information about the parsed WAV file.
+
+**Returns:** Dictionary with file metadata (must call `parse()` first)
+
+#### Properties
+
+- `format_info`: `WAVFormat` object containing format details
+- `chunks`: Dictionary of `WAVChunk` objects keyed by chunk ID
+- `audio_data`: Raw audio data as bytes
+
+### WAVFormat
+
+Dataclass containing WAV format information.
+
+**Attributes:**
+
+- `audio_format`: Audio format code (1 = PCM)
+- `channels`: Number of audio channels
+- `sample_rate`: Sample rate in Hz
+- `byte_rate`: Bytes per second
+- `block_align`: Block alignment in bytes
+- `bits_per_sample`: Bits per sample
+
+**Properties:**
+
+- `is_pcm`: Boolean indicating if format is PCM (uncompressed)
+- `duration_seconds`: Audio duration in seconds
+
+### WAVChunk
+
+Dataclass representing a RIFF chunk.
+
+**Attributes:**
+
+- `id`: Chunk identifier (e.g., "fmt ", "data")
+- `size`: Chunk size in bytes
+- `data`: Raw chunk data
+- `offset`: Byte offset in the file
+
+## Exception Hierarchy
+
+```
+RiffyError (base exception)
+├── WAVError
+│   ├── InvalidWAVFormatError
+│   ├── CorruptedFileError
+│   └── UnsupportedFormatError
+└── ChunkError
+    ├── InvalidChunkError
+    └── MissingChunkError
+```
+
+### Exception Handling
+
+```python
+from riffy import WAVParser, InvalidWAVFormatError, CorruptedFileError
+
+try:
+    parser = WAVParser("audio.wav")
+    info = parser.parse()
+except InvalidWAVFormatError as e:
+    print(f"Invalid WAV format: {e}")
+except CorruptedFileError as e:
+    print(f"File is corrupted: {e}")
+except FileNotFoundError:
+    print("File not found")
+```
+
+## Supported Formats
+
+Currently, Riffy supports:
+
+- **WAV Files**: PCM (uncompressed) audio only
+- **RIFF Chunks**: Standard chunk parsing for any RIFF file
+
+### Planned Support
+
+- AVI files
+- WebP images
+- Additional WAV compression formats
+- RIFF chunk writing/modification
+
+## Requirements
+
+- Python 3.8 or higher
+- No external dependencies!
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=riffy --cov-report=html
+```
+
+### Code Formatting
+
+```bash
+# Format code with black
+black src/
+
+# Lint with ruff
+ruff check src/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### Version 0.1.0 (Initial Release)
+
+- Pure Python WAV file parser
+- RIFF chunk management
+- Zero external dependencies
+- Full type hints
+- Comprehensive error handling
+
+## Acknowledgments
+
+- RIFF format specification: [Microsoft RIFF Specification](https://learn.microsoft.com/en-us/windows/win32/xaudio2/resource-interchange-file-format--riff-)
+- WAV format specification: [WAV Audio File Format](http://soundfile.sapp.org/doc/WaveFormat/)
+
+## Support
+
+For bugs, feature requests, or questions, please [open an issue](https://github.com/jmcmeen/riffy/issues).

riffy-0.1.0/README.md

@@ -0,0 +1,314 @@
+# riffy
+
+A low-dependency Python library for parsing and managing RIFF (Resource Interchange File Format) files.
+
+Riffy provides a pure Python implementation for working with RIFF format files, with initial support for WAV audio files. The library is designed to have **zero external dependencies** while providing robust parsing capabilities for managing RIFF chunks.
+
+## Features
+
+- **Zero Dependencies**: Pure Python implementation with no external dependencies
+- **WAV File Support**: Complete WAV file parsing with format validation
+- **RIFF Chunk Management**: Access and inspect individual RIFF chunks
+- **Audio Metadata Extraction**: Extract sample rate, channels, bit depth, and duration
+- **Format Validation**: Automatic validation of file format and integrity
+- **Type Safety**: Full type hints for better IDE support and code quality
+- **Lightweight**: Minimal footprint, perfect for embedded systems or restricted environments
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install riffy
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/jmcmeen/riffy.git
+cd riffy
+
+# Install in development mode
+pip install -e .
+
+# Or build and install
+pip install build
+python -m build
+pip install dist/riffy-*.whl
+```
+
+### For Development
+
+```bash
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic WAV File Parsing
+
+```python
+from riffy import WAVParser
+
+# Parse a WAV file
+parser = WAVParser("audio.wav")
+info = parser.parse()
+
+# Access format information
+print(f"Sample Rate: {info['format']['sample_rate']} Hz")
+print(f"Channels: {info['format']['channels']}")
+print(f"Bit Depth: {info['format']['bits_per_sample']} bits")
+print(f"Duration: {info['duration_seconds']:.2f} seconds")
+```
+
+### Accessing RIFF Chunks
+
+```python
+from riffy import WAVParser
+
+parser = WAVParser("audio.wav")
+parser.parse()
+
+# Access all chunks
+for chunk_id, chunk in parser.chunks.items():
+    print(f"Chunk: {chunk_id}, Size: {chunk.size} bytes, Offset: {chunk.offset}")
+
+# Access specific chunk
+if 'fmt ' in parser.chunks:
+    fmt_chunk = parser.chunks['fmt ']
+    print(f"Format chunk size: {fmt_chunk.size}")
+```
+
+### Working with Audio Data
+
+```python
+from riffy import WAVParser
+
+parser = WAVParser("audio.wav")
+parser.parse()
+
+# Access raw audio data
+audio_data = parser.audio_data
+print(f"Audio data size: {len(audio_data)} bytes")
+
+# Get sample count
+info = parser.get_info()
+print(f"Total samples: {info['sample_count']}")
+```
+
+### Getting Detailed File Information
+
+```python
+from riffy import WAVParser
+import json
+
+parser = WAVParser("audio.wav")
+info = parser.parse()
+
+# Pretty print all information
+print(json.dumps(info, indent=2))
+```
+
+Output example:
+
+```json
+{
+  "file_path": "/path/to/audio.wav",
+  "file_size": 1234567,
+  "format": {
+    "audio_format": 1,
+    "channels": 2,
+    "sample_rate": 44100,
+    "byte_rate": 176400,
+    "block_align": 4,
+    "bits_per_sample": 16,
+    "is_pcm": true
+  },
+  "duration_seconds": 3.5,
+  "audio_data_size": 617400,
+  "sample_count": 154350,
+  "chunks": {
+    "fmt ": 16,
+    "data": 617400
+  }
+}
+```
+
+## API Reference
+
+### WAVParser
+
+The main class for parsing WAV files.
+
+#### Constructor
+
+```python
+WAVParser(file_path: Union[str, Path])
+```
+
+**Parameters:**
+
+- `file_path`: Path to the WAV file (string or `pathlib.Path`)
+
+#### Methods
+
+##### `parse() -> Dict`
+
+Parse the WAV file and return comprehensive information.
+
+**Returns:** Dictionary containing file information, format details, and chunk data
+
+**Raises:**
+
+- `FileNotFoundError`: If the file doesn't exist
+- `InvalidWAVFormatError`: If the file is not a valid WAV file
+- `CorruptedFileError`: If the file is corrupted or incomplete
+
+##### `get_info() -> Dict`
+
+Get comprehensive information about the parsed WAV file.
+
+**Returns:** Dictionary with file metadata (must call `parse()` first)
+
+#### Properties
+
+- `format_info`: `WAVFormat` object containing format details
+- `chunks`: Dictionary of `WAVChunk` objects keyed by chunk ID
+- `audio_data`: Raw audio data as bytes
+
+### WAVFormat
+
+Dataclass containing WAV format information.
+
+**Attributes:**
+
+- `audio_format`: Audio format code (1 = PCM)
+- `channels`: Number of audio channels
+- `sample_rate`: Sample rate in Hz
+- `byte_rate`: Bytes per second
+- `block_align`: Block alignment in bytes
+- `bits_per_sample`: Bits per sample
+
+**Properties:**
+
+- `is_pcm`: Boolean indicating if format is PCM (uncompressed)
+- `duration_seconds`: Audio duration in seconds
+
+### WAVChunk
+
+Dataclass representing a RIFF chunk.
+
+**Attributes:**
+
+- `id`: Chunk identifier (e.g., "fmt ", "data")
+- `size`: Chunk size in bytes
+- `data`: Raw chunk data
+- `offset`: Byte offset in the file
+
+## Exception Hierarchy
+
+```
+RiffyError (base exception)
+├── WAVError
+│   ├── InvalidWAVFormatError
+│   ├── CorruptedFileError
+│   └── UnsupportedFormatError
+└── ChunkError
+    ├── InvalidChunkError
+    └── MissingChunkError
+```
+
+### Exception Handling
+
+```python
+from riffy import WAVParser, InvalidWAVFormatError, CorruptedFileError
+
+try:
+    parser = WAVParser("audio.wav")
+    info = parser.parse()
+except InvalidWAVFormatError as e:
+    print(f"Invalid WAV format: {e}")
+except CorruptedFileError as e:
+    print(f"File is corrupted: {e}")
+except FileNotFoundError:
+    print("File not found")
+```
+
+## Supported Formats
+
+Currently, Riffy supports:
+
+- **WAV Files**: PCM (uncompressed) audio only
+- **RIFF Chunks**: Standard chunk parsing for any RIFF file
+
+### Planned Support
+
+- AVI files
+- WebP images
+- Additional WAV compression formats
+- RIFF chunk writing/modification
+
+## Requirements
+
+- Python 3.8 or higher
+- No external dependencies!
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=riffy --cov-report=html
+```
+
+### Code Formatting
+
+```bash
+# Format code with black
+black src/
+
+# Lint with ruff
+ruff check src/
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### Version 0.1.0 (Initial Release)
+
+- Pure Python WAV file parser
+- RIFF chunk management
+- Zero external dependencies
+- Full type hints
+- Comprehensive error handling
+
+## Acknowledgments
+
+- RIFF format specification: [Microsoft RIFF Specification](https://learn.microsoft.com/en-us/windows/win32/xaudio2/resource-interchange-file-format--riff-)
+- WAV format specification: [WAV Audio File Format](http://soundfile.sapp.org/doc/WaveFormat/)
+
+## Support
+
+For bugs, feature requests, or questions, please [open an issue](https://github.com/jmcmeen/riffy/issues).

riffy-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riffy"
+version = "0.1.0"
+description = "A low-dependency Python library for parsing and managing RIFF format files"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+authors = [
+    {name = "John McMeen", email = "johnmcmeen@gmail.com"},
+]
+keywords = ["riff", "wav", "audio", "parser", "chunk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# No external dependencies - pure Python implementation
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmcmeen/riffy"
+Repository = "https://github.com/jmcmeen/riffy"
+Issues = "https://github.com/jmcmeen/riffy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/riffy"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

riffy-0.1.0/src/riffy/__init__.py

@@ -0,0 +1,56 @@
+"""
+Riffy - A low-dependency Python library for parsing and managing RIFF format files.
+
+Riffy provides a pure Python implementation for parsing RIFF (Resource Interchange File Format)
+files, with initial support for WAV audio files. The library is designed to have minimal
+dependencies while providing robust parsing capabilities.
+
+Main Features:
+- Pure Python implementation with zero external dependencies
+- Parse WAV files and extract format information
+- Access individual RIFF chunks
+- Extract audio data and metadata
+- Validate file format and integrity
+
+Basic Usage:
+    >>> from riffy import WAVParser
+    >>> parser = WAVParser("audio.wav")
+    >>> info = parser.parse()
+    >>> print(f"Sample rate: {info['format']['sample_rate']} Hz")
+    >>> print(f"Duration: {info['duration_seconds']:.2f} seconds")
+"""
+
+__version__ = "0.1.0"
+__author__ = "John"
+
+# Import main classes and functions
+from .wav import WAVParser, WAVFormat, WAVChunk
+from .exceptions import (
+    RiffyError,
+    WAVError,
+    InvalidWAVFormatError,
+    CorruptedFileError,
+    UnsupportedFormatError,
+    ChunkError,
+    InvalidChunkError,
+    MissingChunkError,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    "__author__",
+    # WAV parsing
+    "WAVParser",
+    "WAVFormat",
+    "WAVChunk",
+    # Exceptions
+    "RiffyError",
+    "WAVError",
+    "InvalidWAVFormatError",
+    "CorruptedFileError",
+    "UnsupportedFormatError",
+    "ChunkError",
+    "InvalidChunkError",
+    "MissingChunkError",
+]

riffy-0.1.0/src/riffy/exceptions.py

@@ -0,0 +1,41 @@
+"""Custom exceptions for the riffy RIFF parser library."""
+
+
+class RiffyError(Exception):
+    """Base exception for all riffy errors."""
+    pass
+
+
+class WAVError(RiffyError):
+    """Base exception for WAV-related errors."""
+    pass
+
+
+class InvalidWAVFormatError(WAVError):
+    """Raised when a WAV file has an invalid format."""
+    pass
+
+
+class CorruptedFileError(WAVError):
+    """Raised when a file is corrupted or incomplete."""
+    pass
+
+
+class UnsupportedFormatError(WAVError):
+    """Raised when a WAV format is not supported."""
+    pass
+
+
+class ChunkError(RiffyError):
+    """Base exception for RIFF chunk-related errors."""
+    pass
+
+
+class InvalidChunkError(ChunkError):
+    """Raised when a RIFF chunk is invalid."""
+    pass
+
+
+class MissingChunkError(ChunkError):
+    """Raised when a required RIFF chunk is missing."""
+    pass

riffy-0.1.0/src/riffy/wav.py

@@ -0,0 +1,181 @@
+import struct
+from typing import Dict, Optional, Union
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import WAVError, InvalidWAVFormatError, CorruptedFileError
+
+@dataclass
+class WAVFormat:
+    """WAV format information."""
+    audio_format: int
+    channels: int
+    sample_rate: int
+    byte_rate: int
+    block_align: int
+    bits_per_sample: int
+    
+    @property
+    def is_pcm(self) -> bool:
+        """Check if format is PCM (uncompressed)."""
+        return self.audio_format == 1
+    
+    @property
+    def duration_seconds(self) -> float:
+        """Calculate duration based on byte rate (requires data size)."""
+        return getattr(self, '_duration', 0.0)
+
+
+@dataclass
+class WAVChunk:
+    """Represents a RIFF chunk in the WAV file."""
+    id: str
+    size: int
+    data: bytes
+    offset: int
+
+
+class WAVParser:
+    """Pure Python WAV file parser."""
+    
+    def __init__(self, file_path: Union[str, Path]):
+        """Initialize parser with file path."""
+        self.file_path = Path(file_path)
+        self.format_info: Optional[WAVFormat] = None
+        self.chunks: Dict[str, WAVChunk] = {}
+        self.audio_data: Optional[bytes] = None
+        self._file_size = 0
+        
+    def parse(self) -> Dict:
+        """Parse the WAV file and return comprehensive information."""
+        if not self.file_path.exists():
+            raise FileNotFoundError(f"WAV file not found: {self.file_path}")
+        
+        self._file_size = self.file_path.stat().st_size
+        
+        with open(self.file_path, 'rb') as f:
+            self._parse_riff_header(f)
+            self._parse_chunks(f)
+            self._calculate_duration()
+            self._validate_format()
+        
+        return self.get_info()
+    
+    def _parse_riff_header(self, f) -> None:
+        """Parse the RIFF header."""
+        riff_header = f.read(12)
+        if len(riff_header) != 12:
+            raise CorruptedFileError("File too small to be a valid WAV file")
+        
+        riff_id, file_size, wave_id = struct.unpack('<4sI4s', riff_header)
+        
+        if riff_id != b'RIFF':
+            raise InvalidWAVFormatError("Not a valid RIFF file")
+        
+        if wave_id != b'WAVE':
+            raise InvalidWAVFormatError("Not a valid WAV file")
+    
+    def _parse_chunks(self, f) -> None:
+        """Parse all chunks in the WAV file."""
+        while True:
+            chunk_header = f.read(8)
+            if len(chunk_header) < 8:
+                break
+            
+            chunk_id, chunk_size = struct.unpack('<4sI', chunk_header)
+            chunk_id = chunk_id.decode('ascii', errors='ignore')
+            
+            chunk_offset = f.tell()
+            chunk_data = f.read(chunk_size)
+            if len(chunk_data) != chunk_size:
+                raise CorruptedFileError(f"Incomplete chunk: {chunk_id}")
+            
+            self.chunks[chunk_id] = WAVChunk(
+                id=chunk_id,
+                size=chunk_size,
+                data=chunk_data,
+                offset=chunk_offset
+            )
+            
+            if chunk_id == 'fmt ':
+                self._parse_format_chunk(chunk_data)
+            elif chunk_id == 'data':
+                self.audio_data = chunk_data
+            
+            if chunk_size % 2:
+                f.read(1)
+    
+    def _parse_format_chunk(self, data: bytes) -> None:
+        """Parse the format chunk."""
+        if len(data) < 16:
+            raise InvalidWAVFormatError("Format chunk too small")
+        
+        fmt_data = struct.unpack('<HHIIHH', data[:16])
+        
+        self.format_info = WAVFormat(
+            audio_format=fmt_data[0],
+            channels=fmt_data[1],
+            sample_rate=fmt_data[2],
+            byte_rate=fmt_data[3],
+            block_align=fmt_data[4],
+            bits_per_sample=fmt_data[5]
+        )
+    
+    def _calculate_duration(self) -> None:
+        """Calculate audio duration after all chunks are parsed."""
+        if self.audio_data and self.format_info and self.format_info.byte_rate > 0:
+            duration = len(self.audio_data) / self.format_info.byte_rate
+            self.format_info._duration = duration
+    
+    def _validate_format(self) -> None:
+        """Validate the parsed format."""
+        if not self.format_info:
+            raise InvalidWAVFormatError("No format chunk found")
+        
+        if not self.format_info.is_pcm:
+            raise InvalidWAVFormatError(
+                f"Unsupported audio format: {self.format_info.audio_format} "
+                "(only PCM is supported)"
+            )
+        
+        if self.format_info.channels == 0:
+            raise InvalidWAVFormatError("Invalid number of channels")
+        
+        if self.format_info.sample_rate == 0:
+            raise InvalidWAVFormatError("Invalid sample rate")
+        
+        if self.audio_data is None:
+            raise InvalidWAVFormatError("No audio data found")
+    
+    def get_info(self) -> Dict:
+        """Get comprehensive information about the WAV file."""
+        if not self.format_info:
+            raise WAVError("File not parsed yet. Call parse() first.")
+        
+        info = {
+            'file_path': str(self.file_path),
+            'file_size': self._file_size,
+            'format': {
+                'audio_format': self.format_info.audio_format,
+                'channels': self.format_info.channels,
+                'sample_rate': self.format_info.sample_rate,
+                'byte_rate': self.format_info.byte_rate,
+                'block_align': self.format_info.block_align,
+                'bits_per_sample': self.format_info.bits_per_sample,
+                'is_pcm': self.format_info.is_pcm
+            },
+            'duration_seconds': self.format_info.duration_seconds,
+            'audio_data_size': len(self.audio_data) if self.audio_data else 0,
+            'sample_count': self._calculate_sample_count(),
+            'chunks': {chunk_id: chunk.size for chunk_id, chunk in self.chunks.items()}
+        }
+        
+        return info
+    
+    def _calculate_sample_count(self) -> int:
+        """Calculate total number of samples."""
+        if not self.audio_data or not self.format_info:
+            return 0
+        
+        bytes_per_sample = self.format_info.bits_per_sample // 8
+        return len(self.audio_data) // (bytes_per_sample * self.format_info.channels)