Refactor to object-oriented interface (#29)

* Nearly-working impl

* Full working example

* Clean up layout

* Further cleanup

* Lint OO

* Run pre-commit on _errors.py

* Add oo.py temp implementation

* Undo changes to sample data

* Lint oo.py

* Remove change to sample data

* Add oo to init.py

* Handle edge cases

* Test parsing real files

* Improve robustness of table reader

* Lint oo and conftest

* Clean up text and remove comments

* Port initial test to new style

* Port remaining key tests

* Minor fixes

* Clean up test_key_reader.py

* Progress toward transition to recarray

* Increase tests and fix memory layout bug

* Fixes to memory layout

* Convert table_reader tests

* Linting and doc fixes

* Clean up docs

* Finish porting tests

* Lints

* Fix for scalar array inputs

* Remove unnecessary filterwarning

* Expand on tests

* Clean up unitcells

* Lint tests

* Finalize lints

* Restructure patterns

* Update test_patterns

* Lint and clean up

* Final lint

* Improve a few tests

* Add symops to example cif

* Remove package-unitcells deprecated docs

* Fix link in package-parse

* Update quickstart tutorial

* Move oo.py to parsnip.py

* Update README

* Update Unitcells test imports

* Lint

* Lazily load file

* Remove unused files

* Skip bad_cif test

* Clean up tests

* Lint

* Add tests for table_labels and cast_numerics

* Clean up tests

* Lint

* Clean up docstrings

* Lint and update docstrings

* Further docs

* Codespell

* Tests for cell

* Lint

* Update errors for read_unit_cell

* Clean up tests and todos

* More TODOs

* Lint

* Add test for cell property

* Remove modindex from sidebar

* Consolidate logic for nonsimple data

* Lint

* Fix type annotation in cast_array function

* Add more-itertools as official dependency

* Clean up dependency documentation

* Add index for ase backward compatibility

* Change wording in development.rst

* Replace index specification

* Disable ASE test on python3.7

* Fix version check

* Add additional lints

* Document additional rules in pyproject.toml

* Move PATTERNS dict to end of docs

* Clean up development.rst

* Expand with tests from additional databases

* Disable lint that causes warning

* Fix for multiline data entries

* Progress toward multiline string parsing

* Working impl that fails for blocks containing a semicolon

* Clean up

* Messy working impl

* Clean up

* Retain newlines

* Lint

* Add TODO

* Add missing multiline keys

* Wrap accumulator into a function

* Clean up _accumulate_nonsimple_data

* Clean up unused comments

* Update changelog.rst

* Fix version headings in changelog

* Update README to reflect correct CIF2.0 status

* Add CIFTEST data to gitignore

* Escape dash in regex and allow forward slash in data name

* Swap namedtuple to dataclass and clean up provided keys

* Auto detect cif keys

* Allow pdb matrix keys

* Generalize nonsimple data delimiters

* Add architecture.md

* Update table tests and fix regex for nonsimple data in tabs

* Add pycifrw to test reqs

* Lint tests

* Verify all table content

* Lint

* import annotations

* Remove unused pattern

* Rename tables to loops

* Remove extra character from regex

* Clean up table reader

* Clean up

Author: janbridley

.github/requirements-3.10.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --python-version=3.10 pyproject.toml tests/requirements.in
-ase==3.23.0
+ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
@@ -14,16 +14,19 @@ gemmi==0.7.0
     # via -r tests/requirements.in
 iniconfig==2.0.0
     # via pytest
-kiwisolver==1.4.7
+kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.0
     # via ase
-numpy==2.2.0
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
+numpy==2.2.1
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -33,7 +36,11 @@ pillow==11.0.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
-pyparsing==3.2.0
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
+pyparsing==3.2.1
     # via matplotlib
 pytest==8.3.4
     # via -r tests/requirements.in

.github/requirements-3.11.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --python-version=3.11 pyproject.toml tests/requirements.in
-ase==3.23.0
+ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
@@ -12,16 +12,19 @@ gemmi==0.7.0
     # via -r tests/requirements.in
 iniconfig==2.0.0
     # via pytest
-kiwisolver==1.4.7
+kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.0
     # via ase
-numpy==2.2.0
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
+numpy==2.2.1
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -31,7 +34,11 @@ pillow==11.0.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
-pyparsing==3.2.0
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
+pyparsing==3.2.1
     # via matplotlib
 pytest==8.3.4
     # via -r tests/requirements.in

.github/requirements-3.12.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --python-version=3.12 pyproject.toml tests/requirements.in
-ase==3.23.0
+ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
@@ -12,16 +12,19 @@ gemmi==0.7.0
     # via -r tests/requirements.in
 iniconfig==2.0.0
     # via pytest
-kiwisolver==1.4.7
+kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.0
     # via ase
-numpy==2.2.0
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
+numpy==2.2.1
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -31,7 +34,11 @@ pillow==11.0.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
-pyparsing==3.2.0
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
+pyparsing==3.2.1
     # via matplotlib
 pytest==8.3.4
     # via -r tests/requirements.in

.github/requirements-3.13.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --python-version=3.13 pyproject.toml tests/requirements.in
-ase==3.23.0
+ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
@@ -12,16 +12,19 @@ gemmi==0.7.0
     # via -r tests/requirements.in
 iniconfig==2.0.0
     # via pytest
-kiwisolver==1.4.7
+kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.0
     # via ase
-numpy==2.2.0
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
+numpy==2.2.1
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -31,7 +34,11 @@ pillow==11.0.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
-pyparsing==3.2.0
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
+pyparsing==3.2.1
     # via matplotlib
 pytest==8.3.4
     # via -r tests/requirements.in

.github/requirements-3.7.txt

@@ -20,11 +20,14 @@ kiwisolver==1.4.5
     # via matplotlib
 matplotlib==3.5.3
     # via ase
+more-itertools==9.1.0
+    # via parsnip (pyproject.toml)
 numpy==1.21.6
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.0
     # via
@@ -34,6 +37,10 @@ pillow==9.5.0
     # via matplotlib
 pluggy==1.2.0
     # via pytest
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
 pyparsing==3.1.4
     # via matplotlib
 pytest==7.4.4

.github/requirements-3.8.txt

@@ -20,12 +20,15 @@ kiwisolver==1.4.7
     # via matplotlib
 matplotlib==3.7.5
     # via ase
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
 numpy==1.24.4
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -35,6 +38,10 @@ pillow==10.4.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
 pyparsing==3.1.4
     # via matplotlib
 pytest==8.3.4

.github/requirements-3.9.txt

@@ -1,6 +1,6 @@
 # This file was autogenerated by uv via the following command:
 #    uv pip compile --python-version=3.9 pyproject.toml tests/requirements.in
-ase==3.23.0
+ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.0
     # via matplotlib
@@ -20,12 +20,15 @@ kiwisolver==1.4.7
     # via matplotlib
 matplotlib==3.9.4
     # via ase
+more-itertools==10.5.0
+    # via parsnip (pyproject.toml)
 numpy==2.0.2
     # via
     #   parsnip (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
+    #   pycifrw
     #   scipy
 packaging==24.2
     # via
@@ -35,7 +38,11 @@ pillow==11.0.0
     # via matplotlib
 pluggy==1.5.0
     # via pytest
-pyparsing==3.2.0
+ply==3.11
+    # via pycifrw
+pycifrw==4.4.6
+    # via -r tests/requirements.in
+pyparsing==3.2.1
     # via matplotlib
 pytest==8.3.4
     # via -r tests/requirements.in

README.rst

@@ -27,8 +27,10 @@
 
 .. _parse:
 
-The ``parsnip.parse`` module handles standard CIF files (including those under the `CIF 1.1 <https://www.iucr.org/resources/cif/spec/version1.1>`_ and `CIF 2.0 <https://www.iucr.org/resources/cif/cif2>`_ standards), as well as many features from the `mmCIF <https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/beginner’s-guide-to-pdb-structures-and-the-pdbx-mmcif-format>`_ format.
-The package includes a table reader for `loop\_`-delimited tables as well as a key-value pair reader. Provide a filename and a list of keys to either of these functions and you're all set to read start parsing CIF files!
+Importing ``parsnip`` allows users to read `CIF 1.1 <https://www.iucr.org/resources/cif/spec/version1.1>`_ files, as well as many features from the `CIF 2.0 <https://www.iucr.org/resources/cif/cif2>`_ and `mmCIF <https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/beginner’s-guide-to-pdb-structures-and-the-pdbx-mmcif-format>`_ formats.
+Creating a :class:`~.CifFile` object provides easy access to name-value :attr:`~.CifFile.pairs`, as well
+as `loop\_`-delimited :attr:`~.CifFile.tables`. Data entries can be extracted as python primitives or
+numpy arrays for further use.
 
 .. _installing:
 
@@ -78,5 +80,6 @@ Dependencies
 .. code:: text
 
    numpy>=1.19
+   more-itertools
 
 .. _contributing:

architecture.md

@@ -0,0 +1,17 @@
+Parsnip Architecture
+--------------------
+
+The primary design goal of ``parsnip`` was to create a lightweight, simple CIF parsing
+library. ``parsnip`` has a minimal set of dependencies, relatively few lines of code,
+and extensive testing to validate the accuracy of read files. Dozens of CIF parsing
+libraries exist, but most are either (1) part of a much larger project (and therefore
+undesirable as a simple dependency) or (2) have a poorly documented interface. This
+project is designed to bridge that gap with careful documentation and a minimal subset
+of features that build well into other open-source projects.
+
+
+This project takes a (reasonably) permissive view of the CIF specification: data entries
+that "look like" valid data will be parsed, regardless of file encoding, line length,
+special characters, or syntax specifics like unlabeled blocks. ``parsnip`` is designed
+to read and extract data from CIF, mmCIF, and STAR files regardless of their compliance
+with the full CIF specification.

changelog.rst

@@ -4,7 +4,31 @@ Changelog
 The format is based on `Keep a Changelog <http://keepachangelog.com/en/1.1.0/>`__.
 This project adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`__.
 
-v0.x.x - 20xx-xx-xx
+v1.0.0 - 20xx-xx-xx
+-------------------
 
 Added
 ~~~~~
+- Support for nonsimple (';'-delimited) data entries.
+- Improved support for entries containing special characters.
+- Ability to query multiple keys or columns simultaneously.
+- Additional tests for AMCSD and zeolite databases.
+- Additional documentation and examples for the new interface
+
+Changed
+~~~~~~~
+- Primary interface is now the ``CifFile`` object, which supports all previously implemented features in addition to several new methods.
+- Files are now parsed lazily, and are traversed a single time.
+
+Dependencies
+~~~~~~~~~~~~
+- Added ``more-itertools`` as a dependency for ``peekable`` iterators
+
+
+v0.1.0 - 2024-12-20
+-------------------
+
+Added
+~~~~~
+- Unitcells module
+- Function-based parsing interface for key and table reading