RCSB Python I/O Utility Classes

Introduction

This module contains a collection of utility classes for performing I/O operations on common file formats encountered in the PDB data repository.

Installation

Download the library source software from the project repository:

git clone --recurse-submodules https://github.com/rcsb/py-rcsb_utils_io.git

Optionally, run test suite (Python versions 3.9) using tox:

tox

Installation is via the program pip.

pip install rcsb.utils.io

or from the local repository:

pip install .

Usage

The MarshalUtil offers an easy way for reading in and writing out files in various formats, including CSV, JSON, pickle, mmCIF, bcif (BinaryCIF), fasta , and "list" files (plain text file in which each row is a list item).

Reading files

Let's say you have a JSON file, "data.json". You can read this in by:

from rcsb.utils.io.MarshalUtil import MarshalUtil
mU = MarshalUtil(workDir=".")

dataD = mU.doImport("data.json", fmt="json")

The same method works even if the file is compressed (e.g., "data.json.gz"):

dataD = mU.doImport("data.json.gz", fmt="json")

Note that this automatic handling of compressed gzip files applies to any type of input format.

You can also import remote files directly from the command line, e.g.:

dataD = mU.doImport("https://files.rcsb.org/pub/pdb/holdings/current_file_holdings.json.gz", fmt="json")

To read in a pickle file, "data.pic":

from rcsb.utils.io.MarshalUtil import MarshalUtil
mU = MarshalUtil()

dataD = mU.doImport("data.pic", fmt="pickle")

To read in and parse an mmCIF file, "4hhb.cif.gz":

from rcsb.utils.io.MarshalUtil import MarshalUtil
mU = MarshalUtil()

# Read all data containers from the mmCIF file into `dataContainerList`
dataContainerList = mU.doImport("https://files.rcsb.org/pub/pdb/data/structures/divided/mmCIF/hh/4hhb.cif.gz", fmt="mmcif")

# Get the first dataContainer (in most cases, there will only be one container in the file)
dataContainer = dataContainerList[0]

# Print the name of the container
eName = dataContainer.getName()
print(eName)

# Get the list of categories
catNameList = dataContainer.getObjNameList()
print(catNameList)

# Iterate over all the categories and attributes and store them in a new dictionary 
cifDataD = {}
for catName in catNameList:
    if not dataContainer.exists(catName):
        continue
    dObj = dataContainer.getObj(catName)
    for ii in range(dObj.getRowCount()):
        dD = dObj.getRowAttributeDict(ii)
        cifDataD.setdefault(eName, {}).setdefault(catName, []).append(dD)

For more examples, see testMarshallUtil.py.

Writing files

You can use the MarshalUtil to write out the following data structures into the corresponding file formats:

 Object            |  Output `fmt`
-------------------------------------
 list              |  list
 dict              |  json or pickle
 DataContainerList |  mmcif or bcif

For example, if you have a dictionary, dataD, you can export it via:

from rcsb.utils.io.MarshalUtil import MarshalUtil
mU = MarshalUtil()

dataD = {"name": "John Doe", "age": "33"}

mU.doExport("data.json", dataD, fmt="json", indent=2)

# Or, to export and compress as gzip:
mU.doExport("data.json.gz", dataD, fmt="json", indent=2)

Development Status
- 5 - Production/Stable
Intended Audience
- Developers
Natural Language
- English
Programming Language

Release files for rcsb.utils.io 1.54

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rcsb.utils.io 1.54
File	Size	Uploaded
rcsb_utils_io-1.54.tar.gz	61.3 kB	Aug 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rcsb.utils.io 1.54
File	Interpreter	ABI	Platform	Reset
rcsb_utils_io-1.54-py3-none-any.whl 52.8 kB Aug 24, 2026	Python 3	none	any	Details

Total release size: 114.0 kB

Release files / rcsb_utils_io-1.54.tar.gz

Download URL	rcsb_utils_io-1.54.tar.gz
Size	61.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`f118d961c4e0b4c932e80354797db763e32e538d3d8705dc42b4bfcb2b3badf2`
BLAKE2b-256 checksum How to use checksums	`a7b06c445c93f8372360296e00571f5cdf8aad74bc3f0e74b0299790ba9750e3`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.15`

Release files / rcsb_utils_io-1.54-py3-none-any.whl

Download URL	rcsb_utils_io-1.54-py3-none-any.whl
Size	52.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`eb05ed78eb6af4e0866576b3b29f84ba9e9cd1243e22711c42f80fe9369dd860`
BLAKE2b-256 checksum How to use checksums	`ac92c86f50982fffedd9677fc3be7a37728ef093311b6a06fad4b7fb0c0114c9`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.15`