Monty (Python Complement Library)

Warnings

• gotcha Monty aims to complement the standard library, but be mindful of potential name collisions if you import specific functions that share names with standard library functions (e.g., `open`). Always prefer qualified imports (`monty.io.zopen`) or aliased imports (`import monty as mty`) to avoid unexpected behavior.
  Fix: Use `import monty as mty` and access functions via `mty.module.function()` or `from monty.module import function` for clarity and to prevent shadowing standard library names.
• deprecated The `monty.dev` module contains a `deprecated` decorator. While this is a utility provided by Monty, using it on your own code implies maintaining deprecation warnings. Ensure you understand its usage, especially when migrating or updating your code to remove deprecated features.
  Fix: Regularly review your codebase for deprecated functions or classes marked by `monty.dev.deprecated`. Update your code to use the recommended replacements to avoid future compatibility issues and maintain clean warning logs.
• gotcha There are several Python libraries published under or related to the name 'monty' (e.g., 'pydantic-monty', 'boppreh/monty', 'libmonty'). Ensure you are installing and using the correct 'monty' library (from `materialsvirtuallab/monty`) for the intended functionalities described as 'missing complement to Python'.
  Fix: Always verify the PyPI package name (`monty`) and the project's official source or documentation (e.g., `materialsvirtuallab/monty` on GitHub) to confirm you are using the intended library. Check import paths as different 'monty' libraries will have different top-level packages.
• breaking Older documentation mentions Monty supporting Python 2.7-3.x. However, PyPI metadata for the current version (2026.2.18) clearly states `requires_python: >=3.11`. Attempting to use recent versions of Monty with older Python 3 releases (e.g., 3.9, 3.10) will likely result in installation failures or runtime errors.
  Fix: Ensure your Python environment is version 3.11 or newer to be compatible with the latest `monty` releases. Check the `requires_python` field on PyPI for specific version constraints.
• breaking In `monty` version 1.0.0, `ruamel.yaml` became the default YAML parser and dumper. If your project previously relied on specific behaviors or features of `PyYAML` (which might have been the default prior to this change) when handling YAML files through Monty, this change could introduce subtle breaking changes in how YAML data is serialized or deserialized.
  Fix: If upgrading from very old versions of `monty` (pre-1.0.0) that used a different YAML backend, review YAML serialization/deserialization logic. Test your application's YAML handling thoroughly to ensure compatibility with `ruamel.yaml`'s behavior.

Install

• pip install monty Install latest version

Imports

• monty

  import monty as mty

  The official documentation suggests importing the root `monty` module and using it as an alias (e.g., `mty`) to access its various sub-modules and functions, mirroring the standard Python library's structure.
• zopen

  from monty.io import zopen

  Many of Monty's utilities are organized into submodules (e.g., `io`, `dev`). Direct import from the root `monty` package for specific functions like `zopen` is incorrect; you must specify the submodule.

Quickstart

This quickstart demonstrates `monty.io.zopen`, a utility that transparently handles compressed (gzip, bzip2) or uncompressed files based on their filename extension. It functions similarly to Python's built-in `open`, abstracting away the compression details.

import monty.io

# Example: Transparently open compressed or uncompressed files
# Create a dummy gzipped file
with open('example.txt', 'w') as f:
    f.write('Hello, Monty!\n')

import gzip
with open('example.txt', 'rb') as f_in:
    with gzip.open('example.gz', 'wb') as f_out:
        f_out.writelines(f_in)

# Use monty.io.zopen to read from the gzipped file
with monty.io.zopen('example.gz', 'rt') as f:
    content = f.read()
    print(f'Content from gzipped file: {content.strip()}')

# Use monty.io.zopen to write to a bzipped file
with monty.io.zopen('output.bz2', 'wt') as f:
    f.write('This is written to a bzip2 file using monty.io.zopen.')

# Verify by reading back
with monty.io.zopen('output.bz2', 'rt') as f:
    read_content = f.read()
    print(f'Content from bzipped file: {read_content.strip()}')

import os
os.remove('example.txt')
os.remove('example.gz')
os.remove('output.bz2')