astropy-hdf5io 0.1.0__tar.gz

astropy_hdf5io-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-16
+
+### Added
+- Initial release
+- Support for `astropy.units.Quantity` serialization
+- Support for `astropy.time.Time` serialization
+- Support for `astropy.coordinates.SkyCoord` serialization
+- Support for coordinate representations and differentials
+- Support for `astropy.table.Table` and `QTable`
+- Support for `astropy.timeseries.TimeSeries`
+- Comprehensive test suite with 62 tests
+- Documentation and examples
+
+### Features
+- Automatic registration of serializers on import
+- Metadata preservation for tables and columns
+- Support for masked columns
+- Support for nested structures (dicts, lists)
+- Unicode string handling
+- Logarithmic unit support (magnitudes, decibels)
+
+[0.1.0]: https://github.com/liamh/astropy-hdf5io/releases/tag/v0.1.0

astropy_hdf5io-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to astropy-hdf5io
+
+Thank you for considering contributing to astropy-hdf5io!
+
+## Development Setup
+
+1. Fork the repository on GitHub
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/liamh/astropy-hdf5io.git
+   cd astropy-hdf5io
+   ```
+3. Install in development mode:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Making Changes
+
+1. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes and add tests
+
+3. Run the test suite:
+   ```bash
+   pytest tests/ -v
+   ```
+
+4. Format your code:
+   ```bash
+   black src/ tests/
+   ruff check src/ tests/
+   ```
+
+5. Commit your changes:
+   ```bash
+   git commit -m "Add feature: description"
+   ```
+
+6. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. Open a Pull Request on GitHub
+
+## Testing
+
+All new features must include tests. We aim for high test coverage.
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Run tests with coverage
+pytest tests/ --cov=astropy_hdf5io --cov-report=html
+```
+
+## Code Style
+
+We use:
+
+- Black for code formatting
+- Ruff for linting
+- Type hints where appropriate
+
+## Documentation
+
+Update documentation when adding new features:
+
+- Add docstrings to all public functions/classes
+- Update README.md with usage examples
+- Update CHANGELOG.md
+
+## Adding Support for New AstroPy Types
+
+If you want to add serialization support for a new AstroPy type:
+
+1. Create a new file in `src/astropy_hdf5io/` (e.g., `_newtype.py`)
+
+2. Implement serialization by monkey-patching a `to_hdf5` method:
+   ```python
+   def _newtype_to_hdf5(self, hdf5_handle):
+       """Serialize NewType to HDF5"""
+       hdf5_handle['type_tag'] = 'astropy_hdf5io.NewType'
+       # Store data...
+
+   NewType.to_hdf5 = _newtype_to_hdf5
+   ```
+
+3. Implement deserialization using `@subscribe_hdf5`:
+   ```python
+   from fsc.hdf5_io import subscribe_hdf5
+
+   @subscribe_hdf5('astropy_hdf5io.NewType', check_on_load=False)
+   class _NewTypeDeserializer:
+       @classmethod
+       def from_hdf5(cls, hdf5_handle):
+           """Deserialize NewType from HDF5"""
+           # Load data...
+           return NewType(...)
+   ```
+
+4. Import your module in `src/astropy_hdf5io/__init__.py`
+
+5. Add comprehensive tests in `tests/test_newtype.py`
+
+6. Update README.md with examples
+
+## Reporting Bugs
+
+Please include:
+
+- Python version
+- astropy version
+- fsc.hdf5-io version
+- Minimal code to reproduce the issue
+- Expected vs actual behavior
+- Full error traceback
+
+## Feature Requests
+
+Open an issue describing:
+
+- What AstroPy type/feature you'd like supported
+- Your use case
+- Example of how you'd like it to work
+
+## Code Review Process
+
+All submissions require review. We use GitHub pull requests for this purpose.
+
+## Questions?
+
+Feel free to open an issue for discussion before starting work on major features.
+
+## Code of Conduct
+
+Be respectful and constructive in all interactions. We're all here to make astronomy software better!

