Refactor to object-oriented interface

.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

doc/source/conf.py

@@ -17,6 +17,8 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+add_module_names = False
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",

doc/source/development.rst

@@ -16,15 +16,10 @@ General Guidelines
 
 All code contributed to **parsnip** must adhere to the following guidelines:
 
-  * Use a two branch model of development:
-
-    - Most new features and bug fixes should be developed in branches based on ``main``.
-    - API incompatible changes and those that significantly change existing functionality should be based on ``breaking``
-  * Hard dependencies (those that end users must install to use **parsnip**) are *strongly* discouraged, and should be avoided where possible. Numpy is the sole exception to this, as it is already included in most scientific computing software stacks.
-  * Additional dependencies required by developers (those used to run tests or build docs) are undesirable but allowed.
+  * Hard dependencies (those that end users must install to use **parsnip**) are *strongly* discouraged, and should be avoided where possible. Additional dependencies required by developers (those used to run tests or build docs) are allowed where necessary.
   * All code should adhere to the source code conventions and satisfy the documentation and testing requirements discussed below.
 
-As portability is a primary feature of **parsnip**, tests are run run on Python versions 3.9 and later. However, first class support should only be expected for versions covered by `NEP 29`_.
+As portability is a primary feature of **parsnip**, tests are run run on Python versions 3.7 and later. However, first class support should only be expected for versions covered by `NEP 29`_.
 
 .. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html
 
@@ -57,15 +52,13 @@ All code in **parsnip** should be formatted using `ruff`_ via pre-commit. This p
 Documentation
 -------------
 
-API documentation should be written as part of the docstrings of the package in the `Google style <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>`__.
+API documentation should be written as part of the docstrings of the package in the `Numpy style <https://numpydoc.readthedocs.io/en/latest/format.html>`__.
 
 Docstrings are automatically validated using `pydocstyle <http://www.pydocstyle.org/>`_ whenever the ruff pre-commit hooks are run.
 The `official documentation <https://parsnip.readthedocs.io/>`_ is generated from the docstrings using `Sphinx <http://www.sphinx-doc.org/en/stable/index.html>`_.
 
 In addition to API documentation, inline comments are strongly encouraged.
 Code should be written as transparently as possible, so the primary goal of documentation should be explaining the algorithms or mathematical concepts underlying the code.
-Avoid comments that simply restate the nature of lines of code: for example, the comment "set up regex pattern" is uninformative, since the code itself should make this obvious, *e.g*, ``re.compile(r"^(_\w+)\s+(\d+)")``.
-On the other hand, the comment "read an underscore-prefixed word and a numeric value seperated by whitespace" is instructive.
 Multiline comments for regex strings may sometimes be necessary.
 
 Building Documentation
@@ -82,7 +75,7 @@ Building Documentation
 Unit Tests
 ----------
 
-All code should include a set of tests which test for correct behavior.
+All code should include a set of tests which validate correct behavior.
 All tests should be placed in the ``tests`` folder at the root of the project.
 In general, most parts of parsnip primarily require `unit tests <https://en.wikipedia.org/wiki/Unit_testing>`_, but where appropriate `integration tests <https://en.wikipedia.org/wiki/Integration_testing>`_ are also welcome. Core functions should be tested against the sample CIF files included in ``tests/sample_data``.
 Tests in **parsnip** use the `pytest <https://docs.pytest.org/>`__ testing framework.

doc/source/example_file.cif

@@ -25,3 +25,13 @@ _atom_site_Wyckoff_label
 Cu1 0.0000000000 0.0000000000 0.0000000000  Cu a
 
 _symmetry_space_group_name_H-M  'Fm-3m'
+
+# Note that this table is only a subset of the full symmetry of the crystal, but
+# it is sufficient to reconstruct the unit cell.
+loop_
+_symmetry_equiv_pos_site_id
+_symmetry_equiv_pos_as_xyz
+1  x,y,z
+96  z,y+1/2,x+1/2
+118  z+1/2,-y,x+1/2
+192  z+1/2,y+1/2,x