cif-explorer 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,77 @@
1
+ # Tests and build on every push and pull request.
2
+ # Pushing a tag vX.Y.Z publishes that version to PyPI through trusted
3
+ # publishing (no token): PyPI trusts this file, workflow.yml, in the
4
+ # GitHub environment "pypi".
5
+ name: CI
6
+
7
+ on:
8
+ push:
9
+ branches: [main]
10
+ tags: ["v*"]
11
+ pull_request:
12
+ workflow_dispatch:
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ test:
19
+ name: test (Python ${{ matrix.python }}, ${{ matrix.deps }} deps)
20
+ runs-on: ubuntu-latest
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ python: ["3.12", "3.13", "3.14"]
25
+ deps: [latest]
26
+ include:
27
+ # the oldest numpy and msgpack pyproject.toml allows
28
+ - python: "3.12"
29
+ deps: oldest
30
+ steps:
31
+ - uses: actions/checkout@v7
32
+ - uses: astral-sh/setup-uv@v10.4.0
33
+ # Python comes from uv (no setup-python needed)
34
+ - name: Install
35
+ run: |
36
+ uv venv --python ${{ matrix.python }}
37
+ uv pip install -e ".[test]" ${{ matrix.deps == 'oldest' && '--resolution lowest-direct' || '' }}
38
+ - name: Test
39
+ run: .venv/bin/python -m pytest -q
40
+
41
+ build:
42
+ runs-on: ubuntu-latest
43
+ steps:
44
+ - uses: actions/checkout@v7
45
+ - uses: astral-sh/setup-uv@v10.4.0
46
+ - name: Build sdist and wheel
47
+ run: uv build
48
+ - name: Check metadata
49
+ run: uvx twine check --strict dist/*
50
+ - name: Check that the tag matches the package version
51
+ if: startsWith(github.ref, 'refs/tags/v')
52
+ run: |
53
+ version="${GITHUB_REF_NAME#v}"
54
+ if [ ! -f "dist/cif_explorer-${version}.tar.gz" ]; then
55
+ echo "::error::tag ${GITHUB_REF_NAME} does not match the package version:" dist/*
56
+ exit 1
57
+ fi
58
+ - uses: actions/upload-artifact@v7
59
+ with:
60
+ name: dist
61
+ path: dist/
62
+
63
+ publish:
64
+ needs: [test, build]
65
+ if: startsWith(github.ref, 'refs/tags/v')
66
+ runs-on: ubuntu-latest
67
+ environment:
68
+ name: pypi
69
+ url: https://pypi.org/p/cif-explorer
70
+ permissions:
71
+ id-token: write # trusted publishing
72
+ steps:
73
+ - uses: actions/download-artifact@v8
74
+ with:
75
+ name: dist
76
+ path: dist/
77
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .coverage
9
+ htmlcov/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arthur Zalevsky
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,146 @@
1
+ Metadata-Version: 2.5
2
+ Name: cif-explorer
3
+ Version: 0.1.0
4
+ Summary: Browser-based explorer for IHMCIF files: trace rows up and down the category hierarchy, with live dictionary checks and live reload
5
+ Project-URL: Homepage, https://github.com/aozalevsky/cif-explorer
6
+ Project-URL: Issues, https://github.com/aozalevsky/cif-explorer/issues
7
+ Author-email: Arthur Zalevsky <aozalevsky@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: IHMCIF,PDB-IHM,biocuration,integrative structure,mmCIF
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Web Environment
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
21
+ Requires-Python: >=3.12
22
+ Requires-Dist: ihm>=2.13
23
+ Requires-Dist: msgpack>=1.0.6
24
+ Requires-Dist: numpy>=1.26
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8; extra == 'test'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # cif-explorer
30
+
31
+ A local, browser-based explorer for IHMCIF / mmCIF files, built for
32
+ PDB-IHM biocuration. Pick any row in any category and trace it **up**
33
+ (the rows it refers to) and **down** (the rows that refer to it) through the
34
+ whole hierarchy, with dictionary checks shown next to the values.
35
+
36
+ ```
37
+ cif_explorer 9A1N.cif # opens http://localhost:<port>/ in the browser
38
+ ```
39
+
40
+ ## Features
41
+
42
+ - **Trace tree.** Click a row; the right panel shows its fields, its parent
43
+ rows and the child rows in every category that refers to it. Expand any node
44
+ to keep walking up or down. "↑ all parents" opens the full chain of
45
+ ancestors (e.g. `atom_site → struct_asym → entity`, `ihm_model_list →
46
+ ihm_modeling_protocol → ihm_dataset_group …`).
47
+ - **Composite links.** Parent/child relationships come from the PDBx and IHM
48
+ dictionaries (`_item_linked`). Composite parent keys are completed, so
49
+ `atom_site` rows link to `entity_poly_seq` by entity + residue number +
50
+ residue name, and cross-link partners `_1` / `_2` are traced separately.
51
+ - **Dictionary checks.** Every value is checked against the item's type,
52
+ enumeration, range and mandatory flag (python-ihm's dictionary objects);
53
+ missing mandatory items, unknown categories/items, duplicate keys and broken
54
+ links (child values with no parent row) are listed in the checks panel, with
55
+ links to the offending rows. Bad cells are highlighted in the table and the
56
+ trace. python-ihm's own `Dictionary.validate` can be run from the same panel.
57
+ - **Live reload.** The file is watched; when it changes it is re-read and the
58
+ view (category, page, filters, selected row, expanded trace nodes, scroll
59
+ positions) is kept. If the new version does not parse, the error is shown
60
+ and the previous version stays on screen.
61
+ - **Big files.** Reading is done by python-ihm's C tokenizer. Large tables
62
+ (`atom_site`, `ihm_starting_model_coord`, `ihm_sphere_obj_site`, …) are packed
63
+ into numpy arrays while reading, so memory stays below the file size.
64
+ Paging, filtering, link lookups and child counts work on the packed columns
65
+ and answer in tens of milliseconds even for millions of atoms.
66
+
67
+ | file | atoms | load | checks | stored | peak RSS |
68
+ | --- | --- | --- | --- | --- | --- |
69
+ | 9A1N, 143 MB | 1.9 M | 7.6 s | 5 s | 97 MB | 0.27 GB |
70
+ | synthetic, 680 MB | 9.5 M | 35 s | 9 s | 432 MB | 1.0 GB |
71
+
72
+ The browser opens immediately and shows a progress bar while loading.
73
+ - Reads `.cif`, `.cif.gz` and BinaryCIF (`.bcif`).
74
+
75
+ ## Install
76
+
77
+ ```
78
+ uv tool install cif-explorer # or: pipx install cif-explorer
79
+ pip install cif-explorer
80
+ pip install -e . # from a checkout
81
+ ```
82
+
83
+ ## Usage
84
+
85
+ ```
86
+ cif_explorer FILE [--port N] [--host ADDR] [--no-browser] [--no-watch]
87
+ [--dict DIC ...] [--update-dicts]
88
+ ```
89
+
90
+ The PDBx (`mmcif_pdbx_v50.dic`) and IHM (`mmcif_ihm_ext.dic`) dictionaries are
91
+ downloaded from mmcif.wwpdb.org on first use and cached in
92
+ `~/.cache/cif_explorer/dictionaries` (override the location with
93
+ `CIF_EXPLORER_CACHE`, or pass local files with `--dict`). Use
94
+ `--update-dicts` to refresh them.
95
+
96
+ In the browser:
97
+
98
+ | action | how |
99
+ | --- | --- |
100
+ | trace a row | click it in the table |
101
+ | filter by a value | double-click the cell |
102
+ | full-text filter in a category | "contains…" box in the toolbar |
103
+ | search all categories | search box at the top (`/`) |
104
+ | dictionary definition | hover a column header or field name |
105
+ | jump from the tree to the table | `⌖ table` on a node |
106
+ | re-root the tree | `⤒ root` on a node |
107
+ | resize a panel | drag its divider; double-click the divider to reset |
108
+ | dark / light theme | ◐ button, top right (dark by default) |
109
+
110
+ The theme and panel sizes are saved in
111
+ `~/.config/cif_explorer/prefs.json` (`$XDG_CONFIG_HOME` and
112
+ `CIF_EXPLORER_CONFIG` are honoured) and apply to every run.
113
+
114
+ ## Limitations / ideas
115
+
116
+ - Rows are matched to parents by exact value equality, as the dictionary
117
+ links define. Range-style references (`seq_id_begin`..`seq_id_end`) are
118
+ matched on their end points only; "which spheres cover residue 17" is not
119
+ answered yet.
120
+ - Line numbers are known per category (python-ihm reports them), not per
121
+ row.
122
+ - Only the first data block of a file is shown.
123
+
124
+ ## Development
125
+
126
+ ```
127
+ uv venv && uv pip install -e ".[test]"
128
+ pytest
129
+ ```
130
+
131
+ All CIF parsing is delegated to [python-ihm](https://github.com/ihmwg/python-ihm);
132
+ this package contains no tokenizer of its own.
133
+
134
+ ### Releasing
135
+
136
+ 1. Set `__version__` in `src/cif_explorer/__init__.py` (e.g. `0.2.0`) and
137
+ commit.
138
+ 2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
139
+
140
+ The [workflow](.github/workflows/workflow.yml) runs the tests, builds the
141
+ sdist and wheel, checks that the tag matches the version and publishes to
142
+ PyPI through trusted publishing (GitHub environment `pypi`).
143
+
144
+ ## License
145
+
146
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,118 @@
1
+ # cif-explorer
2
+
3
+ A local, browser-based explorer for IHMCIF / mmCIF files, built for
4
+ PDB-IHM biocuration. Pick any row in any category and trace it **up**
5
+ (the rows it refers to) and **down** (the rows that refer to it) through the
6
+ whole hierarchy, with dictionary checks shown next to the values.
7
+
8
+ ```
9
+ cif_explorer 9A1N.cif # opens http://localhost:<port>/ in the browser
10
+ ```
11
+
12
+ ## Features
13
+
14
+ - **Trace tree.** Click a row; the right panel shows its fields, its parent
15
+ rows and the child rows in every category that refers to it. Expand any node
16
+ to keep walking up or down. "↑ all parents" opens the full chain of
17
+ ancestors (e.g. `atom_site → struct_asym → entity`, `ihm_model_list →
18
+ ihm_modeling_protocol → ihm_dataset_group …`).
19
+ - **Composite links.** Parent/child relationships come from the PDBx and IHM
20
+ dictionaries (`_item_linked`). Composite parent keys are completed, so
21
+ `atom_site` rows link to `entity_poly_seq` by entity + residue number +
22
+ residue name, and cross-link partners `_1` / `_2` are traced separately.
23
+ - **Dictionary checks.** Every value is checked against the item's type,
24
+ enumeration, range and mandatory flag (python-ihm's dictionary objects);
25
+ missing mandatory items, unknown categories/items, duplicate keys and broken
26
+ links (child values with no parent row) are listed in the checks panel, with
27
+ links to the offending rows. Bad cells are highlighted in the table and the
28
+ trace. python-ihm's own `Dictionary.validate` can be run from the same panel.
29
+ - **Live reload.** The file is watched; when it changes it is re-read and the
30
+ view (category, page, filters, selected row, expanded trace nodes, scroll
31
+ positions) is kept. If the new version does not parse, the error is shown
32
+ and the previous version stays on screen.
33
+ - **Big files.** Reading is done by python-ihm's C tokenizer. Large tables
34
+ (`atom_site`, `ihm_starting_model_coord`, `ihm_sphere_obj_site`, …) are packed
35
+ into numpy arrays while reading, so memory stays below the file size.
36
+ Paging, filtering, link lookups and child counts work on the packed columns
37
+ and answer in tens of milliseconds even for millions of atoms.
38
+
39
+ | file | atoms | load | checks | stored | peak RSS |
40
+ | --- | --- | --- | --- | --- | --- |
41
+ | 9A1N, 143 MB | 1.9 M | 7.6 s | 5 s | 97 MB | 0.27 GB |
42
+ | synthetic, 680 MB | 9.5 M | 35 s | 9 s | 432 MB | 1.0 GB |
43
+
44
+ The browser opens immediately and shows a progress bar while loading.
45
+ - Reads `.cif`, `.cif.gz` and BinaryCIF (`.bcif`).
46
+
47
+ ## Install
48
+
49
+ ```
50
+ uv tool install cif-explorer # or: pipx install cif-explorer
51
+ pip install cif-explorer
52
+ pip install -e . # from a checkout
53
+ ```
54
+
55
+ ## Usage
56
+
57
+ ```
58
+ cif_explorer FILE [--port N] [--host ADDR] [--no-browser] [--no-watch]
59
+ [--dict DIC ...] [--update-dicts]
60
+ ```
61
+
62
+ The PDBx (`mmcif_pdbx_v50.dic`) and IHM (`mmcif_ihm_ext.dic`) dictionaries are
63
+ downloaded from mmcif.wwpdb.org on first use and cached in
64
+ `~/.cache/cif_explorer/dictionaries` (override the location with
65
+ `CIF_EXPLORER_CACHE`, or pass local files with `--dict`). Use
66
+ `--update-dicts` to refresh them.
67
+
68
+ In the browser:
69
+
70
+ | action | how |
71
+ | --- | --- |
72
+ | trace a row | click it in the table |
73
+ | filter by a value | double-click the cell |
74
+ | full-text filter in a category | "contains…" box in the toolbar |
75
+ | search all categories | search box at the top (`/`) |
76
+ | dictionary definition | hover a column header or field name |
77
+ | jump from the tree to the table | `⌖ table` on a node |
78
+ | re-root the tree | `⤒ root` on a node |
79
+ | resize a panel | drag its divider; double-click the divider to reset |
80
+ | dark / light theme | ◐ button, top right (dark by default) |
81
+
82
+ The theme and panel sizes are saved in
83
+ `~/.config/cif_explorer/prefs.json` (`$XDG_CONFIG_HOME` and
84
+ `CIF_EXPLORER_CONFIG` are honoured) and apply to every run.
85
+
86
+ ## Limitations / ideas
87
+
88
+ - Rows are matched to parents by exact value equality, as the dictionary
89
+ links define. Range-style references (`seq_id_begin`..`seq_id_end`) are
90
+ matched on their end points only; "which spheres cover residue 17" is not
91
+ answered yet.
92
+ - Line numbers are known per category (python-ihm reports them), not per
93
+ row.
94
+ - Only the first data block of a file is shown.
95
+
96
+ ## Development
97
+
98
+ ```
99
+ uv venv && uv pip install -e ".[test]"
100
+ pytest
101
+ ```
102
+
103
+ All CIF parsing is delegated to [python-ihm](https://github.com/ihmwg/python-ihm);
104
+ this package contains no tokenizer of its own.
105
+
106
+ ### Releasing
107
+
108
+ 1. Set `__version__` in `src/cif_explorer/__init__.py` (e.g. `0.2.0`) and
109
+ commit.
110
+ 2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
111
+
112
+ The [workflow](.github/workflows/workflow.yml) runs the tests, builds the
113
+ sdist and wheel, checks that the tag matches the version and publishes to
114
+ PyPI through trusted publishing (GitHub environment `pypi`).
115
+
116
+ ## License
117
+
118
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "cif-explorer"
7
+ dynamic = ["version"]
8
+ description = "Browser-based explorer for IHMCIF files: trace rows up and down the category hierarchy, with live dictionary checks and live reload"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Arthur Zalevsky", email = "aozalevsky@gmail.com" }]
14
+ keywords = ["mmCIF", "IHMCIF", "PDB-IHM", "integrative structure", "biocuration"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Environment :: Web Environment",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Programming Language :: Python :: 3.14",
24
+ "Intended Audience :: Science/Research",
25
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
26
+ ]
27
+ dependencies = [
28
+ "ihm>=2.13",
29
+ "numpy>=1.26",
30
+ "msgpack>=1.0.6",
31
+ ]
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/aozalevsky/cif-explorer"
35
+ Issues = "https://github.com/aozalevsky/cif-explorer/issues"
36
+
37
+ [project.optional-dependencies]
38
+ test = ["pytest>=8"]
39
+
40
+ [project.scripts]
41
+ cif_explorer = "cif_explorer.cli:main"
42
+ cif-explorer = "cif_explorer.cli:main"
43
+
44
+ [tool.hatch.version]
45
+ path = "src/cif_explorer/__init__.py"
46
+
47
+ [tool.hatch.build.targets.wheel]
48
+ packages = ["src/cif_explorer"]
49
+
50
+ [tool.pytest.ini_options]
51
+ testpaths = ["tests"]
@@ -0,0 +1,3 @@
1
+ """cif_explorer: trace IHMCIF/mmCIF rows up and down the category hierarchy."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ main()