astropy_hdf5io-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, astropy-hdf5io contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

astropy_hdf5io-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+recursive-include tests *.py

astropy_hdf5io-0.1.0/PKG-INFO

@@ -0,0 +1,396 @@
+Metadata-Version: 2.4
+Name: astropy-hdf5io
+Version: 0.1.0
+Summary: HDF5 serialization support for AstroPy objects using fsc.hdf5-io
+Author-email: astropy-hdf5io contributors <838019+liamh@users.noreply.github.com>
+Maintainer-email: "Liam M. Healy" <838019+liamh@users.noreply.github.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/liamh/astropy-hdf5io
+Project-URL: Documentation, https://astropy-hdf5io.readthedocs.io/
+Project-URL: Repository, https://github.com/liamh/astropy-hdf5io.git
+Project-URL: Issues, https://github.com/liamh/astropy-hdf5io/issues
+Project-URL: Changelog, https://github.com/liamh/astropy-hdf5io/blob/main/CHANGELOG.md
+Keywords: astropy,hdf5,serialization,astronomy,astrophysics,io,data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy>=5.0
+Requires-Dist: fsc.hdf5-io>=1.0
+Requires-Dist: h5py>=3.0
+Requires-Dist: numpy>=1.20
+Provides-Extra: munch
+Requires-Dist: munch>=2.5; extra == "munch"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: munch>=2.5; extra == "dev"
+Dynamic: license-file
+
+# astropy-hdf5io
+
+[![PyPI version](https://badge.fury.io/py/astropy-hdf5io.svg)](https://badge.fury.io/py/astropy-hdf5io)
+[![Tests](https://github.com/liamh/astropy-hdf5io/workflows/Tests/badge.svg)](https://github.com/liamh/astropy-hdf5io/actions)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+HDF5 serialization support for AstroPy objects using `fsc.hdf5-io`.
+
+## Features
+
+- **Seamless integration** with `fsc.hdf5-io` for saving/loading AstroPy objects to HDF5
+- **Hierarchical organization** with group-level save/load and recursive dict/Munch support
+- **Comprehensive type support** including:
+  - `Quantity` (with units, including logarithmic units)
+  - `Time` (all formats and scales)
+  - `SkyCoord` and coordinate frames
+  - `Table`, `QTable`, and `TimeSeries`
+  - Coordinate representations and differentials
+  - `EarthLocation`, `Angle`, `Longitude`, `Latitude`, `Distance`
+- **Metadata preservation** for tables and columns
+- **Nested structures** support (tables in dicts/lists)
+- **Masked columns** support
+
+## Installation
+
+```bash
+pip install astropy-hdf5io
+```
+
+### Requirements
+
+- Python ≥ 3.9
+- astropy ≥ 5.0
+- fsc.hdf5-io ≥ 1.0
+- h5py ≥ 3.0
+- numpy ≥ 1.20
+
+## Quick Start
+
+```python
+import astropy.units as u
+from astropy.table import QTable
+from astropy.time import Time
+from astropy.coordinates import SkyCoord
+from fsc.hdf5_io import save, load
+
+# Just import astropy_hdf5io to enable serialization
+import astropy_hdf5io
+
+# Create AstroPy objects
+distance = 1171 * u.Mpc
+time = Time('2023-01-01T00:00:00')
+coord = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree, distance=distance)
+
+# Save to HDF5
+save(distance, 'distance.hdf5')
+save(time, 'time.hdf5')
+save(coord, 'coord.hdf5')
+
+# Load from HDF5
+loaded_distance = load('distance.hdf5')
+loaded_time = load('time.hdf5')
+loaded_coord = load('coord.hdf5')
+
+print(loaded_distance)  # 1171.0 Mpc
+print(loaded_time)      # 2023-01-01 00:00:00.000
+print(loaded_coord)     # <SkyCoord ...>
+```
+
+## Examples
+
+### Working with Quantities
+
+```python
+import astropy.units as u
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+# Scalar and array quantities
+distance = 42.0 * u.pc
+velocities = [100, 200, 300] * u.km / u.s
+
+save(distance, 'distance.hdf5')
+save(velocities, 'velocities.hdf5')
+
+loaded_distance = load('distance.hdf5')
+loaded_velocities = load('velocities.hdf5')
+
+# Complex units work too!
+luminosity = 1e10 * u.solLum
+flux = 1.2e-15 * u.erg / u.s / u.cm**2
+```
+
+### Working with Times
+
+```python
+from astropy.time import Time
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+# Different time formats
+t_iso = Time('2023-01-01T12:00:00')
+t_jd = Time(2459945.5, format='jd')
+t_mjd = Time(59945.0, format='mjd')
+
+# Different time scales
+t_utc = Time('2023-01-01', scale='utc')
+t_tai = Time('2023-01-01', scale='tai')
+
+save(t_iso, 'time.hdf5')
+loaded = load('time.hdf5')
+```
+
+### Working with Coordinates
+
+```python
+from astropy.coordinates import SkyCoord
+import astropy.units as u
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+# 2D coordinates
+coord_2d = SkyCoord(ra=10.68*u.degree, dec=41.27*u.degree, frame='icrs')
+
+# 3D coordinates with distance
+coord_3d = SkyCoord(ra=10.68*u.degree, dec=41.27*u.degree,
+                     distance=770*u.kpc, frame='icrs')
+
+# Arrays of coordinates
+coords = SkyCoord(ra=[10, 20, 30]*u.degree,
+                  dec=[40, 50, 60]*u.degree)
+
+save(coord_3d, 'coord.hdf5')
+loaded = load('coord.hdf5')
+```
+
+### Working with Tables
+
+```python
+from astropy.table import Table, QTable
+import astropy.units as u
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+# Regular Table
+t = Table({
+    'name': ['Star A', 'Star B', 'Star C'],
+    'magnitude': [10.5, 12.3, 11.8],
+    'distance': [100, 150, 120]
+})
+
+# QTable with Quantities
+qt = QTable({
+    'name': ['Galaxy 1', 'Galaxy 2'],
+    'redshift': [0.1, 0.2],
+    'distance': [500, 1000] * u.Mpc,
+    'flux': [1.2e-15, 8.5e-16] * u.erg / u.s / u.cm**2
+})
+
+# Add metadata
+qt.meta['telescope'] = 'HST'
+qt.meta['observer'] = 'J. Smith'
+qt['distance'].info.description = 'Luminosity distance'
+
+save(qt, 'galaxies.hdf5')
+loaded = load('galaxies.hdf5')
+
+print(loaded.meta['telescope'])  # 'HST'
+print(loaded['distance'].info.description)  # 'Luminosity distance'
+```
+
+### Working with TimeSeries
+
+```python
+from astropy.timeseries import TimeSeries
+from astropy.time import Time
+import astropy.units as u
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+times = Time(['2023-01-01T00:00:00',
+              '2023-01-01T01:00:00',
+              '2023-01-01T02:00:00'])
+
+ts = TimeSeries(time=times)
+ts['flux'] = [100, 120, 110] * u.Jy
+ts['temperature'] = [5800, 5850, 5820] * u.K
+
+ts.meta['target'] = 'Variable Star XYZ'
+
+save(ts, 'timeseries.hdf5')
+loaded = load('timeseries.hdf5')
+```
+
+### Complex Nested Structures
+
+```python
+from astropy.table import QTable
+from astropy.time import Time
+from astropy.coordinates import SkyCoord
+import astropy.units as u
+from fsc.hdf5_io import save, load
+import astropy_hdf5io
+
+# Complex nested data structure
+observation_data = {
+    'metadata': {
+        'telescope': 'VLT',
+        'observer': 'J. Smith',
+        'date': Time('2023-01-01')
+    },
+    'targets': [
+        SkyCoord(ra=10*u.degree, dec=40*u.degree, distance=1000*u.pc),
+        SkyCoord(ra=20*u.degree, dec=50*u.degree, distance=2000*u.pc)
+    ],
+    'photometry': QTable({
+        'time': Time(['2023-01-01', '2023-01-02']),
+        'flux': [1.2, 1.5] * u.Jy,
+        'magnitude': [18.5, 18.3]
+    })
+}
+
+save(observation_data, 'observation.hdf5')
+loaded = load('observation.hdf5')
+```
+
+## How It Works
+
+`astropy-hdf5io` extends `fsc.hdf5-io` by:
+
+1. **Monkey-patching** `to_hdf5()` methods onto AstroPy classes
+2. **Registering deserializers** using the `@subscribe_hdf5` decorator
+3. **Preserving metadata** including units, coordinate frames, and table information
+
+Simply importing `astropy_hdf5io` automatically registers all serializers. After that, you can use `fsc.hdf5_io.save()` and `fsc.hdf5_io.load()` with AstroPy objects seamlessly.
+
+## Supported Types
+
+### Units and Quantities
+- `astropy.units.Quantity` (including logarithmic units like magnitudes)
+
+### Time
+- `astropy.time.Time` (all formats: ISO, JD, MJD, etc.)
+
+### Coordinates
+- `astropy.coordinates.SkyCoord`
+- `astropy.coordinates.Angle`
+- `astropy.coordinates.Longitude`
+- `astropy.coordinates.Latitude`
+- `astropy.coordinates.Distance`
+- `astropy.coordinates.EarthLocation`
+
+### Representations
+- `CartesianRepresentation`
+- `SphericalRepresentation`
+- `CylindricalRepresentation`
+- `PhysicsSphericalRepresentation`
+
+### Differentials
+- `CartesianDifferential`
+- `SphericalDifferential`
+- `SphericalCosLatDifferential`
+- `CylindricalDifferential`
+
+### Tables
+- `astropy.table.Table` (including masked columns)
+- `astropy.table.QTable` (with Quantity columns)
+- `astropy.timeseries.TimeSeries`
+
+### Groups
+
+`astropy-hdf5io` provides utilities for organizing data in group hierarchies in the HDF5 file:
+
+```python
+from astropy_hdf5io import save_to_group, load_from_group, print_tree
+from astropy.coordinates import SkyCoord
+import astropy.units as u
+
+
+# Save to nested groups
+coord = SkyCoord(ra=10*u.degree, dec=40*u.degree, distance=1000*u.pc)
+save_to_group(coord, 'astronomy.h5', 'observations/targets/ngc1234')
+
+# Load from specific group
+loaded = load_from_group('astronomy.h5', 'observations/targets/ngc1234')
+
+# Show structure
+print_tree('astronomy.hdf5')
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/liamh/astropy-hdf5io.git
+cd astropy-hdf5io
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Building Documentation
+
+```bash
+cd docs
+make html
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and add tests
+4. Run the test suite (`pytest`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built on top of [fsc.hdf5-io](https://github.com/FrescolinoGroup/pyhdf5io/)
+- Designed for seamless integration with [AstroPy](https://www.astropy.org/)
+- Inspired by the AstroPy community's need for efficient HDF5 storage
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@software{astropy_hdf5io,
+  author = {{astropy-hdf5io contributors}},
+  title = {astropy-hdf5io: HDF5 serialization for AstroPy},
+  url = {https://github.com/liamh/astropy-hdf5io},
+  version = {0.1.0},
+  year = {2026}
+}
+```
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/liamh/astropy-hdf5io/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/liamh/astropy-hdf5io/discussions)
+- **Documentation**: [Read the Docs](https://astropy-hdf5io.readthedocs.io/)