Merge pull request #1 from pedrocamargo/pedro/pytables_for_h5py

First stab at cleaning the code

Author: pedrocamargo

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: Python package
+
+on:
+ push:
+    branches:
+      - 'master'
+ pull_request:
+
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --dev --all-extras
+
+      - name: Lint check
+        run: uv run ruff check --output-format=github
+
+
+  test:
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.os }}-${{ matrix.python-version }}
+      cancel-in-progress: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        exclude:
+          - os: macos-latest
+            python-version: "3.9"
+          - os: macos-latest
+            python-version: "3.10"
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies and test
+      run: |
+        uv sync --dev --all-extras
+        uv run pytest
+

CHANGES.txt

@@ -6,4 +6,5 @@ v0.3.3, 2017-03-07 -- Python 3 compatible
 v0.3.4, 2018-04-05 -- Fix incorrect version being saved
 v0.3.4.1, 2018-10-19 -- python3 compatible next for generator
 v0.3.5, 2019-12-21 -- add validator and clean-up repo structure
+v0.4.0, 2025-12-21 -- Replaces PyTables with H5Py, cleans repo structure, adds CI
 

MANIFEST.in

@@ -1,6 +1,6 @@
 # OMX Python API Documentation
 
-The Python OMX API borrows heavily from PyTables. An OMX file extends the equivalent PyTables File object, so anything you can do in PyTables you can do with OMX as well. This API attempts to be very Pythonic, including dictionary-style lookup of matrix names.
+The Python OMX API is built on top of h5py. An OMX file extends the equivalent h5py File object, so anything you can do in h5py you can do with OMX as well. This API attempts to be very Pythonic, including dictionary-style lookup of matrix names.
 
 * [Pre-requisites](#pre-requisites)
 * [Installation](#installation)
@@ -12,16 +12,22 @@ The Python OMX API borrows heavily from PyTables. An OMX file extends the equiva
 
 # Pre-requisites
 
-Python 2.6+, PyTables 3.1+, and NumPy. Python 3 is now supported too. 
+Python 3.9+, h5py 2.10+, and NumPy. 
 
-On Windows, the easiest way to get these is from [Anaconda](https://www.continuum.io/downloads#windows) or from Chris Gohlke's python binaries [page](http://www.lfd.uci.edu/~gohlke/pythonlibs/).  On Linux, your distribution already has these available. 
+Binaries for all these dependencies are readily available from PyPI and can be installed via pip.
 
 # Installation
 
 The easiest way to get OMX on Python is to use pip. Get the latest package (called OpenMatrix) from the [Python Package Index](https://pypi.python.org/pypi)
 
   `pip install openmatrix`
 
+Using uv is also possible and much faster:
+
+  `pip install uv`
+  `uv pip install openmatrix`
+
+
 This command will fetch openmatrix from the PyPi repository and download/install it for you. The package name "omx" was already taken on pip for a lame xml library that no one uses. Thus our little project goes by "openmatrix" on pip instead of "omx". This means your import statements should look like, 
 
   `import openmatrix as omx`
@@ -33,31 +39,30 @@ and NOT:
 # Quick-Start Sample Code
 
 ```python
-from __future__ import print_function
 import openmatrix as omx
 import numpy as np
 
 # Create some data
-ones = np.ones((100,100))
-twos = 2.0*ones
+ones = np.ones((100, 100))
+twos = 2.0 * ones
 
 # Create an OMX file (will overwrite existing file!)
 print('Creating myfile.omx')
-myfile = omx.open_file('myfile.omx','w')   # use 'a' to append/edit an existing file
+myfile = omx.open_file('myfile.omx', 'w')  # use 'a' to append/edit an existing file
 
 # Write to the file.
 myfile['m1'] = ones
 myfile['m2'] = twos
-myfile['m3'] = ones + twos           # numpy array math is fast
+myfile['m3'] = ones + twos  # numpy array math is fast
 myfile.close()
 
 # Open an OMX file for reading only
 print('Reading myfile.omx')
 myfile = omx.open_file('myfile.omx')
 
-print ('Shape:', myfile.shape())                 # (100,100)
-print ('Number of tables:', len(myfile))         # 3
-print ('Table names:', myfile.list_matrices())   # ['m1','m2',',m3']
+print('Shape:', myfile.shape())  # (100,100)
+print('Number of tables:', len(myfile))  # 3
+print('Table names:', myfile.list_matrices())  # ['m1','m2',',m3']
 
 # Work with data. Pass a string to select matrix by name:
 # -------------------------------------------------------
@@ -76,8 +81,8 @@ my_very_special_zone_value = m2[10][25]
 
 # FANCY: Use attributes to find matrices
 # --------------------------------------
-myfile.close()                            # was opened read-only, so let's reopen.
-myfile = omx.open_file('myfile.omx','a')  # append mode: read/write existing file
+myfile.close()  # was opened read-only, so let's reopen.
+myfile = omx.open_file('myfile.omx', 'a')  # append mode: read/write existing file
 
 myfile['m1'].attrs.timeperiod = 'am'
 myfile['m1'].attrs.mode = 'hwy'
@@ -87,13 +92,13 @@ myfile['m2'].attrs.timeperiod = 'md'
 myfile['m3'].attrs.timeperiod = 'am'
 myfile['m3'].attrs.mode = 'trn'
 
-print('attributes:', myfile.list_all_attributes())       # ['mode','timeperiod']
+print('attributes:', myfile.list_all_attributes())  # ['mode','timeperiod']
 
 # Use a DICT to select matrices via attributes:
 
-all_am_trips = myfile[ {'timeperiod':'am'} ]                    # [m1,m3]
-all_hwy_trips = myfile[ {'mode':'hwy'} ]                        # [m1]
-all_am_trn_trips = myfile[ {'mode':'trn','timeperiod':'am'} ]   # [m3]
+all_am_trips = myfile[{'timeperiod': 'am'}]  # [m1,m3]
+all_hwy_trips = myfile[{'mode': 'hwy'}]  # [m1]
+all_am_trn_trips = myfile[{'mode': 'trn', 'timeperiod': 'am'}]  # [m3]
 
 print('sum of some tables:', np.sum(all_am_trips))
 
@@ -102,23 +107,23 @@ print('sum of some tables:', np.sum(all_am_trips))
 # (any mapping would work, such as a mapping with large gaps between zone
 #  numbers. For this simple case we'll just assume TAZ numbers are 1-100.)
 
-taz_equivs = np.arange(1,101)                  # 1-100 inclusive
+taz_equivs = np.arange(1, 101)  # 1-100 inclusive
 
 myfile.create_mapping('taz', taz_equivs)
-print('mappings:', myfile.list_mappings()) # ['taz']
+print('mappings:', myfile.list_mappings())  # ['taz']
 
-tazs = myfile.mapping('taz') # Returns a dict:  {1:0, 2:1, 3:2, ..., 100:99}
+tazs = myfile.mapping('taz')  # Returns a dict:  {1:0, 2:1, 3:2, ..., 100:99}
 m3 = myfile['m3']
-print('cell value:', m3[tazs[100]][tazs[100]]) # 3.0  (taz (100,100) is cell [99][99])
+print('cell value:', m3[tazs[100]][tazs[100]])  # 3.0  (taz (100,100) is cell [99][99])
 
 myfile.close()
 ```
 
 # Testing
-Testing is done with [nose](https://nose.readthedocs.io/en/latest/).  Run the tests via:
+Testing is done with [pytest](https://docs.pytest.org/).  Run the tests via:
 
 ```
-openmatrix\test> nosetests -v
+pytest
 ```
 
 # OMX File Validator
@@ -132,7 +137,7 @@ omx-validate my_file.omx
 
 ### File Objects
 
-OMX File objects extend Pytables.File, so all Pytables functions work normally. We've also added some useful stuff to make things even easier.
+OMX File objects extend h5py.File, so all h5py functions work normally. We've also added some useful stuff to make things even easier.
 
 ### Writing Data
 
@@ -148,25 +153,24 @@ will call createMatrix() for you and populate it with the specified array.
 
 ### Accessing Data
 
-You can access matrix objects by name, using dictionary lookup e.g. `myfile['hwydist']` or using PyTables path notation, e.g. `myfile.root.hwydist`
+You can access matrix objects by name, using dictionary lookup e.g. `myfile['hwydist']`.
 
 ### Matrix objects
 
-OMX matrices extend numpy arrays. An OMX matrix object extends a Pytables/HDF5 "node" which means all HDF5 methods and properties behave normally. Generally these datasets are going to be numpy CArray objects of arbitrary shape.
+OMX matrices are h5py Dataset objects. An OMX matrix object extends an h5py Dataset which means all h5py methods and properties behave normally.
 You can access a matrix object by name using:
 
 * dictionary syntax, e.g. `myfile['hwydist']`
-* or by Pytables path syntax, e.g. `myfile.root.hwydist`
 
 Once you have a matrix object, you can perform normal numpy math on it or you can access rows and columns pythonically:
 
 ```python
 myfile['biketime'][0][0] = 0.60 * myfile['bikedist'][0][0]
-total_trips = numpy.sum(myfile.root.trips)`
+total_trips = np.sum(myfile.root.trips)`
 ```
 
 ### Properties
-Every Matrix has its own dictionary of key/value pair attributes (properties) which can be accessed using the standard Pytables .attrs field.  Add as many attributes as you like; attributes can be string, ints, floats, and lists:
+Every Matrix has its own dictionary of key/value pair attributes (properties) which can be accessed using the standard h5py .attrs field.  Add as many attributes as you like; attributes can be string, ints, floats, and lists:
 
 ```python
 print mymatrix.attrs
@@ -202,7 +206,7 @@ OMX module version string.  Currently '0.3.5' as of this writing. This is the Py
 ### `__omx_version__`
 OMX file format version. Currently '0.2'. This is the OMX file format specification that omx-python adheres to.
 
-### `open_file`(filename, mode='r', title='', root_uep='/', filters=Filters(complevel=1, complib='zlib', shuffle=True, bitshuffle=False, fletcher32=False, least_significant_digit=None), shape=None, **kwargs)
+### `open_file`(filename, mode='r', title='', filters=None, shape=None, **kwargs)
         Open or create a new OMX file. New files will be created with default
         zlib compression enabled.
         
@@ -218,7 +222,7 @@ OMX file format version. Currently '0.2'. This is the OMX file format specificat
         title : string
             Short description of this file, used when creating the file. Default is ''.
             Ignored in read-only mode.
-        filters : tables.Filters
+        filters : dict
             HDF5 default filter options for compression, shuffling, etc. Default for
             OMX standard file format is: zlib compression level 1, and shuffle=True. 
             Only specify this if you want something other than the recommended standard 
@@ -258,46 +262,48 @@ OMX file format version. Currently '0.2'. This is the OMX file format specificat
         
         Returns:
         --------
-        mapping : tables.array
+        mapping : h5py.Dataset
             Returns the created mapping.
         
         Raises:
             LookupError : if the mapping exists and overwrite=False
 
-### `create_matrix`(self, name, atom=None, shape=None, title='', filters=None, chunkshape=None, byteorder=None, createparents=False, obj=None, attrs=None)
-        Create an OMX Matrix (CArray) at the root level. User must pass in either
-        an existing numpy matrix, or a shape and an atom type.
+### `create_matrix`(self, name, shape=None, title='', filters=None, chunks=True, obj=None, dtype=None, attrs=None)
+        Create an OMX Matrix (Dataset) at the root level. User must pass in either
+        an existing numpy matrix, or a shape and a dtype.
         
         Parameters
         ----------
         name : string
             The name of this matrix. Stored in HDF5 as the leaf name.
         title : string
             Short description of this matrix. Default is ''.
-        obj : numpy.CArray
+        obj : numpy.ndarray
             Existing numpy array from which to create this OMX matrix. If obj is passed in,
-            then shape and atom can be left blank. If obj is not passed in, then a shape and
-            atom must be specified instead. Default is None.
+            then shape and dtype can be left blank. If obj is not passed in, then a shape and
+            dtype must be specified instead. Default is None.
         shape : numpy.array
             Optional shape of the matrix. Shape is an int32 numpy array of format (rows,columns).
-            If shape is not specified, an existing numpy CArray must be passed in instead, 
+            If shape is not specified, an existing numpy array must be passed in instead, 
             as the 'obj' parameter. Default is None.
-        atom : atom_type
-            Optional atom type of the data. Can be int32, float32, etc. Default is None.
+        dtype : dtype
+            Optional data type of the data. Can be 'int32', 'float32', etc. Default is None.
             If None specified, then obj parameter must be passed in instead.
-        filters : tables.Filters
+        filters : dict
             Set of HDF5 filters (compression, etc) used for creating the matrix. 
             Default is None. See HDF5 documentation for details. Note: while the default here
             is None, the default set of filters set at the OMX parent file level is 
             zlib compression level 1. Those settings usually trickle down to the table level.
+        chunks : tuple or bool
+            Chunk shape, or True to enable auto-chunking. Default is True.
         attrs : dict
             Dictionary of attribute names and values to be attached to this matrix.
             Default is None.
         
         Returns
         -------
-        matrix : tables.carray
-            HDF5 CArray matrix
+        matrix : h5py.Dataset
+            HDF5 Dataset matrix
 
 ### `delete_mapping`(self, title)
         Remove a mapping.